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

Default

Description

-color color

color

Color

#000080; active pen: #0000ff

Sets the trace color.

-dashes dashes

dashes

Dashes

Empty

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

1

Sets the requested size of error-bar caps. 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.

-linewidth width

lineWidth

LineWidth

1

Sets the trace width. 0 suppresses the trace.

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

-pixels size

pixels

Pixels

0.125i

Sets the requested symbol size.

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

-symbol symbol

symbol

Symbol

circle

Sets the symbol drawn at data points.

-type type

—

—

line

Selects the pen type when the pen is created. line creates a line pen; strip also creates a line pen.

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

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

Default

Description

-background color

background

Background

navyblue; active pen: red

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.

-bg color

—

—

navyblue; active pen: red

Synonym for -background.

-borderwidth width

borderWidth

BorderWidth

2

Sets the width of the 3-D border around bars.

-bd width

—

—

2

Synonym for -borderwidth.

-errorbarcolor color

errorBarColor

ErrorBarColor

defcolor

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

-errorbarwidth width

errorBarWidth

ErrorBarWidth

1

Sets the error-bar line width.

-errorbarcap width

errorBarCap

ErrorBarCap

1

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

-fillopacity value

fillOpacity

FillOpacity

1.0

Fill opacity from 0.0 to 1.0. Cairo/SVG support partial opacity; native/PostScript only suppress zero.

-foreground color

foreground

Foreground

blue; active pen: pink

Specifies the primary bar fill color. With a stipple, it supplies the stipple foreground. An empty value disables the foreground fill.

-fg color

—

—

blue; active pen: pink

Synonym for -foreground.

-relief relief

relief

Relief

raised

Sets the relief used to draw bars.

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

-stipple bitmap

stipple

Stipple

Empty

Specifies a bitmap used to stipple the bar fill. An empty value selects a solid fill.

-type type

—

—

bar

Selects the pen type when the pen is created.

-valueanchor anchor

valueAnchor

ValueAnchor

s

Sets the anchor used to position value labels relative to bars.

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

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