Trackgraph widget instance TRACKGRAPH command
This page documents widgets created by ::rbc::trackgraph and their named-track operations.
TRACKGRAPH is a fictional documentation prefix for widgetPath track, not a runtime command.
For example, TRACKGRAPH create voltage -yaxes volts means .g track create voltage -yaxes volts.
The commands described here are native widget operations, not Tcl wrappers to invoke directly.
Common widget commands and configuration are described in ::rbc::GRAPHINST. Use ::rbc::AXIS for axes, ::rbc::LINEELEMENT and ::rbc::STRIPELEMENT for traces, ::rbc::MARKER for annotations, and ::rbc::LEGEND for global and track-local legends. Toolbar integration is described in ::rbc::graphtoolbar.
Stacked tracks
rbc::trackgraph is one native graph window containing named vertical plot regions. It reuses the graph’s
line, strip and bar elements, renderers and SVG, PDF and PostScript exporters. It does not create child graphs.
The axis-region approach is also used by BLT’s -stackaxes feature; RBC tracks explicitly group one or
more Y axes and their elements into a row.
rbc::trackgraph .g -width 800 -height 500
.g axis create voltageY -title Voltage
.g axis create currentY -title Current
.g track create voltage -weight 2 -yaxes voltageY
.g track create current -weight 1 -yaxes currentY
.g line create voltageTrace -track voltage -mapy voltageY -xdata time -ydata voltage
.g strip create currentTrace -track current -mapy currentY -xdata time -ydata current
pack .g -fill both -expand yes
Tracks initially appear in creation order from top to bottom. Use track order to change their order without
recreating axes, elements or markers. Every track receives the same horizontal plotting bounds.
The common left margin accommodates the widest set of track Y axes, including titles and tick labels. X axes
remain widget-wide: elements select them with -mapx, and ordinary xaxis use and x2axis use control their
display. Independent X axes need not have matching tick positions. By default, tracks inherit the graph’s
::rbc::GRID settings: grid -mapx selects the shared X axis, and a nonempty grid -mapy enables grid lines
from each track’s first Y axis. An empty axis selection disables that direction. See
track grid for independent grid settings within each track.
Track option |
Default |
Meaning |
|---|---|---|
|
|
Positive finite share of remaining layout space after track minima are allocated; at most 1000000. |
|
|
Positive minimum requested plot height, or width when inverted, in Tk screen-distance units. |
|
|
Requested plot height in scroll layout, or width when inverted; from 1 to 1000000 pixels, with Tk screen-distance units accepted. The effective size is at least |
|
empty |
List of existing Y axes assigned exclusively to this track and displayed in its left margin (bottom when inverted). |
|
|
Bar mode for this track: inherit the graph setting, or use normal, aligned, overlap or stacked. |
Track configuration and lifecycle
Track operations and option names accept unambiguous abbreviations. Configuration queries follow the ordinary Tk/RBC component convention:
.g track cget voltage -height
# Returns the current value, for example 160.
.g track configure voltage -height
# Returns {-height height Height 160 160}.
.g track configure voltage
# Returns a list of five-field descriptions, one for each option.
.g track configure voltage -hei 240
Each description contains the option name, resource name, resource class, built-in default and current
value. The default field remains the built-in default even when the option database supplied the initial
value. Current values include subsequent separator resizing and explicit configuration changes.
Earlier trackgraph versions returned an option/value dictionary from configure and a bare value from
configure name option. Use cget for values; to build an option/value dictionary from all descriptions:
set settings {}
foreach option [.g track configure voltage] {
dict set settings [lindex $option 0] [lindex $option 4]
}
track exists name returns a boolean for an exact name. track names ?pattern ...? returns tracks in
layout order, matching any supplied Tcl glob pattern, without duplicates. With no patterns it returns
every track. Pattern matching is case-sensitive; exists and delete do not interpret patterns.
track delete ?name ...? deletes one or more empty tracks and retains their axes. All names and ownership
constraints are checked before any deletion: an unknown track or a track still used by an element or
marker rejects the whole batch. Repeated names are accepted, and an empty batch does nothing. Local grids
and legends are released along with their tracks. Move or delete elements and markers first.
Track background bindings
track bind name|all ?sequence ?command?? uses the ordinary RBC component binding machinery. The named
track must exist; all is a reserved binding selector applying to every track background, including tracks
created later. Name bindings run before the track all binding. These tags are independent of element,
marker, axis and legend tags, even when their names match.
.g track bind voltage <ButtonPress-3> {ShowTrackMenu %W voltage %X %Y}
.g track bind all <Enter> {ShowTrackStatus [%W track get current]}
.g track bind all <Leave> {ClearTrackStatus}
.g track bind voltage <ButtonPress-3>
.g track bind voltage
.g track bind voltage <ButtonPress-3> {}
With no sequence, bind lists the target’s event sequences; with a sequence it queries that binding’s
script. An empty script removes the binding. Prefix a script with + to append it. Standard Tk event
substitutions such as %W, %x, %y, %X and %Y apply. break in a name binding stops the remaining
component binding tags for that event; it does not disable ordinary widget/class bindings or toolbar gestures.
Backgrounds are the lowest-priority plot targets: markers and elements retain their existing picking order and halo, and visible legends, including blank padding, exclude background picking. Track bindings do not receive events bubbling from those components. Axis margins and separator gaps are not backgrounds; separators continue to use the existing widget/class resize bindings.
track get current returns the currently picked track background, or an empty string when another
component, a separator, or the outside of the plot is picked. It is not a general geometric owner lookup;
use track identify for that. During a Leave callback, current still identifies the background being
left; during Enter it identifies the newly entered background. Existing component button-grab behaviour
is retained while a button is held down.
Only visible track rectangles are pickable in either orientation. Native redraws repick a stationary
pointer after scrolling, reordering or resizing and generate the corresponding Enter/Leave transitions.
Temporary export layouts do not repick or run background bindings. Deleting a track removes its name
bindings and clears current/pending references; recreating its name starts with no name bindings. The
all binding remains until removed or the widget is destroyed. Callbacks may delete tracks or the widget.
Bars in tracks
Create bars with bar create name -track trackName -mapy axisName, using an existing Y axis owned by
the track. Bars can coexist with line and strip elements and use the same legends, bindings and exporters.
Ordinary bar options, including width, alignment, offset, pens, value labels and error-bar positioning,
retain their meaning. Scrolling maps bars in full track coordinates and clips them to the visible area.
Each track has -barmode inherit|normal|aligned|overlap|stacked, default inherit, with resource name
barMode and class BarMode. Inherited tracks follow the graph’s -barmode; an explicit track setting
overrides it until reset to inherit. infront is accepted as an alias of normal.
Grouping and stacking use the mapped X/Y axis pair. Tracks exclusively own their Y axes, so bars in
different tracks never form a group or stack together, even when their X values match. Within a track,
bars mapped to different axes remain separate. Each Y axis autoscales from its own bars and stacks;
shared X axes include bar widths and placement offsets across their tracks.
.g track configure voltage -barmode aligned
.g bar create measured -track voltage -mapy volts -data {1 2 2 3}
.g bar create predicted -track voltage -mapy volts -data {1 2.2 2 2.8}
.g track configure current -barmode stacked
Track option database
Tracks are named option-database components with class Track. As with axes and elements, the resource
name is the track name with only its first character converted to lowercase. For example, Voltage
uses voltage, while VOLTAGE uses vOLTAGE. Track names in commands remain unchanged and case-sensitive;
Voltage and voltage may coexist, but use the same option-database resource name.
Creation reads these defaults once; explicit track create options take precedence. Later database
changes do not modify existing tracks, including during track configure, resizing or scrolling.
Option |
Resource name |
Resource class |
Default |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Empty |
|
|
|
|
option add *Track.height 200
option add *Track.minHeight 60
option add *voltage.height 300
.g track create voltage -yaxes volts
.g track create current -yaxes amps -height 240
Database values undergo the same validation as explicit values. Axes supplied through yAxes must
already exist and satisfy the usual exclusive ownership rules. Prefer a track-specific resource for
axis assignments; a class-wide assignment cannot give the same axis to several tracks. Failed creation
leaves no track or axis ownership behind. Tracks do not create child windows for resource lookup.
Scrolling tracks and their data
The default -tracklayout fit divides the available plot space using -weight and -minheight, as before.
With -tracklayout scroll, each track retains max(-height, -minheight) pixels and adjacent tracks have
a 12-pixel gap. Content may extend beyond the visible viewport. Track weights are ignored in this mode.
Scrolling moves tracks vertically, or horizontally with -invertxy yes; shared X axes remain fixed.
Tracks do not change their data ranges or rescale when partially visible. Drawing and picking use only
the visible part. bbox returns that visible rectangle; a fully hidden track has zero size along the
scrolling direction. Transforms still use the full track geometry and may return offscreen coordinates.
Use track view for the track list and track yview for local data scrolling. They are independent:
.g configure -tracklayout scroll -trackscrollcommand {.tracks set}
.g track configure voltage -height 280
ttk::scrollbar .tracks -orient vertical -command {.g track view}
.g axis configure voltageY -scrollmin -10 -scrollmax 10 -scrollcommand {.volts set}
ttk::scrollbar .volts -orient vertical -command {.g track yview voltage -mapy voltageY}
track view with no arguments returns first last fractions of the track-list extent. Its moveto
form places a fraction at the leading viewport edge; scroll moves by 20-pixel units or pages of 90%
of the viewport. Movement is clamped. Fit layout, an empty list, or content fitting the viewport returns
0.0 1.0. This command never changes data-axis limits.
track yview name ?-mapy axis? queries the selected owned Y axis, or the first owned Y axis by default.
Append moveto fraction or scroll number units|pages to change the view. Without -mapy, changes apply
to all Y axes owned by the track, using each axis’s scroll range, increment, log scale and direction.
Invalid multi-axis requests leave all requested limits unchanged. An unowned axis or a track without Y
axes reports an error. Track position and shared X axes do not change.
Position the scrollbar widgets with ordinary Tk geometry management. For an inverted graph, use horizontal
scrollbars. Each track may have a separate local scrollbar, and each of its Y axes may have one too.
Existing axis -scrollmin, -scrollmax, -scrollincrement, and -scrollcommand settings apply to local
scrolling; the graph’s -trackscrollcommand receives the track-list viewport’s first and last fractions.
Use finite axis scroll limits when the full data range is not a useful scroll region.
Separator dragging in scroll layout changes the preceding track’s requested -height and the total
content extent. It leaves the next track’s size and both weights unchanged. Escape restores the original
size. In fit layout, dragging continues to redistribute adjacent weights. A change to the list viewport,
orientation or layout mode cancels active separator/toolbar gestures rather than reusing stale pixels.
SVG, PDF and PostScript export the viewport at the current scroll offset, with track sizes expressed in
output pixels; a differently sized export can include more or fewer tracks. Export does not change the
screen scroll position or notify its scrollbar. Local axes, legends, grids and ordinary markers are
clipped to the viewport. Window markers retain the existing partial-child-clipping limitations described
in ::rbc::MARKER; fully offscreen track windows are hidden.
demos/trackgraph1.tcl includes a track-list scrollbar and separate local Y scrollbars.
Assign axes with track configure -yaxes, rather than yaxis use. An axis may belong to only one track.
Elements must specify both -track and a -mapy axis belonging to that track. Change both options in one
element configure call to move an element. An axis in use by an element cannot be detached, and an axis owned
by a track cannot be deleted until detached. These ownership checks include markers, even hidden markers or
markers with empty coordinates, and Y axes selected by independently configured track grids. Hiding an axis
hides its decorations, not its track. Lists and RBC vectors retain their ordinary ownership and notification
behaviour.
Track coordinate conversion
.g track transform voltage x y ?-mapx axis? ?-mapy axis?
.g track invtransform voltage x y ?-mapx axis? ?-mapy axis?
track transform maps data coordinates to physical widget pixels; track invtransform maps them back.
Track transforms default to shared axis x and the track’s first Y axis. Use -mapx or -mapy to select
alternatives. Ordinary graph-level transform and invtransform are ambiguous in a trackgraph and report
an error; individual axis transform and axis invtransform operations remain available.
The layout fits the available height. After minimum heights, spare space is distributed by weight. Tracks have a 12-pixel gap, reduced in very small windows. If minimum heights do not fit, they are scaled proportionally to avoid forcing the window larger. Resizing and export recompute the layout. Elements and closest-point searches are restricted to their own track; normal, descending and logarithmic Y scales work independently. Horizontal zoom or pan is performed through the shared X axes; vertical navigation uses the desired track’s Y axes. The native crosshair’s vertical line spans all tracks and its horizontal line follows the pointer’s row.
Line and strip elements retain their existing -decimate none|auto option; the default remains none.
Set -decimate auto on each desired element. Density is measured along the shared physical X-axis span,
not by the number of tracks: plot width normally, plot height when inverted. Local Y mapping and clipping
still use the owning track. The existing eligibility rules apply, including fallback for smoothed traces
and unsupported fill/style combinations. Data-domain caches remain per element and follow vector updates;
closest-point queries retain original samples, and exports use full geometry. See ::rbc::LINEELEMENT.
Each row also owns an optional local legend, hidden by default. For example:
.g track legend voltage configure -hide no -position right -anchor ne
shows only that row’s element labels. Local legends overlay and clip to the track; they do not change shared X alignment. The global legend remains independent. See ::rbc::LEGEND for options, bindings and export behavior.
Track grid selection
track grid name operation ?args ...? queries or configures the named track’s grid. Supports the ::rbc::GRID
operations configure, cget, on, off and toggle, with Cartesian options -color, -dashes, -hide,
-linewidth, -mapx, -mapy and -minor.
Until its first successful configuration or visibility change, a track inherits the graph-wide grid. Queries do not change inheritance. The first mutation copies the current effective settings, then applies the requested changes. Later graph-wide grid changes do not affect that track. Failed changes preserve both the previous settings and inheritance. Deleting and recreating the track restores inheritance.
-mapx selects an existing shared X axis; -mapy selects an existing Y axis owned by this track, including
any of its additional Y axes. An empty string disables that direction. Inherited -mapy reports the
first owned Y axis, or empty when the graph disables Y grid lines or the track owns no Y axes.
A selected local Y axis cannot be detached until the grid is remapped or that direction is disabled.
Lines are clipped to the owning track and follow resizing, reordering, axis range changes and inversion. X lines are vertical normally and horizontal when inverted; Y lines rotate correspondingly. Native, Cairo, SVG, PDF and PostScript output use the same local configuration. A local visible grid is drawn even when the graph-wide grid is hidden.
.g grid configure -hide no -minor no
.g track grid voltage configure -mapx x -mapy voltageY -color steelblue
.g track grid current configure -mapx samples -mapy currentY -color darkorange
.g track grid current off
.g track grid voltage cget -mapx
Inverted tracks
Set .g configure -invertxy yes to rotate the layout into side-by-side columns. Track order runs left to
right, shared X axes run vertically, and each track’s Y axes run horizontally below its column. The common
bottom margin accommodates the largest set of track Y axes. Shared X grid lines are horizontal; local Y grid
lines are vertical. Track weights divide the available width. The existing -minheight option now requests a
minimum column width; it retains its name and value when toggling orientation. Tiny layouts compress those
minima proportionally in either orientation.
track identify and track sashpos take a physical X coordinate in inverted mode. track bbox, track
separator, track transform and track invtransform always use physical widget X/Y coordinates. Axis names
and data X/Y values retain their meaning. Markers, picking, local legends and exports follow the column
rectangle. Legend positions and anchors remain physical directions: right is still the right edge. Global and
local legends can be shown together, as in demos/trackgraph1.tcl. Toolbar navigation works in either
orientation; changing orientation during a gesture cancels it.
Reordering and resizing tracks
track order takes the full list of existing track names, with no omissions or duplicates. Ownership, axis
configuration, vector subscriptions and marker bindings remain unchanged. Legend order still follows element
order, independently of track order.
.g track order {current voltage}
set y [.g track sashpos current]
.g track sashpos current [expr {$y+30}]
.g configure -trackresize yes
track sashpos changes the two adjacent tracks’ weights while preserving their sum. Other tracks keep their
weights and allocated space, subject to one-pixel layout rounding. Requested positions are clamped by the
adjacent minimum heights and the positive weight range. The returned position is the actual one. If minimum
heights already consume the available space, the separator cannot move. The resulting weights continue to
govern later window resizes and exports; no fixed pixel sizes are stored.
-trackresize is a graph option with database name trackResize, class TrackResize, and default no. Only
trackgraph widgets accept yes. With it enabled, the standard Trackgraph class bindings show a vertical
resize cursor over a row gap, or a horizontal cursor between inverted columns. Drag with button 1 to resize the
adjacent tracks; release to keep the result, or press Escape to restore the weights from the start of the
drag. The gesture borrows keyboard focus so Escape works, then restores the previous focus on release,
cancellation or invalidation, provided focus is still on the graph. If there was no previous focus or its
widget has been destroyed, focus returns to the graph’s toplevel. Focus moved elsewhere during dragging is left
alone; a graph already focused before dragging remains focused. Pointer events in plot interiors keep their
ordinary behaviour. Changing the track list/order, orientation, or disabling resizing invalidates the gesture
on the next motion or release, without restoring obsolete weights. Destroying the widget removes its gesture
state. These dependency-free bindings are loaded with package require rbc.
Optional divider lines make separator gaps visible. -trackseparatorcolor (database name
trackSeparatorColor, class TrackSeparatorColor) defaults to empty, disabling the lines.
-trackseparatorwidth (trackSeparatorWidth, TrackSeparatorWidth) defaults to 1 and accepts a positive Tk
screen distance. These graph options affect only trackgraphs. For example:
.g configure -trackresize yes -trackseparatorcolor gray60 -trackseparatorwidth 2
Each divider follows the centre returned by track sashpos, horizontally for rows and vertically for inverted
columns. Its width is limited to the available gap. It does not change track geometry or enlarge the existing
separator hit area, and can be shown without enabling dragging. Dividers appear in SVG, PDF and PostScript
exports when -decorations yes is selected.
Applications may call the native order and separator operations regardless of -trackresize; the option
controls only the supplied mouse bindings. Custom interaction code can leave it disabled and use the same
commands. Keep the Trackgraph class in bindtags to use the standard bindings; a widget binding that returns
break before the class binding can intentionally suppress them.
Trackgraph supports line, strip and bar elements in both orientations. Polar elements are rejected. The
optional rbc::graphtoolbar package accepts -type trackgraph: zoom and pan use shared X axes and the
starting track’s Y axes; wheel zoom and coordinate annotations follow the pointed track. Separator dragging
remains available. See ::rbc::graphtoolbar and demos/trackgraph1.tcl for the interaction controls. Markers
can select a track with -track name -mapy axisName; see ::rbc::MARKER for clipping, ownership and
restrictions. See demos/trackgraph1.tcl for multiple shared X axes, live vector updates, track weights,
annotations and shared horizontal navigation.
Copyright (c) George Yashin