Graph marker MARKER command

Commands in this namespace document graph markers.

MARKER is used below as a placeholder for:

GRAPHINST marker

Markers are graph annotations. They are independent of graph elements and do not contribute to the calculation of axis limits.

With -renderer cairo, line markers, arrowheads, and polygon fills/outlines use -antialias. Solid and stippled fills, colored dash gaps, caps, clipping, and -under ordering are supported. Mapped outline segments remain independent, as in native drawing. XOR markers remain native. Photo image markers use Cairo alpha compositing with existing placement and scaling. They clip to the plot; -antialias does not resample their pixels. Source image changes refresh the marker. Bitmap markers use Cairo with existing scaling, rotation, and masks. Their mapped pixels stay sharp; -antialias affects rotated background polygons. An empty foreground uses Cairo with the native GC color. Text-marker backgrounds use Cairo, including rotated edges, and clip to the plot. Text itself stays native. Window and non-photo image markers keep their Tk rendering; line markers with an empty -outline use Cairo with the native GC color.

Rbc provides six marker types:

Type	Description
bitmap	Displays a Tk bitmap
image	Displays a Tk image
line	Displays one or more connected line segments
polygon	Displays a filled and/or outlined polygon
text	Displays text
window	Displays an embedded Tk window

A marker is created by specifying its type:

graph .g
.g marker create text -name label -coords {1.0 2.0} -text "Operating point"
.g marker create line -name limit -coords {0 5 10 5} -outline red

Unlike elements and pens, the marker name is not a positional argument of MARKER create. Use -name to select an explicit name. If -name is omitted, Rbc generates a marker name.

Marker coordinates

Marker coordinates are graph coordinates and are mapped through the axes selected by -mapx and -mapy.

The number of coordinates depends on the marker type:

Marker type	Coordinates
bitmap	One or two X-Y pairs
image	One or two X-Y pairs
line	Two or more X-Y pairs
polygon	Three or more X-Y pairs
text	One X-Y pair
window	One X-Y pair

For bitmap and image markers, one X-Y pair specifies the marker position. Two pairs specify opposite corners of a bounding rectangle. Bitmap markers are scaled to that rectangle. Photo images are likewise scaled to the rectangle; other Tk image types are drawn at their natural size.

Coordinate values may be Tcl numeric expressions. Inf, +Inf, and -Inf select elastic axis bounds.

An empty -coords value leaves the marker without drawable coordinates.

For example:

.g marker create text -coords {-Inf Inf} -anchor nw -text "upper left"

Drawing order

Markers have their own display order. MARKER before and MARKER after change the position of a marker in that order.

By default markers are drawn over graph elements. The -under option changes whether an individual marker is drawn below or above the element layer.

.g marker configure region -under yes

The marker ordering operations affect ordering between markers; they do not replace the -under setting.

Element association

-element associates a marker with an element:

.g marker create text -name note -element signal -coords {2 5} -text signal

The marker is displayed only while the associated element is displayed. An empty -element value removes the association.

Marker bindings

Markers participate in graph component bindings. Bindings are made with MARKER bind.

Every marker has its marker name as an implicit binding tag. Additional tags are selected with -bindtags.

The default binding tags depend on the marker type:

Type	Default -bindtags
bitmap	Bitmap all
image	Image all
line	Line all
polygon	Polygon all
text	Text all
window	Window all

For example:

.g marker create text -name note -coords {1 2} -text "click me" -bindtags {annotation all}
.g marker bind annotation <Button-1> {
    puts "annotation selected"
}

Marker types and options

All marker types share the coordinate, visibility, axis-mapping, naming, binding, state, drawing-order, and offset options described below. Each concrete marker type then adds its own drawing options.

MARKER cget and MARKER configure operate on the option table of the concrete marker being addressed. An option valid for one marker type is not necessarily valid for another.

Common marker options

Option	Database name	Database class	Description
-bindtags tagList	bindTags	BindTags	Specifies additional binding tags associated with the marker. The marker name is always an implicit binding tag. The default class tag depends on the marker type.
-coords coordList	coords	Coords	Specifies the graph coordinates of the marker. The required number of coordinates depends on the marker type. The default is empty. Each coordinate accepts a Tcl numeric expression; Inf, +Inf and -Inf select elastic bounds.
-element elementName	element	Element	Associates the marker with an element. The marker is displayed only while that element is displayed. An empty value removes the association.
-hide boolean	hide	Hide	Specifies whether the marker is hidden. The default is no.
-mapx axisName	mapX	MapX	Specifies the X axis used to map marker 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 marker coordinates. The axis must exist and must be a Y axis. The default is y.
-name markerName	—	—	Specifies the marker name. During creation, an omitted name is generated automatically. Reconfiguring -name renames the marker; the new name must be non-empty, must not begin with -, and must not already belong to another marker.
-state state	state	State	Specifies the marker state: normal, active, or disabled. The default is normal.
-under boolean	under	Under	Specifies whether the marker is drawn below graph elements rather than above them. The default is no.
-xoffset distance	xOffset	XOffset	Adds a horizontal screen-coordinate offset after the marker has been mapped. The default is 0.
-yoffset distance	yOffset	YOffset	Adds a vertical screen-coordinate offset after the marker has been mapped. The default is 0.

Bitmap marker options

Bitmap markers display a Tk bitmap.

.g marker create bitmap -name bitmap1 -coords {1 2} -bitmap questhead

In addition to the common marker options, bitmap markers support:

Option	Database name	Database class	Description
-anchor anchor	anchor	Anchor	Specifies how the bitmap is positioned relative to its reference coordinates. The default is center.
-background color	—	—	Specifies the bitmap background color. This is a synonym for -fill.
-bg color	—	—	Synonym for -background.
-bitmap bitmap	bitmap	Bitmap	Specifies the Tk bitmap to display.
-fill color	background	Background	Specifies the bitmap background color.
-foreground color	—	—	Specifies the bitmap foreground color. This is a synonym for -outline.
-fg color	—	—	Synonym for -foreground.
-mask bitmap	mask	Mask	Specifies an optional bitmap mask.
-outline color	foreground	Foreground	Specifies the bitmap foreground color.
-rotate degrees	rotate	Rotate	Specifies the rotation angle in degrees. The default is 0.

Image marker options

Image markers display a Tk image.

image create photo icon -file icon.png
.g marker create image -name iconMarker -coords {1 2} -image icon

In addition to the common marker options, image markers support:

Option	Database name	Database class	Description
-anchor anchor	anchor	Anchor	Specifies how the image is positioned relative to its coordinate. The default is center.
-image imageName	image	Image	Specifies the Tk image to display.

Line marker options

Line markers draw connected line segments through their X-Y coordinate pairs.

.g marker create line -name threshold -coords {-Inf 5 Inf 5} -outline red -linewidth 2

In addition to the common marker options, line markers support:

Option	Database name	Database class	Description
-arrow position	arrow	Arrow	Specifies whether arrowheads are drawn at the ends of the line marker. position must be none, first, last, or both. first draws an arrowhead at the first coordinate, last at the final coordinate, and both at both ends. The shaft is shortened to the neck of each arrowhead so that it does not protrude through the arrowhead. Arrowheads use the marker’s -outline color. The default is none.
-arrowshape {a b c}	arrowShape	ArrowShape	Specifies the arrowhead geometry as three screen distances. a is the distance from the arrowhead neck to its tip, b is the distance from the trailing points to the tip, and c is the distance from the outside edge of the line to the trailing points. The default is {8 10 3}.
-cap style	cap	Cap	Specifies the line cap style. Accepted styles are butt, projecting, and round. The default is butt.
-dashes dashList	dashes	Dashes	Specifies the dash pattern. An empty value selects a solid line. Each numeric list item accepts a Tcl integer expression.
-dashoffset distance	dashOffset	DashOffset	Specifies the offset into the dash pattern. The default is 0.
-fill color	fill	Fill	Specifies the color used for the off portions of a dashed line. An empty value uses ordinary on/off dashes. The default is empty.
-join style	join	Join	Specifies how adjacent segments are joined. Accepted styles are bevel, miter, and round. The default is miter.
-linewidth distance	lineWidth	LineWidth	Specifies the line width. The default is 1.
-outline color	outline	Outline	Specifies the primary line color. The default is black.
-xor boolean	xor	Xor	Specifies whether the line is drawn using XOR drawing. The default is no.

Arrowheads

Line markers may draw an arrowhead at either end of the line by using the -arrow option. Accepted values are none, first, last, and both.

For example:

graph .g
pack .g
.g marker create line -name direction -coords {0 0 5 4 10 2} -outline red -linewidth 2 -arrow last

The arrowhead shape may be adjusted with -arrowshape. It accepts three screen distances {a b c}:

.g marker configure direction -arrow both -arrowshape {8 10 3}

a specifies the distance from the arrowhead neck to its tip, b specifies the distance from the trailing points to the tip, and c specifies the distance from the outside edge of the line to the trailing points.

The arrowhead uses the line marker’s -outline color. The line shaft is shortened to the neck of the arrowhead so that it does not protrude through the filled arrowhead.

Screen-distance units accepted by Tk may also be used:

.g marker configure direction -arrowshape {8p 10p 3p}

Polygon marker options

Polygon markers draw the closed polygon formed by their coordinate pairs.

.g marker create polygon -name region -coords {0 0 4 0 4 3 0 3} -fill lightblue -outline navy

In addition to the common marker options, polygon markers support:

Option	Database name	Database class	Description
-cap style	cap	Cap	Specifies the outline cap style. Accepted styles are butt, projecting, and round. The default is butt.
-dashes dashList	dashes	Dashes	Specifies the dash pattern used for the polygon outline. An empty value selects a solid outline. Each numeric list item accepts a Tcl integer expression.
-fill colorList	fill	Fill	Specifies the polygon fill colors. The value may contain one foreground color or a foreground and background color. With -stipple, the second color supplies the stipple background. An empty value disables filling. The default foreground color is red.
-join style	join	Join	Specifies how adjacent outline segments are joined. Accepted styles are bevel, miter, and round. The default is miter.
-linewidth distance	lineWidth	LineWidth	Specifies the width of the polygon outline. The value must be non-negative. The default is 1.
-outline colorList	outline	Outline	Specifies the polygon outline colors. The value may contain one foreground color or a foreground and background color. For dashed outlines, the second color is used for the off portions of the dash pattern. An empty value disables the outline color. The default foreground color is black.
-stipple bitmap	stipple	Stipple	Specifies an optional stipple bitmap used when filling the polygon. An empty value selects an unstippled fill.
-xor boolean	xor	Xor	Specifies whether the polygon outline uses XOR drawing. The default is no.

Text marker options

Text markers display one or more lines of text.

.g marker create text -name annotation -coords {3 8} -text "maximum" -anchor s

In addition to the common marker options, text markers support:

Option	Database name	Database class	Description
-anchor anchor	anchor	Anchor	Specifies how the text is positioned relative to its coordinate. The default is center.
-background color	background	MarkerBackground	Specifies the text background color. This is a synonym for -fill.
-bg color	—	—	Synonym for -background.
-fill color	—	—	Specifies the text background color.
-font font	font	Font	Specifies the font used to draw the text.
-foreground color	foreground	Foreground	Specifies the text color. This is a synonym for -outline.
-fg color	—	—	Synonym for -foreground.
-justify justify	justify	Justify	Specifies justification of multiline text. The default is left.
-outline color	—	—	Specifies the text color. The default is black.
-padx padding	padX	PadX	Specifies horizontal padding around the text. The default is 4.
-pady padding	padY	PadY	Specifies vertical padding around the text. The default is 4.
-rotate degrees	rotate	Rotate	Specifies the text rotation angle in degrees. The default is 0.
-shadow shadow	shadow	Shadow	Specifies the text shadow.
-text text	text	Text	Specifies the text to display.

Window marker options

Window markers display a Tk window inside the graph.

The window must be managed by the graph marker.

button .g.info -text Info
.g marker create window -name infoMarker -coords {2 4} -window .g.info

In addition to the common marker options, window markers support:

Option	Database name	Database class	Description
-anchor anchor	anchor	Anchor	Specifies how the window is positioned relative to its coordinate. The default is center.
-height distance	height	Height	Specifies an explicit positive height for the embedded window. When left at its initial default of 0, the child’s requested height is used. Explicitly configuring 0 is not accepted.
-width distance	width	Width	Specifies an explicit positive width for the embedded window. When left at its initial default of 0, the child’s requested width is used. Explicitly configuring 0 is not accepted.
-window pathName	window	Window	Specifies the Tk window managed by the marker. The window must be a direct child of the graph widget. An empty value removes the managed window.

Option database

Marker options may be supplied through Tk’s option database. Each concrete marker type has its own resource class:

Marker type	Resource class
bitmap	BitmapMarker
image	ImageMarker
line	LineMarker
polygon	PolygonMarker
text	TextMarker
window	WindowMarker

The resource name is the marker name.

For example:

option add *Graph.TextMarker.Foreground navy
option add *Graph.LineMarker.LineWidth 2

---

Copyright (c) George Yashin