unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

cdk_alphalist(3)           Library Functions Manual           cdk_alphalist(3)



NAME
       newCDKAlphalist,   activateCDKAlphalist,   injectCDKAlphalist,   setCD-
       KAlphalist,  setCDKAlphalistContents,  getCDKAlphalistContents,  setCD-
       KAlphalistFillerChar,   getCDKAlphalistFillerChar,  setCDKAlphalistCon-
       tents, getCDKAlphalistContents, setCDKAlphalistHighlight, getCDKAlphal-
       istHighlight,  setCDKAlphalistBox,  getCDKAlphalistBox, setCDKAlphalis-
       tULChar,  setCDKAlphalistURChar,  setCDKAlphalistLLChar,  setCDKAlphal-
       istLRChar,  setCDKAlphalistVerticalChar, setCDKAlphalistHorizontalChar,
       setCDKAlphalistBoxAttribute,  setCDKAlphalistBackgroundColor,   moveCD-
       KAlphalist,  positionCDKAlphalist, drawCDKAlphalist, eraseCDKAlphalist,
       destroyCDKAlphalist, setCDKAlphalistPreProcess, setCDKAlphalistPostPro-
       cess - Creates a managed curses sorted alphabet list widget.

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

       #include <cdk.h>

       CDKALPHALIST  *newCDKAlphalist  (CDKSCREEN  *cdkscreen,  int  xpos, int
       ypos, int height, int width, char * title, char * label, char **  list,
       int  listSize,  chtype  fillerCharacter, chtype highlight, boolean box,
       boolean shadow);

       char *activateCDKAlphalist (CDKALPHALIST *alphalist, chtype *actions);

       char *injectCDKAlphalist (CDKALPHALIST *alphalist, chtype input);

       void setCDKAlphalist (CDKALPHALIST *alphalist, char ** list, int  list-
       Size, chtype fillerCharacter, chtype highlight, boolean box);

       void  setCDKAlphalistContents  (CDKALPHALIST  *alphalist, char ** list,
       int listSize);

       char **getCDKAlphalistContents (CDKALPHALIST *alphalist);

       void setCDKAlphalistFillerChar (CDKALPHALIST *alphalist, chtype filler-
       Character);

       chtype getCDKAlphalistFillerChar (CDKALPHALIST *alphalist);

       void  setCDKAlphalistHighlight  (CDKALPHALIST  *alphalist, chtype high-
       light);

       chtype setCDKAlphalistHighlight (CDKALPHALIST *alphalist);

       void setCDKAlphalistBox (CDKALPHALIST *alphalist, boolean box);

       boolean getCDKAlphalistBox (CDKALPHALIST *alphalist);

       void setCDKAlphalistULChar (CDKALPHALIST  *,alphalist,  chtype  charac-
       ter);

       void  setCDKAlphalistURChar  (CDKALPHALIST  *,alphalist, chtype charac-
       ter);

       void setCDKAlphalistLLChar (CDKALPHALIST  *,alphalist,  chtype  charac-
       ter);

       void  setCDKAlphalistLRChar  (CDKALPHALIST  *,alphalist, chtype charac-
       ter);

       void  setCDKAlphalistVerticalChar  (CDKALPHALIST  *,alphalist,   chtype
       character);

       void  setCDKAlphalistHorizontalChar  (CDKALPHALIST  *,alphalist, chtype
       character);

       void  setCDKAlphalistBoxAttribute  (CDKALPHALIST  *,alphalist,   chtype
       character);

       void  setCDKAlphalistBackgroundColor  (CDKALPHALIST *,alphalist, char *
       color);

       void moveCDKAlphalist (CDKALPHALIST *alphalist, int box, int box, bool-
       ean relative, boolean refresh);

       void positionCDKAlphalist (CDKALPHALIST *alphalist);

       void drawCDKAlphalist (CDKALPHALIST *alphalist, boolean box);

       void eraseCDKAlphalist (CDKALPHALIST *alphalist);

       void destroyCDKAlphalist (CDKALPHALIST *alphalist);

       void   setCDKAlphalistPreProcess  (CDKALPHALIST  *alphalist,  PROCESSFN
       callback, void * data);

       void  setCDKAlphalistPostProcess  (CDKALPHALIST  *alphalist,  PROCESSFN
       callback, void * data);

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

DESCRIPTION
       The Cdk alphalist allows a user to select from a list of alphabetically
       sorted  words.  The user can use the arrow keys to traverse through the
       list or type in the beginning of the word and the list  will  automati-
       cally  adjust  itself  in the correct place in the scrolling list. This
       widget, like the file selector widget, is a compound widget of both the
       entry field widget and the scrolling list widget.


AVAILABLE FUNCTIONS
       CDKALPHALIST  *newCDKAlphalist (CDKSCREEN * screen, int xpos, int ypos,
       int height, int width, char *title, char *label, char **list, int list-
       Size,   chtype  fillerChar,  chtype  highlight,  boolean  box,  boolean
       shadow);
          This function creates a pointer to an alphalist 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 take 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 val-
          ues of TOP, BOTTOM, and CENTER. The parameters height and width con-
          trol the height and width of the widget. If you provide a  value  of
          zero  for either of the height or the width, the widget will be cre-
          ated with the full width and height of the screen. If you provide  a
          negative  value, the widget will be created the full height or width
          minus the value provided. The title parameter is  the  string  which
          will be displayed at the top of the scrolling list. 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 dis-
          played in the label of the entry field.  The parameter list  is  the
          list  of  words  which will be displayed in the scrolling list. This
          list does not have to be sorted, this widget automatically sorts the
          list.  The  parameter  listSize  tells the widget how large the word
          list is.  The field fillerCharacter is the character which is to  be
          displayed  in an empty space in the entry field. The field highlight
          is the attribute of the highlight bar in the scrolling list. The box
          parameter  states whether the widget 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 cre-
          ated then a NULL pointer is returned.

       char *activateCDKAlphalist (CDKALPHALIST *alphalist, chtype *actions);
          This function activates the  alphalist  widget  and  lets  the  user
          interact  with the widget. The parameter alphalist is a pointer to a
          non-NULL alphalist 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 then this function will return a char *  of  the  information
          which  was  typed in the field. If the TAB character is hit then the
          widget will try to complete the word in the entry field. If the wid-
          get  is  exited  with the RETURN character then the structure member
          exitType will be set to vNORMAL. If the widget was exited  with  the
          ESCAPE  key  then  the  structure  member  exitType  will  be set to
          vESCAPE_HIT and the widget returns NULL.

       char *injectCDKAlphalist (CDKALPHALIST *alphalist, chtype character);
          This function injects a single character into the widget. The param-
          eter  alphalist  is  a  pointer  to a non-NULL alphalist widget. The
          parameter character is the character to inject into the  widget.  If
          the character injected into this widget was RETURN then the informa-
          tion in the entry field of this widget  will  be  returned  and  the
          structure  member  exitType will be set to vNORMAL. If the character
          injected was ESCAPE  then  the  widget  will  exit,  return  a  NULL
          pointer,  and  set the structure member exitType to vESCAPE_HIT. Any
          other character injected into the widget will set the structure mem-
          ber  exitType  to  a value of vEARLY_EXIT and a NULL pointer will be
          returned.

       void setCDKAlphalist (CDKALPHALIST *alphalist, char **list,  int  list-
       Size, chtype fillerCharacter, chtype highlight, boolean box);
          This  function  lets  the  programmer  modify certain elements of an
          already defined alphalist widget. The parameter names correspond  to
          the same parameter names listed in the newCDKAlphalist function.

       void setCDKAlphalistContents (CDKALPHALIST *alphalist, char **list, int
       listSize);
          This function sets the contents of the alphalist widget.

       char **getCDKAlphalistContents (CDKALPHALIST *alphalist);
          This function returns the contents of the alphalist.

       void   setCDKAlphalistFillerChar   (CDKALPHALIST   *alphalist,   chtype
       filler);
          This  sets the character to use when drawing the entry field portion
          of the widget.

       chtype getCDKAlphalistFillerChar (CDKALPHALIST *alphalist);
          This returns the character being used as the filler character in the
          entry field portion of the widget.

       void  setCDKAlphalistHighlight  (CDKALPHALIST  *alphalist, chtype high-
       light);
          This function sets  the  attribute  of  the  highlight  bar  of  the
          scrolling list portion of the widget.

       chtype getCDKAlphalistHighlight (CDKALPHALIST *alphalist);
          This  returns  the  attribute  of the highlight bar of the scrolling
          list portion of the widget.

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

       boolean getCDKAlphalistBox (CDKALPHALIST *alphalist);
          This  returns  whether  or  not  the widget will be drawn with a box
          around it.

       void setCDKAlphalistULChar (CDKALPHALIST *alphalist, chtype character);
          This function sets the upper left hand corner of the widgets box  to
          the given character.

       void setCDKAlphalistURChar (CDKALPHALIST *alphalist, chtype character);
          This function sets the upper right hand corner of the widgets box to
          the given character.

       void setCDKAlphalistLLChar (CDKALPHALIST *alphalist, chtype character);
          This function sets the lower left hand corner of the widgets box  to
          the given character.

       void setCDKAlphalistLRChar (CDKALPHALIST *alphalist, chtype character);
          This function sets the lower right hand corner of the widgets box to
          the given character.

       void setCDKAlphalistVerticalChar (CDKALPHALIST *alphalist, chtype char-
       acter);
          This function sets the vertical drawing character for the box to the
          given character.

       void  setCDKAlphalistHorizontalChar  (CDKALPHALIST  *alphalist,  chtype
       character);
          This  function  sets the horizontal drawing character for the box to
          the given character.

       void  setCDKAlphalistBoxAttribute  (CDKALPHALIST   *alphalist,   chtype
       attribute);
          This function sets the attribute of the box.

       void   setCDKAlphalistBackgroundColor  (CDKALPHALIST  *alphalist,  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 moveCDKAlphalist (CDKALPHALIST *alphalist,  int  xpos,  int  ypos,
       boolean relative, 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 positionCDKAlphalist (CDKALPHALIST *alphalist);
          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 drawCDKAlphalist (CDKALPHALIST *alphalist, boolean box);
             This  function  draws the alphalist widget on the screen. The box
             option draws the widget with or without a box.

          void eraseCDKAlphalist (CDKALPHALIST *alphalist);
             This function removes the widget from the screen. This  does  NOT
             destroy the widget.

          void destroyCDKAlphalist (CDKALPHALIST *alphalist);
             This function removes the widget from the screen and frees up any
             memory the object may be using.

          void setCDKAlphalistPreProcess (CDKALPHALIST  *alphalist,  PROCESSFN
          function, void *data);
             This  function allows the user to have the widget call a function
             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  setCDKAlphalistPostProcess (CDKALPHALIST *alphalist, PROCESSFN
          function, void *data);
             This function allows the user to have the widget call a  function
             after  the  key  has  been  applied to the widget.  The parameter
             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. To learn more about the type EObject-
             Type 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 call-back 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 call-back 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.
       Since  this widget is built from both the scrolling list widget and the
       entry field widget, the key bindings are the same  for  the  respective
       fields. The extra key bindings are listed below.

       Key Bindings
          Key          Action
          Up Arrow     Scrolls the scrolling list up one line.
          Down Arrow   Scrolls the scrolling list down one line.
          Page Up      Scrolls the scrolling list up one page.
          CTRL-B       Scrolls the scrolling list up one page.
          Page Down    Scrolls the scrolling list down one page.
          CTRL-F       Scrolls the scrolling list down one page.
          Tab          Tries to complete the word in the entry field.
                       If the word segment is not unique then the
                       widget will beep and present a list of close
                       matches.
          Return       Returns the word in the entry field. It also
                       sets the structure member exitType in
                       the widget pointer to the value of 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.


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

NOTES
       This  widget  is  created  from the scrolling list widget and the entry
       field widget.  This is a good example on how to build your own  widgets
       using the base widgets provided in this distribution.

       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_alphalist(3)