Home AESAES Scrap libraryScrap library MagiC libraryMagiC library

8.15 List boxes

The following routines were introduced with MagiC 4, and permit the creation and hadling of list boxes:

lbox_ascroll_to Positions slider A of the list box
lbox_bscroll_to Positions slider B of the list box
lbox_cnt_items Obtains number of list items
lbox_create Creates a list box
lbox_delete Releases memory allocated for a list box
lbox_do Processes button of a list box
lbox_free_items Releases items list
lbox_free_list Releases items list
lbox_get_afirst Obtains index of first visible item (slider A)
lbox_get_avis Obtains number of visible entries (slider A)
lbox_get_bentries Obtains number of entries (slider B)
lbox_get_bfirst Obtains index of first visible item (slider B)
lbox_get_bvis Obtains number of visible entries (slider B)
lbox_get_idx Obtains index of an item
lbox_get_item Returns pointer to n-th item
lbox_get_items Returns pointer to the first item
lbox_get_slct_idx Obtains index of the first selected item
lbox_get_slct_item Returns pointer to the first selected item
lbox_get_tree Obtains object tree of the dialog
lbox_get_udata Gets pointer to program-specific data
lbox_set_asldr Sets position of the slider A
lbox_set_bentries Sets number of entries for slider B
lbox_set_bsldr Sets position of the slider B
lbox_set_items Sets new items list
lbox_update Updates list box

Hint: The presence of this call should be checked for using appl_getinfo (Opcode 7).

See also:
Calling procedure for modal dialogs   Style guidelines   WDIALOG

8.15.1 lbox_ascroll_to

Name: »List box scroll to, Slider A« - Set position of slider A of the list box.
 
Opcode: 175 (sub-opcode 4)
 
Syntax: void lbox_ascroll_to ( LIST_BOX *box, int16_t first, GRECT *box_rect, GRECT *slider_rect );
 
or
 
void lbox_scroll_to ( ... );
 
Description: The call lbox_ascroll_to positions slider A in a list box. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
first Index of the first visible entry
box_rect Pointer to redraw rectangle or 0L
slider_rect Pointer to redraw rectangle or 0L

Hint: This function works in principle like a call of lbox_set_slider followed by a lbox_update; scrolling takes place if possible, however, to reduce the amount of drawing required. One may therefore not use lbox_scroll_to if the item list of the list box has changed.
 
Return value: The function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_do   lbox_set_slider
 

8.15.1.1 Bindings for lbox_ascroll_to

C: void lbox_ascroll_to ( LIST_BOX *box, int16_t first, GRECT *box_rect, GRECT *slider_rect );
 
or
 
void lbox_scroll_to ( ... );
 
Binding:
 
void lbox_ascroll_to ( LIST_BOX *box, int16_t first,
                       GRECT *box_rect,
                       GRECT *slider_rect )

or

void lbox_scroll_to ( ... )
{
   addr_in[0] = box;
   addr_in[1] = box_rect;
   addr_in[2] = slider_rect;

   int_in[0] = 4;
   int_in[1] = first;
   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
addr_in+4 addr_in[1] box_rect
addr_in+8 addr_in[2] slider_rect
int_in int_in[0] 4 # Sub-opcode
int_in+2 int_in[1] first

8.15.2 lbox_bscroll_to

Name: »List box scroll to, Slider B« - Set position of slider B of the list box.
 
Opcode: 175 (sub-opcode 7)
 
Syntax: void lbox_bscroll_to ( LIST_BOX *box, int16_t first, GRECT *box_rect, GRECT *slider_rect );
 
Description: The call lbox_bscroll_to positions slider B of a list box. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
first Index of the first visible entry
box_rect Pointer to redraw rectangle or 0L
slider_rect Pointer to redraw rectangle or 0L

Hint: The parameter box_rect is the redraw rectangle for the list box and slider_rect is the redraw rectangle for the slider.
 
The function works in principle like a call of lbox_set_bslider followed by a lbox_update; scrolling takes place if possible, however, to reduce the amount of drawing required. One may therefore not use lbox_scroll_to if the item list of the list box has changed.
 
Return value: The function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_get_slct_item
 

8.15.2.1 Bindings for lbox_bscroll_to

C: void lbox_bscroll_to ( LIST_BOX *box, int16_t first, GRECT *box_rect, GRECT *slider_rect );
 
Binding:
 
void lbox_bscroll_to ( LIST_BOX *box, int16_t first,
                       GRECT *box_rect,
                       GRECT *slider_rect )
{
   addr_in[0] = box;
   addr_in[1] = box_rect;
   addr_in[2] = slider_rect;

   int_in[0] = 7;
   int_in[0] = first;
   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
addr_in+4 addr_in[1] box_rect
addr_in+8 addr_in[2] slider_rect
int_in int_in[0] 7 # Sub-opcode
int_in+2 int_in[1] first

8.15.3 lbox_cnt_items

Name: »List box count items« - Obtain the number of list items.
 
Opcode: 174 (Sub-opcode 0)
 
Syntax: int16_t lbox_cnt_items ( LIST_BOX *box );
 
Description: The call lbox_cnt_items counts the items of the chained list in the list box.
 

Parameter Meaning
box Pointer to the list box structure
Return value: Number of the items in the list
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_get_slct_item
 

8.15.3.1 Bindings for lbox_cnt_items

C: int16_t lbox_cnt_items ( LIST_BOX *box );
 
Binding:
 
int16_t lbox_cnt_items ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 0;
   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 0 # Sub-opcode
int_out int_out[0] Return value

8.15.4 lbox_create

Name: »List Box Create« - Create a list box
 
Opcode: 170
 
Syntax: LIST_BOX *lbox_create ( OBJECT *tree, SLCT_ITEM slct, SET_ITEM set, LBOX_ITEM *items, int16_t visible_a, int16_t first_a, int16_t *ctrl_objs, int16_t *objs, int16_t flags, int16_t pause_a, void *user_data, DIALOG *dialog, int16_t visible_b, int16_t first_b, int16_t entries_b, int16_t pause_b );
 
Description: The function lbox_create allocates memory for a list box and initializes the objects.
 
Parameter Meaning
   
tree Pointer to the object tree of the dialog
slct Pointer to selection routine
set Pointer to set routine
items Pointer to linked list with LBOX_ITEMs or NULL
visible_a Number of visible entries (Slider A)
first_a Index of the first visible entry (Slider A)
ctrl_objs Pointer to a field with the object indices of the buttons and slider (5 entries)
ctrl_objs[0] = Object index of the BOX or IBOX, that contains the actual list box object
ctrl_objs[1] = Object index of the buttons for scrolling upwards or left
ctrl_objs[2] = Object index of the buttons for scrolling downwards or right
ctrl_objs[3] = Object index of the slider background box
ctrl_objs[4] = Object index of the slider box


If the list box has 2 sliders, ctrl_objs[5-8] contain the numbers of the objects for Slider B:
ctrl_objs[5] = Object index of the button for scrolling upwards or left
ctrl_objs[6] = Object index of the button for scrolling downwards or right
ctrl_objs[7] = Object index of the slider background box
ctrl_objs[8] = Object index of the slider box
objs Pointer to a field with the object indices of the list box items (entries).
objs[0] = Number of the first object
objs[entries-1] = Number of the last object

The objects should normally have TOUCHEXIT status.
flags Various flags
pause_a Delay during scrolling in ms (Slider A)
user_data Pointer for application
dialog Pointer to the window dialog structure or 0L
visible_b Number of visible items (Slider B)
first_b First visible item (Slider B)
entries_b Number of items (Slider B)
pause_b Delay during scrolling in ms (Slider B)

Note: The initialization is performed by calling the routine set for each of the objects specified in objs. Calling this function does not draw the list box.
 
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.
 
Independent of the main scroll direction, the list box can have a second slider as well if the entries themselves should also be scrolled sideways; this can be sensible for a vertical list box with text entries that are wider than the box itself, for instance.
 
Both slct and set are functions whose parameters are passed on the stack. The functions may alter registers d0-d2/a0-a2.
 
slct is always called whenever an entry is selected or deselected. The variable selected in the LBOX_ITEM structure already contains the new status of the object when slct is called.
 
Return value: The function returns a pointer to the structure of the list box (or the value NULL in case of error).
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_delete   lbox_do
 

8.15.4.1 Bindings for lbox_create

C: LIST_BOX *lbox_create ( OBJECT *tree, SLCT_ITEM slct, SET_ITEM set, LBOX_ITEM *items, int16_t visible_a, int16_t first_a, int16_t *ctrl_objs, int16_t *objs, int16_t flags, int16_t pause_a, void *user_data, DIALOG *dialog, int16_t visible_b, int16_t first_b, int16_t entries_b, int16_t pause_b );
 
Binding:
 
LIST_BOX *lbox_create ( OBJECT *tree, SLCT_ITEM slct,
                        SET_ITEM set,
                        LBOX_ITEM *items, int16_t visible_a,
                        int16_t first_a, int16_t *ctrl_objs,
                        int16_t *objs, int16_t flags,
                        int16_t pause_a, void *user_data,
                        DIALOG *dialog, int16_t visible_b,
                        int16_t first_b, int16_t entries_b,
                        int16_t pause_b )
{
   addr_in[0] = tree;
   addr_in[1] = slct;
   addr_in[2] = set;
   addr_in[3] = items;
   addr_in[4] = ctrl_objs;
   addr_in[5] = objs;
   addr_in[6] = user_data;
   addr_in[7] = dialog;

   int_in[0]  = visible_a;
   int_in[1]  = first_a;
   int_in[2]  = flags;
   int_in[3]  = pause_a;

   int_in[4]  = visible_b;
   int_in[5]  = first_b;
   int_in[6]  = entries_b;
   int_in[7]  = pause_b;

   crys_if (170);

   return ( addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 170 # Function opcode
control+2 control[1] 4/8 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 8 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] tree
addr_in+4 addr_in[1] slct
addr_in+8 addr_in[2] set
addr_in+12 addr_in[3] items
addr_in+16 addr_in[4] ctrl_objs
addr_in+20 addr_in[5] objs
addr_in+24 addr_in[6] user_data
addr_in+28 addr_in[7] dialog
int_in int_in[0] visible_a
int_in+2 int_in[1] first_a
int_in+4 int_in[2] flags
int_in+6 int_in[3] pause_a
int_in+8 int_in[4] visible_b
int_in+10 int_in[5] first_b
int_in+12 int_in[6] entries_b
int_in+14 int_in[7] pause_b
addr_out addr_out[0] Return value

8.15.5 lbox_delete

Name: »List box delete« - Release memory allocated for a list box.
 
Opcode: 173
 
Syntax: int16_t lbox_delete ( LIST_BOX *box );
 
Description: The call lbox_delete releases the memory allocated for the list box.
 

Parameter Meaning
box Pointer to the list box structure
Return value: Always 1
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_create   lbox_do
 

8.15.5.1 Bindings for lbox_delete

C: int16_t lbox_delete ( LIST_BOX *box );
 
Binding:
 
int16_t lbox_delete ( LIST_BOX *box )
{
   addr_in[0] = box;
   crys_if (173);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 173 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_out int_out[0] Return value

8.15.6 lbox_do

Name: »List box do« - Process button of a list box.
 
Opcode: 172
 
Syntax: int16_t lbox_do ( LIST_BOX *box, int16_t obj );
 
Description: The call lbox_do reacts to the operation of a button of a list box. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
obj Index of the selected object

Hint: The function should be called after form_do (or by the service function of the window dialog). Double-clicks (see below) are recognized by the function by a set top bit (obj | 0x8000) of the object index. In the returned object index the top bit is cleared in all cases.
 
Return value: The function returns the index of the selected object (or the value -1 if a double-click was made on an entry). In the latter case the dialog should be closed and the action seen as a click on the OK button.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_delete   lbox_create
 

8.15.6.1 Bindings for lbox_do

C: int16_t lbox_do ( LIST_BOX *box, int16_t obj );
 
Binding:
 
int16_t lbox_do ( LIST_BOX *box, int16_t obj )
{
   addr_in[0] = box;
   int_in[0]  = obj;
   crys_if (172);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 172 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] obj
int_out int_out[0] Return value

8.15.7 lbox_free_items

Name: »List box free items« - Release items list.
 
Opcode: 175 (sub-opcode 2)
 
Syntax: void lbox_free_items ( LIST_BOX *box );
 
Description: The call lbox_free_items frees the memory used for the chained list from LBOX_ITEM. The following applies:
 

Parameter Meaning
box Pointer to the list box structure

Hint: A prerequisite for this is that memory was allocated with Malloc for each item of the list.
 
If custom memory management was used for LBOX_ITEM (e.g. the C standard functions), then a custom function must also be called to free the memory.
 
Return value: The function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_list   lbox_delete
 

8.15.7.1 Bindings for lbox_free_items

C: void lbox_free_items ( LIST_BOX *box );
 
Binding:
 
void lbox_free_items ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 2;

   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 2 # Sub-opcode

8.15.8 lbox_free_list

Name: »List box free item list« - Release items list.
 
Opcode: 175 (sub-opcode 3)
 
Syntax: void lbox_free_list ( LBOX_ITEM *items );
 
Description: The call lbox_free_list releases the memory used for the items of the list box. The following applies:
 

Parameter Meaning
items Pointer to linked list with LBOX_ITEM

Hint: This functions works exactly the same as lbox_free_items. In contrast to that however lbox_free_list is called with the pointer on the first LBOX_ITEM of the list.
 
Return value: The function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_delete
 

8.15.8.1 Bindings for lbox_free_list

C: void lbox_free_list ( LBOX_ITEM *items );
 
Binding:
 
void lbox_free_list ( LBOX_ITEM *items )
{
   addr_in[0] = items;
   int_in[0]  = 3;

   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] items
int_in int_in[0] 3 # Sub-opcode

8.15.9 lbox_get_afirst

Name: »List box get first visible item, Slider A« - Obtain index of first visible item (slider A).
 
Opcode: 174 (sub-opcode 4)
 
Syntax: int16_t lbox_get_afirst ( LIST_BOX *box );
 
Description: The call lbox_get_afirst obtains the index of the first visible item of the list box for slider A. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: The function returns the index of the first visible item for slider A.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_idx   lbox_get_item
 

8.15.9.1 Bindings for lbox_get_afirst

C: int16_t lbox_get_afirst ( LIST_BOX *box );
 
or
 
int16_t lbox_get_first ( ... );
 
Binding:
 
int16_t lbox_get_afirst ( LIST_BOX *box )

(!I)or(!i)

int16_t lbox_get_first  ( ... )
{
   addr_in[0] = box;
   int_in[0]  = 4;
   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 4 # Sub-opcode
int_out int_out[0] Return value

8.15.10 lbox_get_avis

Name: »List box get number of visible items, Slider A« - Obtain number of visible items (slider A).
 
Opcode: 174 (sub-opcode 2)
 
Syntax: int16_t lbox_get_avis ( LIST_BOX *box );
 
Description: The call lbox_get_avis obtains the number of visible items of a list box for slider A. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: The function returns the number of visible items for slider A.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_tree   lbox_get_first
 

8.15.10.1 Bindings for lbox_get_avis

C: int16_t lbox_get_avis ( LIST_BOX *box );
 
or
 
int16_t lbox_get_visible ( ... );
 
Binding:
 
int16_t lbox_get_avis ( LIST_BOX *box )

(!I)or(!i)

int16_t lbox_get_visible ( ... )
{
   addr_in[0] = box;
   int_in[0]  = 2;
   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 2 # Sub-opcode
int_out int_out[0] Return value

8.15.11 lbox_get_bentries

Name: »List box get number of entries, Slider B« - Obtain number of entries (slider B).
 
Opcode: 174 (sub-opcode 11)
 
Syntax: int16_t lbox_get_bentries ( LIST_BOX *box );
 
Description: The call lbox_get_bentries returns the number of entries in the list for slider B. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: This function returns the number of items for slider B.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_delete
 

8.15.11.1 Bindings for lbox_get_bentries

C: int16_t lbox_get_bentries ( LIST_BOX *box );
 
Binding:
 
int16_t lbox_get_bentries ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 11;

   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 11 # Sub-opcode
int_out int_out[0] Return value

8.15.12 lbox_get_bfirst

Name: »List box get first visible item, Slider B« - Obtain index of first visible item (slider B).
 
Opcode: 174 (sub-opcode 12)
 
Syntax: int16_t lbox_get_bfirst ( LIST_BOX *box );
 
Description: The call lbox_get_bfirst obtains the index of the first visible item of a list box for slider B. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: This function returns the index of the first visible item for slider B.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_delete
 

8.15.12.1 Bindings for lbox_get_bfirst

C: int16_t lbox_get_bfirst ( LIST_BOX *box );
 
Binding:
 
int16_t lbox_get_bfirst ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 12;

   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 12 # Sub-opcode
int_out int_out[0] Return value

8.15.13 lbox_get_bvis

Name: »List box get number of visible items, Slider B« - Obtain number of visible items (slider B).
 
Opcode: 174 (sub-opcode 10)
 
Syntax: int16_t lbox_get_bvis ( LIST_BOX *box );
 
Description: The call lbox_get_bvis obtains the number of visible items of a list box for slider B. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: This function returns the number of visible items for slider B.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_delete
 

8.15.13.1 Bindings for lbox_get_bvis

C: int16_t lbox_get_bvis ( LIST_BOX *box );
 
Binding:
 
int16_t lbox_get_bvis ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 10;

   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 10 # Sub-opcode
int_out int_out[0] Return value

8.15.14 lbox_get_idx

Name: »»List box get item index« - Obtain index of an item.
 
Opcode: 174 (sub-opcode 9)
 
Syntax: int16_t lbox_get_idx ( LBOX_ITEM *items, LBOX_ITEM *search );
 
Description: The call lbox_get_idx returns the index of a given item of the list box. The following apply:
 

Parameter Meaning
items Pointer to the first item of the list
search Pointer to the item to be found
Return value: This function returns the index of the item. If the item is not an element of the list, the return value is -1.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_item   lbox_get_first
 

8.15.14.1 Bindings for lbox_get_idx

C: int16_t lbox_get_idx ( LBOX_ITEM *items, LBOX_ITEM *search );
 
Binding:
 
int16_t lbox_get_idx ( LBOX_ITEM *items, LBOX_ITEM *search )
{
   addr_in[0] = items;
   addr_in[1] = search;
   int_in[0]  = 9;
   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] items
addr_in+4 addr_in[1] search
int_in int_in[0] 9 # Sub-opcode
int_out int_out[0] Return value

8.15.15 lbox_get_item

Name: »List box get item« - Return pointer to n-th item.
 
Opcode: 174 (sub-opcode 7)
 
Syntax: LBOX_ITEM *lbox_get_item ( LIST_BOX *box, int16_t n );
 
Description: The call lbox_get_item returns a pointer to the n-th item of the list box. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
n Index of the items
Return value: The function returns the pointer to item n, or NULL if this is not found.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_first   lbox_get_idx
 

8.15.15.1 Bindings for lbox_get_item

C: LBOX_ITEM *lbox_get_item ( LIST_BOX *box, int16_t n );
 
Binding:
 
LBOX_ITEM *lbox_get_item ( LIST_BOX *box, int16_t n )
{
   addr_in[0] = box;
   int_in[0]  = 7;
   int_in[1]  = n;
   crys_if (174);

   return ( addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 7 # Sub-opcode
int_in+2 int_in[1] n
addr_out addr_out[0] Return value

8.15.16 lbox_get_items

Name: »List box get items« - Return pointer to the first item.
 
Opcode: 174 (sub-opcode 6)
 
Syntax: LBOX_ITEM *lbox_get_items ( LIST_BOX *box );
 
Description: The call lbox_get_items returns a pointer to the first item of the list box. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: The function returns the pointer to the chained list.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_first   lbox_get_idx
 

8.15.16.1 Bindings for lbox_get_items

C: LBOX_ITEM *lbox_get_items ( LIST_BOX *box );
 
Binding:
 
LBOX_ITEM *lbox_get_items ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 6;
   crys_if (174);

   return ( addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 6 # Sub-opcode
addr_out addr_out[0] Return value

8.15.17 lbox_get_slct_idx

Name: »List box get index of selected item« - Obtain index of the first selected item.
 
Opcode: 174 (sub-opcode 5)
 
Syntax: int16_t lbox_get_slct_idx ( LIST_BOX *box );
 
Description: The call lbox_get_slct_idx returns the index of the first selected item of the list box. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: The function returns the index of the selected item. If no item in the list is selected then -1 will be returned.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_slct_item
 

8.15.17.1 Bindings for lbox_get_slct_idx

C: int16_t lbox_get_slct_idx ( LIST_BOX *box );
 
Binding:
 
int16_t lbox_get_slct_idx ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 5;
   crys_if (174);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 5 # Sub-opcode
int_out int_out[0] Return value

8.15.18 lbox_get_slct_item

Name: »List box get selected item« - Return pointer to first selected item.
 
Opcode: 174 (sub-opcode 8)
 
Syntax: LBOX_ITEM *lbox_get_slct_item ( LIST_BOX *box );
 
Description: The call lbox_get_slct_item obtains a pointer to the first selected item of a list box. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: The function returns the pointer to the first selected item, or NULL if none is selected.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_slct_idx
 

8.15.18.1 Bindings for lbox_get_slct_item

C: LBOX_ITEM *lbox_get_slct_item ( LIST_BOX *box );
 
Binding:
 
LBOX_ITEM *lbox_get_slct_item ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 8;
   crys_if (174);

   return ( addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 8 # Sub-opcode
addr_out addr_out[0] Return value

8.15.19 lbox_get_tree

Name: »List box get tree« - Obtain object tree of the list box dialog.
 
Opcode: 174 (sub-opcode 1)
 
Syntax: OBJECT *lbox_get_tree ( LIST_BOX *box );
 
Description: The call lbox_get_tree obtains a pointer to the object tree of the list box dialog. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: The function returns a pointer to the object tree of the list box dialog.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_udata   lbox_get_first
 

8.15.19.1 Bindings for lbox_get_tree

C: OBJECT *lbox_get_tree ( LIST_BOX *box );
 
Binding:
 
OBJECT *lbox_get_tree ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 1;
   crys_if (174);

   return ( addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 1 # Sub-opcode
addr_out addr_out[0] Return value

8.15.20 lbox_get_udata

Name: »List box get user data« - Get pointer to program-specific data.
 
Opcode: 174 (sub-opcode 3)
 
Syntax: void *lbox_get_udata ( LIST_BOX *box );
 
Description: The call lbox_get_udata obtains a pointer to the program-specific data. The following applies:
 

Parameter Meaning
box Pointer to the list box structure
Return value: The function returns the pointer <user_data>.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_get_tree   lbox_get_first
 

8.15.20.1 Bindings for lbox_get_udata

C: void *lbox_get_udata ( LIST_BOX *box );
 
Binding:
 
void *lbox_get_udata ( LIST_BOX *box )
{
   addr_in[0] = box;
   int_in[0]  = 3;
   crys_if (174);

   return ( addr_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 174 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 1 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 3 # Sub-opcode
addr_out addr_out[0] Return value

8.15.21 lbox_set_asldr

Name: »List box set Slider A« - Set position of slider A of a list box.
 
Opcode: 175 (sub-opcode 0)
 
Syntax: void lbox_set_asldr ( LIST_BOX *box, int16_t first, GRECT *rect );
 
or
 
void lbox_set_slider ( LIST_BOX *box, int16_t first, GRECT *rect );
 
Description: The call lbox_set_asldr positions the slider A of a list box. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
first Index of the first visible entry
rect Pointer to redraw rectangle, or 0L

Hint: The contents of the list box will not be updated, so one may have to call lbox_update. If rect is 0L, then only the position of the slider objects will be altered, but the objects will not be drawn.
 
Return value: The function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_scroll_to
 

8.15.21.1 Bindings for lbox_set_asldr

C: void lbox_set_asldr ( LIST_BOX *box, int16_t first, GRECT *rect );
 
or
 
void lbox_set_slider ( ... );
 
Binding:
 
void lbox_set_asldr ( LIST_BOX *box, int16_t first,
                      GRECT *rect )

(!I)or(!i)

void lbox_set_slider ( ... )
{
   addr_in[0] = box;
   addr_in[1] = rect;

   int_in[0] = 0;
   int_in[1] = first;
   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
addr_in+4 addr_in[1] rect
int_in int_in[0] 0 # Sub-opcode
int_in+2 int_in[1] first

8.15.22 lbox_set_bentries

Name: »List box set number of entries, Slider B« - Set number of entries for slider B.
 
Opcode: 175 (Sub-opcode 6)
 
Syntax: void lbox_set_bentries ( LIST_BOX *box, int16_t entries );
 
Description: The call lbox_set_bentries sets the number of entries (or subdivisions) for slider B of a list box. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
entries Number of items
Return value: The function does not return a result.k.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_cnt_items
 

8.15.22.1 Bindings for lbox_set_bentries

C: void lbox_set_bentries ( LIST_BOX *box, int16_t entries );
 
Binding:
 
void lbox_set_bentries ( LIST_BOX *box, int16_t entries )
{
   addr_in[0] = box;

   int_in[0] = 6;
   int_in[1] = entries;
   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
int_in int_in[0] 6 # Sub-opcode
int_in+2 int_in[1] entries

8.15.23 lbox_set_bsldr

Name: »List box set slider B« - Set position of slider B of a list box.
 
Opcode: 175 (sub-opcode 5)
 
Syntax: void lbox_set_bsldr ( LIST_BOX *box, int16_t first, GRECT *rect );
 
Description: The call lbox_set_bsldr positions the slider B of a list box. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
first Index of the first visible entry
rect Pointer to redraw rectangle, or 0L

Hint: This function draws the slider within the redraw rectangle rect. The contents of the list box will not be updated, so one may have to call lbox_update. If rect is 0L, then only the position of the slider objects will be altered, but the objects will not be drawn.
 
Return value: The function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_cnt_items
 

8.15.23.1 Bindings for lbox_set_bsldr

C: void lbox_set_bsldr ( LIST_BOX *box, int16_t first, GRECT *rect );
 
Binding:
 
void lbox_set_bsldr ( LIST_BOX *box, int16_t first,
                      GRECT *rect )
{
   addr_in[0] = box;
   addr_in[1] = rect;

   int_in[0] = 5;
   int_in[1] = first;
   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
addr_in+4 addr_in[1] rect
int_in int_in[0] 5 # Sub-opcode
int_in+2 int_in[1] first

8.15.24 lbox_set_items

Name: »List box set new item list« - Sets new items list for the list box.
 
Opcode: 175 (sub-opcode 1)
 
Syntax: void lbox_set_items ( LIST_BOX *box, LBOX_ITEM *items );
 
Description: The call lbox_set_items sets a new list with list box items. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
items Pointer to the new list of items, or NULL

Hint: The old list must first be freed with lbox_free_items. The pointer items can also be 0L if the list box is empty and contains no entries.
 
Return value: This function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_free_items   lbox_cnt_items
 

8.15.24.1 Bindings for lbox_set_items

C: void lbox_set_items ( LIST_BOX *box, LBOX_ITEM *items );
 
Binding:
 
void lbox_set_items ( LIST_BOX *box, LBOX_ITEM *items )
{
   addr_in[0] = box;
   addr_in[1] = items;

   int_in[0]  = 1;
   crys_if (175);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 175 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
addr_in+4 addr_in[1] items
int_in int_in[0] 1 # Sub-opcode

8.15.25 lbox_update

Name: »List box update« - Update contents of list box objects.
 
Opcode: 171
 
Syntax: void lbox_update ( LIST_BOX *box, GRECT *rect );
 
Description: The call lbox_update brings the contents of the list box objects to the current state. The following apply:
 

Parameter Meaning
box Pointer to the list box structure
rect Pointer to the redraw GRECT, or 0L

Hint: The updating is sequentiat, i.e. the function set (see above) is called for each of the objects. If rect is not 0L it will be regarded as a pointer to a GRECT that will be used for the redraw of the list box. Otherwise the objects will only be updated but not drawn.
 
Return value: The function does not return a result.
 
Availability: The presence of this call should be checked for using appl_getinfo (Opcode 7).
 
Group: List boxes
 
See also: Binding   lbox_do   lbox_scroll_to
 

8.15.25.1 Bindings for lbox_update

C: void lbox_update ( LIST_BOX *box, GRECT *rect );
 
Binding:
 
void lbox_update ( LIST_BOX *box, GRECT *rect )
{
   addr_in[0] = box;
   addr_in[1] = rect;

   crys_if (171);
}
GEM-Arrays:
 

Address Element Contents
control control[0] 171 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] box
addr_in+4 addr_in[1] rect

8.15.26 Calling procedure for modal dialogs

wind_update() Lock screen
lbox_create() Create list box
form_center() Centre dialog
form_dial() Buffer screen portion
.  
Loop: form_do()
lbox_do()

End of loop, possibly. lbox_get_slct_item()...

.  
form_dial() Send redraw message
wind_update() Release screen
lbox_delete() Release memory for list box

8.15.27 Flags for the behaviour of the list box

Bit
State Description
 
0
0 The box scrolls horizontally
1 The box scrolls vertically
1
0 No automatic scrolling
1 Scrolling takes place automatically as soon as the mouse cursor is moved past the first or last item with the mouse button held down
2
0 The selection routine will be called only after the automatic scrolling has finished, i.e. it will be called for the last selected entry.
1 With automatic scrolling the selection routine will be called for each selected entry during scrolling
3
0 When moving the slider a frame will be moved (graf_slidebox), the list box will only be updated after releasing the mouse button
1 The slider is a real-time slider
4
0 Multiple selections within the list box are possible
1 Only one item can be selected
5
0 Multiple selections possible without the [Shift] key
1 Multiple selections only possible with the [Shift] key
6
0 On selection the status is always SELECTED
1 On selection the status is always changed
7
0 The list box has only one slider
1 The list box has two sliders
#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.

See also: List boxes   lbox_create


Home AESAES Scrap libraryScrap library MagiC libraryMagiC library