GEMLIB  0.44.0
Macros | Functions

display or modify object trees More...

Macros

#define objc_add(a, b, c)   mt_objc_add(a,b,c,aes_global)
 
#define objc_change(a, b, c, d, e, f, g, h, i)   mt_objc_change(a,b,c,d,e,f,g,h,i,aes_global)
 
#define objc_delete(a, b)   mt_objc_delete(a,b,aes_global)
 
#define objc_draw(a, b, c, d, e, f, g)   mt_objc_draw(a,b,c,d,e,f,g,aes_global)
 
#define objc_draw_grect(a, b, c, d)   mt_objc_draw_grect(a,b,c,d,aes_global)
 
#define objc_edit(a, b, c, d, e)   mt_objc_edit(a,b,c,d,e,aes_global)
 
#define objc_find(a, b, c, d, e)   mt_objc_find(a,b,c,d,e,aes_global)
 
#define objc_xfind(a, b, c, d, e)   mt_objc_xfind(a,b,c,d,e,aes_global)
 
#define objc_offset(a, b, c, d)   mt_objc_offset(a,b,c,d,aes_global)
 
#define objc_order(a, b, c)   mt_objc_order(a,b,c,aes_global)
 
#define objc_sysvar(a, b, c, d, e, f)   mt_objc_sysvar(a,b,c,d,e,f,aes_global)
 

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.

Macro Definition Documentation

#define objc_add (   a,
  b,
 
)    mt_objc_add(a,b,c,aes_global)

single-thread version of mt_objc_add()

#define objc_change (   a,
  b,
  c,
  d,
  e,
  f,
  g,
  h,
 
)    mt_objc_change(a,b,c,d,e,f,g,h,i,aes_global)

single-thread version of mt_objc_change()

#define objc_delete (   a,
 
)    mt_objc_delete(a,b,aes_global)

single-thread version of mt_objc_delete()

#define objc_draw (   a,
  b,
  c,
  d,
  e,
  f,
 
)    mt_objc_draw(a,b,c,d,e,f,g,aes_global)

single-thread version of mt_objc_draw()

#define objc_draw_grect (   a,
  b,
  c,
 
)    mt_objc_draw_grect(a,b,c,d,aes_global)

single-thread version of mt_objc_draw_grect()

#define objc_edit (   a,
  b,
  c,
  d,
 
)    mt_objc_edit(a,b,c,d,e,aes_global)

single-thread version of mt_objc_edit()

#define objc_find (   a,
  b,
  c,
  d,
 
)    mt_objc_find(a,b,c,d,e,aes_global)

single-thread version of mt_objc_find()

#define objc_offset (   a,
  b,
  c,
 
)    mt_objc_offset(a,b,c,d,aes_global)

single-thread version of mt_objc_offset()

#define objc_order (   a,
  b,
 
)    mt_objc_order(a,b,c,aes_global)

single-thread version of mt_objc_order()

#define objc_sysvar (   a,
  b,
  c,
  d,
  e,
 
)    mt_objc_sysvar(a,b,c,d,e,f,aes_global)

single-thread version of mt_objc_sysvar()

#define objc_xfind (   a,
  b,
  c,
  d,
 
)    mt_objc_xfind(a,b,c,d,e,aes_global)

single-thread version of mt_objc_xfind()

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
treespecifies the object tree to modify.
parentspecify the parent object.
childspecify the child object to update.
global_aesglobal 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 (-1) 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
treespecifies the object tree of the object to modify.
objectspecifies the object to modify.
resis reserved and should be 0.
cxx-position of the the clipping rectangle if the object is to be redrawn.
cyy-position of the the clipping rectangle if the object is to be redrawn.
cwwidth of the the clipping rectangle if the object is to be redrawn.
chheight of the the clipping rectangle if the object is to be redrawn.
new_statespecifies the new state of the object (same as ob_state).
redrawmay be one of the following value:
  • NO_DRAW (0) : the object is not redrawn
  • REDRAW (1) : the object is redrawn.
global_aesglobal 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
treespecifies the object tree of the object to delete.
objectis the object to be deleted.
global_aesglobal 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
treespecifies the object tree to draw
startspecifies the object index at which drawing is to begin.
depthspecifies 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).
cxx-position of the the clipping rectangle to enforce during drawing.
cyy-position of the the clipping rectangle to enforce during drawing.
cwwidth of the the clipping rectangle to enforce during drawing.
chheight of the the clipping rectangle to enforce during drawing.
global_aesglobal 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
treesee mt_objc_draw()
startsee mt_objc_draw()
depthsee mt_objc_draw()
rclipping rectangle to enforce during drawing
global_aesglobal 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
treespecifies the object tree containing the editable object
objectis the editable object to modify
cha character to insert, depending of kind. See below.
indexpointer to the index (cursor position of the editable object). See below.
kindspecifies 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_aesglobal 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
treespecifies the object tree containing the objects to search
startis the index of the object to start searshing from.
depthspecifies 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).
mxspecify the x-coordinate to search at.
myspecify the y-coordinate to search at.
global_aesglobal 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
treespecifies the object tree
objectis an object of tree.
xwill be filled with the absolute X screen position of object
[option CHECK_NULLPTR] x may be NULL
ywill be filled with the absolute Y screen position of object
[option CHECK_NULLPTR] y may be NULL
global_aesglobal 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
treespecifies the object tree
objectis the object to be moved
new_posspecifies 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_aesglobal 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
modedetermines 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.
whichdetermines what attribute you wish to read or modify. see the table below.
in1specifies the 1st new value when modifying values, unused otherwise.
in2specifies the 2nd new value when modifying values, unused otherwise.
out1will be filled by the 1st value when reading value, unused otherwise.
[option CHECK_NULLPTR] out1 may be NULL
out2will be filled by the 2st value when reading value, unused otherwise.
[option CHECK_NULLPTR] out2 may be NULL
global_aesglobal 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
treeas for mt_objc_change()
objas for mt_objc_change()
new_stateas for mt_objc_change()
clipNULL => whole window
whandlewindow handle
global_aesglobal 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
treeas for mt_objc_draw()
startas for mt_objc_draw()
depthas for mt_objc_draw()
clipclipping area applied when drawing the tree. If clip is NULL, then this function will take the work area of the window as clipping area.
whandlewindow handle
global_aesglobal 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
treeas for mt_objc_edit()
objas for mt_objc_edit()
keyas for mt_objc_edit()
idxas for mt_objc_edit()
kindas for mt_objc_edit()
whandlewindow handle
global_aesglobal 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
treesee mt_objc_edit()
objsee mt_objc_edit()
keysee mt_objc_edit()
xpossee mt_objc_edit()
subfnsee mt_objc_edit()
ris the clipping area used when drawing
global_aesglobal 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
treespecifies the object tree containing the objects to search
startis the index of the object to start searshing from.
depthspecifies 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).
mxspecify the x-coordinate to search at.
myspecify the y-coordinate to search at.
global_aesglobal 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.