Base DFRM functions

Basic and low-level functions of DFRM. More...

Defines
#define	dfrm_create(m, t)   mt_dfrm_create (gl_appvar,m,t)
	Create a new form, see mt_dfrm_create().
#define	dfrm_free(d)   mt_dfrm_free(gl_appvar,d)
	Release from the memory a form, see mt_dfrm_create().
#define	dfrm_add_menu(d, l)   mt_dfrm_add_menu(gl_appvar,d,l)
	Add and place an object in a form, see mt_dfrm_add_menu().
#define	dfrm_win_attach(t, w, d)   mt_dfrm_win_attach(gl_appvar,t,w,d)
	Makes effective bindings performed with mt_dfrm_attach(), see mt_dfrm_win_attach().
#define	dfrm_find_label(d, l)   mt_dfrm_find_label(gl_appvar,d,l)
	Searching object by its label, see mt_dfrm_find_label().
#define	dfrm_delete(d, i)   mt_dfrm_delete(gl_appvar,d,i)
	Delete an object from a form, see mt_dfrm_delete().
Functions
void *	mt_dfrm_create (APPvar *ap, int maxobj, int type)
	Creating a new dynamic form.
void	mt_dfrm_free (APPvar *ap, void *dfrm)
	Release from the memory a form.
void	dfrm_add (void *dfrm, int pind, int cind, int wspace, int hspace, int dir)
	Add and place an object in a form.
int	mt_dfrm_add_menu (APPvar *ap, void *dfrm, char *label)
	Special function to adding a title in a menu bar.
void	dfrm_align (void *dfrm, int ind, int dir, int align)
	Giving alignement directives to objects.
void	dfrm_repack (void *dfrm)
	Applying alignment directives.
void	dfrm_order (void *dfrm, int ind, int order)
	Ordering children's object in a dynamic form.
void	dfrm_attach (void *dfrm, int ind, int type,...)
	ObjcAttach() remplacement for menu and form.
void	mt_dfrm_win_attach (APPvar *ap, int type, void *win, void *dfrm)
	Make effective bindings performed with mt_dfrm_attach().
OBJECT *	dfrm_tree (void *dfrm)
	Returns the OBJECT tree of a form.
int	dfrm_cellsize (int mode)
	Return cell character size .
int	mt_dfrm_find_label (APPvar *ap, void *dfrm, char *label)
	Searching object by its label.
int	mt_dfrm_delete (APPvar *ap, void *dfrm, int ind)
	Delete an object from a form.

---

Detailed Description

Basic and low-level functions of DFRM.

Contains functions to create or release AES object tree, adding, align and modify object in a object tree. Contains interface to WinDom environmment.

---

Define Documentation

#define dfrm_add_menu	(	d,
		l		)	mt_dfrm_add_menu(gl_appvar,d,l)

Add and place an object in a form, see mt_dfrm_add_menu().

#define dfrm_create	(	m,
		t		)	mt_dfrm_create (gl_appvar,m,t)

Create a new form, see mt_dfrm_create().

#define dfrm_delete	(	d,
		i		)	mt_dfrm_delete(gl_appvar,d,i)

Delete an object from a form, see mt_dfrm_delete().

#define dfrm_find_label	(	d,
		l		)	mt_dfrm_find_label(gl_appvar,d,l)

Searching object by its label, see mt_dfrm_find_label().

#define dfrm_free

(

d

)

mt_dfrm_free(gl_appvar,d)

Release from the memory a form, see mt_dfrm_create().

#define dfrm_win_attach	(	t,
		w,
		d		)	mt_dfrm_win_attach(gl_appvar,t,w,d)

Makes effective bindings performed with mt_dfrm_attach(), see mt_dfrm_win_attach().

---

Function Documentation

void dfrm_add	(	void *	_dfrm,
		int	pind,
		int	cind,
		int	wspace,
		int	hspace,
		int	dir
	)

Add and place an object in a form.

Parameters:

	_dfrm	form descriptor
	pind	parent object index
	cind	child object index
	wspace,hspace	horizontal and vertically spacing
	dir	direction of spacing. It is a bit field of DIR_VERT relative vertically spacing on DIR_HORI relative horizontaly spacing on DIR_NONE no relative spacing

Adds an object in a object tree. 'cind' is the index object to add. This object will be always added as THE LAST CHILD of the parent object pointed by 'pind' parameter. If parent object has not child, it will be the first child.

'wspace' and 'hspace' are relative or absolute spatial position of the child object. It depends on 'dir' parameter :

• DIR_VERT is true : hspace is the vertically spacing between 'cind' object and previous child object if it exists or parent object else,
• DIR_VERT is false, hspace is y-coordinate of 'cind' object,
• DIR_HORI acts on horizontal spacing using wspace parameter,
• DIR_NONE means DIR_VERT and DIR_HORI bits are false.

wspace and hspace can be positive, negative or null. Positive value means the unit is pixel. Negative value means the unit is a semi character size. Advantage to use character unit is the position of objects is independant of screen resolution (and system font system).

If needed, size of parent object is adjusted in order to contain all children objects.

If you want add a title in menu, you have to use the special function dfrm_add_menu().

References dfrm_adjust_size(), dfrm_tree(), DIR_HORI, DIR_NONE, DIR_VERT, _dfrm::_dfrm::properties::hspace, NILOBJ, _dfrm::props, and _dfrm::_dfrm::properties::wspace.

Referenced by mt_dfrm_add_menu(), mt_dfrm_new_dmenu(), mt_dfrm_new_slider(), mt_dfrm_thumb_add(), and mt_dfrm_thumb_new().

void dfrm_align	(	void *	dfrm,
		int	ind,
		int	dir,
		int	align
	)

Giving alignement directives to objects.

This function indicates the way the object position will be calculated by dfrm_repack(). This position is always relative to the parent object. For example a LEFT_ALIGN means the object will be align on the left in the object parent (and not the on the left of the previous object in the same level).

Alignement takes into account the spacing information you gave in when the object was added in the object tree (with dfrm_add()). For example, an object adding the a w-spacing of 10, aligned to the right, will be set with a spacing of 10 pixels between the right border of the object and the right border of the parent.

Parameters:

	dfrm	form descriptor,
	ind	index of object,
	dir	direction of alignement (DIR_HORI or DIR_VERT),
	align	kind of alignement, if dir = DIR_HORI: ALIGN_LEFT align to left, ALIGN_CENTER center object, ALIGN_RIGHT align to right, ALIGN_JUSTIFY justify on father object width. if dir = DIR_VERT: ALIGN_TOP align to top, ALIGN_CENTER center object, ALIGN_BOT align to bottom, ALIGN_JUSTIFY justify on father object height.

References DIR_HORI, and DIR_VERT.

Referenced by mt_dfrm_new_dmenu(), and mt_dfrm_thumb_add().

void dfrm_attach	(	void *	_dfrm,
		int	ind,
		int	type,
			...
	)

ObjcAttach() remplacement for menu and form.

Parameters:

	_dfrm	dialog pointer,
	ind	index of object
	type	type of form, see ObjcAttach(),
	...	see see ObjcAttach().

This function remplaces ObjcAttach(). As the building of the form is dynamic, the structure can change during the building process then ObjcAttach() can not be used directly. The real binding of object will be effective when dfrm_win_attach() is be called.

Use dfrm_attach() exactly as ObjcAttach().

References _dfrm::bind, _dfrm::_dfrm::_bind::bit, _dfrm::_dfrm::_bind::data, _dfrm::_dfrm::_bind::fnc, _dfrm::_dfrm::_bind::value, and _dfrm::_dfrm::_bind::var.

int dfrm_cellsize

(

int

mode

)

Return cell character size .

Parameters:

mode

should be : SWIDTH returns width of a small character, SHEIGHT returns height of a small character, LWIDTH returns width of a large character, LHEIGHT returns height of a large character.

References LHEIGHT, LWIDTH, SHEIGHT, and SWIDTH.

Referenced by mt_dfrm_new_button(), mt_dfrm_new_edit(), mt_dfrm_new_fedit(), mt_dfrm_new_ftext(), mt_dfrm_new_label(), mt_dfrm_new_tbox(), mt_dfrm_new_text(), and mt_dfrm_new_xedit().

void dfrm_order	(	void *	dfrm,
		int	ind,
		int	order
	)

Ordering children's object in a dynamic form.

Parameters:

	dfrm	form pointer
	ind	object index to reorder
	order	new order : ORD_TOP object is ordered as the top children of its parent ORD_BOT object is ordered as the bottom children of its parent

dfrm_order() reorders children of an object in the dialog object tree. This function is used specially to create thumb indexed button : buttons of each subform are created before subforms if buttons are placed over subform but buttons should be drawn before (for the best visual aspect) subform. After building of the form, thumb buttons can be reorder (as last children) using the function dfrm_reoder() (see example in demo.c). objc_order() is more powerfull but cannot be used because, additional ressources need to be reordered in the dynamic form.

References dfrm_tree(), obj_root(), ORD_BOT, and ORD_TOP.

Referenced by mt_dfrm_thumb_end().

void dfrm_repack

(

void *

_dfrm

)

Applying alignment directives.

Computes size and position of objects in an form according to alignment directives given by dfrm_align() and dfrm_add(). This function is called only one time juste before displaying form at screen.

Parameters:

_dfrm

form pointer

References ALIGN_BOT, ALIGN_CENTER, ALIGN_FJUSTIFY, ALIGN_JUSTIFY, ALIGN_LEFT, ALIGN_RIGHT, ALIGN_TOP, dfrm_tree(), get_next_obj(), _dfrm::_dfrm::properties::halign, _dfrm::_dfrm::properties::hspace, NILOBJ, obj_root(), _dfrm::props, _dfrm::_dfrm::properties::walign, and _dfrm::_dfrm::properties::wspace.

OBJECT* dfrm_tree

(

void *

dfrm

)

Returns the OBJECT tree of a form.

Parameters:

dfrm

form descriptor

Returns:

address of root OBJECT structure element.

Referenced by dfrm_add(), dfrm_new_box(), dfrm_new_cbox(), dfrm_new_fbox(), dfrm_order(), dfrm_repack(), mt_dfrm_add_menu(), mt_dfrm_delete(), mt_dfrm_find_label(), mt_dfrm_form(), mt_dfrm_free(), mt_dfrm_menu(), mt_dfrm_modal(), mt_dfrm_new_button(), mt_dfrm_new_cicon(), mt_dfrm_new_edit(), mt_dfrm_new_fedit(), mt_dfrm_new_ftext(), mt_dfrm_new_icon(), mt_dfrm_new_image(), mt_dfrm_new_label(), mt_dfrm_new_line(), mt_dfrm_new_mtext(), mt_dfrm_new_slider(), mt_dfrm_new_tbox(), mt_dfrm_new_text(), mt_dfrm_new_xcicon(), mt_dfrm_new_xedit(), mt_dfrm_thumb_add(), mt_dfrm_thumb_end(), mt_dfrm_thumb_new(), mt_dfrm_toolbar(), and mt_dfrm_win_attach().

int mt_dfrm_add_menu	(	APPvar *	app,
		void *	_dfrm,
		char *	label
	)

Special function to adding a title in a menu bar.

This function is used (instead of dfrm_add()) for insert a new title (a G_TITLE object) in the menu bar. dfrm_add() should never be called because inserting a new title object needs reorder all objects in the menu tree.

Parameters:

	app	application descriptor,
	_dfrm	pointer to a DFRM dialog
	label	text of title object.

Returns:

index of the menu object.

See also:

dfrm_create()

References BAR, _dfrm::bind, dfrm_add(), dfrm_new_fbox(), dfrm_tree(), DIR_HORI, DIR_NONE, FREEOBJ, mt_dfrm_new_label(), NILOBJ, _dfrm::props, SCREEN, TITLES, and TYPE_MTITLE.

Referenced by mt_dfrm_new_dmenu().

void* mt_dfrm_create	(	APPvar *	app,
		int	maxobj,
		int	type
	)

Creating a new dynamic form.

Parameters:

	app	application descriptor,
	maxobj	maximal number of objects,
	type	type of form : TYPE_MENU form is a menu, TYPE_NORMAL a form with a normal background TYPE_OUTLINED a form with a outlined backgound TYPE_EMPTY an empty object tree

Returns:

form descriptor or NULL if an error occurs.

See also:

dfrm_add(), dfrm_new_box(), ...

Use this function to create a new and empty form. The next step is to define new objects (using functions dfrm_new_*()) and adding and placing them in the form using dfrm_add().

If the number of allowed objects is reached (by functions dfrm_new_*()), the program will be stopped by an false assertion.

References BAR, _dfrm::bind, DESKTOP, DRAW3D, FLAGS9, _dfrm::_dfrm::_bind::fnc, FREEOBJ, NILOBJ, _dfrm::props, _dfrm::root, SCREEN, TITLES, TYPE_EMPTY, TYPE_MENU, TYPE_NORMAL, TYPE_OUTLINED, and _dfrm::_dfrm::_bind::var.

int mt_dfrm_delete	(	APPvar *	app,
		void *	dfrm,
		int	ind
	)

Delete an object from a form.

Delete an object from a dynamic form. Actually, the object is just disconnected and eventually its resources allocated are released.

Parameters:

	app	application descriptor,
	dfrm	form descriptor,
	ind	object index in form,

Returns:

return of mt_objc_delete() function.

References __free_obspec(), dfrm_tree(), and FREEOBJ.

int mt_dfrm_find_label	(	APPvar *	app,
		void *	dfrm,
		char *	label
	)

Searching object by its label.

Parameters:

	app	application descriptor,
	dfrm	form descriptor,
	label	string to find as label object,

Returns:

first index of object containing label object or -1 if any object is found.

References dfrm_tree().

void mt_dfrm_free	(	APPvar *	app,
		void *	_dfrm
	)

Release from the memory a form.

Parameters:

	app	applicationd descriptor,
	_dfrm	form descriptor.

References __free_obspec(), _dfrm::bind, dfrm_tree(), _dfrm::props, and _dfrm::root.

void mt_dfrm_win_attach	(	APPvar *	app,
		int	type,
		void *	win,
		void *	_dfrm
	)

Make effective bindings performed with mt_dfrm_attach().

Parameters:

	app	application descriptor,
	type	type of form (OC_FORM, OC_MENU, OC_TOOLBAR),
	win	window hosting form,
	_dfrm	pointer to the form structure.

This function makes effectives all binding declaring with mt_dfrm_attach(). The function should be called when the building of the form is finished.

References _dfrm::bind, _dfrm::_dfrm::_bind::bit, _dfrm::_dfrm::_bind::data, dfrm_tree(), _dfrm::_dfrm::_bind::fnc, _dfrm::_dfrm::_bind::value, and _dfrm::_dfrm::_bind::var.

Referenced by mt_dfrm_form(), mt_dfrm_menu(), mt_dfrm_modal(), and mt_dfrm_toolbar().