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

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

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

8.15.2.1 Bindings for lbox_bscroll_to

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

8.15.3.1 Bindings for lbox_cnt_items

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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	The box scrolls horizontally
1	The box scrolls vertically

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

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

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

0	Multiple selections within the list box are possible
1	Only one item can be selected

0	Multiple selections possible without the [Shift] key
1	Multiple selections only possible with the [Shift] key

0	On selection the status is always SELECTED
1	On selection the status is always changed

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.