FormCreate()

NAME

FormCreate - Create a window formular.

PROTOTYPAGE

WINDOW *FormCreate( OBJECT *tree, int attrib, void (*func)(), char *name, GRECT *coord, int grow, int dup);

PARAMETERS

tree:

address of the object tree,

attrib:

GEM window widgets,

func:

form event function or NULL,

name:

window name,

coord:

position and size of the window or NULL,

grow:

a TRUE value actives the graphic effects when the window is opened and closed,

dup:

a TRUE value duplicates the object tree.

return:

the window descriptor or NULL if error.

DESCRIPTION

FormCreate() creates a window formular and display 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 GrectCenter()) if a NULL value is given to coord parameter. A non NULL value of this parameter allows you to define the position in the desktop od the window (coord->g_x and coord->g_y) and the size of the window (coord->g_w and coord->g_h). If a formular is bigger than the window, FormCreate() creates sliders wigdet to make scroll the window. The name parameter specifies the window name (equivalent to a WindSet( WF_NAME) call).

It is possible to create several window with a same formular by setting the dup parameter of FormAttach() to 1 : the object tree is duplicated in memory (see 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 the status field of the window descriptor is set to one.

FormCreate() attaches to the window specials event functions dedicated to the formular handling (see the TECHNICALS NOTES paragraphe). In perticular, when the user selects an object in a formular, a GEM message is sent. This message has the following structure :

               evnt.buff[0] = WM_FORM
               evnt.buff[1] = GEM application identifior
               evnt.buff[2] = 0
               evnt.buff[3] = GEM window handle of the formular,
               evnt.buff[4] = index of the selected object,
               evnt.buff[5] = keyboard state ( a bit field of
     						 K_CTRL, K_ALT, K_LSHIFT, R_SHILT).

If an event function was attached to this message (with the parameter func of FormCreate() or with EvntAttach()), EvntWindom() will call this function when this event occurs. Instead of using an event function to handle the formular feedback, it is possible to attach variables or function to an object (see ObjcAttach()). A complet example of formular handling can be found in the tutorial The window formulars.

TECHNICAL NOTES

FormCreate() attaches a set of event function dedicated to the formular handling. We list these functions in the following table.

Standard event functions of a formular.

Name	Event	Description
frm_drw	WM_REDRAW	Draw the formular in the window. The
		formular root position is adpated the window
		work area position. Displays the cursor
		in the first text editable object.
frm_dstry	WM_DESTROYED	Close and destroy the window formular.
frm_tpd	WM_TOPPED	Set the window in foreground and eventually
		switch on the cursor of text editable
		object.
frm_mvd	WM_MOVED	Move the window and adaptes the formular
		root position.
frm_keyhd	MU_KEYBD	Handle the keyboard shortcuts and cursor
		movement in editable objects.

SEE ALSO

ObjcChange(), ObjcDraw(), ObjcDup(), ObjcAttach(), FormAttach(), GrectCenter().