Graph pen `PEN` command¶

Commands in this namespace document graph pens.

PEN is used below as a placeholder for:

GRAPHINST pen

Pens define reusable drawing attributes for graph elements. An element may use a pen as its normal pen, as its active pen, or select several pens through its -weights and -styles options.

For example:

graph .g
.g pen create tracePen -type line -color red -linewidth 2
.g element create signal -x {0 1 2 3} -y {1 4 2 5} -pen tracePen

See ELEMENT, LINEELEMENT, STRIPELEMENT, and BARELEMENT for how elements select and use pens.

Pen types¶

Rbc has two concrete pen implementations:

Pen type	Used by
line	line and strip elements
bar	bar elements

The -type option selects the pen type when the pen is created:

.g pen create lineStyle -type line
.g pen create barStyle -type bar

-type strip also creates a line pen because strip elements use the same drawing implementation as line elements.

If -type is omitted, the default follows the graph widget type:

Widget	Default pen type
`graph`	line
`barchart`	bar
`stripchart`	line

The actual concrete pen type may be queried with PEN type.

Line pens may be assigned to line and strip elements. Bar pens may be assigned only to bar elements. Rbc rejects attempts to use a pen with an incompatible element type.

-type is a creation-time selector. Changing it after a pen has been created does not convert the existing pen to another concrete type. Use PEN type to determine the actual type of an existing pen.

Built-in active pens¶

Every graph, barchart, stripchart, and polar widget automatically creates two named pens:

activeLine
activeBar

activeLine is the default active pen for line and strip elements. activeBar is the default active pen for bar elements.

They may be configured like any other named pen:

.g pen configure activeLine -color red -symbol square

Changing one of these pens changes the active appearance of all elements that reference it.

The normal defaults differ from the active defaults. A normal line pen uses navy blue while activeLine uses blue. A normal bar pen uses blue foreground with navy-blue background while activeBar uses pink foreground with red background.

Using named pens¶

-pen selects the normal pen of an element:

.g pen create normalStyle -type line -color navy -linewidth 2
.g element configure signal -pen normalStyle

-activepen selects its active pen:

.g pen create selectedStyle -type line -color red -symbol diamond
.g element configure signal -activepen selectedStyle

Pens can also be selected per data point through an element’s -weights and -styles options:

.g pen create low  -type line -color blue
.g pen create high -type line -color red

.g element configure signal -weights {0.2 0.8 1.2 1.7} -styles {{low 0 1} {high 1 2}}

See LINEELEMENT and BARELEMENT for the complete weight/style semantics.

Pen lifetime¶

Named pens belong to a single graph widget.

Deleting a pen removes its name immediately from the graph’s visible pen collection. If an element is still using that pen, physical destruction is deferred until the final reference is released.

This means it is safe to delete a pen currently referenced by an existing element: that element can continue drawing with the retained pen. The deleted name is no longer available for new references.

Line pens¶

Line pens control connecting traces, symbols, error bars, and data-value labels for line and strip elements.

Traces¶

-color, -linewidth, -dashes, and -offdash control the connecting trace.

.g pen create dashed -type line -color blue -linewidth 2 -dashes {4 2}

-linewidth 0 suppresses the connecting trace while leaving symbols and other pen features available.

An empty -dashes value selects a solid trace.

-offdash optionally supplies a color for the normally empty portions of a dashed line. An empty value leaves those portions transparent; defcolor uses the trace color.

Symbols¶

-symbol selects the symbol drawn at data points.

Built-in symbols are:

none
circle
square
diamond
plus
cross
splus
scross
triangle
arrow

A Tk bitmap may also be specified:

-symbol bitmapName
-symbol {bitmapName maskName}

Symbol appearance is controlled by:

-pixels
-fill
-outline
-outlinewidth

-fill defcolor and -outline defcolor use the trace color. An empty -fill leaves the symbol interior transparent.

Error bars of line element pen¶

A line pen controls the appearance of error-bar data supplied by its element.

-showerrorbars
-errorbarcolor
-errorbarwidth
-errorbarcap

-showerrorbars selects X errors, Y errors, both, or neither.

-errorbarcolor defcolor uses the trace color.

The pen does not contain error data itself. Error coordinates are supplied by the element through -xerror, -yerror, -xlow, -xhigh, -ylow, and -yhigh.

Value labels of line element pen¶

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

A line pen may display the element’s data values with -showvalues.

Appearance is controlled by:

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

The default value format is %g.

-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, and dynamic width or precision using * is not permitted.

Line pen options¶

Option	Database name	Database class	Description
`-color color`	`color`	`Color`	Sets the trace color. The default is navy blue for normal line pens and blue for `activeLine`.
`-dashes dashes`	`dashes`	`Dashes`	Sets the trace dash pattern. An empty value selects a solid line. Each numeric list item accepts a Tcl integer expression.
`-errorbarcap width`	`errorBarCap`	`ErrorBarCap`	Sets the requested size of error-bar caps. A positive value selects an explicit size; `0` automatically derives the size from the symbol size. The default is `1`.
`-errorbarcolor color`	`errorBarColor`	`ErrorBarColor`	Sets the error-bar color. `defcolor` uses the trace color.
`-errorbarwidth width`	`errorBarWidth`	`ErrorBarWidth`	Sets the error-bar line width. The default is `1`.
`-fill color`	`fill`	`Fill`	Sets the symbol fill color. `defcolor` uses the trace color; an empty value leaves symbols unfilled.
`-linewidth width`	`lineWidth`	`LineWidth`	Sets the trace width. The default is `1`; `0` suppresses the trace.
`-offdash color`	`offDash`	`OffDash`	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`	Sets the symbol outline color. `defcolor` uses the trace color.
`-outlinewidth width`	`outlineWidth`	`OutlineWidth`	Sets the non-negative width of symbol outlines. The default is `1`.
`-pixels size`	`pixels`	`Pixels`	Sets the requested symbol size. The default is `0.125i`.
`-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 data points. The default is `no`.
`-symbol symbol`	`symbol`	`Symbol`	Sets the symbol drawn at data points. The default is `circle`.
`-type type`	—	—	Selects the pen type when the pen is created. `line` creates a line pen; `strip` also creates a line pen. The default is `line`.
`-valueanchor anchor`	`valueAnchor`	`ValueAnchor`	Sets the anchor used to position value labels relative to their data points. The default is `s`.
`-valuecolor color`	`valueColor`	`ValueColor`	Sets the color used to draw value labels. The default is black.
`-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.

Bar pens¶

Bar pens control bar fill, border appearance, error bars, and data-value labels.

Bar appearance¶

The principal options are:

-foreground
-background
-borderwidth
-relief
-stipple

-foreground specifies the primary bar fill color.

-background supplies the Tk 3-D border and the background used for an opaque stipple.

For example:

.b pen create bars -type bar -foreground steelblue -background navy -borderwidth 2 -relief raised

-fg, -bg, and -bd are synonyms for -foreground, -background, and -borderwidth.

An optional Tk bitmap may be supplied through -stipple.

Error bars of bar element pen¶

As with line pens, bar pens control error-bar appearance rather than the error data itself.

-showerrorbars
-errorbarcolor
-errorbarwidth
-errorbarcap

-errorbarcolor defcolor uses the normal bar drawing color.

Value labels of bar element pen¶

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

Bar pens use the same value-label controls as line pens:

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

See BARELEMENT for placement of value labels relative to the baseline and rendered bar geometry.

Bar pen options¶

Option	Database name	Database class	Description
`-background color`	`background`	`Background`	Specifies the bar background and the color resource used for its 3-D border. With a stipple, it supplies the stipple background. An empty value disables the background and 3-D border. The default is navy blue; `activeBar` defaults to red.
`-bg color`	—	—	Synonym for `-background`.
`-borderwidth width`	`borderWidth`	`BorderWidth`	Sets the width of the 3-D border around bars. The default is `2`.
`-bd width`	—	—	Synonym for `-borderwidth`.
`-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`.
`-errorbarcap width`	`errorBarCap`	`ErrorBarCap`	Sets the requested size of error-bar caps. A positive value selects an explicit size; `0` automatically derives the size from the bar width. The default is `1`.
`-foreground color`	`foreground`	`Foreground`	Specifies the primary bar fill color. With a stipple, it supplies the stipple foreground. An empty value disables the foreground fill. The default is blue; `activeBar` defaults to pink.
`-fg color`	—	—	Synonym for `-foreground`.
`-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`.
`-stipple bitmap`	`stipple`	`Stipple`	Specifies a bitmap used to stipple the bar fill. An empty value selects a solid fill.
`-type type`	—	—	Selects the pen type when the pen is created. The default is `bar`.
`-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. The default is black.
`-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.

Option database¶

Named pens use the Tk option database with resource class Pen.

This allows common pen defaults or defaults for particular named pens to be supplied before a graph is created.

For example:

option add *Graph.Pen.Color blue
option add *Graph.activeLine.color green

Copyright (c) George Yashin

Graph pen `PEN` command¶

Pen types¶

Built-in active pens¶

Using named pens¶

Pen lifetime¶

Line pens¶

Traces¶

Symbols¶

Error bars of line element pen¶

Value labels of line element pen¶

Line pen options¶

Bar pens¶

Bar appearance¶

Error bars of bar element pen¶

Value labels of bar element pen¶

Bar pen options¶

Option database¶

Table of Contents

Previous topic

Next topic

This Page

Graph pen PEN command¶

Pen types¶

Built-in active pens¶

Using named pens¶

Pen lifetime¶

Line pens¶

Traces¶

Symbols¶

Error bars of line element pen¶

Value labels of line element pen¶

Line pen options¶

Bar pens¶

Bar appearance¶

Error bars of bar element pen¶

Value labels of bar element pen¶

Bar pen options¶

Option database¶

Graph pen `PEN` command¶