Formular Library
[Reference documentation]

Display and handle formulars. More...

Defines

#define mt_FormDo(a, b, c)   mt_form_do(b,c,a->aes_global)
 Handle a formular created by mt_FormBegin().
#define FormDo(a, b)   mt_form_do(a,b,gl_appvar->aes_global)
 See mt_FormDo().

Functions

WINDOW * mt_FormWindBegin (APPvar *app, OBJECT *dial, char *nom)
 Open a formular in a modal window.
void mt_FormWindEnd (APPvar *app)
 close a modal window formular
int mt_FormWindDo (APPvar *app, int __evnt)
 handle a modal window formular
int mt_FormWindDoBuff (APPvar *app, int __evnt, short buff[8])
 handle a modal window formular
int mt_FormAttach (APPvar *app, WINDOW *win, OBJECT *tree, func_evnt func)
 Attach a formular to a window.
void mt_FormResize (APPvar *app, WINDOW *win, INT16 *x, INT16 *y, INT16 *w, INT16 *h)
 compute the window size prior to the formular size.
WINDOW * mt_FormCreate (APPvar *app, OBJECT *tree, int attrib, func_evnt func, char *name, GRECT *coord, int grow, int dup)
 Create and handle a formular in a window.
int mt_FormSave (APPvar *app, WINDOW *win, int mode)
 Store objects state of a windowed formular.
int mt_FormRestore (APPvar *app, WINDOW *win, int mode)
 Restore state of object in windowed formular.
void mt_FormBegin (APPvar *app, OBJECT *tree, MFDB *bckgrnd)
 Open a classic formular.
void mt_FormEnd (APPvar *app, OBJECT *tree, MFDB *bckgrnd)
 Close a classic formular.
int mt_FormAlert (APPvar *app, int but, char fmt[],...)
 Display a GEM alert.
void * mt_FormThumb (APPvar *app, WINDOW *win, int *idxthb, int *idxbut, int nb)
 handle a thumb object in a windowed formular.
void mt_FormThbSet (APPvar *app, WINDOW *win, int but)
 Retrieve active thumb.
int mt_FormThbGet (APPvar *app, void *thb, int mode)
 Retrieve active thumb.
void __CDECL mt_stdFormClose (WINDOW *win, int ind, int mode, void *data, APPvar *app)
 Standard callback function to handle a close button in formular.
int FormAlert (int but, char fmt[],...)
 see mt_FormAlert()
void __CDECL stdFormClose (WINDOW *win, int ind, int mode, void *data)
 see mt_stdFormClose()

Detailed Description

Display and handle formulars.

Define Documentation

#define FormDo (  a,
b   )     mt_form_do(a,b,gl_appvar->aes_global)
 

See mt_FormDo().

#define mt_FormDo (  a,
b,
c   )     mt_form_do(b,c,a->aes_global)
 

Handle a formular created by mt_FormBegin().

This function is just an alias to mt_form_do().

See also:
mt_FormBegin(), mt_FormEnd()

Function Documentation

int FormAlert (  int  but,
char  fmt[],
  ...
) 
 

see mt_FormAlert()

int mt_FormAlert (  APPvar *  app,
int  but,
char  fmt[],
  ...
) 
 

Display a GEM alert.

Parameters:
app application descriptor,
but number of the exit button which is to be made default (1-3),
fmt formatted string as follows: "[#][Alert Text][Buttons]" and accepting printf's variable descriptor,
... variable argument list according to format specified in fmt.
This function is a direct call to the AES function mt_form_alert() allowing you printing variable value as with printf().

Example 

 FormAlert( 1, "[1][Event message %d occurs.][OK]", buff[0]);

int mt_FormAttach (  APPvar *  app,
WINDOW *  win,
OBJECT *  tree,
func_evnt  proc
) 
 

Attach a formular to a window.

Parameters:
app application descriptor,
win window descriptor,
tree formular object tree,
proc callback function handling user selection or NULL,
Returns:
a window descriptor.
This function is a sub function of mt_FormCreate(). It should be used the case where mt_FormCreate() cannot be used. If a NULL value is given to parameter tree, mt_FormAttach() removes the formalar attached to the window (the formular should be prevously attached by mt_FormAttach()).

mt_FormAttach() does not duplicated the object tree. If you create multiple window formular from an unique object tree with mt_FormAttach() you should duplicate the object tree with mt_ObjcDup().

See also:
mt_FormCreate(), mt_FormResize(), mt_ObjcDup().

void mt_FormBegin (  APPvar *  app,
OBJECT *  tree,
MFDB *  bckgrnd
) 
 

Open a classic formular.

Parameters:
app application descriptor,
tree objects tree standing for the formular,
bckgrnd pointer to a valid MFDB structure or NULL.
This function creates and displays a classic formular i.e. a preemptive formular blocking the AES events (not displayed in a window). The formular is centered at screen (by calling the mt_GrectCenter() function). If a NULL value is given to parameter bckgrnd, the screen area hidden by the formular is not saved in memory. A simple WM_REDRAW will be sent when the formular will be closed (mt_FormEnd()). This mode can be used when the formular hides the desktop or windows. If a valid parameter is given to bckgrnd, the screen area hidden by the formular will stored in this buffer. This mode can be used when the formular hides another classic formulars otherwise hidden formulars need to be redrawn.

A call of mt_FormDo() handles user interaction with the formular. A call of mt_FormClose() close and release memory used by mt_FormBegin().

Example 

 void do_dialog( int tree_index) {
   MFDB screen;
   OBJECT *tree;
   int res;
          
   rsrc_gaddr( 0, tree_index, &tree);
   FormBegin( tree, &screen);
   res = FormDo( tree, -1)
   switch(res){
   case OK:
     ...
     break;
   }
   FormEnd( tree, &screen);
 }
See also:
mt_FormDo(), mt_FormEnd(), mt_GrectCenter().

WINDOW* mt_FormCreate (  APPvar *  app,
OBJECT *  tree,
int  attrib,
func_evnt  proc,
char *  name,
GRECT *  gpos,
int  grow,
int  dup
) 
 

Create and handle a formular in a window.

Parameters:
app application descriptor,
tree formular object tree ,
attrib widget attribute,
proc callback function handling user selection or NULL,
name window title,
gpos window position and size or NULL,
grow if TRUE, actives the visual graphic effects when window is opened and closed,
dup if TRUE, duplicates formular object tree in memory,
Returns:
a window descriptor.
mt_FormCreate() creates a window formular and displays it to the screen. If a window formular with the same object tree already exists, the function returns the window descriptor associated to this formular. If the window formular is closed, the window is re-open, if the window is iconified, the window is uniconified. The window is eventually topped.

The formular is centered at screen (by using mt_GrectCenter()) if a NULL value is given to gpos parameter. A non NULL value of this parameter allows you to define the position in the desktop od the window (gpos->g_x and gpos->g_y) and the size of the window (gpos->g_w and gpos->g_h). If a formular is bigger than the window, mt_FormCreate() creates sliders wigdet to make scroll the window.

The name parameter specifies the window name (equivalent to a mt_WindSet( WF_NAME) call).

It is possible to create several windows with a same formular by setting the dup parameter of mt_FormAttach() to 1 : the object tree is duplicated in memory (see mt_ObjcDup()) and this copy is used as formular. A such tree is always unique. The raison of using duplicated objects is that each formular has to have their own coordinates, flags and state. When an object tree is duplicated, the bit WS_FORMDUP of win->status of the window descriptor is set to 1.

Event mesages handled by default

In addition to events handled by mt_WindCreate(), mt_FormCreate() defines the following events :

Handling a window formular

There are three ways in WinDom to handle user selection in a windowed formular :

  • handle directly the event message WM_FORM. This message is emited when user actes on a formular.
  • use the callback function specified by mt_FormCreate(). When a event message WM_FORM is emit, this function is invoked by window kernel. The AES event buffer message needs to be read.
  • for each selectable object in the formular, attaches a callback function (or a variable). For that purpose, see mt_ObjcAttach().

These methods are illustrated in examples provided in WinDom package.

See also:
mt_FormAttach(), mt_FormResize().

void mt_FormEnd (  APPvar *  app,
OBJECT *  tree,
MFDB *  bckgrnd
) 
 

Close a classic formular.

Parameters:
app application descriptor,
tree formular objects tree,
bckgrnd pointer to a valid memory structure or NULL.
This function closes a formular previously created with mt_FormBegin(). A NULL value for bckgrnd parameter sent a WM_REDRAW event to the desktop. A correct value of bckgrnd restores the screen area hidden by the formular and memory allocated by mt_FormBegin() is freed.

See also:
mt_FormEnd(), mt_FormDo()

void mt_FormResize (  APPvar *  app,
WINDOW *  win,
INT16 *  x,
INT16 *  y,
INT16 *  w,
INT16 *  h
) 
 

compute the window size prior to the formular size.

Parameters:
app application descriptor,
win window descriptor,
x,y,w,h new size and window position.
This function computes the size of a window formular in order to host the formular. This function can be used to resize a formular when it changes its size.

If the window containing formular is already opened at screen, the window is resize and parameters x, y, w and h have not signification (NULL value can be used). If the window is not opened at screen, x, y, w and h parameters are filled with the new size and position and can be used to call WindSet(WF_CURRXYWH) function.

See also:
mt_FormCreate(), mt_FormAttach().

int mt_FormRestore (  APPvar *  app,
WINDOW *  win,
int  mode
) 
 

Restore state of object in windowed formular.

Parameters:
app application descriptor,
win window descriptor,
mode type of formular : OC_FORM or 0C_TOOLBAR
This function restores the objects state of a formular or a toolbar previously saved by mt_FormSave().

See also:
mt_FormSave()

int mt_FormSave (  APPvar *  app,
WINDOW *  win,
int  mode
) 
 

Store objects state of a windowed formular.

Parameters:
app application descriptor,
win window descriptor,
mode type of formular : OC_FORM or 0C_TOOLBAR
This function stores in a special buffer of the WINDOW structure value of ob_state of each object in the formular. These values can be restored by mt_FormRestore() (typically, after a Cancel action).

Memory used by mt_FormSave() is released when window is destroyed or when the formular (or toolbar) is removed from the window via mt_FormAttach() (or mt_WindSet(WF_TOOLBAR)).

Currently, this function is incomplete because editable objects are not saved. It is probably most powerful to use mt_ObjcDup() to create a snapshot of a formular that is make probably this function deprecated.

See also:
mt_FormRestore()

int mt_FormThbGet (  APPvar *  app,
void *  data,
int  type
) 
 

Retrieve active thumb.

Parameters:
app application descriptor,
data pointer to the thumb structure (provide by mt_FormThumb()),
type possible values are :
  • 0 returns active button,
  • 1 returns active thumb (sub-dialog).
Returns:
an object index or -1 if an error occurs.
This function returns the active thumb (the thumb itself or button linked to the active thumb).

See also:
mt_FormThumb(), mt_FormThbSet().

void mt_FormThbSet (  APPvar *  app,
WINDOW *  win,
int  but
) 
 

Retrieve active thumb.

Parameters:
app application descriptor,
win window formular hosting the thumb,
but index button linked to thumb to active.
This function changes the active thumb (without a user manipulation).

Bug:
FIXME - Does not work correctly.
See also:
mt_FormThumb(), mt_FormThbSet().

void* mt_FormThumb (  APPvar *  app,
WINDOW *  win,
int *  idxthb,
int *  idxbut,
int  nb
) 
 

handle a thumb object in a windowed formular.

Parameters:
app application descriptor,
win window descriptor,
idxthb list of thumb index,
idxbut list of button index to link,
nb number of thumb object,
Returns:
a pointer to a thumb structure or NULL if an error occurs.
The function declares a thumb, i.e. a multiple subdialog, inside a window dialog. After this call, thumb buttons are automatically handled. Parameters idxthb and idxbut describe links between sub dialogs and thumb buttons. There are arrays of nb items. For each item i of these arrays, idxthb[i] is linked to idxbut[i].

The fonction returns a pointer which be used by functions mt_FormThbSet() and mt_FormThbGet().

Example: 

 // Example of thumb indexes with three elements
int but [] = {BUT1, BUT2, BUT3};
int sub [] = {SUB1, SUB2, SUB3};

win = FormCreate( ...);
FormThumb( win, sub, but, 3);

See also:
mt_FormThbSet(), mt_FormThbGet().

WINDOW* mt_FormWindBegin (  APPvar *  app,
OBJECT *  tree,
char *  name
) 
 

Open a formular in a modal window.

Parameters:
app application descriptor,
tree formular object tree,
name window title,
Returns:
a window descriptor.
mt_FormWindBegin() creates a modal window formular that is a formular displayed in a modal window. A modal window disables the user interaction of the application excepted in this own window. It is very similar to the classic formular except the AES is not stopped. Events of the formular are handled by mt_FormWindDo(). The formular is closed with mt_FormWindEnd().

The user WinDom variable windom.mform.widget defines the widgets of the window.

See also:
mt_FormWindDo(), mt_FormWindEnd().

int mt_FormWindDo (  APPvar *  app,
int  Evnt
) 
 

handle a modal window formular

Parameters:
app application descriptor,
Evnt bit field of event to catch (see mt_EvntWindom()) + the special value FORM_EVNT,
Returns:
depend on user interaction :
  • object index if a WM_FORM event occurs,
  • a combinaison of FORM_EVNT flag and event returned by evnt_multi() if Evnt parameter has the FORM_EVNT flag set.
  • (-1) if WM_DESTROY event occurs.
This function is used in order handle a formular opened by mt_FormWindBegin(). A MU_MESAG is always required to handle correctly the formular.

User interaction or event can be traited directly from the output of the function. In the case where FORM_EVNT flag is used, a while() structure is required because event imply the output of mt_FormWindDo().

Another method to trait event and user selection is to catch up event with mt_EvntAttach() and object selection with mt_ObjcAttach().

mt_FormWindDo() and mt_FormWindEnd() does not need a window paramater : window formular are modals and there is no ambiguity because a modal window is always the top window application. Several modal window can be imbricated.

Note:
This function does not allow to read the whole AES message that occured (if the function returns MU_MESAG). If you need to read the full AES message when this function returns, then you should use mt_FormWindDoBuff().
See also:
mt_FormWindBegin(), mt_FormWindEnd().

int mt_FormWindDoBuff (  APPvar *  app,
int  Evnt,
short  buff[8]
) 
 

handle a modal window formular

Parameters:
app,Evnt same as for mt_FormWindDo()
buff the buffer to use for AES messages
Returns:
same as mt_FormWindDo()
This function is similar to mt_FormWindDo() -- in fact this is what mt_FormWindDo() invoke to do the whole job.

The main difference is the parameter buff[8].

This parameter allows to read the full content of the AES message that occurs (if the function returns MU_MESAG).

void mt_FormWindEnd (  APPvar *  app  ) 
 

close a modal window formular

Parameters:
app application descriptor.
Use this function to close a formular opened by mt_FormWindBegin().

See also:
mt_FormWindBegin(), mt_FormWindDo().

void __CDECL mt_stdFormClose (  WINDOW *  win,
int  index,
int  mode,
void *  data,
APPvar *  app
) 
 

Standard callback function to handle a close button in formular.

This function is a standard callback function that you can link to 'Close' button in a formular (using mt_ObjcAttach()). This function restore the NORMAL state of the object and destroy the formular.

void __CDECL stdFormClose (  WINDOW *  win,
int  ind,
int  mode,
void *  data
) 
 

see mt_stdFormClose()

Generated on Thu Jun 22 11:45:28 2006 for WinDom by  doxygen 1.4.6