DEXiTree v0.94
==============

DEXiTree is a utility program for DEXi, a computer program for
qualitative multi-attribute decision modeling. DEXiTree makes drawings
of DEXi's decision models, displaying the tree structure and names of
attributes. DEXiTree is an interactive Windows program with which you
can:

1. Load a DEXi model from a DEXi (.dxi) file;
2. Interactively design the drawing by
   - choosing between four tree-drawing algorithms,
   - selecting the drawing direction, and
   - modifying an extensive set of drawing parameters;
3. Save the drawing to a file, or copy the drawing to clipboard for
   transferring to other Windows applications.

Drawings are rendered in two graphic formats:

- Windows Enhanced Metafile (.emf) [vector graphic format],
- Windows Bitmap (.bmp) [bitmap graphic format].

DEXiTree uses its own XML-based "DEXiTree" (.dxt) file format for
storing the current tree structure and drawing parameters. DEXiTree can
both load and save the .dxt files.


DEXiTree Menu Commands
----------------------

File/Open:
  With this command, DEXiTree can load a:
  - DEXi file (.dxi), from which it reads the strucure and names of
    attributes; or
  - DEXiTree file (.dxt), from which it can read:
    - both the tree structure and tree-drawing parameters,
    - only tree structure (using the current tree-drawing parameters), or
    - only tree-drawing parameters (using the currently displayed tree).

File/Save:
  Save the drawing to a file defined previously by File/Save As...

File/Save As...:
  The current drawing can be saved either:
  - graphically in one of the two graphic formats
    (Enhanced Metafile or Bitmap), or
  - textually on an XML-based DEXiTree file.

Edit/Copy:
  Copy the current drawing to Windows Clipboard. The drawing is copied
  in both graphic formats. Use commands such as Paste Special... in
  Microsoft Word to select the format for pasting.

Help/About...:
  Displays some basic information and current version of DEXiTree.


Tree-Drawing Directions
-----------------------

DEXiTree can draw trees in four different directions: Top-Down,
Left-Right, Bottom-Up and Right-Left. The Top-Down direction places the
root of the tree at the top of the drawing and branches the tree
downwards. The other three directions in turn correspond to 90-degree
counter-clockwise rotations of the tree structure. Displayed text,
however, is never rotated. [See also the "Mirror" parameter below.]


Tree-Drawing Algorithms
-----------------------

DEXiTree uses four different tree-drawing algorithms [4]:

1. Distribute

For Top-Down and and Bottom-Up drawings, this algorithm horizontally
distributes leaves of the tree so that each leaf occupies its own
vertical "band". This algorithm works especially well for Left-Right and
Right-Left drawings, where each leaf occupies one "line" of the drawing.

2. Align

The same as "Distribute", except that all leaves are aligned at the same
(lowest) level of the drawing.

3. Walker

This is an implementation of the Walker's algorithm [1], which is
particularly suitable for Top-Down and Bottom-Up drawings. In principle,
this algorithm tries to "shrink" the displayed tree by moving sub-trees
together as close as possible while maintaining some tree-drawing
"aesthetic criteria" [2, p.5].

4. QP

This is my own version of a "stress-minimization" algorithm that
positions tree nodes by solving a constrained quadratic minimization
problem (also known as "Quadratic Programming") [3]. Typically, this
algorithm uses the available drawing space very efficiently and makes
pleasant drawings, even though it may violate some "aesthetic criteria".


Tree-Drawing Parameters
-----------------------

On the right-hand side of DEXiTree, there are two pages, "Tree" and
"Node", on which you can define and modify a number of parameters that
affect the appearance of tree and its components. The "Node" page has
two sub-pages: "Graphic" and "Text".


_Tree_

The "Tree" page parameters affect the placement of the tree as a whole.


Stretch:
  Percentage of additional horizontal and vertical stretching of the drawing.

Picture borders:
  Additional pixels added at each side of the drawing.

Separation: [all units are in pixels]
  Node:
    Separation of two adjacent nodes. More precisely: horizontal
    separation for Top-Down and Bottom-Up drawings, and vertical
    separation for Left-Right and Right-Left drawings.
  Level:
    Separation of two adjacent levels.
  Min. level:
    Minimum distance between two node boxes that appear at adjacent
    levels. This applies when node boxes become too large (e.g., due to
    displayed text) to fit between the "Levels".
  Apply Min. level:
    Check to activate "Min. level".

Placement:
  Align parents:
    When checked, each parent is placed centrally above all of its
    descendants in the tree. Otherwise, it is centered only above its
    immediate descendants ("sons"). "Align parents" does not work with
    the "QP" algorithm.
  Mirror:
    Mirror the whole tree. This is especially useful for Left-Right
    drawings so that the leaves appear in the "logical" top-down order.

Background color:
  This button activates a dialog for selecting the background color of
  the whole drawing.


_Node_

The "Node" page controls the display of tree nodes. It has two
sub-pages: "Graphic" and "Text".

At the top of the "Node" page, you can select the class of nodes or a
specific node to which the displayed tree-drawing parameters apply. The
node classes are:

- "all": whole tree;
- "basic": basic attributes - leaves of the tree;
- "aggregate": aggregate attributes - internal nodes;
- "link": DEXi's "linked atributes"
  (in DEXiTree, these are treated as a special class of leaves).

Using the same controls, you can assign any of the above classes to any
of the nodes in the tree. Also, you can assign the class "individual" to
any of the nodes, which will allow you to set the drawing parameters
specifically for that node.


_Node/Graphic_

This sub-page defines graphical properties for displaying tree nodes.

Dimensions:
  Set the minimum and maximum dimensions of the node "box" [in pixels].
  When the minimum and maximum are different, the actual "box"
  dimensions are determined according to the text displayed in the box.

Parent line:
  Opens a dialog to set the style, width and color of the line that
  connects the current node (or node class) with its parent node(s).

Shape...:
  Opens a dialog to define the shape that graphically represents the
  node(s): shape type (rectangle, ellipse or rounded box), border line
  (style, width and color of the line) and fill pattern (style and
  color).

Node alignment:
  Refers to how nodes of different dimensions (such as heights) are
  positioned at one level, that is, whether they are aligned at their
  top, middle or bottom.

Rounded edges:
  These controls define the rounding of edges when node shape is a
  rounded rectangle. The rounding can be specified either in pixels or
  percentage of the whole width or height of the rectangle.

Top anchor:
  Defines the originating point position for the line that connects this
  node with its parent. The point is defined relative to the node "box"
  and can be expressed in terms of pixels or percentage.

Bottom anchor:
  Similar to "Top anchor", except that it refers to lines that connect
  the node with its descendants in the tree.


_Node/Text_

This sub-page defines properties of text that is displayed within tree
nodes.

Text borders:
  Defines internal borders [in pixels] that separate displayed text from
  the surrounding node rectangle.

Format:
  Wrap:
    When checked, the text can be wrapped so as to fit into the node "box".
  Clip:
    When checked, only the text within the "box" is displayed. Any text
    or part of text that does not fit into the box is not displayed.
  Trim to:
    Here you can specify the maximum number of displayed characters.
    This is useful for trimming long node text.
  Line space:
    For wrapped text, specify line spacing. 100% refers to single spacing.

Position:
  Nine buttons for specifying text position. Horizontally, the displayed
  text can be left-justified, centered or right-justified. Vertically,
  the text can top-aligned, centered or bottom-aligned.

Font:
  Define font of the text.

Edit:
  Edit the text that is displayed in the current node.


References
----------

[1] John Q. Walker II. Positioning nodes for general trees.
    Software—Practice and Experience, 10(7):553–561, July 1980.
[2] Giuseppe Di Battista, Peter Eades, Roberto Tamassia, Ioannis Tollis.
    Annotated Bibliography on Graph Drawing Algorithms. Computational
    Geometry: Theory and Applications  4, 235-282, 1994.
[3] Tim Dwyer, Yehuda Koren, Kim Marriott. Drawing Directed Graphs Using
    Quadratic Programming. IEEE Transactions on Visualization and
    Computer Graphics, 12(4), July/August 2006.
[4] Marko Bohanec. DEXiTree: A program for pretty drawing of trees.
    Proc. Information Society IS 2007, Ljubljana, 8-11, 2007.
    http://kt.ijs.si/MarkoBohanec/pub/IS2007_DEXiTree.pdf    


Web Pages
---------

DEXiTree: http://kt.ijs.si/MarkoBohanec/dexitree.html
DEXi:     http://kt.ijs.si/MarkoBohanec/dexi.html


Version Info
------------

DEXiTree v0.91: [October 2007]
- First public release

DEXiTree v0.93: [September 2008]
- Moved to Delphi 2007
- Bug fixes:
  - Positioning of "Graphic" and "Text" tabs on small screens
  - Scroll bar handling
  - Tree image size allocation, which resulted in the error:
    "Not enough storage is available to process command"

DEXiTree v0.94: [December 2014]
- Moved to Delphi XE7
- Moved to DEXi 4.01 software base
- .dxt files: added saving/loading tree-drawing directions and algorithms


LICENSE
=======

Except where otherwise noted, all of the documentation and software
included in the DEXiTree distribution package is copyrighted by Marko
Bohanec.

Copyright (C) 2007-2015 Marko Bohanec. All rights reserved.

This software is provided "as-is," without any express or implied
warranty. In no event shall the author be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
and to redistribute it, provided that all redistributions, in text and
binary form, retain all copyright notices and web site addresses that
are currently in place, and include this DEXiTree.txt file without
modification.

If you use this software for any purpose, an acknowledgment in your
product and an informative message to the author would be appreciated.
Please cite [4] in your publications.


Marko Bohanec
marko.bohanec AT ijs.si
http://kt.ijs.si/MarkoBohanec/mare.html
