Chart Widgets

The purpose of a chart widget is to control a chart panel. It can do things like

• Open and close deductions

• Pan and zoom

• Show a node or nodes

• Select a node or nodes

• Highlight nodes and/or edges in various colors

Its visual appearance is like a link, i.e. clickable text.

Chart widgets make use of certain special, “compound” data types, which are defined below, under Special data types.

Format

• TYPE: chart

• NAME: Optional.

• LABEL: Required. Appears as clickable text in the page.

• ROLE_FIELD: view

• CONTENT_FIELD: None.

Fields

Required

None.

Optional

Field	Type	Description
color	string	Pass a color spec string, to define highlight colors to be applied to nodes and/or edges. The coloring is applied when users click the widget; see also hoverColor to apply/remove coloring on mouse hover.
coords		Specify the view coordinates directly. If defined, overrides view and viewOpts. Default: undefined
(1)	enum	“fixed”: The view should stay exactly as it is.
(2)	[int, int, float]	Pass array [x, y, zf] to pan to (x, y) and set the zoom factor to zf.
flow	boolean	If true, show flow edges in deducs being opened; if false, suppress them; if undefined, default to current setting in the chart panel. Default: undefined
group	string / int	See Navigation groups.
hoverColor	string	Like color, except the coloring will be applied when users hover their mouse over the widget, and removed when they move their mouse away. Accepts a color spec string just like the color field, except that the update modifier rule cannot be used. This is because hoverColor is always applied as an update, so the command would be meaningless.
layout	enum	Set the layout method to be used in the chart panel. If the set of deductions in the panel is changing (i.e. anything is being opened or closed), then this is the method that will be applied in order to compute the new layout. If not, then a new layout is computed simply to put the desired method into effect. “KLayDown”: Flow chart layout, with downward pointing edges. “KLayUp”: Flow chart layout, with upward pointing edges. “OrderedList1”: List layout (nodes form a vertical list). Default: “KLayDown”
offBoard		Name boxes that should not be present. If offBoard contradicts onBoard or view, it is overruled by them. In other words, putting things on the board is favored over removing them. Default: undefined
(1)	enum	“<all>”: Indicates that you want everything presently on board to be removed.
(2)	boxlisting	Remove the named boxes.
onBoard	boxlisting	Name any list of nodes and/or deductions. The system will ensure that every necessary deduction is on board, to make all these boxes present, opening them as necessary, or leaving them if already there. Default: undefined
select		Say which boxes should be selected. Ordinarily, boxes are selected when the user clicks on them. Selected boxes are marked visually with a highlight, and affect certain things, such as which libpath is displayed (when the panel is in libpath display mode). Default: true if view (see below) is undefined or "<all>"; equal to view when view is a boxlisting.
(1)	boolean	true: keep the selection as it is. false: clear the selection (i.e. no boxes should be selected).
(2)	boxlisting	Select these boxes.
transition	boolean	Specify the desired type of transition, for any and all changes that need to take place, including pan & zoom, as well as opening and closing deductions. true: use a smooth, animated transition. false: jump instantaneously to the new state. Default: true
view		Name boxes that should be viewed, i.e. shown in the controlled chart panel. The same boxes will also be selected unless the select field is defined (see above). The system will automatically ensure first that any boxes to be viewed are actually present, opening deducs as necessary to achieve this, and then will pan and zoom to show these boxes. The view field therefore often makes use of the onBoard field unnecessary (see above). Pan and zoom is automatic, but can be controlled by the viewOpts field (see below). Default: Empty boxlisting.
(1)	enum	“<all>”: View all boxes currently on the board (an “overview”).
(2)	boxlisting	View the named boxes. Note: Unless the select field (see above) is also defined and says otherwise, all boxes listed in view will be selected.
viewOpts	object	Controls how the view is updated to show boxes named in the view field. Fields are defined in separate table below.

viewOpts fields

The chart widget’s viewOpts field controls how the view is updated to show boxes named in the view field.

The value of the viewOpts field is an object. All fields within this object are optional, and are as defined in the table below.

Field	Type	Description
center		Say what to center on, if centering (see panPolicy below). Default: “<all>”
(1)	enum	“<all>”: Center on all boxes on the board. “<core>”: Center on the same boxes named in core. “<named>”: Center on the same boxes named in view.
(2)	boxlisting	Center on these boxes.
core		Nodes that must be viewed, while others may be off-screen if necessary to satisfy the minZoom (see below). Default: “<named>”
(1)	enum	“<named>”: All boxes in view define the core.
(2)	boxlisting	These boxes define the core.
inclNbhd	boolean	Set true to enlarge the view by including all nodes one deduction edge away from those named. Default: false
insetAware	boolean	If true, and if there is an inset pane (such as for an overview) currently obscuring one corner of the panel, then take this into account when determining the view coordinates. If false, work as if there were no inset. Default: true
maxZoom	float	Set the maximum zoom level. This controls how far the view will zoom in, i.e. how large boxes can appear. The view will not be zoomed in any more than maxZoom, even if all the nodes to be viewed could fit in the padded viewbox at a closer zoom level. Default: Depends on the expansion mode. No maximum for chart panels in embedded mode; 1.4 for chart panels in unified mode.
minZoom	float	Set the desired minimum zoom level. This controls how far the view will zoom out, i.e. how small boxes can appear. This is not a hard minimum. If all attempts to fit the whole set of objects to be viewed into the viewbox would require a zoom level less than this value (if set), then an attempt will be made to instead view the core set of objects (see above) at a higher zoom level. Default: No minimum.
panPolicy	enum	Controls whether the boxes to be viewed are centered, or just brought on screen by the minimal movement. “centerAlways”: Always center the boxes that are to be viewed. “centerNever”: Do not center the boxes that are to be viewed. Pan the minimum amount necessary to bring all the boxes into the padded viewbox. “centerDistant”: Center only when we are moving so far that nothing currently in the padded viewbox is going to remain therein. Thus, this policy says that, if we are able to “preserve some context,” then we should aim to preserve as much as possible; however, if we have to move so far away that all context would be lost anyway, then we might as well center the new subject. Default: “centerDistant”
viewboxPaddingPercent	int	Set a variable padding for the viewbox, as a percentage of the corresponding dimension, applied in both the x- and y-dimensions. This is added to the padding resulting from viewboxPaddingPx. Default: 5
viewboxPaddingPx	int	Set a constant padding for the viewbox, in pixels. This is added to the padding resulting from viewboxPaddingPercent. Default: 0

Special data types

In addition to the basic types of int, float, string, boolean, array, object, and libpath that are relevant for all kinds of widgets, for chart widgets we need a couple of special, “compound” data types, built up out of these basic ones.

Multipaths

A multipath is a compact notation with which to denote several libpaths at once.

It is written as a string that is almost the same as a libpath, except that exactly one of its segments is replaced by an expression of the form

{seg_1, seg_2, ..., seg_n}

in which each seg_i is a valid libpath segment.

Thus, a multipath looks like:

prefix.{seg_1, seg_2, ..., seg_n}.postfix

and it represents the n libpaths,

prefix.seg_1.postfix
prefix.seg_2.postfix
...
prefix.seg_n.postfix

For example, this multipath:

Pf.{A10, A20, A30}

expands to the three libpaths Pf.A10, Pf.A20, and Pf.A30, and might refer to three nodes within a deduction.

Boxlistings

When talking about chart widgets, we will say “box” to mean any node or deduction, as displayed in a chart. (Visually, they both appear as boxes.)

By boxlisting we will mean a compound data type that refers to one or more boxes, using any of the following formats:

• a single libpath, as a libpath (see Libpaths),

• a single libpath, as a string,

• a single multipath (which is always a string),

• an array whose elements are any mixture of the above.

For example, each of the following is a valid boxlisting:

Pf.A10
"Pf.A10"
"Pf.{A10, A20, A30}"
[Pf, "Pf.{A10,A20}", Pf.E50.I1]

Color Specs

The chart widget has a couple of fields that allow you to set highlight colors on boxes and edges in chart panels. (See the color and hoverColor fields above.) The value you pass to these fields is a string called a color spec.

Format

The format for a color spec is a multiline string, in which each line defines one color rule or one modifier rule.

A color rule looks like this:

Listing 72 The format of a color rule

CC_1, CC_2, ..., CC_n: BOXLISTING

and it applies a set of color codes CC_i (see below) to a boxlisting.

A modifier rule looks like this:

Listing 73 The format of a modifier rule

MODIFIER

i.e. it simply names a modifier (see below).

Example:

Listing 74 An example color spec string

"""
update
olY, diGB: Pf.{A10,A20}
bgB: Pf.A30
"""

The color spec in Listing 74 starts by naming the update modifier rule (see below). Then it states two color rules. The first sets yellow outline (olY) on nodes A10 and A20 of deduction Pf, and gives incoming deduction edges into these nodes a gradient from green to blue (diGB). The final color rule sets blue background color (bgB) on node A30 in the same deduction.

Modifiers

At this time, there is only one modifier rule:

Modifier

Description

update

Ordinarily, any existing colors on the boxes and edges named in the color rules are cleared before the color rules are applied. The update modifier makes it so that existing colors are not cleared, and the color rules only make changes to those aspects that they directly address. For example, suppose a box had existing red boundary, and red background, and that the rule “blue background” was then applied. Without the update modifier, the final result would be a box with blue background and no boundary color. With the update modifier, the final result would be a box with blue background and the red boundary color still in place from before.

Color codes

Color codes are listed on the left-hand side of a color rule, separated by commas (and optional spaces), as shown in Listing 72. They can set colors either on the boxes named in the boxlisting on the right-hand side of the color rule, or else on the edges incident to those boxes. They can choose from among a fixed palette of colors, as named in Table 14.

Table 14 Color characters

Char:	R	Y	G	B	V
Color:	Red	Yellow	Green	Blue	Violet

Color codes are of two kinds: box codes, and edge codes.

Box codes

A box code names color settings to be applied to every box named in the boxlisting on the right-hand side of the color rule.

A box code is always three characters long. It begins with one of the following two-character sequences:

• ol: Set the box’s outline color.

• bg: Set the box’s background color.

The third character is either 0, to remove any existing color, or else one of the color characters from Table 14.

Examples:

• olB: Make the outline blue.

• bgG: Make the background green.

• bg0: Remove any existing background color.

Edge codes

An edge code names color settings to be applied to the edges incident to all of the boxes named in the boxlisting on the right-hand side of the color rule.

An edge code is either three or four characters long. The first character selects the type of edge to which the rule will apply:

• e: all edges

• d: just deduction edges

• f: just flow edges

The second character selects the direction of the edges to which the rule will apply:

• i: just incoming edges

• o: just outgoing edges

• b: edges in both directions

The third, and possibly fourth, characters set the colors:

• To erase any existing colors from the selected edges, set the third character equal to 0.

• To set a single, solid color on the selected edges, set the third character equal to one of the color characters from Table 14.

• To set a color gradient along the selected edges, set the third and fourth characters equal to two of the color characters from Table 14. The first color will be at the source end of the edges, the second color at the target end (the end with the arrow head).

Examples:

• ebB: Make all edges blue.

• dbG: Make all deduction edges green.

• diVB: Give all incoming deduction edges a gradient from violet to blue.

• fo0: Remove any existing color from outgoing flow edges.