A pane that displays a tree of items in a "stacked" drawing, where each item has an associated value and child items that represent a fraction of that value. Each item is displayed as a rectangle whose width corresponds to the value. Child items are displayed below the item to make a stack of rectangles.
stacked-tree is a subclass of output-pane, which displays a tree of items in a "stacked" drawing. In a stacked drawing, each item of the tree is represented by a horizontal rectangle. The height of the rectangle is fixed to accommodate the height of the font of the
stacked-tree, while the width corresponds to the "value" of the item. The children of each item are drawn side-by-side below the item itself, to make a stack of rectangles ("stacked").
Within each item's rectangle, the
stacked-tree displays a label, consisting of the item's name (the third value of
, see below) and the percentage of the item's value with respect to the value of the
stacked-tree. The name and/or percentage are omitted if the rectangle is not wide enough.
specify the tree that the
stacked-tree is displaying.
can be initialized by the
:root initarg or set by using
(setf stacked-tree-root) or modify-stacked-tree. Likewise,
can be initialized by the
:item-function initarg or set by using
(setf stacked-tree-item-function) or modify-stacked-tree. The
to traverse the tree starting from
is a positive
real, it specifies the item's value, which affects the width of the rectangle used to represent it. If
nil, then the
stacked-tree computes the value as the sum of the values of the
is not positive, then the item is ignored.
A string or
is non-nil, the string representation of it (the result of calling the
inherited from collection) is displayed within the rectangle. Just the rectangle is displayed if
Both root and elements of item-children returned by item-function can be any object. The only requirement is that item-function returns useful values when called with this object. Thus the tree is completely defined by root and by what item-function returns.
Note: Currently there is nothing else to stop the descent down the tree, so you must either have a finite tree, that is your
nil as the
at some level on every branch, or you must supply a non-nil
is non-nil, it specifies the value on which to base the percentage computations when displaying items. If
nil or not specified, it defaults to the
, which is the natural value in many cases, but not always. For example, the Profiler tool in the LispWorks IDE uses a
that is the number of times that the profiling was done, while the
is the sum of the number of times that each process was profiled, which will be much larger when you profile more than one process.
is non-nil, then
is called for each item, the first time the item is displayed, with two arguments: the
stacked-tree and the item. It must return a color specification (a color-spec or a recognized symbol, see The Color System), which is then used as the background color of the rectangle for the item.
defaults to a plausible list of colors, so it does not need to be specified. If it supplied, it must be a list of color specifications. The
stacked-tree selects a random color from this list for each item the first time the item is displayed.
is non-nil, it is called when the user moves the mouse over the
stacked-tree, with three arguments: the
stacked-tree, the item associated with the rectangle at the mouse position or
nil if the mouse is not over any rectangle, and a vector specifying the coordinates of the item (or
nil if the item is
nil). The vector contains eight elements:
The width in pixels of the label that should be displayed (as returned by get-string-extent when called with the label).
are implemented by defining the
:motion gesture in the
stacked-tree. If you supply an
:motion (see output-pane), then this will override the internal one, so
will never be called and
will not have any effect.
, if non-nil, should be a string. The default is "Empty STACKED-TREE displayer". It is displayed in the
stacked-tree if you set
nil, or when a non-positive
is returned when
is called on
is non-nil, it is called when the context menu needs to be raised (normally by right-click of the mouse), with two arguments: the
stacked-tree and the selected item (or
nil if none is selected). It should return a menu, menu-component or
returns a menu, then it is used as the context menu. If it returns a menu-component, LispWorks makes a menu containing the component followed by the default
stacked-tree menu (described later). If it returns
nil, LispWorks raises the default
stacked-tree menu. If
nil, LispWorks also raises the default
is called from the make-pane-popup-menu method of
stacked-tree. You can completely override this by using the
:pane-menu initarg (see Popup menus for panes), or by defining your own make-pane-popup-menu method specializing on
stacked-tree and your own interface class.
Note: When the menu is raised as a result of a mouse click within a rectangle that is associated with an item then this item is selected while the menu is visible. When the menu has been dismissed, if the contents and the selection of the
stacked-tree are still the same, then the selection goes back to the item that was selected before the mouse click.
Some features of
stacked-tree are inherited from output-pane as described here.
stacked-tree implements its user input interaction (see below) using the
of output-pane. If you supply the
:input-model initarg, its value will be appended before the internal input-model of
stacked-tree, so your callbacks will override the internal ones. Note that this affects all interaction, including selection of an item. Your input-model callbacks can use stacked-tree-item-at-point to find the item at the x,y coordinates.
Some features of
stacked-tree are inherited from choice as described here.
The selection-callback and action-callback (inherited from callbacks) can be used, and are called due to the input-model as described above.
In the following discussion,
is the width in pixels of the rectangle used to display
is changed (and initially),
is set such that width of the rectangle used to display
is the visible width of the
Left-double-click on a item changes the
such that the width of the clicked item's rectangle matches the visible width of the
stacked-tree, and scrolls horizontally such that the item's rectangle starts at the left of the
The arrow keys change the selected item in the direction indicated if possible. The
Down key moves to the first child of the currently selected item (if any). The
Right keys move to the item at the same depth if there is any, which may be on a completely different branch of the tree.
Go to the previous or next state of the display. Whenever the
changes or the user left-clicks, the
stacked-tree records the current state of the display, including the
and scroll position. It uses a ring of length 50 for this record.
Ctrl-f rotate around this ring.
Try to increment or decrement the font size by one point, and if this fails then try changing the font size by two points. If the font size changes then the height of the rectangles is adjusted to fit the new font height.
stacked-tree context menu contains items to perform the operations listed for keyboard interaction above. It is intended mainly as a way for the user to find the keyboard interaction shortcut. Note that if you override the input-model, and you redefine some of the keys, the menu will be confusing and you should replace it by your own menu.
stacked-tree is useful when the values of an item's children sum to the value of the item itself or less. If the values of the children sum to more than the value of the item, they will overflow to the right of the item and clash with the children of the item's next sibling.
(setf stacked-tree-root) or modify-stacked-tree is used to set the
stacked-tree that is already displayed, it immediately computes an internal representation by traversing the tree. This means that if the tree is big, this operation may take enough time to cause a noticeable delay.
CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017