WinDom: Object Library

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

# 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.