Provided by: libcdk5-dev_5.0.20230201-4_amd64 bug

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

            •   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 widget is exited with the RETURN character then the widget 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).

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

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

            The return value and side-effect (setting the widget data exitType) 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 widget data exitType is set to vEARLY_EXIT.

       moveCDKAlphalist
            moves the given widget to the given position.

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

            •   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:

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

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

                 •   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 CENTER.

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

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

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

                 •   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).

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

                 •   fillerCharacter  is the character which is to be displayed in an empty space
                     in the entry field.

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

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

                 •   shadow is true to turn the shadow on around this widget.

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

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

                 •   The parameter function is the callback function.

                 •   The parameter data points to data passed to the callback 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.

                 •   The parameter function is the callback function.

                 •   The parameter data points to data passed to the callback 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 respective fields.  The extra key bindings are listed below.

                        ┌────────────────┬─────────────────────────────────────┐
                        │KeyAction                              │
                        ├────────────────┼─────────────────────────────────────┤
                        ├────────────────┼─────────────────────────────────────┤
                        │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 widgets using the base widgets provided in this
       distribution.

                                                                                 cdk_alphalist(3)