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 three-state legend entries.
PNG snapshots, PostScript and SVG output.
Either a permanently visible toolbar or a right-click context menu.

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

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

or, after importing the Rbc commands:

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

::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]

Control surfaces¶

-controlmode toolbar, the default, creates a visible toolbar. Snapshot, PostScript and SVG buttons are always present. 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:

Make snapshot…
PostScript…
SVG…
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.

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.

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.

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.

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 mode, 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.

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.

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 polling timer or synthetic pointer-motion event is required.

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 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.

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 -smithgrid.

-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.

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.

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 three-state Button-1 cycle to every legend entry:

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

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.

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

The package itself also installs:

option add *Element.ScaleSymbols no widgetDefault

so graph elements default to fixed-size symbols rather than scaling their symbols with the graph.

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

-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 or contextmenu. The default is toolbar.
-type type:: Selects the embedded Rbc widget. Must be graph, barchart, stripchart, or polar. 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:: For a Smith representation, selects impedance, admittance, or both. The default is impedance.
-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 three-state Button-1 interaction on legend entries.

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, toolbarFrame, and, in context-menu mode, contextMenu. Toolbar mode may additionally create snapshot, PostScript, SVG, zoom, and crosshair control widgets.

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¶

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¶

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¶

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¶

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`¶