graphtoolbar¶

The graphtoolbar command creates an Rbc graph megawidget with an optional toolbar or context-menu control surface and a set of coordinated interactive graph-navigation facilities.

The graph itself is a normal Rbc graph, barchart, stripchart, or polar widget. The megawidget adds:

Drag-selection zoom.
Mouse-wheel zoom.
Plot-area panning.
Reversible navigation history shared by zoom and pan operations.
Current-position and closest-element crosshair annotations.
Polar and Smith-chart coordinate displays.
Interactive linear/logarithmic axis toggling.
Interactive two-state or three-state legend entries.
PNG snapshots, PostScript, SVG and PDF output.
Either a permanently visible toolbar or a right-click context menu.

Load this optional package with package require rbc::graphtoolbar. It loads rbc, Tk, and argparse. An installed argparse package is preferred. When argparse is missing, the toolbar loads its bundled Tcl-only argparse 0.65 implementation. Errors from an installed package are reported without switching to the fallback. The bundled copy is private to toolbar loading; it is not registered in pkgIndex.tcl. Plain package require rbc provides the native widgets without loading the toolbar or requiring argparse. Require the toolbar package before importing ::rbc::* so the import includes the toolbar command.

The command is exported from the ::rbc namespace and may normally be used as:

package require rbc::graphtoolbar
::rbc::graphtoolbar .gtb ?option ...?

or, after importing the Rbc commands:

package require rbc::graphtoolbar
namespace import ::rbc::*
graphtoolbar .gtb ?option ...?

Basic example¶

The following creates a normal graph with rectangle zoom, wheel zoom, panning, crosshair annotations, active legend entries, and interactive axis scale selection:

package require Tk
package require rbc::graphtoolbar

::rbc::graphtoolbar .gtb -width 800 -height 500 -zoom -zoomwheel -pan -crosshairs -crosshairsmode closest -scaletoggle all -activelegend

pack .gtb -fill both -expand yes
.gtb graph configure -title {Interactive graph}
.gtb graph element create trace -data {0 0 1 1 2 4 3 9 4 16}

graph forwards the remaining arguments directly to the embedded Rbc graph widget. The graph pathname can alternatively be obtained with:

set graph [.gtb subwidget graph]

Stacked-track interaction¶

Select -type trackgraph to use the same controls with named tracks; see ::rbc::TRACKGRAPH for the native API. Create tracks and their axes through the embedded graph command, then enable scale toggling for the custom axis names:

package require rbc::graphtoolbar
rbc::graphtoolbar .gtb -type trackgraph -interactive -crosshairsmode current
set g [.gtb subwidget graph]
$g axis create volts -min -1 -max 1
$g axis create amps -min -10 -max 10
$g track create voltage -yaxes volts
$g track create current -yaxes amps
$g line create v -track voltage -mapy volts -data {0 -1 5 1 10 -1}
$g strip create i -track current -mapy amps -data {0 10 5 -10 10 10} -linewidth 2
$g configure -trackresize yes
.gtb setAxisActiveScale all
pack .gtb -fill both -expand yes

Box zoom changes all used shared X axes and all Y axes owned by the starting track. The selection rectangle and its corner annotations stay inside that track, even when the pointer crosses another row.
Pan changes the shared X axes and the starting track’s Y axes for the whole drag.
Wheel zoom inside a track changes shared X axes and that track’s Y axes. Over an axis it changes only that axis, using the usual axis-targeting rules. Empty tracks permit shared-X wheel zoom and pan; box zoom requires at least one owned Y axis.
Previous view and Reset view restore the axes saved by navigation, by name. Reordering tracks does not change their identity. An axis deleted after navigation is skipped during restoration; unrelated rows’ limits are not restored by an entry that did not affect them.
Current point reports shared visible X axes and the pointed track’s visible Y axes. When every owned Y axis is hidden, its first Y axis is used. Closest point searches the pointed track’s elements. Text, backgrounds and point markers are clipped to their owning row. Gaps have no coordinate annotation.
Active legend operates on the global legend and any visible track-local legends. Scale toggling operates on each enabled axis separately. -interactive initially enables scale toggling for x and y; call setAxisActiveScale all after creating custom axes, or pass an explicit list of names. Newly created axes are not automatically added to that list.

Separator gaps do not start toolbar navigation. Native separator dragging remains available when -trackresize yes is configured. Changing track order, ownership, weights, minimum heights, orientation, or widget size during a box selection or pan cancels the gesture on its next motion or release. A cancelled pan restores its saved limits. Toolbar and context-menu modes share these behaviors, including -controlmode both.

Track zoom boxes use clipped redraws, including when -zoomboxopts {-xor yes} selects native XOR drawing. With -invertxy yes, tracks become columns: shared X navigation is vertical and local Y navigation is horizontal. Point selection and separator dragging follow the columns. Window markers retain ordinary graph overlap behaviour.

Show a local legend with $g track legend voltage configure -hide no. Active-legend bindings are added for tracks created after the toolbar, once graph changes are displayed. Existing nonempty custom local bindings are preserved. Box zoom and pan do not start over local legend rectangles, and coordinate annotations are suppressed there. Global and local legends remain independently configurable; hide the global legend explicitly if only local legends are desired. See ::rbc::LEGEND and demos/trackgraph2.tcl.

Control surfaces¶

Use -interactive to enable the standard graph interactions with their defaults:

::rbc::graphtoolbar .gtb -interactive

This is shorthand for -zoom -pan -zoomwheel -crosshairs -activelegend -scaletoggle {x y}. Explicit feature options override the defaults, before or after -interactive. For example, -interactive -scaletoggle x -activelegendmode show-hide limits scale toggling to X and selects the two-state legend cycle. Providing -scaletoggle {} disables scale toggling. The switch selects features at construction time; it does not change the control mode.

-controlmode toolbar creates a visible toolbar. One Export menu button is always present, with PNG snapshot…, PostScript…, SVG…, and PDF… choices. Enabling -zoom adds Reset view and Previous view controls. Enabling -crosshairs adds one Crosshairs menu button. Its Crosshairs mode submenu selects Current point, Closest point, No marker, or Disabled. Its Closest crosshairs format submenu is enabled only in Closest point mode. Formats follow the current graph representation, including Polar radians/degrees and configured Custom text.

Toolbar instances with -crosshairs expose crosshairsMenuButton and crosshairsMenu through subwidget. These replace the former crosshair comboboxes and their labels. Menu selections and configuration properties stay synchronized; changing representation updates the available formats when the menu is opened.

-controlmode contextmenu leaves the graph occupying the entire megawidget. Right-clicking the graph displays the corresponding controls in a popup menu:

Export, a submenu with the same four output formats as the toolbar.
Reset view, when -zoom is enabled.
Previous view, when -zoom is enabled.
Crosshairs mode, when -crosshairs is enabled.
Closest crosshairs format, when -crosshairs is enabled.

The toolbar frame still exists in context-menu mode but is neither populated nor managed.

-controlmode both (the default) provides the visible toolbar and the right-click context menu together. The toolbar still follows -toolbarside; both control surfaces operate on the same graph and crosshair settings. Right-click cancels an active zoom or pan before it can open the menu.

The exportMenu subwidget is available in all control modes. Toolbar and both modes also expose exportButton. In both mode, exportMenu belongs to the toolbar and contextExportMenu belongs to the context menu.

SVG and PDF open modal export dialogs with width, height, decorations and -embedfonts yes/no controls. Their initial values come from the graph’s configured export options. Font embedding defaults to no for SVG and yes for PDF. Reset reloads the current graph settings; Print applies the dialog values and opens the save-file chooser. Cancel closes the dialog without applying unsubmitted changes. SVG embedding requires a viewer supporting CSS webfonts and data URLs. PDF without embedding uses standard fonts with Windows-1252 text; other characters require embedding. See ::rbc::SVG and ::rbc::PDF.

Zooming and navigation¶

With -zoom, rectangle zoom is performed by pressing the event selected by -zoomstartbut, together with -zoommod, dragging over the plot, and releasing the event selected by -zoomendbut.

The defaults are:

start       <Any-ButtonPress-1>
finish      <ButtonRelease-1>
previous    <Any-ButtonPress-2>

The finish binding intentionally does not require -zoommod. A selection therefore still finishes normally if the modifier is released before the mouse button.

The final release position is always used as the second zoom corner, even if no final Motion event occurred.

Dragging outside the plot area clamps the selected corner to the plot boundary.

Each completed rectangle zoom saves the preceding limits and scale type of every axis participating in the displayed coordinate system. Previous view restores the latest saved state. Reset view restores the oldest state and clears the navigation history.

Automatic axis limits are saved as their actual configured value {}, rather than as the temporary numerical limits calculated from the data, so undoing a navigation operation correctly restores autoscaling.

-zoomtitle briefly displays Zoom #n after a navigation change. -zoommark annotates the corners of a rectangle selection.

Demo of rectangular zoom

rectangular_zoom

Wheel zoom¶

-zoomwheel requires -zoom. By default, Control-MouseWheel scales the graph by a factor of 1.1.

When the pointer is inside the plot area, every used X and Y axis is scaled around the value beneath the pointer. The value underneath the pointer therefore remains at the same physical screen position.

When the pointer is over an axis instead, only that axis is scaled, around the centre of its numerical range.

Linear axes are scaled arithmetically. Logarithmic axes are scaled in logarithmic space.

Every wheel step is added to the same navigation history used by rectangle zoom and panning.

Demo of wheel zoom

wheel_zoom

Panning¶

-pan requires -zoom.

With the defaults, holding Shift and dragging Button-1 inside the plotting area translates the visible coordinate system:

start       <Shift-ButtonPress-1>
drag        <Motion>
finish      <ButtonRelease-1>

The Shift modifier is required only when the operation starts. Releasing Shift while Button-1 remains held does not terminate or strand the pan.

Pan motion samples the current pointer position so delayed Motion events do not replay older positions. Releasing the button applies the release-event coordinates as the final position.

Panning changes axis limits without changing their scale:

Linear axes preserve max-min.
Logarithmic axes preserve max/min.

Axis scrolling limits are also honored during panning. If an axis has -scrollmin or -scrollmax configured, or uses -scrollcommand, the effective axis view scrolling region bounds the pan. When the viewport reaches a scrolling boundary it simply stops moving; its width or logarithmic ratio is never reduced.

If several used axes belong to the same data dimension, their scrolling constraints are combined. The most restrictive axis limits the common physical drag displacement, so all mapped axes remain synchronized.

When -scrollcommand is configured without explicit -scrollmin or -scrollmax, Rbc uses the complete data range of the axis as the scrolling region.

If the current viewport already covers that complete range, axis view reports the full interval 0.0 1.0. The associated scrollbar thumb therefore fills the entire trough, and graphtoolbar panning is correspondingly unable to move the viewport because there is no remaining scrollable region.

This normally occurs for an automatically scaled axis before any zoom has been performed. After zooming into a smaller portion of the data range, the scrollbar represents that smaller viewport and panning can move it within the complete data range.

Applications that want to permit panning beyond the data range should define a larger scrolling world explicitly with -scrollmin and/or -scrollmax. For example:

$graph axis configure x -scrollmin 0 -scrollmax 12 -scrollcommand {.xbar set}

With data occupying only part of that range, the viewport may then be panned through the additional empty region while preserving its scale.

All axes actually participating in the displayed coordinate system are moved together. This includes axes installed in margins, hidden axes mapped by elements, and the axes mapped by a Polar or Smith grid. Completely unused axes are not changed.

Panning and zooming therefore operate correctly with multiple axes and with graph -invertxy.

A completed pan creates one normal navigation-history entry. Pressing and releasing without movement creates no history entry. Moving away and returning exactly to the starting position is also treated as a no-op.

Demo of panning

panning

Cross-interactions¶

The navigation facilities deliberately suspend conflicting interactions while a transient operation is active.

During rectangle zoom:

active axis scale toggling is temporarily disabled;
current/closest crosshair marker interaction is temporarily disabled;
toolbar controls are temporarily disabled;
wheel zoom is ignored;
panning cannot start.

During panning:

active axis scale toggling is temporarily disabled;
both raw crosshair lines and crosshair marker interaction are suspended;
existing crosshair marker graphics are removed before axis limits move;
toolbar controls are temporarily disabled;
wheel zoom is ignored;
rectangle zoom cannot start.

At the end of the operation the previous interaction state is restored. Fixed-pixel crosshair annotation boxes are rebuilt only after the new graph transform is current, preventing their geometry from being stretched by the changed axis scale.

Button-3 has a special role in both control modes. If a rectangle zoom or pan is currently active, Button-3 cancels that operation and consumes the event. In context-menu and both modes, Button-3 posts the menu only when there is no transient navigation operation to cancel.

Rectangle zoom and panning do not start when the initial press is on a legend drawn inside the plot area. The press is left for normal legend interaction instead.

While an already-started zoom or pan passes through an internal plot-area legend, active-legend hover and click changes are suppressed. Normal legend interaction resumes when the transient operation finishes.

Crosshairs¶

-crosshairs enables the enhanced crosshair system. The -crosshairsmode property selects one of four modes:

current - show Rbc crosshair lines and annotate the current pointer coordinates.
closest - find plotted data near the pointer and annotate the selected point or points.
none - show ordinary Rbc crosshair lines without an annotation marker.
disabled - disable both the lines and the annotation marker.

The default is closest.

In closest mode, -crosshairsclosestopts controls the search:

-interpolate yes allows a closest point on an interpolated trace.
-halo 10 sets the search halo in pixels.
-single yes displays the globally closest result. With -single no, each visible element is searched independently.
-hide yes hides the ordinary Rbc crosshair lines while closest annotations are displayed.

Elements configured with -hideplot yes do not participate in closest searches.

A closest line, strip, or Polar point is marked by a bitmap pointer together with its text annotation. The -pointeropts property controls the appearance of this pointer. A closest bar instead uses a dimension line with arrowheads spanning the displayed bar. Very short bars use external arrowheads when two internal heads would overlap.

Closest annotations also show configured source-point errors when available: symmetric errors appear as x error=±value or y error=±value; asymmetric bounds appear as x bounds=[low, high] or y bounds=[low, high]. The existing -formatx and -formaty settings format these numbers. Bounds remain in their original data coordinates, including in polar/Smith display modes. Custom closest callbacks receive the same optional xerror, yerror, xlow, xhigh, ylow and yhigh fields and control their own text.

When an element has a valid -param mapping, the parameter value reported by element closest is appended to the closest annotation. Its format is controlled by -formatparam.

In axis-format closest mode, an axis -command formatter is honoured. If the formatter fails, the graphtoolbar numeric format is used as a fallback.

Posting the context menu temporarily removes crosshair graphics. After the menu is dismissed, the selected crosshair mode is restored at the pointer’s current location rather than at the old popup location.

Closest point mode:

Demo of crosshairs in closest point mode

crosshairs_closest_point

Current coordinate mode:

Demo of crosshairs in current coordinate mode

crosshairs_current_coordinate

Closest point with barchart:

Demo of crosshairs in closest point mode for bars

closest_point_barchart

Refreshing beneath a stationary pointer¶

Enhanced crosshair annotations refresh when the displayed graph changes, even if the pointer has not moved. This is useful for streaming stripcharts, where automatic X-axis scrolling changes the coordinates beneath a stationary pointer.

The refresh behavior follows the selected crosshair mode:

current keeps the annotation anchored to the pointer’s current position within the plotting area and recalculates the displayed coordinates. As the axes scroll, the values change while the annotation remains beside the pointer.
closest repeats the closest-point search using the pointer’s current position and the current plotted data. The selected point and annotation can move or change even though the pointer remains stationary. The configured interpolation, halo, and single-result settings still apply.
none displays ordinary crosshair lines without an enhanced annotation.
disabled displays neither crosshair lines nor an annotation.

In closest mode, -crosshairsclosestopts {-hide yes} continues to hide the ordinary crosshair lines during automatic refreshes.

Annotation positions and background boxes are recalculated using the current coordinate mapping. This prevents axis scrolling or scaling from carrying a current-position annotation away from the pointer. Box dimensions follow the newly formatted text.

Refresh scheduling¶

The toolbar listens for <<RbcGraphChanged>> on its embedded graph. Geometry, mapping, and pointer entry events also request a refresh, allowing the toolbar to account for the graph or its containing window moving beneath a stationary pointer.

Refresh requests are combined into an idle callback. The callback reads the actual pointer position at that time; it does not reuse coordinates from the last motion event. No synthetic pointer-motion event is required.

As a fallback for missed pointer-leave events, a one-second timer checks for leftover crosshair markers. It removes them when the physical pointer is outside the plotting area, another window covers the pointer, or the graph is hidden. This check only deletes private crosshair markers; it does not rebuild annotations, repeat closest-point searches, or remove application markers.

Refreshing respects temporary crosshair suspension during interactions such as rectangle zooming and panning. It does not recreate annotations while the context menu is posted. When a refresh finds that the pointer is outside the graph’s plotting area or over another window, it removes stale annotations.

Pending refresh callbacks and the cleanup timer are cancelled when the toolbar is destroyed.

Streaming graphs¶

Automatic refresh requires no additional option or application binding. Enable enhanced crosshairs and select the desired mode:

::rbc::graphtoolbar .gtb -type stripchart -crosshairs -crosshairsmode current
pack .gtb -fill both -expand yes
set graph [.gtb subwidget graph]
$graph axis configure x -autorange 2.0 -shiftby 0.5

As the application updates plotted data and returns control to the Tk event loop, the graph redraws and the toolbar refreshes the annotation beneath the pointer.

Applications that also need graph-change notifications should bind to the embedded graph returned by .gtb subwidget graph. The event is generated on that widget, not on the toolbar container.

Demo of current coordinate marker refresh

crosshairs_current_point_in_place_refresh

Coordinate marker formats¶

-coordmark controls current-position and rectangle-corner annotations. It accepts:

auto
axis
complex
polar (radians)
polardegrees (degrees)
gamma
normalizedimpedance
normalizedimpedanceri
normalizedadmittance
normalizedadmittanceri

auto uses normal axis coordinates for ordinary and Polar graphs. For a Smith representation it selects real/imaginary normalized impedance or admittance according to the current grid cget -smithgrid value.

-coordclosestmark controls closest-point annotation. The permitted formats depend on the graph representation:

ordinary graph, barchart, or stripchart: axis
Polar representation: axis, complex, polar, polardegrees
Smith representation: axis, gamma, normalizedimpedance, impedance, normalizedadmittance, admittance

The toolbar menu and context-menu submenu expose only the modes valid for the current representation.

polar displays radius and angle in radians; polardegrees displays radius and angle in degrees. The selector labels are Polar (radians) and Polar (degrees). Both modes use the same Cartesian point. Custom closest callbacks receive angle in radians in the information dictionary.

Demo of closest point format for polar plot

crosshairs_closest_point_format_polar

Custom closest-point text¶

-closestcommand configures a Tcl command prefix for custom closest-point annotations. A nonempty prefix adds Custom to the toolbar menu and context menu. Select it with -coordclosestmark custom.

proc DescribePoint {element x y info} {
    return [format "%s\nX: %.4g\nY: %.4g" $element $x $y]
}

.gtb configure -closestcommand ::DescribePoint
.gtb configure -coordclosestmark custom

The callback runs in the global namespace with four arguments appended to its prefix:

element: selected element name.
x, y: numeric values on the element’s mapped axes. Polar elements receive Cartesian real/imaginary components. In Smith representation, Polar elements receive normalized admittance components when -smithgrid admittance is selected, and normalized impedance components for -smithgrid impedance or both.
info: the public element closest result, including index and optional param, extended with mapx, mapy, and coordinateSystem. The coordinate system is axis, complex, or normalizedimpedance. Original info(x) and info(y) are preserved; for Smith elements these are Gamma components.

Values are independent of axis label formatting and -invertxy. Interpolated searches can supply interpolated values. Smith singularities may produce Inf.

The returned string replaces the complete annotation. Neither the element name nor parameter value is appended automatically. Returning an empty string suppresses that result’s annotation and pointer or bar dimension line.

With -single no, the callback runs separately for each matching element. Normal marker styling and placement still apply.

Registration leaves the selected format unchanged. Setting -closestcommand {} removes Custom and restores the representation’s default format if Custom was selected. Callback and format changes refresh annotations at idle.

Use qualified command names or namespace code for namespace-local callbacks. Command prefixes may include bound arguments. Keep callbacks short and avoid graph modifications, widget destruction, or nested update calls. Errors propagate to Tk’s background error handling when invoked from an event.

Demo of closest point custom annotation

crosshair_closest_custom_annotations

Polar and Smith interaction¶

A Polar/Smith graph uses its grid-mapped axes as part of the displayed coordinate system even when those axes are hidden or are not installed in graph margins. They therefore participate in zooming, panning, coordinate display, and navigation history.

Rectangle zoom preserves the physical plot-area aspect ratio. This keeps equal X and Y data units at equal physical scales and prevents Polar or Smith circles from becoming elliptical.

When wheel zoom is performed over one of the Polar/Smith grid axes, both grid axes are scaled by the same factor. Scaling only one grid axis would otherwise force the automatic-aspect layout to resize the plotting area.

A visible Polar/Smith grid requires linear Cartesian grid axes. Interactive scale toggling therefore refuses to change a visible grid axis from linear to logarithmic. Auxiliary axes may still be logarithmic.

Example Smith chart:

::rbc::graphtoolbar .smith -type polar -representation smith -smithgrid impedance -controlmode contextmenu -zoom -zoomwheel -pan -crosshairs -crosshairsmode closest -activelegend

pack .smith -fill both -expand yes
set g [.smith subwidget graph]
::rbc::vector create gamma -type complex
::rbc::vector create frequency
gamma set {
    {0.10  0.05}
    {0.20  0.15}
    {0.30  0.10}
    {0.25 -0.05}
}
frequency set {1.0e9 2.0e9 3.0e9 4.0e9}
$g element create S11 -cdata gamma -param frequency

Active legend¶

-activelegend adds hover activation and a Button-1 cycle to every legend entry. The default -activelegendmode show-active-hide uses three states:

normal -> active -> plot-hidden -> normal

Select a two-state cycle with -activelegendmode show-hide (normal / plot-hidden) or -activelegendmode show-active (normal / persistently active). Hover highlighting remains enabled in every mode. These options are selected at construction time. An externally plot-hidden element returns to normal on its next click, including in show-active mode.

::rbc::graphtoolbar .gtb -controlmode both -activelegend -activelegendmode show-hide

The persistent state is also represented by the element’s legend relief:

flat       normal
raised     active
sunken     plot-hidden

Plot-hidden elements use element -hideplot yes; the plotted element disappears while its legend entry remains available for the next click.

Demo of active legend

active_legend

Active axes¶

Enable interactive axis scale toggling with -scaletoggle, supplying a list of axis names or all:

::rbc::graphtoolbar .gtb -scaletoggle {x y}

Moving the pointer over an enabled axis line highlights its background. Clicking it with Button-1 toggles that axis between linear and logarithmic scaling.

Use setAxisActiveScale to enable or disable this interaction after construction, or customize its activation event and highlight colour:

.gtb setAxisActiveScale {x y} -event Double-Button-1 -background lightgrey
.gtb setAxisActiveScale {y} -disabled

all selects the axes existing when the option or method is applied; axes created later must be enabled separately. The event and highlight bindings are shared by all enabled axes in the toolbar.

Rectangle zoom and panning temporarily disable axis scale toggling. Visible Polar/Smith grid axes cannot be switched to logarithmic scaling; auxiliary axes can still use it.

Demo of active axis

active_legend

Public megawidget access¶

The most common access forms are:

# Forward directly to the Rbc graph.
.gtb graph axis configure x -min 0 -max 10
.gtb graph element create e1 -data {0 0 1 1}

# Obtain a real subwidget pathname.
set graph [.gtb subwidget graph]

# Send a command to any named subwidget.
.gtb widgetcommand graph configure -title Example

# Inspect the names which exist for this particular configuration.
puts [.gtb names]

The exact subwidget set depends on -controlmode and on which optional facilities were enabled.

Reserved internal names¶

graphtoolbar installs private binding tags and graph markers in the embedded Rbc graph.

Binding tags whose names begin with gtb- are reserved for graphtoolbar. Applications should not create, modify, remove, or attach their own bindings to tags using this prefix.

Rbc graph marker names beginning with gtb are likewise reserved for graphtoolbar. Applications using the embedded graph should choose marker names that do not begin with gtb.

The exact private names are implementation details and may change. Applications should rely only on the reserved prefixes, and should use the public graphtoolbar interface rather than manipulating its internal bindings or markers.

Graphtoolbar-created markers are visual overlays only. They are created with -state disabled, which keeps them visible but excludes them from Rbc graph hit testing and binding dispatch. As a result, internal markers such as closest-point symbols, annotation text, annotation backgrounds, zoom outlines, and zoom titles do not become the graph’s current marker and do not interfere with application element bindings.

This is particularly important for element bindings such as:

$graph element bind all <Enter> {
    %W legend activate [%W element get current]
}

$graph element bind all <Leave> {
    %W legend deactivate [%W element get current]
}

Such bindings continue to track the underlying graph element even when a graphtoolbar marker is drawn above that element.

Applications should not depend on the individual names or configuration of gtb* markers. Their names, types, number, geometry, and other options are private implementation details. The only guaranteed convention is that marker names beginning with gtb are reserved for graphtoolbar.

Tk option database¶

Most marker styling dictionaries take their initial defaults from the Tk option database. Applications can therefore customize the graphtoolbar before creating a widget:

option add *gtbCrosshairsColor navy userDefault
option add *gtbCrosshairsTextFont {TkDefaultFont 9} userDefault
option add *gtbZoomTextBoxFill lightyellow userDefault

::rbc::graphtoolbar .gtb -zoom -zoommark -crosshairs

Graph elements default to fixed-size symbols in the native option table (-scalesymbols no). Loading this package does not change the ScaleSymbols option-database setting. To enable scaling for subsequently created elements, use option add *Element.ScaleSymbols yes userDefault, or pass -scalesymbols yes when creating or configuring an individual element.

Zoom option-database resources¶

Property	Key	Database name	Database class	Default
`zoomtitleopts`	`-font`	`gtbZoomTitleFont`	`GtbZoomTitleFont`	`{Arial 18}`
`zoomtitleopts`	`-foreground`	`gtbZoomTitleForeground`	`GtbZoomTitleForeground`	`black`
`zoomtitleopts`	`-shadow`	`gtbZoomTitleShadow`	`GtbZoomTitleShadow`	`yellow4`
`zoomtitleopts`	`-anchor`	`gtbZoomTitleAnchor`	`GtbZoomTitleAnchor`	`nw`
`zoomtitleopts`	`-coords`	`gtbZoomTitleCoords`	`GtbZoomTitleCoords`	`{-Inf Inf}`
`zoomboxopts`	`-dashes`	`gtbZoomOutlineDashes`	`GtbZoomOutlineDashes`	`4`
`zoomboxopts`	`-linewidth`	`gtbZoomOutlineLineWidth`	`GtbZoomOutlineLineWidth`	`1`
`zoomboxopts`	`-outline`	`gtbZoomOutlineColor`	`GtbZoomOutlineColor`	`grey`
`zoomboxopts`	`-xor`	`gtbZoomOutlineXor`	`GtbZoomOutlineXor`	`no`
`zoommarkopts`	`-font`	`gtbZoomTextFont`	`GtbZoomTextFont`	`{ArialNarrow 8}`
`zoommarkopts`	`-anchor`	`gtbZoomTextAnchor`	`GtbZoomTextAnchor`	`ne`
`zoommarkopts`	`-foreground`	`gtbZoomTextForeground`	`GtbZoomTextForeground`	`black`
`zoommarkopts`	`-justify`	`gtbZoomTextJustify`	`GtbZoomTextJustify`	`left`
`zoommarkopts`	`-padx`	`gtbZoomTextPadX`	`GtbZoomTextPadX`	`4`
`zoommarkopts`	`-pady`	`gtbZoomTextPadY`	`GtbZoomTextPadY`	`4`
`zoommarkopts`	`-formatx`	`gtbZoomTextXFormat`	`GtbZoomTextXFormat`	`.4g`
`zoommarkopts`	`-formaty`	`gtbZoomTextYFormat`	`GtbZoomTextYFormat`	`.4g`
`zoommarkboxopts`	`-fill`	`gtbZoomTextBoxFill`	`GtbZoomTextBoxFill`	`#FFEB3B`
`zoommarkboxopts`	`-outline`	`gtbZoomTextBoxOutline`	`GtbZoomTextBoxOutline`	`grey`
`zoommarkboxopts`	`-linewidth`	`gtbZoomTextBoxLineWidth`	`GtbZoomTextBoxLineWidth`	`1`

Crosshair option-database resources¶

Property	Key	Database name	Database class	Default
`crosshairsopts`	`-linewidth`	`gtbCrosshairsLineWidth`	`GtbCrosshairsLineWidth`	`1`
`crosshairsopts`	`-color`	`gtbCrosshairsColor`	`GtbCrosshairsColor`	`grey`
`crosshairsopts`	`-dashes`	`gtbCrosshairsDashes`	`GtbCrosshairsDashes`	`{}`
`crosshairsmarkopts`	`-font`	`gtbCrosshairsTextFont`	`GtbCrosshairsTextFont`	`{ArialNarrow 8}`
`crosshairsmarkopts`	`-anchor`	`gtbCrosshairsTextAnchor`	`GtbCrosshairsTextAnchor`	`nw`
`crosshairsmarkopts`	`-foreground`	`gtbCrosshairsTextForeground`	`GtbCrosshairsTextForeground`	`black`
`crosshairsmarkopts`	`-justify`	`gtbCrosshairsTextJustify`	`GtbCrosshairsTextJustify`	`left`
`crosshairsmarkopts`	`-padx`	`gtbCrosshairsTextPadX`	`GtbCrosshairsTextPadX`	`4`
`crosshairsmarkopts`	`-pady`	`gtbCrosshairsTextPadY`	`GtbCrosshairsTextPadY`	`4`
`crosshairsmarkopts`	`-formatx`	`gtbCrosshairsTextXFormat`	`GtbCrosshairsTextXFormat`	`.4g`
`crosshairsmarkopts`	`-formaty`	`gtbCrosshairsTextYFormat`	`GtbCrosshairsTextYFormat`	`.4g`
`crosshairsmarkopts`	`-formatparam`	`gtbCrosshairsTextParamFormat`	`GtbCrosshairsTextParamFormat`	`.4g`
`crosshairsmarkboxopts`	`-fill`	`gtbCrosshairsTextBoxFill`	`GtbCrosshairsTextBoxFill`	`#FFEB3B`
`crosshairsmarkboxopts`	`-outline`	`gtbCrosshairsTextBoxOutline`	`GtbCrosshairsTextBoxOutline`	`grey`
`crosshairsmarkboxopts`	`-linewidth`	`gtbCrosshairsTextBoxLineWidth`	`GtbCrosshairsTextBoxLineWidth`	`1`
`crosshairsbarlineopts`	`-outline`	`gtbCrosshairsBarLineOutline`	`GtbCrosshairsBarLineOutline`	`black`
`crosshairsbarlineopts`	`-linewidth`	`gtbCrosshairsBarLineWidth`	`GtbCrosshairsBarLineWidth`	`1`
`crosshairsbarlineopts`	`-arrowshape`	`gtbCrosshairsBarLineArrowShape`	`GtbCrosshairsBarLineArrowShape`	`{8 10 3}`
`pointeropts`	`-outline`	`gtbPointerOutline`	`GtbPointerOutline`	`black`
`pointeropts`	`-rotate`	`gtbPointerRotate`	`GtbPointerRotate`	`0`

crosshairsclosestopts has no Tk option-database resources. Its built-in defaults are:

-interpolate yes
-halo        10
-single      yes
-hide        yes

Styling example¶

Dictionary properties may be changed after creation through the oo::configurable configure method:

.gtb configure -zoomtitle yes -zoomtitleopts {-foreground navy -shadow {}} -pointeropts {-outline navy -rotate 0} -crosshairsmarkopts {-font {TkDefaultFont 9} -formatx .6g -formaty .6g -formatparam .6g} -crosshairsmarkboxopts {-fill lightyellow -outline grey40}

For the dictionary properties a later configuration containing only some recognized keys updates those keys while retaining the other current values. Unknown dictionary keys are rejected.

Classes¶

`graphtoolbar`¶

Configurable TclOO class implementing the graphtoolbar megawidget.

A widget is normally created through the exported class command:

::rbc::graphtoolbar .gtb ?option ...?

The Tk pathname becomes the megawidget command. Properties documented below may subsequently be read or changed through the oo::configurable interface:

.gtb configure -crosshairsmode
.gtb configure -crosshairsmode current
.gtb configure -zoomtitle yes

Options such as -type, -controlmode, -zoom, -pan, and -crosshairs select structural features when the megawidget is created and are not configurable properties afterward.

Private binding tags created by the class use the reserved gtb- prefix. Private Rbc graph markers use the reserved gtb prefix. Applications should not use either prefix for objects they create in the embedded graph.

Method summary

constructor: Constructor for the class.
destructor: Destructor for the class.
configure: Configure properties. See ::oo::configuresupport::configurable.
getAxisActiveScale: Returns axes currently enabled for interactive scale toggling. List of axis names carrying the graphtoolbar active-scale binding tag.
graph: Forwards a command directly to the embedded Rbc graph widget.
names: Returns the names of all subwidgets created for this instance. List of subwidget names.
setAxisActiveScale: Configures interactive linear/logarithmic scale toggling for axes.
subwidget: Returns the Tk pathname of a named subwidget. Tk pathname of the requested subwidget.
widgetcommand: Invokes a command on a named graphtoolbar subwidget.

Options

-interactive:: Enables zoom, pan, wheel zoom, crosshairs, active legend and scale toggling on axes x and y, with their default options. Explicit feature options, including -scaletoggle, override these defaults regardless of argument order. This is a construction-time switch.
-width pixels:: Initial requested width of the embedded Rbc graph. The default is 800.
-height pixels:: Initial requested height of the embedded Rbc graph. The default is 600.
-controlmode mode:: Selects the user-interface control surface. Must be toolbar, contextmenu, or both. The default is both.
-type type:: Selects the embedded Rbc widget. Must be graph, barchart, stripchart, polar, or trackgraph. The default is graph.
-representation mode:: For -type polar, selects polar or smith representation. The default is polar. It is ignored by the other graph types.
-smithgrid mode:: Initializes the graph grid component’s -smithgrid option. For a Smith representation, selects impedance, admittance, or both. The default is impedance. Later changes use $toolbar graph grid configure -smithgrid mode.
-coordmark mode:: Initial value of the -coordmark configurable property. The default is auto.
-closestcommand commandPrefix:: Custom closest-point text callback. Receives element x y info. The default is empty.
-coordclosestmark mode:: Initial closest-point coordinate format. The default is axis. For a Smith widget with crosshairs enabled, initialization selects the normalized impedance or admittance format appropriate to -smithgrid.
-toolbarside side:: Places the visible toolbar at bottom or top. The default is bottom. This has no visible effect in context-menu mode.
-zoom:: Enables rectangle zoom and navigation history.
-zoomstartbut event:: Event component which starts rectangle zoom. The default is ButtonPress-1.
-zoomendbut event:: Event component which finishes rectangle zoom. The default is ButtonRelease-1. The finish event is intentionally not combined with -zoommod.
-zoombackbut event:: Event component which restores the previous view. The default is ButtonPress-2.
-zoommod modifier:: Tk event modifier prefix used for the zoom start and previous-view bindings. The default is Any-.
-zoomwheel:: Enables mouse-wheel zoom. Requires -zoom.
-zoomwheelscale factor:: Multiplicative wheel-zoom step. Must be a finite number greater than 1.0. The default is 1.1.
-zoomwheelmod modifier:: Modifier prefix for MouseWheel zoom. The default is Control-.
-zoomtitle:: Enables the transient Zoom #n marker. Requires -zoom.
-zoomtitleopts dictionary:: Initial -zoomtitleopts property. Requires -zoom.
-zoomboxopts dictionary:: Initial -zoomboxopts property. Requires -zoom.
-zoommark:: Displays coordinate annotations at rectangle-zoom corners. Requires -zoom.
-zoommarkopts dictionary:: Initial -zoommarkopts property. Requires -zoom.
-zoommarkboxopts dictionary:: Initial -zoommarkboxopts property. Requires -zoom.
-pan:: Enables plot-area panning. Requires -zoom because panning shares the zoom navigation history.
-panstartbut event:: Event component which starts a pan. The default is ButtonPress-1.
-panendbut event:: Event component which finishes a pan. The default is ButtonRelease-1. It is intentionally not combined with -panmod.
-panmod modifier:: Modifier prefix required to start panning. The default is Shift-.
-crosshairs:: Enables enhanced crosshair interaction.
-pointeropts dictionary:: Initial -pointeropts property. Configures the bitmap pointer used to mark closest line, strip, and Polar points. Recognized keys are -outline and -rotate.
-crosshairsmode mode:: Initial crosshair mode. Must be current, closest, none, or disabled. The default is closest. Requires -crosshairs.
-crosshairsopts dictionary:: Initial Rbc crosshair line options. Requires -crosshairs.
-crosshairsmarkopts dictionary:: Initial text-marker and numeric-format options used by current and closest annotations. Requires -crosshairs.
-crosshairsmarkboxopts dictionary:: Initial background-box options for crosshair annotations. Requires -crosshairs.
-crosshairsclosestopts dictionary:: Initial closest-search options. Recognized keys are -interpolate, -halo, -single, and -hide. Requires -crosshairs.
-crosshairsbarlineopts dictionary:: Initial line-marker options for closest-bar dimension annotations. Requires -crosshairs.
-scaletoggle axes:: Enables interactive linear/logarithmic scale toggling on the specified axis list. all selects all axes existing at construction time.
-activelegend:: Enables hover activation and Button-1 interaction on legend entries.
-activelegendmode mode:: Selects the persistent legend click cycle. Must be show-active-hide (the default), show-hide, or show-active. Requires -activelegend.

Properties

-closestcommand:: Readable, writable. Tcl command prefix for Custom closest-point text. Receives element x y info and returns the complete annotation. An empty prefix removes Custom from the available formats. See the Custom closest-point text section for coordinate semantics.
-coordclosestmark:: Readable, writable. Selects the value representation used for closest-point annotations. The valid values depend on the current graph representation: - ordinary graph/barchart/stripchart: axis - Polar: axis, complex, polar, polardegrees - Smith: axis, gamma, normalizedimpedance, impedance, normalizedadmittance, admittance custom is also available when -closestcommand is nonempty. The toolbar and context-menu selectors are synchronized with this property.
-coordmark:: Readable, writable. Selects the coordinate representation used by current-position crosshair markers and rectangle-zoom corner markers. Accepted values are auto, axis, complex, polar, polardegrees, gamma, normalizedimpedance, normalizedimpedanceri, normalizedadmittance, and normalizedadmittanceri. auto uses ordinary axis values except on a Smith chart, where normalized impedance/admittance real and imaginary components are selected according to the Smith grid.
-crosshairsbarlineopts:: Readable, writable. Dictionary configuring the dimension line used when the closest result is a bar. Recognized keys are -outline, -linewidth, and -arrowshape. -arrowshape contains the three screen distances used by an Rbc line-marker arrowhead. Initial values come from the gtbCrosshairsBarLine* Tk option-database resources.
-crosshairsclosestopts:: Readable, writable. Dictionary controlling closest-element searches. Recognized keys and defaults are: tcl -interpolate yes -halo 10 -single yes -hide yes -interpolate is forwarded to element closest. -halo is the search distance in pixels. -single yes selects one globally closest result; -single no searches every visible element separately. -hide controls visibility of the ordinary Rbc crosshair lines while closest annotations are displayed.
-crosshairsmarkboxopts:: Readable, writable. Dictionary configuring the polygon background behind current and closest text annotations. Recognized keys are -fill, -outline, and -linewidth. If fill and outline are both empty, no background is drawn. Initial values come from the gtbCrosshairsTextBox* Tk option-database resources.
-crosshairsmarkopts:: Readable, writable. Dictionary configuring current/closest text annotations. Recognized keys are -font, -anchor, -justify, -foreground, -padx, -pady, -formatx, -formaty, and -formatparam. The three format keys are format conversion bodies, for example .4g. -formatparam is used when a closest element supplies info(param). Initial values are obtained from the gtbCrosshairsText* Tk option-database resources.
-crosshairsmode:: Readable, writable. Selects enhanced crosshair behaviour. Accepted values are current, closest, none, and disabled. current annotates the current pointer coordinates. closest annotates nearby plotted data. none leaves only ordinary Rbc crosshair lines. disabled suppresses both lines and annotation markers. This property is intended for an instance created with -crosshairs.
-crosshairsopts:: Readable, writable. Dictionary configuring the underlying Rbc crosshair lines. Recognized keys are -linewidth, -color, and -dashes. Initial values come from gtbCrosshairsLineWidth, gtbCrosshairsColor, and gtbCrosshairsDashes.
-pointeropts:: Readable, writable. Dictionary configuring the bitmap pointer used to identify closest line, strip, and Polar points. Recognized keys are -outline and -rotate. -outline specifies the bitmap foreground color. -rotate specifies its rotation angle in degrees. Initial values come from gtbPointerOutline and gtbPointerRotate.
-zoomboxopts:: Readable, writable. Dictionary configuring the rectangle-zoom outline. Recognized keys are -dashes, -linewidth, -outline, and -xor. Initial values are obtained from the gtbZoomOutline* Tk option-database resources.
-zoommarkboxopts:: Readable, writable. Dictionary configuring the polygon drawn behind each rectangle-corner text marker. Recognized keys are -fill, -outline, and -linewidth. If both fill and outline are empty, no background polygon is drawn. Initial values are obtained from the gtbZoomTextBox* option-database resources.
-zoommarkopts:: Readable, writable. Dictionary configuring rectangle-corner text annotations. Recognized keys are -font, -anchor, -justify, -foreground, -padx, -pady, -formatx, and -formaty. -formatx and -formaty are format conversion bodies such as .4g; the leading % is supplied internally. Initial values are obtained from the gtbZoomText* option-database resources.
-zoomtitle:: Readable, writable. Boolean controlling the transient Zoom #n annotation produced after a completed navigation operation. This property is meaningful for instances created with -zoom.
-zoomtitleopts:: Readable, writable. Dictionary of Rbc text-marker options used for the transient zoom-level title. Recognized keys are -font, -foreground, -shadow, -anchor, and -coords. Initial values are obtained from the corresponding gtbZoomTitle* Tk option-database resources.

`constructor`¶

Creates a graphtoolbar megawidget.

graphtoolbar create OBJNAME path ?option ...?
graphtoolbar new path ?option ...?

Parameters

args:: Widget pathname followed by creation options documented in the class Options section.

Description

The first argument is the Tk pathname of the new megawidget. Structural facilities such as zoom, pan, crosshairs, control mode, graph type, and active legend interaction are selected here.

Return value

The newly created megawidget object. When creation is invoked through the exported class command with a pathname, the command result is the widget pathname.

`destructor`¶

Cancel asynchronous work before the object namespace disappears.

GRAPHTOOLBAROBJ destroy

`getAxisActiveScale`¶

Returns axes currently enabled for interactive scale toggling. List of axis names carrying the graphtoolbar active-scale binding tag.

GRAPHTOOLBAROBJ getAxisActiveScale

Return value

Returns axes currently enabled for interactive scale toggling. List of axis names carrying the graphtoolbar active-scale binding tag.

`graph`¶

Forwards a command directly to the embedded Rbc graph widget.

GRAPHTOOLBAROBJ graph ?graphCommand ...?

Parameters

args:: Graph widget command and arguments.

Description

For example:

.gtb graph axis configure x -min 0 -max 10
.gtb graph element create trace -data {0 0 1 1 2 4}

Return value

Result returned by the embedded graph command.

`names`¶

Returns the names of all subwidgets created for this instance. List of subwidget names.

GRAPHTOOLBAROBJ names

Description

The set depends on -controlmode and on which optional features were enabled at construction time. graph and toolbarFrame always # exist.

Return value

Returns the names of all subwidgets created for this instance. List of subwidget names.

`setAxisActiveScale`¶

Configures interactive linear/logarithmic scale toggling for axes.

GRAPHTOOLBAROBJ setAxisActiveScale axes ?-disabled? ?-event event? ?-background color?

Parameters

-background color:: Temporary axis background displayed while the pointer is over the active axis line. The default is grey.
-disabled:: Removes interactive scale toggling from the selected axes instead of enabling it.
-event event:: Event which toggles the active axis. The default is ButtonPress-1.
axes:: List of axis names, or all for every current graph axis.

Description

Only the actual axis line responds to the toggle event.

A visible Polar/Smith grid axis cannot be toggled from linear to logarithmic because the specialized grid requires linear Cartesian axes. Logarithmic-to-linear conversion is still allowed so an externally misconfigured grid can be recovered.

Rectangle zoom and panning temporarily disable this interaction and # restore it when the transient operation finishes.

Return value

Nothing.

`subwidget`¶

Returns the Tk pathname of a named subwidget. Tk pathname of the requested subwidget.

GRAPHTOOLBAROBJ subwidget name

Parameters

name:: Subwidget name as returned by names.

Description

Common names include graph and toolbarFrame. Context-menu and both modes expose contextMenu. Toolbar and both modes also create exportButton, exportMenu, zoom, and crosshair controls. In both mode, contextExportMenu identifies the separate context-menu export submenu.

Return value

Returns the Tk pathname of a named subwidget. Tk pathname of the requested subwidget.

`widgetcommand`¶

Invokes a command on a named graphtoolbar subwidget.

GRAPHTOOLBAROBJ widgetcommand subwidgetName ?command ...?

Parameters

args:: Subwidget name followed by its command and arguments.

Description

For example:

.gtb widgetcommand graph configure -title Example

Return value

Result of the subwidget command.

Copyright (c) George Yashin

graphtoolbar¶

Basic example¶

Stacked-track interaction¶

Control surfaces¶

Zooming and navigation¶

Wheel zoom¶

Panning¶

Cross-interactions¶

Crosshairs¶

Refreshing beneath a stationary pointer¶

Refresh scheduling¶

Streaming graphs¶

Coordinate marker formats¶

Custom closest-point text¶

Polar and Smith interaction¶

Active legend¶

Active axes¶

Public megawidget access¶

Reserved internal names¶

Tk option database¶

Zoom option-database resources¶

Crosshair option-database resources¶

Styling example¶

Classes¶

`graphtoolbar`¶

`constructor`¶

`destructor`¶

`getAxisActiveScale`¶

`graph`¶

`names`¶

`setAxisActiveScale`¶

`subwidget`¶

`widgetcommand`¶

Table of Contents

Previous topic

Next topic

This Page

graphtoolbar¶

Basic example¶

Stacked-track interaction¶

Control surfaces¶

Zooming and navigation¶

Wheel zoom¶

Panning¶

Cross-interactions¶

Crosshairs¶

Refreshing beneath a stationary pointer¶

Refresh scheduling¶

Streaming graphs¶

Coordinate marker formats¶

Custom closest-point text¶

Polar and Smith interaction¶

Active legend¶

Active axes¶

Public megawidget access¶

Reserved internal names¶

Tk option database¶

Zoom option-database resources¶

Crosshair option-database resources¶

Styling example¶

Classes¶

graphtoolbar¶

constructor¶

destructor¶

getAxisActiveScale¶

graph¶

names¶

setAxisActiveScale¶

subwidget¶

widgetcommand¶

`graphtoolbar`¶

`constructor`¶

`destructor`¶

`getAxisActiveScale`¶

`graph`¶

`names`¶

`setAxisActiveScale`¶

`subwidget`¶

`widgetcommand`¶