Bar element BARELEMENT options

This page documents the configuration and behavior of bar elements.

With -renderer cairo, solid/stippled bar fills and error bars use Cairo, including active bars and named pens. Integer rectangle edges and stipple pixels stay sharp; -antialias applies to error strokes. Bar layout, clipping, color defaults, and stipple origin are preserved. Tk relief borders and value labels retain native rendering.

BARELEMENT denotes an element whose concrete type is BarElement. Bar elements are the default element type of a barchart widget:

barchart .b
.b element create values

A bar element may also be created explicitly in any graph widget:

.g bar create values

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

Data

X and Y coordinates may be supplied separately with -x and -y:

.b element create values -x {1 2 3 4} -y {10 15 8 20}

-xdata and -ydata are synonyms for -x and -y.

Each coordinate option may also name an existing Rbc vector:

vector create xValues yValues

xValues set {1 2 3 4}
yValues set {10 15 8 20}

.b element create values -x xValues -y yValues

When an Rbc vector is used, changes to the vector automatically invalidate and update the element.

The number of usable data points is the smaller of the X and Y vector lengths.

-data provides an alternative paired representation containing alternating X and Y values:

.b element create values -data {1 10 2 15 3 8 4 20}

This is equivalent to:

-x {1 2 3 4} -y {10 15 8 20}

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

Non-finite X or Y values are omitted from the rendered bars.

Axis mapping

-mapx and -mapy select the virtual axes through which the bar data are mapped. Their defaults are x and y.

.b axis create secondaryY
.b y2axis use secondaryY

.b element configure values -mapy secondaryY

The selected axes must have the appropriate X or Y orientation.

Bar grouping is performed only between bars mapped through the same X/Y axis pair.

Bar geometry

Each data point describes a bar centered on its X coordinate.

For an ordinary linear Y axis, the bar extends between the data Y value and the graph’s -baseline value.

For example:

.b configure -baseline 0
.b element create values -x {1 2 3} -y {4 7 2}

creates bars extending from Y=0 to the respective Y values.

Values below the baseline extend in the opposite direction:

.b element configure values -y {-4 7 -2}

The baseline is a graph widget option, not a bar-element option:

.b configure -baseline -10

See GRAPHINST for the graph widget option reference.

Bar width

-barwidth on the bar element overrides the graph-wide bar width.

.b element configure values -barwidth 0.5

Width is expressed in graph-coordinate units along the X axis.

The element default is 0.0. Any non-positive element -barwidth means to use the graph widget’s -barwidth value instead.

Therefore:

.b configure -barwidth 0.8
.b element configure values -barwidth 0

gives values an effective width of 0.8.

This permits most elements to share one graph-wide width while individual bar elements override it when necessary.

Bar modes

The graph widget’s -barmode option controls how bars that occur at the same X coordinate are arranged.

Bar mode is global to the graph rather than configured separately for each bar element.

The available modes are:

Mode	Description
normal	Equivalent to infront; bars retain the full width and are drawn according to element display order.
infront	Bars retain their ordinary position and width and may obscure bars drawn earlier.
aligned	Bars sharing an X coordinate are divided across the available bar width and displayed side by side.
overlap	Bars sharing an X coordinate are offset while retaining enough width to overlap neighboring bars.
stacked	Y values sharing an X coordinate are accumulated and drawn as successive vertical segments.

For example:

.b configure -barmode aligned
.b element create first -x {1 2 3} -y {5 7 4}
.b element create second -x {1 2 3} -y {3 6 8}

places the bars from first and second beside each other at each shared X coordinate.

Changing to:

.b configure -barmode stacked

stacks their Y values instead.

Only visible bar elements mapped through the same X/Y axis pair participate in the same grouping.

Stacked bars

In stacked mode, Y values at equal X coordinates are additive.

For example, if two visible bar values at X=1 are:

4
6

they form successive stack boundaries at 4 and 10.

The graph’s automatic Y-axis range takes the accumulated stack height into account rather than considering only the individual source values.

Stacking changes rendered geometry only. The original element Y value remains the source data value.

Consequently, operations such as ELEMENT closest continue to report the original data point associated with a rendered stacked segment rather than replacing its Y value with the cumulative stack height.

Appearance

A bar element contains a built-in normal bar pen.

Its basic appearance is controlled directly by:

Option	Description
-foreground color	Sets the primary fill color of the bar. -fg is a synonym. The default is blue.
-background color	Sets the 3-D border color and the background color used for opaque stippling. -bg is a synonym. The default is navyblue.
-borderwidth width	Sets the non-negative width of the 3-D bar border. -bd is a synonym. The default is 2.
-relief relief	Sets the relief of the 3-D border. The default is raised.
-stipple bitmap	Fills bars through the specified Tk bitmap stipple. An empty value disables stippling.

The 3-D border is drawn only when a background border is present, -borderwidth is greater than zero, and -relief is not flat.

For example:

q.b element configure values -foreground skyblue -background navy -borderwidth 2 -relief raised

With a stipple:

.b element configure values -foreground blue -background white -stipple gray50

the foreground and background colors form an opaque stippled fill.

Pens

A separately created bar pen may replace the element’s built-in normal pen with -pen:

.b pen create normalBars -type bar -foreground steelblue -background navy
.b element configure values -pen normalBars

An empty -pen value selects the built-in bar pen again.

-activepen selects the bar pen used when the element or individual data points are active. Its default is activeBar.

Only bar pens may be used by bar elements and by bar-element styles.

See PEN for creation and configuration of named pens.

Error bars of bar elements

Bar elements support symmetric and asymmetric error-bar data.

Symmetric errors are supplied with:

-xerror
-yerror

For example:

.b element configure values -yerror {0.5 0.8 0.4 1.0}

For a point (x,y), a symmetric Y error value e represents the limits:

y - e
y + e

Absolute asymmetric limits may instead be supplied with:

-xlow
-xhigh
-ylow
-yhigh

When symmetric error data are present for an axis, they take precedence over the corresponding low/high vectors.

Error data may be Tcl lists or Rbc vector names.

Their appearance is controlled by:

Option	Description
-showerrorbars value	Selects whether X errors, Y errors, both, or neither are displayed. The default is both.
-errorbarcolor color	Sets the error-bar color. defcolor uses the normal bar color.
-errorbarwidth width	Sets the non-negative error-bar line width. The default is 1.
-errorbarcap width	Sets the non-negative requested cap width. The default is 1.

If -errorbarcap is 0, Rbc chooses a cap size from the rendered bar width.

Error-bar values also participate in automatic graph extents.

Value labels of bar 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.

-showvalues displays data values at the end of each rendered bar.

It may select X values, Y values, both coordinates, or no values. The default is no.

The label is positioned at the end of the bar away from the baseline. Bars extending below the baseline therefore place their labels at the opposite end from bars extending above it.

For example:

.b element configure values -showvalues y -valueformat %.2f

Label appearance is controlled by:

Option	Description
-valueanchor anchor	Sets the Tk anchor of the label. The default is s.
-valuecolor color	Sets the label color. The default is black.
-valuefont font	Sets the label font.
-valuecommand cmd	Formats value labels with a Tcl command prefix. The default is empty.
-valueoffset {dx dy}	Moves the label anchor by signed integer pixels. Default: {0 0}.
-valueformat format	Sets the printf-style floating-point format. The default is %g.
-valuerotate angle	Rotates the label by the specified angle in degrees. The default is 0.0.
-valueshadow shadow	Specifies an optional text shadow. An empty value disables the shadow.

The displayed value is always formatted from the original X and Y source coordinates, including for bars whose screen geometry has been aligned, overlapped, or stacked.

-valueformat is validated before it is accepted. It may contain at most one floating-point conversion using a, A, e, E, f, F, g, or G; dynamic width or precision using * is not permitted.

Weights and styles

-weights associates numeric weights with data points. The value may be a Tcl list or an Rbc vector.

-styles maps ranges of those weights to named bar pens.

Each style specification has one of the forms:

penName
penName min max

For example:

.b pen create low -type bar -foreground lightblue
.b pen create high -type bar -foreground red
.b element configure values -weights {0.2 0.8 1.2 1.7} -styles {{low 0 1} {high 1 2}}

A style without explicit limits receives the legacy default range based on its position: the first style covers 0 through 1, the second 1 through 2, and so on.

Points whose weights do not match a configured range use the normal pen.

When style ranges overlap, later style entries take precedence.

Only as many weights as there are data points are considered. Points without corresponding weights retain the normal pen.

Logarithmic axes

Bar elements support logarithmic axes, with additional domain restrictions imposed by their rectangular geometry.

On a logarithmic Y axis, the drawable baseline is 1.0 rather than the graph’s linear -baseline value:

.b yaxis configure -logscale yes

Non-positive Y data cannot be mapped to the logarithmic axis and are omitted.

In stacked mode, stack values remain ordinary additive data quantities. The stack accumulator therefore starts from zero, but the first visible stacked segment uses 1.0 as its drawable lower edge because zero cannot be represented on a logarithmic axis.

On a logarithmic X axis, the complete horizontal extent of a bar must remain inside the positive logarithmic domain. A bar is omitted when its left edge, x - barWidth/2, is not positive.

This means that merely having a positive X center is not sufficient when the bar width would extend through or beyond zero.

Closest searches

Bar elements are searched using their rendered rectangles.

If the requested window point lies inside a bar rectangle, its distance is zero. Otherwise Rbc measures the distance to the rectangle boundary.

The result index and graph coordinates identify the original source data point represented by the selected rectangle.

See ELEMENT closest in ELEMENT for the common search syntax and result array.

Bar element options

Option	Database name	Database class	Description
-activepen penName	activePen	ActivePen	Specifies the named bar pen used when the element is active. An empty value disables the named active pen. The default is activeBar.
-background color	background	Background	Sets the background color of bars and the color used for their 3-D border. The default is navy blue.
-barwidth value	barWidth	BarWidth	Specifies the width of bars for this element. A positive value overrides the graph widget’s -barwidth; 0.0 uses the graph’s bar width. The default is 0.0.
-bd distance	—	—	Synonym for -borderwidth.
-bg color	—	—	Synonym for -background.
-bindtags tags	bindTags	BindTags	Specifies additional graph binding tags for the element. The default is all.
-borderwidth distance	borderWidth	BorderWidth	Sets the width of the 3-D border around bars. The default is 2.
-data data	data	Data	Supplies an even-length list of alternating X and Y values. Each literal list item accepts a Tcl numeric expression.
-errorbarcap width	errorBarCap	ErrorBarCap	Sets the requested error-bar cap width. A positive value selects an explicit size; 0 automatically derives the size from the bar width. The default is 1.
-errorbarcolor color	errorBarColor	ErrorBarColor	Sets the error-bar color. defcolor uses the bar foreground color.
-errorbarwidth width	errorBarWidth	ErrorBarWidth	Sets the error-bar line width. The default is 1.
-fg color	—	—	Synonym for -foreground.
-foreground color	foreground	Foreground	Sets the primary bar fill color. The default is blue.
-hide boolean	hide	Hide	Controls whether the element is displayed. The default is no.
-hideplot boolean	hidePlot	HidePlot	Suppresses plotting of the element while keeping it in the display list and legend. A plot-hidden bar does not contribute to automatic axis limits, bar grouping or stacking calculations, closest searches, or element hit testing. The default is no.
-label text	label	Label	Sets the element label used by the legend. The initial label is the element name.
-labelrelief relief	labelRelief	LabelRelief	Sets the relief used for the element’s legend label. The default is flat.
-mapx axisName	mapX	MapX	Specifies the X axis used to map the element’s X coordinates. The axis must exist and must be an X axis. The default is x.
-mapy axisName	mapY	MapY	Specifies the Y axis used to map the element’s Y coordinates. The axis must exist and must be a Y axis. The default is y.
-pen penName	pen	Pen	Specifies a named bar pen containing the element’s normal drawing attributes. An empty value uses the element’s built-in pen.
-relief relief	relief	Relief	Sets the relief used to draw bars. The default is raised.
-showerrorbars value	showErrorBars	ShowErrorBars	Selects which error bars are displayed: X, Y, both, or neither. The default is both.
-showvalues value	showValues	ShowValues	Selects which coordinate values are displayed next to bars. The default is no.
-state state	state	State	Sets the element state. The default is normal.
-stipple bitmap	stipple	Stipple	Specifies a bitmap used to stipple the bar fill. An empty value selects a solid fill.
-styles styles	styles	Styles	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.
-valueanchor anchor	valueAnchor	ValueAnchor	Sets the anchor used to position value labels relative to bars. The default is s.
-valuecolor color	valueColor	ValueColor	Sets the color used to draw value labels.
-valuefont font	valueFont	ValueFont	Sets the font used to draw value labels.
-valuecommand cmd	valueCommand	ValueCommand	Formats value labels with a Tcl command prefix. The default is empty.
-valueoffset {dx dy}	valueOffset	ValueOffset	Moves the label anchor by signed integer pixels. Default: {0 0}.
-valueformat format	valueFormat	ValueFormat	Sets the printf-style format used for value labels. The default is %g.
-valuerotate degrees	valueRotate	ValueRotate	Sets the rotation angle of value labels in degrees. The default is 0.0.
-valueshadow shadow	valueShadow	ValueShadow	Specifies a shadow for value labels. An empty value disables the shadow.
-weights weights	weights	Weights	Supplies per-point numeric weights used to select pens through -styles. Each literal list item accepts a Tcl numeric expression.
-x data	xdata	Xdata	Supplies the element’s X coordinates as a list or Rbc vector. Each literal list item accepts a Tcl numeric expression.
-xdata data	—	—	Synonym for -x.
-xerror data	xError	XError	Supplies symmetric X error magnitudes as a list or Rbc vector. Each literal list item accepts a Tcl numeric expression.
-xhigh data	xHigh	XHigh	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	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	Supplies the element’s Y coordinates as a list or Rbc vector. Each literal list item accepts a Tcl numeric expression.
-ydata data	—	—	Synonym for -y.
-yerror data	yError	YError	Supplies symmetric Y error magnitudes as a list or Rbc vector. Each literal list item accepts a Tcl numeric expression.
-yhigh data	yHigh	YHigh	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	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