2.3.2 WINDOW DIALOG - CREATE (AES 160)

This function allocates memory for a dialog structure and initialises it.

Declaration:
DIALOG  *wdlg_create( HNDL_OBJ handle_exit, OBJECT *tree,
                      void *user_data, WORD code, void *data,
                                               WORD flags );

Call:
dialog = wdlg_create( handle_exit, tree, user_data,
                             code, data, WDLG_BKGD );

Variable         Argument            Meaning
Inputs:

contrl[0]        160                 wdlg_create
contrl[1]        2                   Entries in intin
contrl[3]        4                   Entries in addrin

intin[0]         code                Is passed to handle_exit() 
                                     in <clicks>
intin[1]         flags

addrin[0]        handle_exit         Pointer to the service function
addrin[1]        tree                Pointer to the object tree
addrin[2]        user_data           Pointer to user info
addrin[3]        data                Is passed to handle_exit() in <data>

Outputs:

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

addrout[0]       dialog              Pointer to the dialog structure

Description of <handle_exit>:

<handle_exit> is the pointer to a service routine that is called, among others, by wdlg_evnt(). <handle_exit> is 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 und contains a corresponding function number such as HNDL_CLSD, for instance).

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

Example of a service routine:

WORD cdecl handle_exit( DIALOG *dialog, EVNT *events, WORD obj,
                                       WORD clicks, void *data );
{
  if ( obj < 0 )             /* Event or object number? */
  {
                             /* All events except HNDL_CLSD are ignored
                                in this example */

     if ( obj == HNDL_CLSD ) /* Closer activated? */
        return( 0 );         /* Finish */


     if ( obj == HNDL_EDIT )
     {
        /* In window dialogs it may be useful to ignore key combinations
           with Control in input fields, so that keyboard shortcuts such
           as Ctrl-U, Ctrl-W or Ctrl-Q for instance may be evaluated in 
           the event loops of a program. In that case a 0 should be 
           returned after HNDL_EDIT so that the key is not evaluated 
           by objc_edit().
        */
     }
  }
  else                       /* An object has been selected */
  {
     switch ( obj )          /* Initiate action (if needed) */
     {

        case ...
          .
          .
          .
        case MY_EXIT_OBJECT: ..... return( 0 );   /* Finish */
     }
  }
  return( 1 );                     /* Continue */
}

The parameters have the following meanings:

dialog: Pointer to a dialog structure. One should not access the structure directly. The wdlg_xx functions should be used!

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

obj: >= 0: Object number < 0: Function number (see below)

clicks: Number of mouse clicks (if <obj> is an object number)

data: The contents depend on <obj>

Meaning of <data> depending on <obj>:

If <obj> is a (positive) object number, then the variable <user_data> is passed in <data> (see wdlg_create). <clicks> contains the number of mouse clicks on this object.

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.

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.