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.

Among all the widget types, the chart widget offers perhaps the most complex set of available options, but it is very simple to use in the most common usage patterns.

In its most commonly used form, a chart widget defines just the view field, and the value lists one or more nodes. Clicking the widget causes those nodes to be viewed.

In other forms, chart widgets provide a lot of power, for “pointing to,” “narrating,” and guiding users through a chart in various ways.

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 few special data types.

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

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 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
an array of multipaths and/or libpaths, given as strings

Format#

TYPE: chart
LABEL: Yes. Provide the clickable text you want to appear in the annotation.

Fields#

Attention

UNDER CONSTRUCTION!

This section is a work in progress.

Please check back again soon!

Field	Req	Type	Description
`view`	N		Name boxes that should be “viewed,” and optionally control how the viewbox is updated. Also affects the node selection unless `select` field is also defined (see below). 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 update the viewbox to show these boxes. The `view` field therefore often makes use of the `on_board` field unnecessary (see below). The `view` field has both a simple form and a complex form. In the simple form, its value is not an object; in the complex form, its value is an object, whose possible fields are defined below. Use the simple form when you are happy for the system to determine how to update the viewbox automatically; use the complex form in order to control the way the viewbox is updated. Default: Empty boxlisting

		enum	“<all>”: View all boxes currently on the board (an “overview”).

		boxlisting	View the named boxes. Note: Unless the `select` field (see below) is also defined and says otherwise, all boxes listed in `view` will be selected.

		object	(see below)

`view.objects`	Y	mixed	Accepts the same values as the simple (non object) `view` field, with the same meaning.

`view.incl_nbhd`	N	bool	If `true`, automatically add the full deductive neighborhood of each node named in `view.objects`. Default: `false`

`view.zoom_range`	N	array	Array of floats, of length exactly two. The first sets the minimum acceptable zoom level, the second the maximum acceptable zoom level. Default: The zoom can be adjusted however necessary to make the desired boxes visible.

`view.core`	N	boxlisting	Nodes that must be viewed, while others may be off-screen if need be to satisfy the `zoom_range`. Default: All boxes in `view.objects` define the core.

`view.pan_policy`	N	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”

`view.center`	N		Say what to center on, if centering. Default: “all”

		enum	“<all>”: Center on all boxes on the board. “<core>”: Center on the same boxes named in `view.core`.

		boxlisting	Center on these boxes.

`view.viewbox_padding_px`	N	int	Set a constant padding for the viewbox, in pixels. Default: 0

`view.viewbox_padding_percent`	N	int	Set a variable padding as a percentage of the corresponding viewbox dimension (x or y). Default: 5