Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

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.


Generated on Wed Nov 3 22:42:20 2004 for GEMLIB by  doxygen 1.3.9.1