Strip element STRIPELEMENT options

This page documents the configuration and behavior of strip elements.

STRIPELEMENT denotes an element whose concrete type is StripElement. Strip elements are the default element type of a stripchart widget:

stripchart .s
.s element create signal

The common element operations such as create, configure, activate, closest, bind, and delete are documented in ELEMENT.

Strip elements use the same underlying line-rendering machinery as line elements. Their data handling, axis mapping, pens, smoothing, symbols, error bars, value labels, weights, and styles therefore have the same semantics as described in LINEELEMENT.

Differences from line elements

A strip element exposes a restricted line-element option set intended for stripchart use.

In particular, the following LINEELEMENT options are not available for strip elements:

Option

Line-element feature

-areabackground

area-fill stipple background

-areaforeground

area-fill foreground

-areapattern

area filling with a solid or stipple pattern

-areaclose

area fill closure

-areaopacity

Cairo/SVG solid area fill opacity

-areatile

tiled area filling

-param

per-point parameter mapping returned by ELEMENT closest

-state

line-element state option

-trace

filtering of increasing/decreasing X trace directions

All other options listed below use the same interpretation as the corresponding option on LINEELEMENT.

Data

Strip-element coordinates may be supplied with:

-x
-y
-xdata
-ydata
-data

For example:

.s element create signal -x {0 1 2 3 4} -y {1 4 2 5 3}

RBC vector names may be used instead of literal coordinate lists:

vector create time voltage

time set    {0 1 2 3 4}
voltage set {1 4 2 5 3}

.s element create signal -x time -y voltage

The same transactional and left-to-right data-option semantics described for LINEELEMENT apply.

Non-finite data values and values outside the domain of a logarithmic axis form discontinuities in the rendered trace. Points on opposite sides of such a discontinuity are not connected.

Display decimation

Strip elements support -decimate none|auto with the same screen-density decimation semantics described for LINEELEMENT.

With -decimate auto, dense eligible strip data can be reduced before full world-to-screen mapping. The persistent data-domain cache supports monotonic X data, ranged Y updates, and pure tail growth of attached RBC vectors.

This makes -decimate auto particularly suitable for continuously growing stripchart waveforms:

stripchart .s
vector create time voltage
.s element create signal -xdata time -ydata voltage -symbol none -showvalues no -smooth linear -decimate auto
time append $newTime
voltage append $newVoltage

If appended X values preserve the existing monotonic direction, only the newly exposed source data and affected cache summaries need to be examined. Shrinkage, non-monotonic growth, invalid data, or unknown source changes automatically fall back to the more general mapping path.

Decimation affects screen rendering only. PostScript output retains full source resolution.

Smoothing

Strip elements support the same smoothing modes as line elements:

linear
step
natural
cubic
quadratic
catrom

linear is the default.

Spline smoothing operates in mapped screen coordinates. Natural, quadratic, and Catmull-Rom smoothing require at least three mapped points.

As with line elements, spline smoothing never bridges a discontinuity. Each continuous run containing at least three mapped points is smoothed independently. Runs containing fewer than three mapped points remain ordinary linear trace segments.

Pens and symbols

Strip elements use line pens.

The built-in normal pen can be configured directly with options such as:

-color
-linewidth
-dashes
-offdash
-fill
-outline
-outlinewidth
-pixels
-symbol

A separately created line pen may be selected with -pen:

.s pen create tracePen -type line -color blue -linewidth 2
.s element configure signal -pen tracePen

-activepen selects the pen used when the element or individual data points are active.

See LINEELEMENT for detailed descriptions of line pens, symbols, symbol scaling, and symbol-density control.

Error bars of strip elements

Strip elements support the same symmetric and asymmetric error-bar data as line elements:

-xerror
-xlow
-xhigh
-yerror
-ylow
-yhigh

Their appearance is controlled by:

-showerrorbars
-errorbarcolor
-errorbarwidth
-errorbarcap

See LINEELEMENT for the complete error-bar semantics.

X and Y error bands of strip elements

Strip elements support -errorband none|x|y and all five band-style options listed below, with the same relative/absolute bounds, gap handling, linear/step interpolation, and renderer limitations as line elements. See the X and Y error bands section in LINEELEMENT. Their lack of ordinary area-fill options does not prevent error-band filling.

Value labels of strip elements

-valuecommand can replace the label text with a Tcl callback. See the custom value-label text section in LINEELEMENT for the callback arguments and error handling.

Strip elements can display coordinate values next to their data points using -showvalues.

Label appearance is controlled by:

-valueanchor
-valuecolor
-valuefont
-valuecommand
-valueoffset
-valueformat
-valuerotate
-valueshadow

See LINEELEMENT for value-selection and formatting behavior.

Weights and styles

-weights supplies a numeric weight for each data point and -styles maps weight ranges to named line pens.

The syntax and precedence rules are identical to those described for LINEELEMENT.

Strip element options

The complete strip-element option set is:

Option

Database name

Database class

Default

Description

-activepen penName

activePen

ActivePen

activeLine

Specifies the named line pen used when the element is active. An empty value disables the named active pen.

-bindtags tags

bindTags

BindTags

all

Specifies additional graph binding tags for the element.

-color color

color

Color

#000080

Sets the built-in normal pen’s trace color.

-dashes dashes

dashes

Dashes

Empty

Sets the built-in normal pen’s trace dash pattern. An empty value selects a solid line. Each numeric list item accepts a Tcl integer expression.

-data data

data

Data

Empty

Supplies an even-length list of alternating X and Y values. Each literal list item accepts a Tcl numeric expression.

-decimate mode

decimate

Decimate

none

Selects automatic screen-density trace decimation. Accepted values are none and auto. auto is applied only when the strip element and current display density are suitable.

-errorband mode

errorBand

ErrorBand

none

Selects none, x or y; fills between the selected error bounds.

-errorbandpattern pattern

errorBandPattern

ErrorBandPattern

solid

Solid, Tk bitmap stipple, or empty to disable the pattern.

-errorbandforeground color

errorBandForeground

ErrorBandForeground

black

Band solid/stipple foreground.

-errorbandbackground color

errorBandBackground

ErrorBandBackground

white

Band stipple background. Empty leaves gaps transparent.

-errorbandtile image

errorBandTile

ErrorBandTile

Empty

Image tile; takes precedence over the pattern.

-errorbandopacity value

errorBandOpacity

ErrorBandOpacity

1.0

Solid opacity 0 to 1, Cairo/SVG only. Native/PostScript ignore it.

-errorbarcap width

errorBarCap

ErrorBarCap

1

Sets the requested error-bar cap width. A positive value selects an explicit size; 0 automatically derives the size from the symbol size.

-errorbarcolor color

errorBarColor

ErrorBarColor

defcolor

Sets the error-bar color. defcolor uses the trace color.

-errorbarwidth width

errorBarWidth

ErrorBarWidth

1

Sets the error-bar line width.

-fill color

fill

Fill

defcolor

Sets the symbol fill color. defcolor uses the trace color; an empty value leaves symbols unfilled.

-hide boolean

hide

Hide

no

Controls whether the element is displayed.

-hideplot boolean

hidePlot

HidePlot

no

Suppresses plotting of the element while keeping it in the display list and legend. A plot-hidden element does not contribute to automatic axis limits and is ignored by closest searches and element hit testing.

-label text

label

Label

Element name

Sets the element label used by the legend. The initial label is the element name.

-labelrelief relief

labelRelief

LabelRelief

flat

Sets the relief used for the element’s legend label.

-linewidth width

lineWidth

LineWidth

1

Sets the built-in normal pen’s trace width. 0 suppresses the trace.

-track name

track

Track

Empty

Assigns the element to a named ::rbc::TRACKGRAPH track. The selected -mapy axis must belong to the same track. Required in trackgraph.

-mapx axisName

mapX

MapX

x

Specifies the X axis used to map the element’s X coordinates. The axis must exist and must be an X axis.

-mapy axisName

mapY

MapY

y

Specifies the Y axis used to map the element’s Y coordinates. The axis must exist and must be a Y axis.

-reduce tolerance

reduce

Reduce

0.0

Sets the screen-space trace reduction tolerance in pixels. 0 disables reduction. With -symbolpoints reduced, symbols and value labels use surviving original samples.

-symbolpoints mode

symbolPoints

SymbolPoints

all

Selects all or reduced original samples for symbols and value labels. Reduced selection requires a positive -reduce tolerance.

-maxsymbols number

maxSymbols

MaxSymbols

0

Requests a reduced symbol display density when the element contains many points. 0 draws symbols without this reduction.

-offdash color

offDash

OffDash

Empty

Sets the color used for the gaps of a dashed trace. An empty value leaves the gaps transparent; defcolor uses the trace color.

-outline color

outline

Outline

defcolor

Sets the symbol outline color. defcolor uses the trace color.

-outlinewidth width

outlineWidth

OutlineWidth

1

Sets the non-negative width of symbol outlines.

-pen penName

pen

Pen

Empty

Specifies a named line pen containing the element’s normal drawing attributes. An empty value uses the element’s built-in pen.

-pixels size

pixels

Pixels

0.125i

Sets the requested symbol size.

-scalesymbols boolean

scaleSymbols

ScaleSymbols

no

Controls whether symbol sizes are automatically scaled as the axis ranges change.

-showerrorbars value

showErrorBars

ShowErrorBars

both

Selects which error bars are displayed: X, Y, both, or neither.

-showvalues value

showValues

ShowValues

no

Selects which coordinate values are displayed next to data points.

-smooth mode

smooth

Smooth

linear

Selects line smoothing. Accepted modes are linear, step, natural, cubic, quadratic, and catrom.

-styles styles

styles

Styles

Empty

Specifies pens selected according to -weights. Each style is either penName or {penName min max}. Bare pen names receive successive implicit weight ranges. An empty value disables weight-selected styles.

-symbol symbol

symbol

Symbol

circle

Sets the symbol drawn at data points.

-valueanchor anchor

valueAnchor

ValueAnchor

s

Sets the anchor used to position value labels relative to their data points.

-valuecolor color

valueColor

ValueColor

#000000

Sets the color used to draw value labels.

-valuefont font

valueFont

ValueFont

TkSmallCaptionFont (Unix); Arial 6 (Windows)

Sets the font used to draw value labels.

-valuecommand cmd

valueCommand

ValueCommand

Empty

Formats value labels with a Tcl command prefix.

-valueoffset {dx dy}

valueOffset

ValueOffset

0 0

Moves the label anchor by signed integer pixels.

-valueformat format

valueFormat

ValueFormat

%g

Sets the printf-style format used for value labels.

-valuerotate degrees

valueRotate

ValueRotate

0.0

Sets the rotation angle of value labels in degrees.

-valueshadow shadow

valueShadow

ValueShadow

Empty

Specifies a shadow for value labels. An empty value disables the shadow.

-weights weights

weights

Weights

Empty

Supplies per-point numeric weights used to select pens through -styles. Each literal list item accepts a Tcl numeric expression.

-x data

xData

XData

Empty

Supplies the element’s X coordinates as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.

-xdata data

—

—

Empty

Synonym for -x.

-xerror data

xError

XError

Empty

Supplies symmetric X error magnitudes as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.

-xhigh data

xHigh

XHigh

Empty

Supplies the upper X error endpoints as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.

-xlow data

xLow

XLow

Empty

Supplies the lower X error endpoints as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.

-y data

yData

YData

Empty

Supplies the element’s Y coordinates as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.

-ydata data

—

—

Empty

Synonym for -y.

-yerror data

yError

YError

Empty

Supplies symmetric Y error magnitudes as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.

-yhigh data

yHigh

YHigh

Empty

Supplies the upper Y error endpoints as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.

-ylow data

yLow

YLow

Empty

Supplies the lower Y error endpoints as a list or RBC vector. Each literal list item accepts a Tcl numeric expression.


Copyright (c) George Yashin