Object Library
[AES Function Reference]

display or modify object trees More...

Functions
short	mt_objc_add (OBJECT *, short Parent, short Child, short *global)
short	mt_objc_change (OBJECT *, short Object, short Res, short Cx, short Cy, short Cw, short Ch, short NewState, short Redraw, short *global_aes)
short	mt_objc_delete (OBJECT *, short Object, short *global_aes)
short	mt_objc_draw (OBJECT *, short Start, short Depth, short Cx, short Cy, short Cw, short Ch, short *global_aes)
short	mt_objc_draw_grect (OBJECT *, short Start, short Depth, const GRECT *r, short *global_aes)
short	mt_objc_edit (OBJECT *, short Object, short Char, short *Index, short Kind, short *global_aes)
short	mt_objc_find (OBJECT *, short Start, short Depth, short Mx, short My, short *global_aes)
short	mt_objc_xfind (OBJECT *, short Start, short Depth, short Mx, short My, short *global_aes)
short	mt_objc_offset (OBJECT *, short Object, short *X, short *Y, short *global_aes)
short	mt_objc_order (OBJECT *, short Object, short NewPos, short *global_aes)
short	mt_objc_sysvar (short mode, short which, short in1, short in2, short *out1, short *out2, short *global_aes)
void	mt_objc_wchange (OBJECT *tree, short obj, short new_state, GRECT *clip, short whandle, short *global)
void	mt_objc_wdraw (OBJECT *tree, short start, short depth, GRECT *clip, short whandle, short *global)
short	mt_objc_wedit (OBJECT *tree, short obj, short key, short *idx, short kind, short whandle, short *global)
short	mt_objc_xedit (OBJECT *tree, short obj, short key, short *xpos, short subfn, GRECT *r, short *global)

---

Detailed Description

display or modify object trees

The Object Library is responsible for the drawing and manipulation of AES objects such as boxes, strings, icons, etc. See earlier in this chapter for a complete discussion of AES objects.

---

Function Documentation

short mt_objc_add (  OBJECT *  tree, short  parent, short  child, short *  global_aes )

establishes a child object's relationship to its parent. Parameters: tree  specifies the object tree to modify. parent  specify the parent object. child  specify the child object to update. global_aes  global AES array Returns: 0 if an error occurred or non-zero otherwise. Since: All AES versions. See also: mt_objc_order(), mt_objc_delete() In order for this function to work, the object to be added must be already be a member of the OBJECT array. This function simply updates the ob_next, ob_head, and ob_tail structure members of OBJECTs in the object tree. These fields should be initialized to NIL (0) in the child to be added.

short mt_objc_change (  OBJECT *  tree, short  object, short  res, short  cx, short  cy, short  cw, short  ch, short  new_state, short  redraw, short *  global_aes )

changes the display state of an object. Parameters: tree  specifies the object tree of the object to modify. object  specifies the object to modify. res  is reserved and should be 0. cx  x-position of the the clipping rectangle if the object is to be redrawn. cy  y-position of the the clipping rectangle if the object is to be redrawn. cw  width of the the clipping rectangle if the object is to be redrawn. ch  height of the the clipping rectangle if the object is to be redrawn. new_state  specifies the new state of the object (same as ob_state). redraw  may be one of the following value: NO_DRAW (0) : the object is not redrawn REDRAW (1) : the object is redrawn. global_aes  global AES array Returns: 0 if an error occurred and non-zero otherwise. Since: All AES versions. See also: mt_objc_draw() In general, if not redrawing the object, it is usually quicker to manipulate the object tree directly.

short mt_objc_delete (  OBJECT *  tree, short  object, short *  global_aes )

removes an object from an object tree. Parameters: tree  specifies the object tree of the object to delete. object  is the object to be deleted. global_aes  global AES array Returns: 0 if an error occurred or non-zero otherwise. Since: All AES versions. See also: mt_objc_add() This function does not move other objects in the tree structure, it simply unlinks the specified object from the object chain by updating the other object's ob_next, ob_head, and ob_tail structure members.

short mt_objc_draw (  OBJECT *  tree, short  start, short  depth, short  cx, short  cy, short  cw, short  ch, short *  global_aes )

renders an AES object tree on screen. Parameters: tree  specifies the object tree to draw start  specifies the object index at which drawing is to begin. depth  specifies 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). cx  x-position of the the clipping rectangle to enforce during drawing. cy  y-position of the the clipping rectangle to enforce during drawing. cw  width of the the clipping rectangle to enforce during drawing. ch  height of the the clipping rectangle to enforce during drawing. global_aes  global AES array Returns: 0 if an error occurred and non-zero otherwise. Since: All AES versions. See also: mt_objc_draw()

short mt_objc_draw_grect (  OBJECT *  tree, short  start, short  depth, const GRECT *  r, short *  global_aes )

see mt_objc_draw() Parameters: tree  see mt_objc_draw() start  see mt_objc_draw() depth  see mt_objc_draw() r  clipping rectangle to enforce during drawing global_aes  global AES array Returns: see mt_objc_draw() Since: see mt_objc_draw()

short mt_objc_edit (  OBJECT *  tree, short  object, short  ch, short *  index, short  kind, short *  global_aes )

allows manual control of an editable text field. Parameters: tree  specifies the object tree containing the editable object object  is the editable object to modify ch  a character to insert, depending of kind. See below. index  pointer to the index (cursor position of the editable object). See below. kind  specifies the action of the call and the meaning of the other parameters as follows: ED_START (0) Reserved for future use. Do not call. ED_INIT (1) Display the edit cursor in the object specified. ch is ignored. The WORD pointed to by index is filled in with the current index of the edit cursor in the field. ED_CHAR (2) A key has been pressed that needs special processing. ch contains the keyboard scan code in the high byte and ASCII code in the low byte. index points to the current index of the text cursor in the field. index will be updated as a result of this call. ED_END (3) Turn off the text cursor. ED_CRSR (100) TO BE COMPLETED (TODO) ED_DRAW (103) TO BE COMPLETED (TODO) global_aes  global AES array Returns: 0 if an error occurred or non-zero otherwise. Since: All AES versions. See also: mt_objc_xedit(), mt_form_keybd() This function is usually used in conjunction with mt_form_keybd() in a custom mt_form_do() handler.

short mt_objc_find (  OBJECT *  tree, short  start, short  depth, short  mx, short  my, short *  global_aes )

determines which object is found at a given coordinate. Parameters: tree  specifies the object tree containing the objects to search start  is the index of the object to start searshing from. depth  specifies the depth in the tree to search (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). mx  specify the x-coordinate to search at. my  specify the y-coordinate to search at. global_aes  global AES array Returns: the object index of the object found at coordinates ( mx, my ) or -1 if no object is found. Since: All AES versions. See also: mt_objc_xfind()

short mt_objc_offset (  OBJECT *  tree, short  object, short *  x, short *  y, short *  global_aes )

calculates the true (absolute) screen coordinates of an object. Parameters: tree  specifies the object tree object  is an object of tree. x  will be filled with the absolute X screen position of object [option CHECK_NULLPTR] x may be NULL y  will be filled with the absolute Y screen position of object [option CHECK_NULLPTR] y may be NULL global_aes  global AES array Returns: 0 if an error occurred or non-zero otherwise. Since: All AES versions. See also: mt_objc_draw() The ob_x and ob_y structure members of objects give an offset from their parent as opposed to absolute screen location. This call is used to determine a absolute screen coordinate (from top left corner of the screen). The values returned by mt_objc_offset() coupled with the ob_width and ob_height members do not take into account negative borders, shadowing, or sculpturing. When redrawing an object you are responsible for using these values to and the object's state to compensate for a correct clipping rectangle. Note: if you call the AES trap by yourself, note that some AES write to intout[3..6]!

short mt_objc_order (  OBJECT *  tree, short  object, short  new_pos, short *  global_aes )

changes the position of an object relative to other child objects of the same parent. Parameters: tree  specifies the object tree object  is the object to be moved new_pos  specifies the new position of the object as follow: OO_LAST (-1) : Make object the last child. OO_FIRST (0) : Make object the first child. 1 : Make object the second child. 2 : etc... global_aes  global AES array Returns: 0 if an error occurred or non-zero otherwise. Since: All AES versions. mt_objc_order() does not actually move structure elements in memory. It works by updating the OBJECT tree's ob_head, ob_tail, and ob_next fields to 'move' the OBJECT in the tree hierarchy.

short mt_objc_sysvar (  short  mode, short  which, short  in1, short  in2, short *  out1, short *  out2, short *  global_aes )

returns/modifies information about the color and placement of 3D object effects. Parameters: mode  determines whether attributes should be read or modified. A value of SV_INQUIRE (0) will read the current values whereas a value of SV_SET (1) will modify the current values. which  determines what attribute you wish to read or modify. see the table below. in1  specifies the 1st new value when modifying values, unused otherwise. in2  specifies the 2nd new value when modifying values, unused otherwise. out1  will be filled by the 1st value when reading value, unused otherwise. [option CHECK_NULLPTR] out1 may be NULL out2  will be filled by the 2st value when reading value, unused otherwise. [option CHECK_NULLPTR] out2 may be NULL global_aes  global AES array Returns: 0 if an error occurred or non-zero otherwise. Since: mt_appl_getinfo() with mode AES_OBJECT gives the availability of this function. which in1 / out1 in2 / out2 LK3DIND (1) If 1, the text of indicator objects does move when selected, otherwise, if 0, it does not. If 1, the color of indicator objects does change when selected, otherwise, if 0, it does not. LK3DACT (2) Same as LK3DIND for activator objects. Same as LK3DIND for activator objects. INDBUTCOL (3) specifies the default color for indicator objects. unused. ACTBUTCOL (4) specifies the default color for activator objects. unused. BACKGRCOL (5) specifies the default color for background objects. unused. AD3DVAL (6) specifies the number of extra pixels on each horizontal side of an indicator or activator object needed to accomodate 3D effects. This setting may only be read, not modified. specifies the number of extra pixels on each vertical side of an indicator or activator object needed to accomodate 3D effects. This setting may only be read, not modified. MX_ENABLE3D (10) If 1, the 3D look is enabled. Set to 0 to disable the 3D-look. (Since MagiC 3) set to 0 to disable the 3D look (Since MagiC 3) MENUCOL (11) TO BE COMPLETED (TODO) TO BE COMPLETED (TODO) Applications should not use mt_objc_sysvar() to change these settings since all changes are global. Only CPXs or Desk Accessories designed to modify these parameters should.

void mt_objc_wchange (  OBJECT *  tree, short  obj, short  new_state, GRECT *  clip, short  whandle, short *  global_aes )

Alter object status and redraw object Parameters: tree  as for mt_objc_change() obj  as for mt_objc_change() new_state  as for mt_objc_change() clip  NULL => whole window whandle  window handle global_aes  global AES array Since: Magic 5.10 This call is equivalent to mt_objc_change() without a redraw followed by mt_objc_wdraw().

void mt_objc_wdraw (  OBJECT *  tree, short  start, short  depth, GRECT *  clip, short  whandle, short *  global_aes )

Draw object(tree) Parameters: tree  as for mt_objc_draw() start  as for mt_objc_draw() depth  as for mt_objc_draw() clip  clipping area applied when drawing the tree. If clip is NULL, then this function will take the work area of the window as clipping area. whandle  window handle global_aes  global AES array Since: MagiC 5.10

short mt_objc_wedit (  OBJECT *  tree, short  obj, short  key, short *  idx, short  kind, short  whandle, short *  global_aes )

Text field input for window dialogs Parameters: tree  as for mt_objc_edit() obj  as for mt_objc_edit() key  as for mt_objc_edit() idx  as for mt_objc_edit() kind  as for mt_objc_edit() whandle  window handle global_aes  global AES array Returns: as for mt_objc_edit() Since: MagiC 5.10

short mt_objc_xedit (  OBJECT *  tree, short  obj, short  key, short *  xpos, short  subfn, GRECT *  r, short *  global_aes )

Parameters: tree  see mt_objc_edit() obj  see mt_objc_edit() key  see mt_objc_edit() xpos  see mt_objc_edit() subfn  see mt_objc_edit() r  is the clipping area used when drawing global_aes  global AES array Returns: Since:

short mt_objc_xfind (  OBJECT *  tree, short  start, short  depth, short  mx, short  my, short *  global_aes )

determines which object is found at a given coordinate. Parameters: tree  specifies the object tree containing the objects to search start  is the index of the object to start searshing from. depth  specifies the depth in the tree to search (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). mx  specify the x-coordinate to search at. my  specify the y-coordinate to search at. global_aes  global AES array Returns: the object index of the object found at coordinates ( mx, my ) or -1 if no object is found. See also: mt_objc_find() The Difference between this function and mt_objc_find() is it, that not the normal rectangle of the OBJECT, but the outer rectangle is used, so that this function handles the border of the OBJECTs.   Since: The existence of this function can be checked with mt_appl_getinfo() with AES_PCGEM mode.

---