unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-2.0)
Page:
Section:
Apropos / Subsearch:
optional field

cdk_mentry(3)              Library Functions Manual              cdk_mentry(3)



NAME
       newCDKMentry, activateCDKMentry, injectCDKMentry, setCDKMentry, setCDK-
       MentryValue,   getCDKMentryValue,   setCDKMentryMin,   getCDKMentryMin,
       setCDKMentryFillerChar, getCDKMentryFillerChar, setCDKMentryBox, getCD-
       KMentryBox, setCDKMentryULChar, setCDKMentryURChar, setCDKMentryLLChar,
       setCDKMentryLRChar,    setCDKMentryVerticalChar,   setCDKMentryHorizon-
       talChar, setCDKMentryBoxAttribute, setCDKMentryBackgroundColor, setCDK-
       MentryCB, drawCDKMentry, eraseCDKMentry, cleanCDKMentry, destroyCDKMen-
       try, setCDKMentryPreProcess, setCDKMentryPostProcess  - Creates a  man-
       aged curses multiple line entry widget.

SYNOPSIS
       cc [ flag ... ] file ...  -lcdk [ library ... ]

       #include <cdk.h>

       CDKMENTRY *newCDKMentry (CDKSCREEN *cdkscreen, int xpos, int ypos, char
       *title, char *label,  chtype  fieldAttribute,  chtype  fillerCharacter,
       EDisplayType  displayType,  int fieldWidth, int fieldRows, int logical-
       Rows, int minimumLength, boolean box, boolean shadow);

       char *activateCDKMentry (CDKMENTRY *mentry, chtype *actions);

       char *injectCDKMentry (CDKMENTRY *mentry, chtype input);

       void setCDKMentry (CDKMENTRY *mentry, char *value,  int  minimumLength,
       boolean box);

       void setCDKMmentryValue (CDKMENTRY *mentry, char *value);

       char *getCDKMmentryValue (CDKMENTRY *mentry);

       void setCDKMmentryMin (CDKMENTRY *mentry, int minimum);

       int getCDKMmentryMin (CDKMENTRY *mentry);

       void setCDKMmentryBox (CDKMENTRY *mentry, boolean box);

       boolean getCDKMmentryBox (CDKMENTRY *mentry);

       void setCDKMmentryBox (CDKMENTRY *mentry, boolean box);

       boolean getCDKMmentryBox (CDKMENTRY *mentry);

       void setCDKMentryCB (CDKMENTRY *mentry, MENTRYCB callBackFunction);

       void setCDKMentryULChar (CDKMENTRY *,mentry, chtype character);

       void setCDKMentryURChar (CDKMENTRY *,mentry, chtype character);

       void setCDKMentryLLChar (CDKMENTRY *,mentry, chtype character);

       void setCDKMentryLRChar (CDKMENTRY *,mentry, chtype character);

       void setCDKMentryVerticalChar (CDKMENTRY *,mentry, chtype character);

       void setCDKMentryHorizontalChar (CDKMENTRY *,mentry, chtype character);

       void setCDKMentryBoxAttribute (CDKMENTRY *,mentry, chtype character);

       void setCDKMentryBackgroundColor (CDKMENTRY *,mentry, char * color);

       void  moveCDKMentry (CDKMENTRY *mentry, int box, int box, boolean rela-
       tive, boolean refresh);

       void positionCDKMentry (CDKMENTRY *mentry);

       void drawCDKMentry (CDKMENTRY *mentry, boolean box);

       void eraseCDKMentry (CDKMENTRY *mentry);

       void cleanCDKMentry (CDKMENTRY *mentry);

       void destroyCDKMentry (CDKMENTRY *mentry);

       void setCDKMentryPreProcess  (CDKMENTRY  *mentry,  PROCESSFN  callback,
       void * data);

       void  setCDKMentryPostProcess  (CDKMENTRY  *mentry, PROCESSFN callback,
       void * data);

       void bindCDKObject (EObjectType widgetType, void *object,  chtype  key,
       BINDFN function, void *data);

DESCRIPTION
       The  Cdk  mentry  widget creates a multiple line entry box with a label
       and an entry field. The following are functions which create or manipu-
       late the Cdk mentry box widget.


AVAILABLE FUNCTIONS
       CDKMENTRY  *newCDKMentry  (CDKSCREEN  *screen, int xpos, int ypos, char
       *title, char *label,  chtype  fieldAttribute,  chtype  fillerCharacter,
       chtype displayType, int fieldWidth, int fieldRows, int logicalRows, int
       minimumLength, boolean box, boolean shadow);
          This function creates a pointer  to  a  mentry  widget.  The  screen
          parameter  is  the  screen you wish this widget to be placed in. The
          parameter xpos controls the placement of the object along the  hori-
          zontal  axis.  This  parameter can accept an integer value or one of
          the pre-defined values of LEFT, RIGHT,  and  CENTER.  The  parameter
          ypos  controls  the placement of the object along the vertical axis.
          This parameter can accept an integer value or one of the pre-defined
          values  of  TOP,  BOTTOM,  and  CENTER.   The title parameter is the
          string which will be displayed at the top of the widget.  The  title
          can  be more than one line; just provide a carriage return character
          at the line break. The label parameter is the string which  will  be
          displayed  in  the  label of the mentry field. The fieldAttribute is
          the attribute of the characters to be displayed when they are  typed
          in.   filler  is  the character which is to be displayed in an empty
          space in the mentry field. The parameter displayType tells  how  the
          mentry field will behave when a character is entered into the field.
          The following table outlines valid values for this  field  and  what
          they mean:

             Display_Type      Meaning
             vCHAR             Only accepts alphabetic characters.
             vLCHAR            Only accepts alphabetic characters.
                               Maps the character to lower case
                               when a character has been accepted.
             vUCHAR            Only accepts alphabetic characters.
                               Maps the character to upper case
                               when a character has been accepted.
             vHCHAR            Only accepts alphabetic characters.
                               Displays a . when a character
                               has been accepted.
             vUHCHAR           Only accepts alphabetic characters.
                               Displays a . and maps the
                               character to upper case when a
                               character has been accepted.
             vLHCHAR           Only accepts alphabetic characters.
                               Displays a . and maps the
                               character to lower case when a
                               character has been accepted.
             vINT              Only accepts numeric characters.
             vHINT             Only accepts numeric characters.
                               Displays a . when a character
                               has been accepted.
             vMIXED            Accepts any character types.
             vLMIXED           Accepts any character types.
                               Maps the character to lower case
                               when an alphabetic character has
                               been accepted.
             vUMIXED           Accepts any character types.
                               Maps the character to upper case
                               when an alphabetic character has
                               been accepted.
             vHMIXED           Accepts any character types.
                               Displays a . when a character
                               has been accepted.
             vLHMIXED          Accepts any character types.
                               Displays a . and maps the
                               character to lower case when a
                               character has been accepted.
             vUHMIXED          Accepts any character types.
                               Displays a . and maps the
                               character to upper case when a
                               character has been accepted.
             vVIEWONLY         Uneditable field.

          The parameters fieldRows and fieldWidth control the height and width
          of the field of the widget. If you  provide  a  value  of  zero  for
          either  of the values, the field in the widget will be made as large
          as it can both in width and in height.  If you  provide  a  negative
          value,  the field will be created the full height or width minus the
          value provided.  While logicalRows states how many rows  the  mentry
          field will have. The parameter minimumLength states how many charac-
          ters have to be entered before the use can exit  the  mentry  field.
          The  callBackFunction is where the use can swap out the key process-
          ing element of the widget. The box parameter states whether the wid-
          get  will be drawn with a box around it or not. The shadow parameter
          accepts a boolean value to turn the shadow on  or  off  around  this
          widget.  If  the  widget could not be created then a NULL pointer is
          returned.

       char *activateCDKMentry (CDKMENTRY *mentry, chtype *actions);
          This function activates the mentry widget and lets the user interact
          with  the  widget.  The  parameter mentry is a pointer to a non-NULL
          mentry widget.  If the actions parameter is passed with  a  non-NULL
          value, the characters in the array will be injected into the widget.
          To activate the widget interactively pass  in  a  NULL  pointer  for
          actions.  If the character entered into this widget is RETURN or TAB
          then this function will return a char * representing the information
          typed  into the widget and the structure member exitType will be set
          to vNORMAL. If the character entered was ESCAPE  then  the  function
          will  returns  NULL pointer and the structure member exitType is set
          to vESCAPE_HIT.

       char *injectCDKMentry (CDKMENTRY *mentry, chtype character);
          This function injects a single character into the widget. The param-
          eter mentry is a pointer to a non-NULL mentry. The parameter charac-
          ter is the character to inject into the  widget.  If  the  character
          injected  into this widget was RETURN or TAB then this function will
          return a char * representing the information typed into  the  widget
          and  the  structure  member  exitType will be set to vNORMAL. If the
          character entered was ESCAPE then the  function  will  returns  NULL
          pointer and the structure member exitType is set to vESCAPE_HIT. Any
          other character injected into the widget will set the structure mem-
          ber  exitType  to  vEARLY_EXIT  and  the function will return a NULL
          pointer.

       void setCDKMentry (CDKMENTRY *mentry, char *value,  int  minimumLength,
       boolean box);
          This  function  lets  the  programmer  modify certain elements of an
          already defined entry widget. The parameter names correspond to  the
          same parameter names listed in the newCDKMentry function.

       void setCDKMentryValue (CDKMENTRY *mentry, char *value);
          This sets the current value of the widget.

       char *getCDKMentryValue (CDKMENTRY *mentry);
          This returns the current value of the widget.

       void setCDKMentryMin (CDKMENTRY *mentry, int maximum);
          This  sets  the  minimum  length  of the string that the widget will
          allow.

       int getCDKMentryMin (CDKMENTRY *mentry);
          This returns the minimum length of a string the widget will allow.

       void setCDKMentryFillerChar (CDKMENTRY *mentry, chtype filler);
          This sets the character to use when  drawing  unused  space  in  the
          field.

       chtype getCDKMentryFillerChar (CDKMENTRY *mentry);
          This  returns  the  character being used to draw unused space in the
          widget.

       void setCDKMentryBox (CDKMENTRY *mentry, boolean boxWidget);
          This sets whether or not the widget will be draw with a  box  around
          it.

       boolean getCDKMentryBox (CDKMENTRY *mentry);
          This  returns  whether  or  not  the widget will be drawn with a box
          around it.

       void setCDKMentryULChar (CDKMENTRY *mentry, chtype character);
          This function sets the upper left hand corner of the widgets box  to
          the given character.

       void setCDKMentryURChar (CDKMENTRY *mentry, chtype character);
          This function sets the upper right hand corner of the widgets box to
          the given character.

       void setCDKMentryLLChar (CDKMENTRY *mentry, chtype character);
          This function sets the lower left hand corner of the widgets box  to
          the given character.

       void setCDKMentryLRChar (CDKMENTRY *mentry, chtype character);
          This function sets the lower right hand corner of the widgets box to
          the given character.

       void setCDKMentryVerticalChar (CDKMENTRY *mentry, chtype character);
          This function sets the vertical drawing character for the box to the
          given character.

       void setCDKMentryHorizontalChar (CDKMENTRY *mentry, chtype character);
          This  function  sets the horizontal drawing character for the box to
          the given character.

       void setCDKMentryBoxAttribute (CDKMENTRY *mentry, chtype attribute);
          This function sets the attribute of the box.

       void setCDKMentryBackgroundColor (CDKMENTRY *mentry, char *color);
          This sets the background color of the widget. The parameter color is
          in  the  format  of  the Cdk format strings. To get more information
          look at the cdk_display manual page.

       void setCDKMentryCB (CDKMENTRY *mentry, MENTRYCB callbackFunction);
          This function allows the programmer to set a different widget  input
          handler.   The  parameter  callbackFunction is of type MENTRYCB. The
          current default function is CDKMentryCallBack.

       void moveCDKMentry (CDKMENTRY *mentry, int xpos, int ypos, boolean rel-
       ative, boolean refresh);
          This  function  moves  the  given  widget to the given position. The
          parameters xpos and ypos is the new  position  of  the  widget.  The
          parameter xpos can accept an integer value or one of the pre-defined
          values of TOP, BOTTOM, and CENTER. The parameter ypos can accept  an
          integer  value  or one of the pre-defined values of LEFT, RIGHT, and
          CENTER. The parameter relative states whether the xpos/ypos pair  is
          a  relative  move  or  an absolute move. For example if xpos = 1 and
          ypos = 2 and relative = TRUE, then the widget  would  move  one  row
          down  and two columns right. If the value of relative was FALSE then
          the widget would move to the position (1,2). Do not use  the  values
          of  TOP, BOTTOM, LEFT, RIGHT, or CENTER when relative = TRUE. (weird
          things may happen). The final parameter refresh is a  boolean  value
          which states whether the widget will get refreshed after the move or
          not.

       void positionCDKMentry (CDKMENTRY *mentry);
          This function allows the user to move the widget around  the  screen
          via  the  cursor/keypad keys. The following key bindings can be used
          to move the widget around the screen.

          Key Bindings
             Key          Action
             Up Arrow     Moves the widget up one line.
             Down Arrow   Moves the widget down one line.
             Left Arrow   Moves the widget left one column
             Right Arrow  Moves the widget right one column
             Keypad-1     Moves the widget down one line
                          and left one column.
             Keypad-2     Moves the widget down one line.
             Keypad-3     Moves the widget down one line
                          and right one column.
             Keypad-4     Moves the widget left one column
             Keypad-5     Centers the widget both vertically
                          and horizontally.
             Keypad-6     Moves the widget right one column
             Keypad-7     Moves the widget up one line
                          and left one column.
             Keypad-8     Moves the widget up one line.
             Keypad-9     Moves the widget up one line
                          and right one column.
             t            Moves the widget to the top of the screen.
             b            Moves the widget to the bottom of the screen.
             l            Moves the widget to the left of the screen.
             r            Moves the widget to the right of the screen.
             c            Centers the widget between the left and
                          right of the window.
             C            Centers the widget between the top and
                          bottom of the window.
             Escape       Returns the widget to its original position.
             Return       Exits the function and leaves the widget
                          where it was.

             Keypad means that if the keyboard you are  using  has  a  keypad,
             then  the Num-Lock light has to be on in order to use the keys as
             listed. (The numeric keys at the top of the keyboard will work as
             well.)

             void drawCDKMentry(CDKMENTRY *mentry, boolean box);
                This  function  draws the widget on the screen. The box option
                draws the widget with or without a box.

             void eraseCDKMentry (CDKMENTRY *mentry);
                This function removes the widget from the  screen.  This  does
                NOT destroy the widget.

             void cleanCDKMentry (CDKMENTRY *mentry);
                This function clears the information from the field.

             void destroyCDKMentry (CDKMENTRY *mentry);
                This  function removes the widget from the screen and frees up
                any memory the object may be using.

             void setCDKMentryPreProcess (CDKMENTRY *mentry,  PROCESSFN  func-
             tion, void *data);
                This  function allows the user to have the widget call a func-
                tion after a key is hit and before the key is applied  to  the
                widget.  The  parameter  function  if  of  type PROCESSFN. The
                parameter data is a pointer to void. To learn more about  pre-
                processing read the cdk_process manual page.

             void  setCDKMentryPostProcess (CDKMENTRY *mentry, PROCESSFN func-
             tion, void *data);
                This function allows the user to have the widget call a  func-
                tion after the key has been applied to the widget.  The param-
                eter function if of type PROCESSFN. The parameter  data  is  a
                pointer  to void. To learn more about post-processing read the
                cdk_process manual page.

             void bindCDKObject (EObjectType widgetType,  void  *object,  char
             key, BINDFN function, void *data);
                This  function allows the user to create special key bindings.
                The widgetType parameter is a defined type which  states  what
                Cdk  object  type  is  being used. The object parameter is the
                pointer to the widget object. The widgetType  parameter  is  a
                defined  type which states what Cdk object type is being used.
                To learn more about the type EObjectType read the  cdk_binding
                manual page. The object parameter is the pointer to the widget
                object. The key is the character to bind. The function is  the
                function  type.  To  learn more about the key binding callback
                function types read the  cdk_binding  manual  page.  The  last
                parameter  data  is  a  pointer  to any data that needs to get
                passed to the callback function.

KEY BINDINGS
       When the widget is activated there are  several  default  key  bindings
       which  will  help the user enter or manipulate the information quickly.
       The following table outlines the keys and their actions for  this  wid-
       get.

          Key         Action
          Left Arrow  Moves the cursor the the left.
          CTRL-B      Moves the cursor the the left.
          Right Arrow Moves the cursor the the right.
          CTRL-F      Moves the cursor the the right.
          Up Arrow    Moves the cursor one row down.
          Down Arrow  Moves the cursor one row up.
          Delete      Deletes the character to the left of the cursor.
          Backspace   Deletes the character to the left of the cursor.
          CTRL-H      Deletes the character to the left of the cursor.
          CTRL-V      Pastes whatever is in the paste buffer, into the widget.
          CTRL-X      Cuts the contents from the widget and saves a copy in
                      the paste buffer.
          CTRL-Y      Copies the contents of the widget into the paste buffer.
          CTRL-U      Erases the contents of the widget.
          CTRL-A      Moves the cursor to the beginning of the entry field.
          CTRL-E      Moves the cursor to the end of the entry field.
          CTRL-T      Transposes the character under the cursor with the
                      character to the right.
          Return      Exits the widget and returns a char * representing
                      the information which was typed into the field. It also
                      sets the structure member exitType in the widget
                      pointer to vNORMAL.
          Tab         Exits the widget and returns a char * representing
                      the information which was typed into the field. It also
                      sets the structure member exitType in the widget
                      pointer to vNORMAL.
          Escape      Exits the widget and returns a NULL pointer. It also
                      sets the structure member exitType in the widget pointer
                      to the value of vESCAPE_HIT.
          Ctrl-L      Refreshes the screen.

SEE ALSO
       cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)

NOTES
       The  header  file  &lt&lt;cdk.h&gt&gt;  automatically  includes  the  header  files
       &lt&lt;curses.h&gt&gt;, &lt&lt;stdlib.h&gt&gt;, &lt&lt;string.h&gt&gt;, &lt&lt;ctype.h&gt&gt;, &lt&lt;unistd.h&gt&gt;,  &lt&lt;dirent.h&gt&gt;,
       &lt&lt;time.h&gt&gt;, &lt&lt;errno.h&gt&gt;, &lt&lt;pwd.h&gt&gt;, &lt&lt;grp.h&gt&gt;, &lt&lt;sys/stat.h&gt&gt;, and &lt&lt;sys/types.h&gt&gt;.
       The &lt&lt;curses.h&gt&gt; header file includes &lt&lt;stdio.h&gt&gt; and &lt&lt;unctrl.h&gt&gt;.

       If you have Ncurses installed on your machine add -DNCURSES to the com-
       pile line to include the Ncurses header files instead.



                                 24 April 1997                   cdk_mentry(3)