WinDom: Formular Library

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

# 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 : WM_REDRAW : handled by frm_drw(), WM_DESTROYED : handled by frm_dstry(), WM_MOVED : handled by frm_mvd(), WM_FULLED : handled by frm_fld(), WM_TOPPED : handled by frm_tpd(), MU_BUTTON : handled by frm_click(), MU_KEYBD : handled by frm_keyhd(). 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()