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