Object Library
[Reference documentation]

Group of functions for controling efficiently AES objects. More...

Defines
#define	mt_ObjcDraw(a, b, c, d, e)   mt_ObjcDrawParent(a,b,c,d,0,e)
#define	mt_ObjcStrCpy(a, tree, index, str)   strcpy(mt_ObjcString(a,tree,index,NULL),str)
	Modify an object label.
#define	mt_ObjcStrFmt(a, b, c, d)   ObjcStrFmt(b,c,d)
	See ObjcStrFmt().
#define	ObjcStrCpy(tree, index, str)   strcpy(mt_ObjcString(gl_appvar,tree,index,NULL),str)
	See mt_ObjcStrCpy().
Functions
int	mt_ObjcChange (APPvar *app, int mode, void *data, int __index, int state, int redraw)
	Change the object state.
int	mt_ObjcChar (APPvar *app, OBJECT *tree, int idx, int put)
	Get and set the character of an object.
int	mt_ObjcDrawParent (APPvar *app, int mode, void *win, int __index, int parent_depth, int child_depth)
	Draws an objet in a formular.
int	mt_ObjcIsHidden (APPvar *app, int mode, void *win, int __index)
	tell if the object or one of its parent is hidden.
OBJECT *	mt_ObjcDup (APPvar *app, OBJECT *tree, WINDOW *win)
	Objects tree duplication.
OBJECT *	mt_ObjcNDup (APPvar *app, OBJECT *src, WINDOW *win, int nb)
	Objects duplication.
OBJECT *	mt_ObjcNDupAtAddr (APPvar *app, OBJECT *src, WINDOW *win, int nb, OBJECT *dest)
	Objects duplication at a given address.
int	mt_ObjcEdit (APPvar *app, int mode, WINDOW *win, int obj, int val, INT16 *idx, int kind)
	Control texte edition of EDITABLE object in formular.
void	mt_ObjcFree (APPvar *app, OBJECT *tree)
	Release from memory a duplicated objects tree.
void	mt_ObjcNFreeAtAddr (APPvar *app, OBJECT *tree, int nb)
	Release from memory a duplicated objects tree.
char *	mt_ObjcString (APPvar *app, OBJECT *tree, int __index, char *put)
	Get and set the label of an object.
void	mt_ObjcStr3d (APPvar *app, OBJECT *tree)
	Transform 3D FTEXT MagiC objects.
int	mt_ObjcWindDraw (APPvar *app, WINDOW *win, OBJECT *tree, int __index, int depth, int xclip, int yclip, int wclip, int hclip)
	Draw any object in any window.
int	mt_ObjcWindDrawParent (APPvar *app, WINDOW *win, OBJECT *tree, int __index, int parent_depth, int child_depth, int xclip, int yclip, int wclip, int hclip)
	Draw any object (and its parents) in any window.
int	mt_ObjcWindChange (APPvar *app, WINDOW *win, OBJECT *tree, int __index, int xclip, int yclip, int wclip, int hclip, int state)
	Change state of any object in any window.
OBJECT *	mt_ObjcTree (APPvar *app, int mode, WINDOW *win)
	Returns the objects tree hosted by a window.
void	ObjcStrFmt (char *dest, char *src, int size)
	Troncate a string in order to fit in an object label.

---

Detailed Description

Group of functions for controling efficiently AES objects.

---

Define Documentation

#define mt_ObjcDraw (  a, b, c, d, e   )     mt_ObjcDrawParent(a,b,c,d,0,e)

#define mt_ObjcStrCpy (  a, tree, index, str   )     strcpy(mt_ObjcString(a,tree,index,NULL),str)

Modify an object label. Just a fast call of mt_ObjcString().

#define mt_ObjcStrFmt (  a, b, c, d   )     ObjcStrFmt(b,c,d)

See ObjcStrFmt().

#define ObjcStrCpy (  tree, index, str   )     strcpy(mt_ObjcString(gl_appvar,tree,index,NULL),str)

See mt_ObjcStrCpy().

---

Function Documentation

int mt_ObjcChange (  APPvar *  app, int  mode, void *  win, int  index, int  state, int  redraw )

Change the object state. Parameters: app  application descriptor, mode  type of target : OC_FORM if the formular is a window, OC_TOOLBAR if the formular is a toolbar, OC_OBJC if the formular is a classic formular, win  window descriptor or an object tree if mode is set to OC_OBJC, index  object index to change, state  new object state, redraw  bit 0 indicates if object should be redrawn, OC_MSG resquestes a redraw by WinDom kernel. Returns: 0 if an error occurred or non-zero otherwise. Precondition: If a redraw is requested, mt_ObjcChange() cannot be called from a callback function because mt_EvntWindom() uses the AES rectangle list. This function replaces the AES mt_objc_change() function mainfully to change the object state in window formular or toolbar. If you use mt_ObjcChange() with the NORMAL value, the extended bits of the objet state (known as extended states) will be not affected. Negative states (e.g. ~SELECTED) have effect to unset the state. See mt_ObjcDraw() for recommandation usage. See also: mt_ObjcDraw()

int mt_ObjcChar (  APPvar *  app, OBJECT *  tree, int  idx, int  put )

Get and set the character of an object. Parameters: app  application descriptor, tree  address of an objects tree, idx  object index, put  new character (from 0 to 255) or -1 to inquire current value, Returns: character of the object or a negative error code. mt_ObjcChar() provides an universal acces of the character of any object. The object can be a charbox, an icon, a WinDom extended object containing a character. If the object has not a character, the function does nothing. If a -1 value is given to put parameter, mt_ObjcChar() returns the character of the object.

int mt_ObjcDrawParent (  APPvar *  app, int  mode, void *  win, int  index, int  parent_depth, int  child_depth )

Draws an objet in a formular. Parameters: app  application descriptor, mode  type of target : OC_FORM if the formular is a window, OC_TOOLBAR if the formular is a toolbar, OC_OBJC if the formular is a classic formular, win  window descriptor or an object tree if mode is set to OC_OBJC, index  object index to draw, parent_depth  the level of the parent that may be drawn. A value of 1 will draw the parent of the object, the object itself, and its children (specified by next parameter child_depth). child_depth  the maximum object depth to draw (a value of 1 searches only first generation objects, a value of 2 searches up to second generation objects, up to a maximum of 7 to search all objects), if the bit OC_MSG is set, a redraw event will be requested instead of a direct drawn on screen. Returns: 0 if an error occurred or non-zero otherwise. Precondition: mt_ObjcDraw() cannot be called from a callback function used to redraw the screen (that is callback functions attached to WM_REDRAW for example) because this functions may lock the screen and use the AES rectangle list. To draw an object from a that kind of callback function, use mt_objc_draw() (with win->graf.clip as clip area), or use OC_MSG mode. This function replaces the AES objc_draw() function. It is specially designed to draw object in window formular (OC_FORM mode) or toolbar (OC_TOOLBAR mode) but it works on classical formular (OC_OBJC mode) too. Using this last mode, mt_ObjcDraw() is equivalent to objc_draw(). When mt_ObjcDraw() is applied on a window, the redraw is done with respect to the window clipping. It works even the window formular is behind an another window. Special bit OC_MSG If the depth parameter has its OC_MSG bit set to 1, objects will be drawn by sending a set of WM_REDRAW messages to the AES kernel (redraw will be handled by mt_EvntWindom()) instead of drawing immediatly the object. See also: mt_ObjcChange()

OBJECT* mt_ObjcDup (  APPvar *  app, OBJECT *  src, WINDOW *  win )

Objects tree duplication. Parameters: app  application descriptor, src  objects tree to duplicate, win  window hosting the src object tree if src contains userdefs objects, Returns: a copy of src object tree. mt_ObjcDup() performs a dynamic copy of an object tree. The new object tree created try to be totally memory independant of the source. However, some objects are not totally duplicated yet. It is the case with icons and images bitmap. We plan to fix that in futur. An object tree created with mt_ObjcDup() should be freed by mt_ObjcFree(). If object tree contains USERDRAW objects, the parameter win is absolutely required. In other case, NULL is a correct value. This function is used by mt_FormCreate() to open several formulars with the same objects tree. If the WS_FORMDUP bit of the win->status window descriptor field is set to 1, the standard destroy function releases the memory with mt_ObjcFree(). Toolbars and menus attached to a window with mt_WindSet() are duplicated in memory using mt_ObjcDup() and the memory automatically released when the window is destroyed. See also: mt_ObjcFree() Todo: mt_ObjcDup() should duplicate icon and image bitmap.

int mt_ObjcEdit (  APPvar *  app, int  mode, WINDOW *  win, int  obj, int  val, INT16 *  idx, int  kind )

Control texte edition of EDITABLE object in formular. Parameters: app  application descriptor, mode  type of target : OC_FORM if the formular is a window, OC_TOOLBAR if the formular is a toolbar, OC_OBJC if the formular is a classic formular, win  window descriptor or an object tree if mode is set to OC_OBJC, obj  index of an EDITABLE object, val  parameter whose meanning depends on the kind parameter, idx  position of cursor, kind  type of action. Possible values are : ED_INIT activate the cursor initiale position is given by idx, ED_END desactivate the cursor, ED_CHAR insert the charater 'val' at current cursor position, ED_BLC_OFF desactivate a block selection, ED_BLC_START set the beginning of a block selection, ED_BLC_END set the end of a block selection and activate it, Returns: O or a negative code error if an error occurs. This function replaces the AES mt_objc_edit() function and works with all editable field. ED_BLC_OFF, ED_BLC_START and ED_BLC_END are extended modes only valid with XEDIT objects (WinDom extended editable fields). Thess modes are currently under developpement.

void mt_ObjcFree (  APPvar *  app, OBJECT *  cpy )

Release from memory a duplicated objects tree. Parameters: app  application descriptor, cpy  duplicated objects tree to release. This function releases an object tree explicitly duplicated by mt_ObjcDup(). See also: mt_ObjcDup(), mt_ObjcNDup()

int mt_ObjcIsHidden (  APPvar *  app, int  mode, void *  win, int  index )

tell if the object or one of its parent is hidden. Parameters: app  application descriptor, mode  type of target : OC_FORM if the formular is a window, OC_TOOLBAR if the formular is a toolbar, OC_OBJC if the formular is a classic formular, win  window descriptor or an object tree if mode is set to OC_OBJC, index  object index to draw, Returns: 1 if the object is hidden, 0 if the objet is not hidden, or a negative value in case of error.

OBJECT* mt_ObjcNDup (  APPvar *  app, OBJECT *  src, WINDOW *  win, int  nb )

Objects duplication. Parameters: app  application descriptor, src  objects tree to duplicate, win  window hosting the src object tree if src contains userdefs objects, nb  number of objects to copy, Returns: a copy of the nb objects starting at src. See also: mt_ObjcDup(), mt_ObjcNDupAtAddr()

OBJECT* mt_ObjcNDupAtAddr (  APPvar *  app, OBJECT *  src, WINDOW *  win, int  nb, OBJECT *  cpy )

Objects duplication at a given address. Parameters: app  application descriptor, src  objects tree to duplicate, win  window hosting the src object tree if src contains userdefs objects, nb  number of objects to copy, cpy  address where objects tree will be duplicated Returns: a copy of the nb objects starting at src. See also: mt_ObjcDup(), mt_ObjcNDup()

void mt_ObjcNFreeAtAddr (  APPvar *  app, OBJECT *  cpy, int  nb )

Release from memory a duplicated objects tree. Parameters: app  application descriptor, cpy  duplicated objects tree to release. nb  number of OBJECTs of the tree cpy to release. This function releases an object tree explicitly duplicated by mt_ObjcNDupAtAddr(). See also: mt_ObjcNDupAtAddr()

void mt_ObjcStr3d (  APPvar *  app, OBJECT *  tree )

Transform 3D FTEXT MagiC objects. Parameters: app  application descriptor, tree  objects tree to transform. The function transform FTEXT objects having a 15-bit state (this state is STATE3D supported by MagiC) in order to give us a 3D look like in MagiC.

char* mt_ObjcString (  APPvar *  app, OBJECT *  tree, int  idx, char *  put )

Get and set the label of an object. Parameters: app  application descriptor, tree  address of an objects tree, idx  object index, put  new label or NULL, Returns: address of the object label. mt_ObjcString() provides an universal acces of the label (text) of any object. The object can be a button, a string, an icon, a WinDom extended object containing a label. If the object has not text, the function does nothing. If a NULL value is given to put parameter, mt_ObjcString() returns the address of the object text. The text returned can be read or modified with respect of the buffer size : printf( "Object i : %s\n", ObjcString( tree, i, NULL), i); strcpy( ObjcString( tree, i, NULL), "New text"); It is possible to define a new buffer for the object: char txt[120] = "New text"; ObjcString( tree, i, txt); mt_ObjcString() should never be used to change the text of an menu item. For that purpose, use mt_MenuText() instead of mt_ObjcString(). See also: ObjcStrCpy(), ObjcStrFmt()

OBJECT* mt_ObjcTree (  APPvar *  app, int  mode, WINDOW *  win )

Returns the objects tree hosted by a window. Parameters: app  application descriptor, mode  type of host : OC_FORM objects tree is a window formular, OC_TOOLBAR objects tree is a window toolbar, OC_MENU objects tree is a window menu, win  host window descriptor, Returns: address of the objects tree or NULL if an error occures.

int mt_ObjcWindChange (  APPvar *  app, WINDOW *  win, OBJECT *  tree, int  index, int  x, int  y, int  w, int  h, int  state )

Change state of any object in any window. Parameters: app  application descriptor, win  targeted window descriptor, tree  objects tree containing the object to draw, index  index of object to draw in tree, x,y,w,h  clipping aera coordinates, state  new object state, Returns: 0 or a negative code error. Precondition: Do not use this function in a callback function. This function is a sub-function of my_ObjcChange(). It allows you to chage an object state and redraw it in a window with respect to the window workspace. Usually, you don't need to call this function, only mt_ObjcChange(). See also: mt_ObjcChange(), mt_ObjcWindDraw().

int mt_ObjcWindDraw (  APPvar *  app, WINDOW *  win, OBJECT *  tree, int  index, int  depth, int  xclip, int  yclip, int  wclip, int  hclip )

Draw any object in any window. Parameters: app  application descriptor, win  targeted window descriptor, tree  objects tree containing the object to draw, index  index of object to draw in tree, depth  level of redraw in children hierarchy, xclip,yclip,wclip,hclip  clipping aera coordinates, Returns: 0 or a negative code error. Precondition: Do not use this function in a callback function. This function is a sub-function of my_ObjcDraw(). It allows you to draw an object tree in a window with respect to the window workspace. Usually, you don't need to call this function, only mt_ObjcDraw(). See also: mt_ObjcDraw(), mt_ObjcWindChange().

int mt_ObjcWindDrawParent (  APPvar *  app, WINDOW *  win, OBJECT *  tree, int  index, int  parent_depth, int  child_depth, int  xclip, int  yclip, int  wclip, int  hclip )

Draw any object (and its parents) in any window. Parameters: app  application descriptor, win  targeted window descriptor, tree  objects tree containing the object to draw, index  index of object to draw in tree, child_depth  level of redraw in children hierarchy, parent_depth  level of redraw in parent hierarchy, xclip,yclip,wclip,hclip  clipping aera coordinates, Returns: 0 or a negative code error. Precondition: Do not use this function in a callback function. This function is a sub-function of my_ObjcDraw(). It allows you to draw an object tree in a window with respect to the window workspace. Usually, you don't need to call this function, only mt_ObjcDraw(). See also: mt_ObjcDraw(), mt_ObjcWindChange().

void ObjcStrFmt (  char *  dest, char *  src, int  size )

Troncate a string in order to fit in an object label. Parameters: dest  troncated string, src  string to troncate, size  new lenght of string This function troncate a string in order to fit in an object label. If the string is too long (prior to size parameter), excedented characters are removed at the middle of the string and tree points '...' are inserted. This function is used to format correctly filename or pathname in TEXT objects before displaying the formular.

---