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

MagiC extension: Window Dialog
[AES Function Reference]

AES extended dialog in window. More...

Data Structures

struct  HNDL_OBJ_args

Defines

#define WDLG_BKGD   1
#define HNDL_INIT   -1
#define HNDL_MESG   -2
#define HNDL_CLSD   -3
#define HNDL_OPEN   -5
#define HNDL_EDIT   -6
#define HNDL_EDDN   -7
#define HNDL_EDCH   -8
#define HNDL_MOVE   -9
#define HNDL_TOPW   -10
#define HNDL_UNTP   -11

Typedefs

typedef void * DIALOG
typedef short __CDECL(* HNDL_OBJ )(struct HNDL_OBJ_args)

Functions

DIALOGmt_wdlg_create (HNDL_OBJ handle_exit, OBJECT *tree, void *user_data, short code, void *data, short flags, short *global)
short mt_wdlg_open (DIALOG *dialog, char *title, short kind, short x, short y, short code, void *data, short *global)
short mt_wdlg_close (DIALOG *dialog, short *x, short *y, short *global)
short mt_wdlg_delete (DIALOG *dialog, short *global)
short mt_wdlg_get_tree (DIALOG *dialog, OBJECT **tree, GRECT *r, short *global)
short mt_wdlg_get_edit (DIALOG *dialog, short *cursor, short *global)
void * mt_wdlg_get_udata (DIALOG *dialog, short *global)
short mt_wdlg_get_handle (DIALOG *dialog, short *global)
short mt_wdlg_set_edit (DIALOG *dialog, short obj, short *global)
short mt_wdlg_set_tree (DIALOG *dialog, OBJECT *tree, short *global)
short mt_wdlg_set_size (DIALOG *dialog, GRECT *size, short *global)
short mt_wdlg_set_iconify (DIALOG *dialog, GRECT *g, char *title, OBJECT *tree, short obj, short *global)
short mt_wdlg_set_uniconify (DIALOG *dialog, GRECT *g, char *title, OBJECT *tree, short *global)
short mt_wdlg_evnt (DIALOG *dialog, EVNT *events, short *global)
void mt_wdlg_redraw (DIALOG *dialog, GRECT *rect, short obj, short depth, short *global)

Detailed Description

AES extended dialog in window.

TODO


Define Documentation

#define HNDL_CLSD   -3
 

Dialog window was closed

#define HNDL_EDCH   -8
 

Edit-field was changed

#define HNDL_EDDN   -7
 

Character was entered in edit-field

#define HNDL_EDIT   -6
 

Test characters for an edit-field

#define HNDL_INIT   -1
 

Initialise dialog

#define HNDL_MESG   -2
 

Initialise dialog

#define HNDL_MOVE   -9
 

Dialog was moved

#define HNDL_OPEN   -5
 

End of dialog initialisation (second call at end of wdlg_init)

#define HNDL_TOPW   -10
 

Dialog-window has been topped

#define HNDL_UNTP   -11
 

Dialog-window is not active

#define WDLG_BKGD   1
 

Permit background operation


Typedef Documentation

typedef void* DIALOG
 

an opaque structure. One should not access the structure directly. The mt_wdlg_xx functions should be used!

typedef short __CDECL(* HNDL_OBJ)(struct HNDL_OBJ_args)
 

service routine that is called, among others, by mt_wdlg_evnt().

This function may be called if an exit or touchexit object was clicked on (in that case obj is a positive object number) or when an event has occurred that affects the dialog (in that case obj is negative and contains a corresponding function number such as HNDL_CLSD, for instance).

If obj is an object number (>= 0), then events points to the EVNT structure that was passed by mt_wdlg_evnt(). Otherwise events is basically 0L and can not be used for addressing.

clicks contains then number of mouse clicks (if obj is an object number)

Here is a list of event (value given in the obj parameter):

  • HNDL_INIT (-1) :
    data is the variable passed by wdlg_create. If handle_exit() returns 0, mt_wdlg_create() does not create a dialog structure (error). The variable code is passed in clicks.
  • HNDL_OPEN (-5) :
    data is the variable passed by wdlg_open. The variable code is passed in clicks.
  • HNDL_CLSD (-3) :
    data is user_data. If handle_exit() returns 0, the dialog will be closed -- mt_wdlg_evnt() returns 0 events points to the EVNT structure passed by mt_wdlg_evnt().
  • HNDL_MOVE (-9) :
    data is user_data. If handle_exit() returns 0, the dialog will be closed -- mt_wdlg_evnt() returns 0. events points to the EVNT structure passed by mt_wdlg_evnt().
  • HNDL_TOPW (-10) :
    data is user_data. If handle_exit() returns 0, the dialog will be closed -- mt_wdlg_evnt() returns 0. events points to the EVNT structure passed by mt_wdlg_evnt().
  • HNDL_UNTP (-11) :
    data is user_data. If handle_exit() returns 0, the dialog will be closed -- mt_wdlg_evnt() returns 0. events points to the EVNT structure passed by mt_wdlg_evnt().
  • HNDL_EDIT (-6) :
    data points to a word with the key code. If handle_exit() returns 1, the key press will be evaluated, if 0 ignored. events points to the EVNT structure passed by mt_wdlg_evnt().
  • HNDL_EDDN (-7) :
    data points to a word with the key code. events points to the EVNT structure passed by mt_wdlg_evnt().
  • HNDL_EDCH (-8) :
    data points to a word with the object number of the new editable field.
  • HNDL_MESG (-2) :
    data is user_data. If handle_exit() returns 0, the dialog will be closed -- mt_wdlg_evnt() returns 0. events points to the EVNT structure passed by mt_wdlg_evnt().
    HNDL_MESG is only passed if a message code between 20 and 39 was received that is not handled by other opcodes. Is required for iconification, for instance.
    Warning: This opcode is only present from MagiC 4.5 of 18.4.96
Of these function numbers one only has to react to HNDL_CLSD. All other events need only be paid attention to when needed.
If handle_exit is called with an unknown function number in obj, or one of the above function numbers is to be ignored, then 1 has to be returned.

The parameters are passed via the stack and the routine may alter registers d0-d2/a0-a2.


Function Documentation

short mt_wdlg_close DIALOG dialog,
short x,
short y,
short global_aes
 

closes the window dialog

Parameters:
dialog Pointer to the dialog structure
x Last x-coordinate of the dialog
x may be NULL
y Last y-coordinate of the dialog
y may be NULL
global_aes global AES array
Returns:
1
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability
Note:
: Old WDIALOG versions do not return the window coordinates. In that case the binding enters -1, so that the dialog will be centred automatically at the next call.

DIALOG* mt_wdlg_create HNDL_OBJ  handle_exit,
OBJECT tree,
void *  user_data,
short  code,
void *  data,
short  flags,
short global_aes
 

allocates memory for a dialog structure and initialises it.

Parameters:
handle_exit Pointer to the service function
tree Pointer to the object tree
user_data Pointer to user info
code Is passed to handle_exit() as clicks parameter
data Is passed to handle_exit() as data parameter
flags 
global_aes global AES array
Returns:
Pointer to the dialog structure
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability
Note:
WDIALOG versions below 1.06 have an error in the edit object handling, which can lead to a crash with object trees with only one object (ROOT). If you absolutely want to display an empty window dialog, make sure that the tree is made up of at least two objects.

short mt_wdlg_delete DIALOG dialog,
short global_aes
 

releases the memory allocated for a window dialog

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

short mt_wdlg_evnt DIALOG dialog,
EVNT events,
short global_aes
 

This function must be called in an event-loop

Parameters:
dialog Pointer to the dialog structure
events Pointer to the EVNT-structure
global_aes global AES array
Returns:
continue: 0 (Close dialog) or 1 (All OK)
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability
The event-bits that refer to the window dialog are cleared in the bit vector mwhich. Following mt_wdlg_evnt() the EVNT-structure of the application can be used to evaluate the events intended for it. If mt_wdlg_evnt() returns a 0, the window dialog has to be closed (call mt_wdlg_close()).

Note: The Iconify-event is not supported by mt_wdlg_evnt(). Those wanting to install the Iconifier icon as a window object during mt_wdlg_open() therefore have to evaluate this even and handle it themselves. The same applies if one want to install the Sizer icon as an object.

short mt_wdlg_get_edit DIALOG dialog,
short cursor,
short global_aes
 

returns the number of the current edit object. If the result is 0, then no edit object is active at the present time.

Parameters:
dialog Pointer to the dialog structure
cursor Index of the character
[option CHECK_NULLPTR] cursor may be NULL
global_aes global AES array
Returns:
Number of the current edit object (or 0, if none is active)
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability
Note:
With old WDIALOG versions cursor is not returned. The binding ensures that -1 is entered in this case.

short mt_wdlg_get_handle DIALOG dialog,
short global_aes
 

returns the handle of the dialog window

Parameters:
dialog Pointer to the dialog structure
global_aes global AES array
Returns:
Window handle
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability

short mt_wdlg_get_tree DIALOG dialog,
OBJECT **  tree,
GRECT r,
short global_aes
 

returns the size of the object tree and the size of the window (of the working area). If the dialog size has not been altered with mt_wdlg_set_size(), then the working area corresponds to the GRECT of the root object.

Parameters:
dialog Pointer to the dialog structure
tree Pointer to object tree
r Pointer to GRECT
global_aes global AES array
Returns:
1
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability

void* mt_wdlg_get_udata DIALOG dialog,
short global_aes
 

returns the variable user_data that was passed at the mt_wdlg_create() call.

Parameters:
dialog Pointer to the dialog structure
global_aes global AES array
Returns:
The pointer user_data
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability

short mt_wdlg_open DIALOG dialog,
char *  title,
short  kind,
short  x,
short  y,
short  code,
void *  data,
short global_aes
 

opens a window with the title line title at the position x, y. Before mt_wdlg_open() returns to the caller, the service routine handle_exit (see above) is called with the function number HNDL_OPEN:
handle_exit(dialog, HNDL_OPEN, code, data );

Parameters:
dialog Pointer to the dialog structure
title Pointer to the window name or 0L
kind Window components (NAME/MOVER/CLOSER)
x x-coordinate of the dialog or -1 (centred)
y y-coordinate of the dialog or -1 (centred)
code Is passed to handle_exit() in clicks
data Is passed to handle_exit() in data
global_aes global AES array
Returns:
Handle of the dialog window (0: Error)
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability

void mt_wdlg_redraw DIALOG dialog,
GRECT rect,
short  obj,
short  depth,
short global_aes
 

works in a similar way to mt_objc_draw(), but unlike there the rectangle list of the dialog window is taken into account

Parameters:
dialog Pointer to the dialog structure
rect Pointer to the bounding GRECT
obj Number of the start object
depth Number of the plane/depth
global_aes global AES array
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability
If one wants to draw an object within the dialog then one should always use mt_wdlg_redraw() and not mt_objc_draw(). Before calling mt_wdlg_redraw(), just as before and after mt_objc_draw(), a mt_wind_update() call is necessary.

short mt_wdlg_set_edit DIALOG dialog,
short  obj,
short global_aes
 

activates an edit object, i.e. the cursor will be drawn in object obj and deleted from any previously active object.

Parameters:
dialog Pointer to the dialog structure
obj Number of the new edit object (or 0, if none is to be active)
global_aes global AES array
Returns:
Number of the current edit object
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability

short mt_wdlg_set_iconify DIALOG dialog,
GRECT g,
char *  title,
OBJECT tree,
short  obj,
short global_aes
 

With mt_wdlg_set_iconify() one can iconify a window dialog. The GRECT g sets the new position and size of the window (external dimensions). Generally one will pass msg+4 here when one has received the message WM_ICONIFIY. But equally one can also pass a GRECT {-1,-1,-1,-1} which MagiC uses to ascertain the position.

Parameters:
dialog Pointer to the dialog structure
g Pointer to GRECT
title New window title or NULL
tree New window tree or NULL
obj Object to be centred or -1
global_aes global AES array
Returns:
1
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability. This function is only present from WDIALOG 1.05 onwards. If it is not present, intout[0] contains a 0.
ICONIFY alters the position and size of the root object. As one usually wants to display a different object tree for iconified windows, this can be passed in tree (otherwise set it to NULL).

Usually such an object tree consists only of the root object (G_BOX) and an icon (G_(C)ICON). If the icon (or another object) is to be centred in the window, the object number is passed in obj, otherwise -1. Furthermore one can specify a new window title. However the calling routine must ensure that the original title is restored at the mt_wdlg_set_uniconify() call.

short mt_wdlg_set_size DIALOG dialog,
GRECT new_size,
short global_aes
 

With mt_wdlg_set_size() one can alter the size of a window dialog. The GRECT new_size sets the new position and size of the window's working area. mt_wdlg_set_size() does not alter either the position or the size of the root object. If the root object is to be moved or enlarged then the object dimensions have to be altered before calling mt_wdlg_set_size().

Parameters:
dialog Pointer to the dialog structure
new_size Pointer to GRECT
global_aes global AES array
Returns:
1
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability

short mt_wdlg_set_tree DIALOG dialog,
OBJECT new_tree,
short global_aes
 

represents a new object tree in a dialog. If the new root object has a different size, the window size will be adapted to suit. The window contents will be updated in each case.

Parameters:
dialog Pointer to the dialog structure
new_tree Pointer to the new object tree
global_aes global AES array
Returns:
1
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability

short mt_wdlg_set_uniconify DIALOG dialog,
GRECT g,
char *  title,
OBJECT tree,
short global_aes
 

The counterpart to mt_wdlg_set_iconify(). The GRECT g sets the new position and size of the window (external dimensions). Generally one will pass msg+4 here when one has received the message WM_UNICONIFIY. UNICONIFY alters the position and size of the root object. As one usually displayed a different object tree for iconified windows, the original tree can be passed in tree (otherwise set it to NULL). Furthermore one can specify the original window title if it was altered with mt_wdlg_set_iconify().

Parameters:
dialog Pointer to the dialog structure
g Pointer to GRECT
title New window title or NULL
tree New window tree or NULL
global_aes global AES array
Returns:
1
Since:
mt_appl_getinfo(7) give informations on mt_wdlg_xx() functions availability This function is only present from WDIALOG 1.05 onwards. If it is not present, intout[0] contains a 0.


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