Object Type:
xtree
Description:
Object for displaying and manipulating the relationships
between elements and objects in a simulation. This is an extremely
complex widget designed for building click-and-drag interfaces
within Xodus. The default mode provides a heirarchical
tree display of a simulation. The additional options include
alternative display modes, issuing script calls based on the
source and destinations of mouse-drag operations, and options
for changing the appearance of individual items in the tree.
Xtree is subclassed from pix and can only be displayed in coredraw
or its subclasses.
xtree is not designed to be updated every time step. It is quite
expensive to recalculate. The contents of xtree are updated by
calling the RESET action.
Like xvar and xview, xtree maintains a set of child xshapes named
shape[0], shape[1], ... The items displayed by the xtree use
the coordinate and drawing information in these shapes for display.
When drawing an item, the tree finds a string associated with
the item (usually its object name, see below). It then scans the
list of child shapes to find a match between the 'value' field of
the xshape and this string. The selected shape is used as the icon
for representing the item in the tree. If no match is found,
shape[0]
is used. The child xshape shape[0] is created automatically when
the xtree is created.
The 'items' that the xtree can represent include elements and
objects. In addition to representing these items, xtree can also
display heirarchical (parent-child-sibling) relationships between
them in the form of a tree structure as one of the display options.
Furthermore, xtree can display messages between elements in the
form of arrows.
Display options
Several display options are available:
tree: a heirarchical display, eg, of a directory structure or
a GENESIS heirarchy. Any orientation can be selected.
treenotrunc: ?
custom: The coordinates of the items are user-specified and just
stored in an array.
grid: The items are placed on a rectangular grid or as a single
row or column, as specified by the orientation option.
geometry: The items are located according to their x,y,z coords.
obj_grid: The objects are located on a rectangular grid. This
may be modified depending on the orientation option.
obj_custom: The objects are located according to user-specified
positions.
orientation: Determines two kinds of things: first, the orientation
of the heirarchy in the tree mode. Second, the orientation
and layout of the grid.
In the tree mode the orientation can be one of
u: up - the leaves are up , the root is down
d: down - the leaves are down, the root is up.
l: left - the leaves are on the left, the root on the right.
r: right - the leaves are on the right, the root on the left.
In the grid or obj-grid modes, the orientation can be
u: Grid with horizontal long axis
U: Grid with horizontal long axis and staggered entries.
d: Single column
l: Grid with vertical long axis
r: Single row
R: Single row with staggered entries
m<n>: multiple rows with n entries each.
M<n>: multiple rows with n entries each, staggered in the y
direction to minimize text overlap.
Displaying messages
The tree is frequently used to display messages between elements.
Messages can be displayed in any treemode, except, of course,
between objects. Messages are displayed as arrows which start and
end a few pixels from the item on the screen. If the pair of items
being displayed is very close, the messages are not displayed.
The details of the message display are determined by the MSGARROW
array, which is manipulated using the ADDMSGARROW action.
Executing functions in response to graphical events.
Trees are especially useful for performing drag-and-drop
operations,
though the usual set of actions on the tree is also allowed. The
ADDMSGARROW action, in addition to loading in the specification
for msg display, is also used to set up the script functions to
be performed under various sets of drag-drop operations between
specified object classes.
The ADDMSGARROW action.
As already described, ADDMSGARROW is used both to specify how to
display msgs between elements of particular object-classes, and
also to execute functions in response to particular graphical
operations like drag-and-drop.
The syntax of ADDMSGARROW is:
call tree ADDMSGARROW msgsrc msgdest msgtype msgdesttype fg index
fliparrow script script_add script_drop
msgsrc and msgdest are wildcard paths to two sets of elements.
msgtype is a string defining the type of msg.
msgdesttype is the type of the element at the destination of the
msg
fg is the color of the arrow used to draw the msg
index is for identifying this ADDMSGARROW entry among the array
of other entries. If it is >= 0, the msgarrow
information is placed at the specified index, overwriting
whatever else may have been stored there. If it is
less than 0, the the information is first checked to ensure
that it does not duplicate an existing entry. If not, then
the information is placed in the first free entry.
fliparrow is a flag (0 or 1) to tell the display routines to draw
the arrow backwards. Normally (fliparrow = 0) the arrowhead
points to the destination of the msg.
script, script_add and script_drop are strings with the standard
Xodus syntax for specifying functions and arguments.
The msgsrc and msgdest wildcards are used in two ways. If one is
drawing messages, they are used to specify the elements that the
tree is supposed to check for the sources and the dests of the
message,
respectively. If one is executing functions, then the lists are
scanned to check if the source and dest elms of a drag-drop
operation
lie on the lists. If so, then the function named in "script" is
executed every time; the function named in "script_add" is executed
if
there is NO message of the specified msgtype between the src and
dest,
and the function named in "script_drop" is executed if there is
already a message between src and dest. The intention is that
operations involving creation of messages be specified with the
"script_add", deletion by "script_drop", and other operations by
the
function defined in "script".
SIMULATION PARAMETERS
Function:
XTree [in src/Xodus/widg/xtree.c]
Classes:
gadget output
Actions:
contents.
PROCESS: redraws tree - does NOT check for changes to
RESET:
rebuilds tree from scratch, thereby updating any
changes.
CREATE: Creates the tree and the default child xshape
COPY : currently incomplete
SET: Special handling for the fields
pixflags
sizescale
DELETE: Frees up allocated entries.
DUMP: Saves all the internal information for the tree,
specially the ADMMSGARROW info and the coords of
the display items in certain modes.
UNDUMP: Loads in the information stored using DUMP
ADDMSGARROW: Sets modes for displaying msgs and handling
drag-drop operations. See above.
SHOWMSGARROW: Lists existing msgarrows
MOVECUSTOM: args: elmpath x y z recurse_flag
Handles xyz moves of tree items in custom mode
TRUNCATE: args: elmname [mode]
Applies to treemode 'tree'. Sets truncation of the tree
at the element 'elmname'. If mode is 0, truncation is
turned on. If 1, it is turned off. If -1 (default),
it is toggled.
XUPDATE: update internal fields when
displayed widget is changed.
Xodus actions: handled normally, with the following
exceptions
1. In treemode 'tree', action B1DOUBLE toggles
the truncation of the the tree at the clicked item.
2. Drags and drops are checked against entries
in the msgarrow table to decide if the scriptfuncs
specified by ADDMSGARROW should be called. These
are only called for operations within the same tree.
3. B1DOWN, B2DOWN and B3DOWN are checked against
the hlmode. If it is "one", then one element is
highlit. If it is "multi" then the element is added
to the list of entries to be highlit. If it is "none"
or the default, then no permanent highlight flags are
set.
Messages:
none.
--------------------------------------------------------------------------Notes:
Can only be displayed in a coredraw widget subclass.
Not meant to be clocked.
Examples:
Scripts/examples/XODUS/xtree_example
See also:
xshape, xview