http://invisible-island.net/cdk/manpage/


cdk_alphalist 3

cdk_alphalist(3)                                            cdk_alphalist(3)




NAME

       cdk_alphalist - curses sorted list widget.


SYNOPSIS

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

       #include <cdk.h>

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

       void destroyCDKAlphalist (
                      CDKALPHALIST *alphalist);

       void drawCDKAlphalist (
                      CDKALPHALIST *alphalist,
                      boolean box);

       void eraseCDKAlphalist (
                      CDKALPHALIST *alphalist);

       boolean getCDKAlphalistBox (
                      CDKALPHALIST *alphalist);

       char **getCDKAlphalistContents (
                      CDKALPHALIST *alphalist,
                      int *size);

       int getCDKAlphalistCurrentItem (
                      CDKALPHALIST *widget);

       chtype getCDKAlphalistFillerChar (
                      CDKALPHALIST *alphalist);

       chtype getCDKAlphalistHighlight (
                      CDKALPHALIST *alphalist);

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

       void moveCDKAlphalist (
                      CDKALPHALIST *alphalist,
                      int xpos,
                      int ypos,
                      boolean relative,
                      boolean refresh);

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

       void positionCDKAlphalist (
                      CDKALPHALIST *alphalist);

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

       void setCDKAlphalistBackgroundAttrib (
                      CDKALPHALIST *alphalist,
                      chtype attribute);

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

       void setCDKAlphalistBox (
                      CDKALPHALIST *alphalist,
                      boolean box);

       void setCDKAlphalistBoxAttribute (
                      CDKALPHALIST *alphalist,
                      chtype character);

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

       void setCDKAlphalistCurrentItem (
                      CDKALPHALIST *widget,
                      int item);

       void setCDKAlphalistFillerChar (
                      CDKALPHALIST *alphalist,
                      chtype fillerCharacter);

       void setCDKAlphalistHighlight (
                      CDKALPHALIST *alphalist,
                      chtype highlight);

       void setCDKAlphalistHorizontalChar (
                      CDKALPHALIST *alphalist,
                      chtype character);

       void setCDKAlphalistLLChar (
                      CDKALPHALIST *alphalist,
                      chtype character);

       void setCDKAlphalistLRChar (
                      CDKALPHALIST *alphalist,
                      chtype character);

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

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

       void setCDKAlphalistULChar (
                      CDKALPHALIST *alphalist,
                      chtype character);

       void setCDKAlphalistURChar (
                      CDKALPHALIST *alphalist,
                      chtype character);

       void setCDKAlphalistVerticalChar (
                      CDKALPHALIST *alphalist,
                      chtype character);


DESCRIPTION

       The  Cdk  alphalist allows a user to select from a list of alphabeti-
       cally 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  automatically  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

       activateCDKAlphalist
            activates  the  alphalist widget and lets the user interact with
            the widget.

            o   The parameter alphalist is a pointer to a non-NULL alphalist
                widget.

            o   If  the  actions  parameter is passed with a non-NULL value,
                the characters in the array will be injected into  the  wid-
                get.

                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 widget is exited with the RETURN character then the wid-
            get data exitType will be set to vNORMAL.

            If the widget was exited with the ESCAPE  key  then  the  widget
            data  exitType will be set to vESCAPE_HIT and the widget returns
            NULL.

       destroyCDKAlphalist
            removes the widget from the screen and frees memory  the  object
            used.

       drawCDKAlphalist
            draws the alphalist widget on the screen.

            If the box parameter is true, the widget is drawn with a box.

       eraseCDKAlphalist
            removes  the  widget from the screen.  This does NOT destroy the
            widget.

       getCDKAlphalistBox
            returns true if the widget will be drawn with a box around it.

       getCDKAlphalistContents
            returns the contents of the alphalist.

       getCDKAlphalistCurrentItem
            returns the current position in the scroll-widget.

       getCDKAlphalistFillerChar
            returns the character being used as the filler character in  the
            entry field portion of the widget.

       getCDKAlphalistHighlight
            returns the attribute of the highlight bar of the scrolling list
            portion of the widget.

       injectCDKAlphalist
            injects a single character into the widget (actually  the  entry
            widget).

            o   The parameter alphalist is a pointer to a non-NULL alphalist
                widget.

            o   The parameter character is the character to inject into  the
                widget.

            The  return value and side-effect (setting the widget data exit-
            Type) depend upon the injected character:

            RETURN or TAB
                   the function returns the information in the entry  field.
                   The widget data exitType is set to vNORMAL.

            ESCAPE the  function  returns  a  NULL pointer.  The widget data
                   exitType is set to vESCAPE_HIT.

            Otherwise
                   unless modified by preprocessing, postprocessing  or  key
                   bindings,  the function returns a NULL pointer.  The wid-
                   get data exitType is set to vEARLY_EXIT.

       moveCDKAlphalist
            moves the given widget to the given position.

            o   The parameters xpos and ypos are the  new  position  of  the
                widget.

                The  parameter  xpos  may  be  an integer or one of the pre-
                defined values TOP, BOTTOM, and CENTER.

                The parameter ypos may be an integer  or  one  of  the  pre-
                defined values LEFT, RIGHT, and CENTER.

            o   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 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.

            newCDKAlphalist
                 creates a pointer to an alphalist widget.  Parameters:

                 o   screen is the screen you wish this widget to be  placed
                     in.

                 o   xpos  controls  the  placement  of the object along the
                     horizontal axis.  This parameter can take an integer or
                     one of the pre-defined values LEFT, RIGHT, and CENTER.

                 o   ypos  controls  the  placement  of the object along the
                     vertical axis.  This parameter may be an integer  value
                     or  one of the pre-defined values TOP, BOTTOM, and CEN-
                     TER.

                 o   height and width control 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  created
                     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.

                 o   title  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.

                 o   label is the string which  will  be  displayed  in  the
                     label of the entry field.

                 o   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 (note
                     that it modifies the caller's copy of the  list  to  do
                     this).

                 o   listSize tells the widget how large the word list is.

                 o   fillerCharacter  is  the  character which is to be dis-
                     played in an empty space in the entry field.

                 o   highlight is the attribute of the highlight bar in  the
                     scrolling list.

                 o   box  is  true  if the widget should be drawn with a box
                     around it.

                 o   shadow is true to turn the shadow on around  this  wid-
                     get.

                 If  the  widget could not be created then a NULL pointer is
                 returned.

            positionCDKAlphalist
                 allows the user to move the widget around  the  screen  via
                 the  cursor/keypad keys.  See cdk_position(3) for key bind-
                 ings.

            setCDKAlphalist
                 lets the programmer modify certain elements of an  existing
                 alphalist widget.

                 The  parameter names correspond to the same parameter names
                 listed in the newCDKAlphalist function.

            setCDKAlphalistBackgroundAttrib
                 sets the background attribute of the widget.

                 The  parameter  attribute  is  a  curses  attribute,  e.g.,
                 A_BOLD.

            setCDKAlphalistBackgroundColor
                 sets the background color of the widget.

                 The  parameter  color  is  in  the format of the Cdk format
                 strings.  See cdk_display(3).

            setCDKAlphalistBox
                 sets whether the widget will be drawn with a box around it.

            setCDKAlphalistBoxAttribute
                 sets the attribute of the box.

            setCDKAlphalistContents
                 sets the contents of the alphalist  widget  (note  that  it
                 sorts the caller's copy of the list).

            setCDKAlphalistCurrentItem
                 set the current position in the scroll-widget.

            setCDKAlphalistFillerChar
                 sets the character to use when drawing the entry field por-
                 tion of the widget.

            setCDKAlphalistHighlight
                 sets the attribute of the highlight bar  of  the  scrolling
                 list portion of the widget.

            setCDKAlphalistHorizontalChar
                 sets  the  horizontal  drawing character for the box to the
                 given character.

            setCDKAlphalistLLChar
                 sets the lower left hand corner of the widget's box to  the
                 given character.

            setCDKAlphalistLRChar
                 sets the lower right hand corner of the widget's box to the
                 given character.

            setCDKAlphalistPostProcess
                 allows the user to have the widget call  a  function  after
                 the key has been applied to the widget.

                 o   The parameter function is the callback function.

                 o   The  parameter  data points to data passed to the call-
                     back function.

                 To learn more about post-processing see cdk_process(3).

            setCDKAlphalistPreProcess
                 allows the user to have the widget call a function after  a
                 key is hit and before the key is applied to the widget.

                 o   The parameter function is the callback function.

                 o   The  parameter  data points to data passed to the call-
                     back function.

                 To learn more about pre-processing see cdk_process(3).

            setCDKAlphalistULChar
                 sets the upper left hand corner of the widget's box to  the
                 given character.

            setCDKAlphalistURChar
                 sets the upper right hand corner of the widget's box to the
                 given character.

            setCDKAlphalistVerticalChar
                 sets the vertical drawing character  for  the  box  to  the
                 given character.


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 respec-
       tive fields.  The extra key bindings are listed below.

              +----------------+-------------------------------------+
              |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  widget |
              |                | data exitType to vNORMAL.           |
              +----------------+-------------------------------------+
              |Escape          | Exits the widget and returns a NULL |
              |                | pointer.  It also sets  the  widget |
              |                | data exitType to vESCAPE_HIT.       |
              +----------------+-------------------------------------+

SEE ALSO

       cdk(3),      cdk_binding(3),     cdk_display(3),     cdk_position(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 wid-
       gets using the base widgets provided in this distribution.



                                                            cdk_alphalist(3)