2.4.2 LIST BOX - CREATE (AES 170)

This function allocates memory for a list box and initialises the objects by calling the routine <set> for each object passed in <objs>. However the list box will not be drawn!

Bit 0 of the variable <flags> determines whether the list box is a horizontal one (the first list item at left and last at right) or a vertical one (the first list item at top and last at bottom). Independently of this main scrolling direction the list box can also have a second slider if the items themselves are to be scrolled. This can be sensible, for instance, with a vertical list box with text items that are wider than the box.

Declaration:
LIST_BOX *lbox_create( OBJECT *tree, SLCT_ITEM slct, SET_ITEM set,
                       LBOX_ITEM *items, WORD visible_a, WORD first_a,
                       WORD *ctrl_objs, WORD *objs, WORD flags,
                       WORD pause_a, void *user_data, DIALOG *dialog,
                       visible_b, first_b, entries_b, pause_b );

Call:
box = lbox_create( tree, slct_item, set_item, item_list, 10, 0,
                   ctrl_objs, objs, lbox_flags, 20, 0L, 0L, 10,
                                                     0, 40, 5 );

Variable         Argument   Meaning
Inputs:

contrl[0]        170        lbox_create
contrl[1]        4 or 8     Entries in intin
contrl[3]        8          Entries in addrin

intin[0]         visible_a  Number of visible entries (Slider A)
intin[1]         first_a    Index of the first visible entry (Slider A)
intin[2]         flags      Various flags
intin[3]         pause_a    Delay during scrolling in ms (Slider A)

intin[4]         visible_b  Number of visible items (Slider B)
intin[5]         first_b    First visible item (Slider B)
intin[6]         entries_b  Number of items (Slider B)
intin[7]         pause_b    Delay during scrolling in ms (Slider B)

addrin[0]        tree       Pointer to the object tree of the dialog
addrin[1]        slct       Pointer to selection routine
addrin[2]        set        Pointer to set routine
addrin[3]        items      Pointer to linked list with LBOX_ITEMs
addrin[4]        ctrl_objs  Pointer to a field with the object numbers
                            of the buttons and slider (5 entries)
addrin[5]        objs       Pointer to a field with the object numbers
                            of the list box items (<entries> entries)
addrin[6]        user_data  Pointer for application
addrin[7]        dialog     Pointer to the window dialog structure
                            or 0L

Outputs:

contrl[2]        0            Entries in intout
contrl[4]        1            Entries in addrout

addrout[0]       box          Pointer to the list box structure
                              or 0L

Both <slct> and <set> are functions whose parameters are passed on the stack. The functions may alter registers d0-d2/a0-a2.

<slct> is a pointer to a selection routine that is always called when an entry is selected or deselected:

typedef void (cdecl *SLCT_ITEM)( LIST_BOX *box, OBJECT *tree,
                                 struct _lbox_item *item,
                                 void *user_data,
                                 WORD obj_index, WORD last_state );

<slct> will also be called when the selection of an object is cleared! The variable <selected> from the LBOX_ITEM structure already contains the new status of the object when <slct> is called.

<set> points to the function that is to enter the contents of a LBOX_ITEM into an object of the list box dialog:

typedef WORD (cdecl *SET_ITEM)( LIST_BOX *box, OBJECT *tree,
                                struct _lbox_item *item,
                                WORD obj_index,
                                void *user_data, GRECT *rect,
                                WORD first );

For a list box that only contains text strings, <set> is typically a function that copies a string pointed to by the LBOX_ITEM structure into the object <index>.

<rect> ist 0L when a redraw of the dialog box is executed or when lbox_update() has been called.

<rect> is not 0L when the user has selected or deselected an object, and points to the GRECT for the redraw. The return value of <set> is the number of the start object for objc_draw()/wdlg_redraw(). For entries in the list box that consist of several objects it is sometimes sensible to reduce the redraw rectangle when selecting/deselecting an object, or to alter the start object, to prevent unnecessary drawing operations and/or unnecessary flicker.

In most cases the list box routines call the function objc_draw()/wdlg_redraw() after <set> to display the altered contents.

<first> contains the number of the first visible item for Slider B if the list box has two sliders. For a (vertical) list box with text strings and two sliders, when calling lbox_create(), for instance, one enters the number of visible characters in <visible_b>, the total string length in <entries_b> and the index of the first visible character in <first_b>. If the text is scrolled horizontally, <set> is called for all visible strings and the affected parts of the screen are redrawn or moved. If the list box has only one slider, <first> is always 0.

<items> points to the first item in a list from LBOX_ITEM. The structure used for the items must contain a pointer to its successor (next) as its first element and a word for the condition (selected) as the second:

   typedef struct _lbox_item
   {
      struct _lbox_item *next;
                         /* Pointer to the next entry in the list */
      WORD  selected;    /* Specifies whether the object is selected */
      WORD  data1;       /* Data for the program... */
      void  *data2;
      void  *data3;

   } LBOX_ITEM;

However the structure can well look like the following example with appropriate casting during the call:

   typedef struct
   {
      void  *next;
      WORD  selected;

      ... From here on to suit the application ...

   } LB_EXAMPLE;

<ctrl_objs> is a pointer to a field with 5 or 9 entries that contains the numbers of the control objects (buttons):

If the list box has 2 sliders, ctrl_objs[5-8] contain the numbers of the objects for Slider B:

The buttons, the slider and the slider background should have a TOUCHEXIT status. If the list box contains only buttons and no slider, ctrl_objs[3/4 or 7/8] must contain -1.

<objs> is a field with <entries> entries that contains the numbers of the list box objects (the objects are normally children of ctrl_objs[0]).

   objs[0]:             Number of the first object
        .
        .
        .
   objs[entries - 1]:   Number of the last object

The objects should normally have TOUCHEXIT status.

The word <flags> influences the behaviour of the list box:

#define  LBOX_VERT   1      /* List box with vertical slider */
#define  LBOX_AUTO   2      /* Auto scrolling */
#define  LBOX_AUTOSLCT  4   /* Automatic display during auto scrolling */
#define  LBOX_REAL   8      /* Real-time slider */
#define  LBOX_SNGL   16     /* Only one selectable entry */
#define  LBOX_SHFT   32     /* Multiple selections with Shift */
#define  LBOX_TOGGLE 64     /* On selection change status of an entry */
#define  LBOX_2SLDRS 128    /* Support 2 sliders */

The flag LBOX_SNGL can also be combined with LBOX_SHFT or LBOX_TOGGLE to permit deselection in a list box with only one selectable entry. LBOX_SNGL + LBOX_SHFT means that the selected entry can be deselected by a click with a pressed Shift key. LBOX_SNGL + LBOX_TOGGLE causes a click to deselect a selected entry.

The pointer <items> can also be 0L if the list box is still empty and does not contain any entries.