Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

MagiC/WDIALOG extension: List Box Library
[AES Function Reference]

list box functions More...

Data Structures

struct  lbox_item
struct  SLCT_ITEM_args
struct  SET_ITEM_args

Defines

#define LBOX_VERT   1
#define LBOX_AUTO   2
#define LBOX_AUTOSLCT   4
#define LBOX_REAL   8
#define LBOX_SNGL   16
#define LBOX_SHFT   32
#define LBOX_TOGGLE   64
#define LBOX_2SLDRS   128
#define mt_lbox_get_avis   mt_lbox_get_visible
#define mt_lbox_get_first   mt_lbox_get_afirst
#define mt_lbox_set_slider   mt_lbox_set_asldr
#define mt_lbox_scroll_to   mt_lbox_ascroll_to

Typedefs

typedef void * LIST_BOX
typedef lbox_item LBOX_ITEM
typedef void __CDECL(* SLCT_ITEM )(struct SLCT_ITEM_args)
typedef short __CDECL(* SET_ITEM )(struct SET_ITEM_args)

Functions

LIST_BOXmt_lbox_create (OBJECT *tree, SLCT_ITEM slct, SET_ITEM set, LBOX_ITEM *items, short visible_a, short first_a, short *ctrl_objs, short *objs, short flags, short pause_a, void *user_data, void *dialog, short visible_b, short first_b, short entries_b, short pause_b, short *global)
void mt_lbox_update (LIST_BOX *box, GRECT *rect, short *global)
short mt_lbox_do (LIST_BOX *box, short obj, short *global)
short mt_lbox_delete (LIST_BOX *box, short *global)
short mt_lbox_cnt_items (LIST_BOX *box, short *global)
OBJECTmt_lbox_get_tree (LIST_BOX *box, short *global)
short mt_lbox_get_visible (LIST_BOX *box, short *global)
void * mt_lbox_get_udata (LIST_BOX *box, short *global)
short mt_lbox_get_afirst (LIST_BOX *box, short *global)
short mt_lbox_get_slct_idx (LIST_BOX *box, short *global)
LBOX_ITEMmt_lbox_get_items (LIST_BOX *box, short *global)
LBOX_ITEMmt_lbox_get_item (LIST_BOX *box, short n, short *global)
LBOX_ITEMmt_lbox_get_slct_item (LIST_BOX *box, short *global)
short mt_lbox_get_idx (LBOX_ITEM *items, LBOX_ITEM *search, short *global)
short mt_lbox_get_bvis (LIST_BOX *box, short *global)
short mt_lbox_get_bentries (LIST_BOX *box, short *global)
short mt_lbox_get_bfirst (LIST_BOX *box, short *global)
void mt_lbox_set_asldr (LIST_BOX *box, short first, GRECT *rect, short *global)
void mt_lbox_set_items (LIST_BOX *box, LBOX_ITEM *items, short *global)
void mt_lbox_free_items (LIST_BOX *box, short *global)
void mt_lbox_free_list (LBOX_ITEM *items, short *global)
void mt_lbox_ascroll_to (LIST_BOX *box, short first, GRECT *box_rect, GRECT *slider_rect, short *global)
void mt_lbox_set_bsldr (LIST_BOX *box, short first, GRECT *rect, short *global)
void mt_lbox_set_bentries (LIST_BOX *box, short entries, short *global)
void mt_lbox_bscroll_to (LIST_BOX *box, short first, GRECT *box_rect, GRECT *slider_rect, short *global)

Detailed Description

list box functions

This List Box library availability can be found calling mt_appl_getinfo(7). Bit 1 of ap_gout1, if equal to 1, says that mt_lbox_xx() functions are available.


Define Documentation

#define LBOX_2SLDRS   128
 

Listbox has a horiz. and a 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_SHFT   32
 

Multi-selection with Shift

#define LBOX_SNGL   16
 

Only a selectable entry

#define LBOX_TOGGLE   64
 

Toggle status of an entry at selection

#define LBOX_VERT   1
 

Listbox with vertical slider

#define mt_lbox_get_avis   mt_lbox_get_visible
 

another name for mt_lbox_get_avis

#define mt_lbox_get_first   mt_lbox_get_afirst
 

another name for mt_lbox_get_first

#define mt_lbox_scroll_to   mt_lbox_ascroll_to
 

another name for mt_lbox_scroll_to

#define mt_lbox_set_slider   mt_lbox_set_asldr
 

another name for mt_lbox_set_slider


Typedef Documentation

typedef struct lbox_item LBOX_ITEM
 

TODO

typedef void* LIST_BOX
 

opaque structure

typedef short __CDECL(* SET_ITEM)(struct SET_ITEM_args)
 

TODO

typedef void __CDECL(* SLCT_ITEM)(struct SLCT_ITEM_args)
 

TODO


Function Documentation

void mt_lbox_ascroll_to LIST_BOX box,
short  first,
GRECT box_rect,
GRECT slider_rect,
short global_aes
 

This function positions Slider A and updates the contents of the list box

Parameters:
box Pointer to the list box structure
first Index of the first visible entry
box_rect is the redraw rectangle for the list box, or NULL
slider_rect is the redraw rectangle for the slider, or NULL
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
mt_lbox_ascroll_to() works in principle like a call of mt_lbox_set_slider() followed by a mt_lbox_update(); scrolling takes place if possible, however, to reduce the amount of drawing required. One may therefore not use mt_lbox_scroll_to() if the item list of the list box has changed.

void mt_lbox_bscroll_to LIST_BOX box,
short  first,
GRECT box_rect,
GRECT slider_rect,
short global_aes
 

This function positions Slider B and updates the contents of the list box

Parameters:
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
global_aes global AES array
Returns:
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This function positions Slider B and updates the contents of the list box. box_rect is the redraw rectangle for the list box and slider_rect is the redraw rectangle for the slider.

mt_lbox_bscroll_to() works in principle like a call of mt_lbox_set_bslider() followed by a mt_lbox_update(); scrolling takes place if possible, however, to reduce the amount of drawing required. One may therefore not use mt_lbox_scroll_to() if the item list of the list box has changed.

short mt_lbox_cnt_items LIST_BOX box,
short global_aes
 

counts the items of the chained list

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Number of the items in the list
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

LIST_BOX* mt_lbox_create OBJECT tree,
SLCT_ITEM  slct,
SET_ITEM  set,
LBOX_ITEM items,
short  visible_a,
short  first_a,
short ctrl_objs,
short objs,
short  flags,
short  pause_a,
void *  user_data,
void *  dialog,
short  visible_b,
short  first_b,
short  entries_b,
short  pause_b,
short global_aes
 

list box - create

Parameters:
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. The pointer items can also be 0L if the list box is still empty and does not contain any entries.
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 numbers of the buttons and slider (5 entries)
objs Pointer to a field with the object numbers of the list box items (entries entries)
flags Various flags:
  • LBOX_VERT (1) List box with vertical slider
  • LBOX_AUTO (2) Auto scrolling
  • LBOX_AUTOSLCT (4) Automatic display during auto scrolling
  • LBOX_REAL (8) Real-time slider
  • LBOX_SNGL (16) Only one selectable entry
  • LBOX_SHFT (32) Multiple selections with Shift
  • LBOX_TOGGLE (64) On selection change status of an entry
  • 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.
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)
global_aes global AES array
Returns:
Pointer to the list box structure or 0L
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
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.

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 );
  • box points to the list box structure
  • tree points to the object tree of the dialog
  • item points to the LBOX_ITEM-structure of the selected entry
  • user_data is the pointer passed by mt_lbox_create()
  • obj_index is the number of the selected object. For a double-click the top bit is set, similar to mt_form_do(). If is 0 it signifies that no object is assigned to this entry; it is not visible. Normally this only the case when one is scrolling and by selecting a new object the (now no longer visible) selection has to be cleared.
  • last_state is the previous status of the object. can also have the same value as selected>. In that case one can normally quit the function immediately.

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 );
  • box points to the list box structure
  • tree points to the object tree of the dialog
  • item points to the LBOX_ITEM structure of the entry to be set
  • obj_index is the number of the object to be set
  • user_data is the pointer passed by mt_lbox_create()
  • rect is the pointer to the GRECT for the object redraw or 0L
  • first contains the number of the first visible item for Slider B

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 is 0L when a redraw of the dialog box is executed or when mt_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 mt_objc_draw()/mt_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 mt_objc_draw()/ mt_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 mt_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;
      WORD  selected;   
      WORD  data1;      
      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):

  • ctrl_objs[0]: Object number of the BOX or IBOX, that contains the actual list box object
  • ctrl_objs[1]: Object number of the buttons for scrolling upwards or left
  • ctrl_objs[2]: Object number of the buttons for scrolling downwards or right
  • ctrl_objs[3]: Object number of the slider background box
  • ctrl_objs[4]: Object number 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 number of the button for scrolling upwards or left
  • ctrl_objs[6]: Object number of the button for scrolling downwards or right
  • ctrl_objs[7]: Object number of the slider background box
  • ctrl_objs[8]: Object number of the slider 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.

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:

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

short mt_lbox_delete LIST_BOX box,
short global_aes
 

releases the memory allocated for the list box.

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
1
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

short mt_lbox_do LIST_BOX box,
short  obj,
short global_aes
 

reacts to the activation of a button

Parameters:
box Pointer to the list box structure
obj Number of the selected object
global_aes global AES array
Returns:
Number of the selected object or -1, if there was a double-click on an entry
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
mt_lbox_do() reacts to the activation of a button. This function should be called after mt_form_do() (or by the service function of the window dialog). If one of the entries of the list box was selected with a double-click, mt_lbox_do() returns -1. The dialog should then be closed as if the OK button had been activated.

mt_lbox_do() recognises double-clicks by the set topmost bit of the object number obj (object number | 0x8000). For the returned object number slct_obj the top bit is always cleared.

void mt_lbox_free_items LIST_BOX box,
short global_aes
 

frees the memory for the chained list from LBOX_ITEMs

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This function frees the memory for the chained list from LBOX_ITEMs. 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_ITEMs (e.g. the C standard functions), then a custom function must also be called to free the memory.

void mt_lbox_free_list LBOX_ITEM items,
short global_aes
 

This functions works exactly the same as mt_lbox_free_items().

Parameters:
items Pointer to linked list with LBOX_ITEMs
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This functions works exactly the same as mt_lbox_free_items(). In contrast to that however mt_lbox_free_list() is called with the pointer on the first LBOX_ITEM of the list.

short mt_lbox_get_afirst LIST_BOX box,
short global_aes
 

returns the index of the first visible item

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Index of the first visible item
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

short mt_lbox_get_bentries LIST_BOX box,
short global_aes
 

returns the number of items for Slider B.

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Number of items
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

short mt_lbox_get_bfirst LIST_BOX box,
short global_aes
 

returns the index of the first visible item (Slider B!).

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Index of the first visible item
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

short mt_lbox_get_bvis LIST_BOX box,
short global_aes
 

returns the number of visible entries, slider B.

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Number of visible entries
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

short mt_lbox_get_idx LBOX_ITEM items,
LBOX_ITEM search,
short global_aes
 

list box - get item index

Parameters:
items Pointer to the first item of the list
search Pointer to the item to be found
global_aes global AES array
Returns:
Index of the item or -1
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This function returns the index n of the item item. If item is not an element of the list, the return value is -1.

LBOX_ITEM* mt_lbox_get_item LIST_BOX box,
short  n,
short global_aes
 

returns a pointer to item n of the list

Parameters:
box Pointer to the list box structure
n Index des items
global_aes global AES array
Returns:
Pointer to item n or 0L
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

LBOX_ITEM* mt_lbox_get_items LIST_BOX box,
short global_aes
 

returns a pointer to the list of the LBOX_ITEMs

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Pointer to the chained list
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

short mt_lbox_get_slct_idx LIST_BOX box,
short global_aes
 

Establish the index of the first selected item

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Index of the selected item. If no item in the list is selected then -1 will be returned.
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

LBOX_ITEM* mt_lbox_get_slct_item LIST_BOX box,
short global_aes
 

returns a pointer to the first selected item of the list.

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Pointer to first selected item or 0L
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

OBJECT* mt_lbox_get_tree LIST_BOX box,
short global_aes
 

returns the pointer to the object tree of the dialog box

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Pointer to the object tree of the dialog
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

void* mt_lbox_get_udata LIST_BOX box,
short global_aes
 

returns the pointer user_data.

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
user_data
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

short mt_lbox_get_visible LIST_BOX box,
short global_aes
 

returns the number of visible items

Parameters:
box Pointer to the list box structure
global_aes global AES array
Returns:
Number of visible items
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

void mt_lbox_set_asldr LIST_BOX box,
short  first,
GRECT rect,
short global_aes
 

list box - set slider a

Parameters:
box Pointer to the list box structure
first Index of the first visible entry
rect Pointer to redraw rectangle or 0L
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This function positions Slider A and draws it within the redraw rectangle rect. The contents of the list box will not be updated, so one may have to call mt_lbox_update(). If rect is 0L, then only the position of the slider objects will be altered, but the objects will not be drawn.

void mt_lbox_set_bentries LIST_BOX box,
short  entries,
short global_aes
 

This Function sets the number of items (the subdivisions) for Slider B.

Parameters:
box Pointer to the list box structure
entries Number of items
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability

void mt_lbox_set_bsldr LIST_BOX box,
short  first,
GRECT rect,
short global_aes
 

This function positions Slider B and draws it within the redraw rectangle.

Parameters:
box Pointer to the list box structure
first Index of the first visible entry
rect Pointer to redraw rectangle or 0L
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This function positions Slider B and draws it within the redraw rectangle rect. The contents of the list box will not be updated, so one may have to call mt_lbox_update(). If rect is 0L, then only the position of the slider objects will be altered, but the objects will not be drawn.

void mt_lbox_set_items LIST_BOX box,
LBOX_ITEM items,
short global_aes
 

This function sets a new list with list box entries

Parameters:
box Pointer to the list box structure
items 
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This function sets a new list with list box entries. The old list must first be freed with mt_lbox_free_items().

The pointer items can also be 0L if the list box is empty and contains no entries.

void mt_lbox_update LIST_BOX box,
GRECT rect,
short global_aes
 

updates the contents of the list box objects

Parameters:
box Pointer to the list box structure
rect Pointer to the redraw GRECT or 0L
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_lbox_xx() functions availability
This function updates the contents of the list box objects, i.e. the function set 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.


Generated on Wed Nov 3 22:42:21 2004 for GEMLIB by  doxygen 1.3.9.1