Graph legend `LEGEND` command¶

With -renderer cairo, legend line samples, geometric and bitmap symbols, and bar swatches use Cairo. They follow -antialias and the normal element pen, including dash colors and stipples. Swatch stipples restart at the sample origin. Text, backgrounds, and relief borders remain native. The same behavior applies to external legend windows.

Commands in this namespace document the graph legend.

LEGEND is used below as a placeholder for:

GRAPHINST legend

The legend displays an entry for graph elements. Each entry contains the element’s symbol and label and uses the drawing attributes of that element.

For example:

graph .g

.g element create signal1 -x {0 1 2 3} -y {1 4 2 5} -label "Input"
.g element create signal2 -x {0 1 2 3} -y {3 2 5 4} -label "Output"
.g legend configure -position rightmargin

The legend is a single component of the graph. Unlike elements, markers, or pens, there are no named legend objects.

Legend entries¶

Legend entries correspond to graph elements. The element’s -label option supplies the text displayed in the legend.

The order of legend entries follows the element display order.

Legend entries may be made active independently of the corresponding graph elements:

.g legend activate signal1
.g legend deactivate signal1

Activating a legend entry changes only the appearance of the entry in the legend. It does not activate the corresponding data points or change how the element is drawn in the plotting area.

To activate both independently:

.g legend activate signal1
.g element activate signal1

Legend position¶

The -position option determines where the legend is displayed.

Position	Description
`leftmargin`	Draws the legend in the left graph margin.
`rightmargin`	Draws the legend in the right graph margin. This is the default.
`topmargin`	Draws the legend in the top graph margin.
`bottommargin`	Draws the legend in the bottom graph margin.
`plotarea`	Draws the legend inside the plotting area.
`@x,y`	Places the legend at the specified screen coordinates.
`.window`	Creates an external legend window with the specified Tk pathname.

For example:

.g legend configure -position plotarea -anchor ne

places the legend in the upper-right part of the plotting area.

An explicit screen position may also be used:

.g legend configure -position @20,30 -anchor nw

For an @x,y position, negative coordinates are measured from the opposite edge of the graph. For example, a negative X coordinate is relative to the right edge and a negative Y coordinate is relative to the bottom edge.

A pathname beginning with . selects an external legend window:

.g legend configure -position .legend

Rbc creates the window at that pathname and draws the legend into it. If the external legend window is destroyed, the legend returns to rightmargin.

The -anchor option controls how the legend is positioned relative to its selected site or screen coordinate.

Legend layout¶

Legend entries are arranged as a table.

-rows and -columns can be used to request a particular table shape:

.g legend configure -columns 2

A value of 0 leaves that dimension automatic.

-ipadx and -ipady specify padding inside individual legend entries. -padx and -pady specify padding around the outside of the complete legend.

Each padding value may contain either one screen distance or two:

.g legend configure -ipadx {2 6} -pady {4 8}

A single value applies equally to both sides. Two values specify the two sides independently.

Active entries¶

LEGEND activate marks entries for drawing with the active legend style and returns the names of all entries that are currently active.

The active appearance is controlled by:

-activebackground
-activeborderwidth
-activeforeground
-activerelief

For example:

.g legend configure -activebackground lightblue -activeforeground navy -activerelief raised
.g legend activate signal1

LEGEND deactivate restores the normal legend appearance.

Legend bindings¶

Event bindings may be associated with legend entries using LEGEND bind.

Element names act as binding tags for their corresponding legend entries:

.g legend bind signal1 <Button-1> {
    puts "signal1"
}

The element under the current pointer may be obtained with LEGEND get and used by a binding:

.g legend bind all <Button-1> {
    set element [.g legend get current]
    puts $element
}

LEGEND get can also identify the entry at an explicit screen position.

Legend options¶

Option	Database name	Database class	Description
`-activebackground color`	`activeBackground`	`ActiveBackground`	Sets the background color used for active legend entries.
`-activeborderwidth distance`	`activeBorderWidth`	`ActiveBorderWidth`	Sets the width of the 3-D border around active legend entries. The default is `2`.
`-activeforeground color`	`activeForeground`	`ActiveForeground`	Sets the foreground color used for active legend entries.
`-activerelief relief`	`activeRelief`	`ActiveRelief`	Sets the relief used for active legend entries. The default is `flat`.
`-anchor anchor`	`anchor`	`Anchor`	Specifies how the legend is positioned relative to the location selected by `-position`. The default is `center`.
`-background color`	`background`	`Background`	Sets the legend background color. An empty value makes the legend background transparent.
`-bg color`	—	—	Synonym for `-background`.
`-borderwidth distance`	`borderWidth`	`BorderWidth`	Sets the width of the 3-D border around the legend. The default is `2`.
`-bd distance`	—	—	Synonym for `-borderwidth`.
`-columns number`	`columns`	`Columns`	Specifies the requested number of columns used to arrange legend entries. `0` selects the automatic layout.
`-font font`	`font`	`Font`	Sets the font used for legend labels.
`-foreground color`	`foreground`	`Foreground`	Sets the foreground color used for legend labels. The default is black.
`-fg color`	—	—	Synonym for `-foreground`.
`-hide boolean`	`hide`	`Hide`	Controls whether the legend is displayed. The default is `no`.
`-ipadx padding`	`iPadX`	`IPadX`	Sets horizontal padding inside each legend entry.
`-ipady padding`	`iPadY`	`IPadY`	Sets vertical padding inside each legend entry.
`-padx padding`	`padX`	`PadX`	Sets horizontal padding around the exterior of the legend.
`-pady padding`	`padY`	`PadY`	Sets vertical padding around the exterior of the legend.
`-position position`	`position`	`Position`	Specifies where the legend is displayed. The value may select a graph margin, `plotarea`, or an explicit `@x,y` window position. The default is `right`. In @x,y form, each coordinate accepts a Tcl integer expression.
`-raised boolean`	`raised`	`Raised`	Controls whether a legend placed in the plotting area is drawn above graph elements. The default is `no`.
`-relief relief`	`relief`	`Relief`	Sets the relief used for the legend border. The default is `sunken`.
`-rows number`	`rows`	`Rows`	Specifies the requested number of rows used to arrange legend entries. `0` selects the automatic layout.
`-shadow shadow`	`shadow`	`Shadow`	Specifies a shadow for legend labels. An empty value disables the shadow.

Legend configuration options may also be set through Tk’s option database. The resource name is legend and the resource class is Legend.

For example:

option add *Graph.legend.Foreground navy
option add *Graph.Legend.Relief raised

Copyright (c) George Yashin

Graph legend `LEGEND` command¶

Legend entries¶

Legend position¶

Legend layout¶

Active entries¶

Legend bindings¶

Legend options¶

Table of Contents

Previous topic

Next topic

This Page

Graph legend LEGEND command¶

Legend entries¶

Legend position¶

Legend layout¶

Active entries¶

Legend bindings¶

Legend options¶

Graph legend `LEGEND` command¶