Trackgraph layout

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 and strip 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
-weight	1.0	Positive finite share of remaining layout space after track minima are allocated; at most 1000000.
-minheight	40	Positive minimum requested plot height, or width when inverted, in Tk screen-distance units.
-height	160	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 -minheight. Ignored in fit layout.
-yaxes	empty	List of existing Y axes assigned exclusively to this track and displayed in its left margin (bottom when inverted).

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 and strip elements in both orientations. Bar/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