The LEGEND function adds a legend to 2D or 3D line plots, bar plots, contour plots, or vector plots. By default, for line plots, bar plots, and contour plots the NAME property of the graphic item is used for the label within the legend. By default, for vector plots the mean magnitude of the vector field is used for length of the sample vector and for the legend label. In both cases the default label can be overridden with the LABEL property.
Example
Copy and paste the following code to the IDL command line to generate the above graphic: y
theory = SIN(2.0*FINDGEN(201)*!PI/25.0)*EXP(-0.02*FINDGEN(201))
observed = theory + RANDOMU(seed,201)*0.4-0.2
plot1 = PLOT(observed, 'b2', NAME='Observed')
plot2 = PLOT(theory, /OVERPLOT, 'r2', NAME='Theory')
leg = LEGEND(TARGET=[plot1,plot2], POSITION=[185,0.9], $
/DATA, /AUTO_TEXT_COLOR)
See the bottom for an example using a vector plot.
Syntax
graphic = LEGEND([, Keywords=value][, Properties=value])
Keywords
Keywords are applied only during the initial creation of the graphic.
[, /DATA] [, /DEVICE] [, /NORMAL] [, /RELATIVE] [, TARGET=variable]
Properties
Properties can be set as keywords to the function during creation, or retrieved or changed using the "." notation after creation.
AUTO_TEXT_COLOR, COLOR, FONT_NAME, FONT_SIZE, FONT_STYLE, HORIZONTAL_ALIGNMENT, HORIZONTAL_SPACING, LABEL, LINESTYLE, ORIENTATION, POSITION, SAMPLE_ANGLE, SAMPLE_MAGNITUDE, SAMPLE_WIDTH, SHADOW, TEXT_COLOR, THICK, TRANSPARENCY, UNITS, UVALUE, VERTICAL_ALIGNMENT, VERTICAL_SPACING, WINDOW
Methods
Close
ConvertCoord
CopyWindow
Delete
Erase
Order
Print
Refresh
Rotate
Save
Scale
Select
Translate
Return Value
The LEGEND function returns a reference to the created graphic. Use the returned reference to manipulate the graphic after creation by changing properties or calling methods.
Keywords
Keywords are applied only during the initial creation of the graphic.
DATA
Set this keyword if the input POSITION is in data coordinates. The coordinates will then be automatically converted to normalized coordinates before inserting the legend into the annotation layer.
DEVICE
Set this keyword if the input POSITION is in device coordinates (pixels). The coordinates will then be automatically converted to normalized coordinates before inserting the legend into the annotation layer.
NORMAL
Set this keyword if the input POSITION is in normalized ( [0, 1] ) coordinates (the default).
RELATIVE
Set this keyword to indicate that the input arguments are specified in normalized [0,1] coordinates, relative to the axis range of the TARGET's dataspace. If the TARGET keyword is not specified, then setting /RELATIVE is the same as setting /NORMAL.
Note: When using /RELATIVE, even though the coordinates are relative to the TARGET's dataspace, the graphic is added to the annotation layer, not to the dataspace.
TARGET
Set this keyword to the visualization to which the legend should be associated. If TARGET is not specified any currently selected objects will be used. If no suitable targets are found no legend will be created.
Properties
AUTO_TEXT_COLOR
Set this property to true (1) to draw the text labels using the same color as the associated plot lines. If this property is set then the TEXT_COLOR property is ignored. The default is false (0).
COLOR
Set this property to a string or RGB vector that specifies the color of the outline.
HORIZONTAL_ALIGNMENT
The horizontal alignment of the legend with respect to the position. This is a value between 0 and 1 where 1 specifies right-aligned (the default). This can also be a string with the following options: 'LEFT', 'CENTER', or 'RIGHT'.
HORIZONTAL_SPACING
The horizontal spacing between items in normalized units. The default is 0.04.
LINESTYLE
Set this property to an integer or string specifying the line style for the outline.
The following table lists the index values and strings you can use with this property.
|
Index |
Property |
Description |
|
0 |
'solid_line', '-'(dash)
|
solid line |
|
1 |
'dot', ':'(colon)
|
dotted |
|
2 |
'dash', '--' (double dashes)
|
dashed |
|
3 |
'dash_dot', '-.'
|
dash dot |
|
4 |
'dash_dot_dot_dot', '-:'
|
dash dot dot dot
|
|
5 |
'long_dash', '__' (two underscores)
|
long dash |
|
6 |
'none', ' ' (space)
|
no line |
You can also set the line style to a two-element vector, [repeat, bitmask], specifying a stippling pattern. The repeat indicates the number of times that individual bits in the bitmask should be repeated. (That is, if three consecutive 0’s appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be an integer between 1 and 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. The bitmask should be specified as a 16-bit hexadecimal value. For example, [2, 'AAAA'X] describes a dashed line with very short dashes of length 2 bits each.
ORIENTATION
The orientation of the legend. Setting this value to one (1) denotes a horizontal legend, the default is a vertical legend.
POSITION
Set this property to set the location of the legend. POSITION is specified as a 2 element vector: [X, Y], defining the upper right corner of the legend. If the DEVICE property is set, the units are given in device units (pixels).
SHADOW
Set this property to true (1) to turn on the legend shadow, or to false (0) to turn off the shadow. The default value is 0.
THICK
Set this property to a value between 0 and 10 that specifies the line thickness of the outline. A thickness of 0 displays a thin hairline on the chosen device. The default value is 1.
TRANSPARENCY
An integer from 0-100 giving the percent transparency.
UVALUE
Set this property to an IDL variable of any data type.
VERTICAL_ALIGNMENT
The vertical alignment of the legend with respect to the position. This is a value between 0 and 1 where 1 specifies top aligned (the default). This can also be a string with the following options: 'TOP', 'CENTER', or 'BOTTOM'.
VERTICAL_SPACING
The vertical spacing between items in normalized units. The default is 0.03.
WINDOW (Get Only)
This property retrieves a reference to the WINDOW object which contains the graphic.
Legend Item Properties
The following properties apply to the individual legend items within the legend. These properties can be set on initial creation of the legend, and will be passed down to all of the newly-created legend items. The properties can also be set on a legend item after creation by retrieving the legend item and then using the "." notation.
FONT_NAME
Set this property equal to a string specifying the IDL or system font. The default value is "DejaVuSans".
FONT_SIZE
Set this property equal to an integer specifying the font size. The default value is 9 points.
FONT_STYLE
A string or integer containing the font style. Allowed values are:
|
Integer |
String |
Resulting Style |
|
0 |
"Normal" or "rm"
|
Default (roman) |
|
1 |
"Bold" or "bf" |
Bold |
|
2 |
"Italic" or "it"
|
Italic |
|
3 |
"Bold italic" or "bi"
|
Bold italic |
LABEL
Set this property to a string giving the label for the legend item. If this property is set then the default label will not be used. Set this property to an empty string to go back to using the default label.
You can add Greek letters and mathematical symbols using a TeX-like syntax. These symbols need to be enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details on the available symbols.
SAMPLE_ANGLE
The angle of the sample line or arrow, in degrees. The default value is zero, which gives a horizontal line for line plots, and a right-pointing arrow for vector plots.
SAMPLE_MAGNITUDE
Note: This keyword only applies to legend items for vector plots.
Set this property to either a case-insensitive string or a floating-point number giving the length of the sample vector. Possible values are:
- "Min" - use the smallest magnitude value as the length of the sample vector.
- "Mean" - use the mean (or average) of all of the magnitude values. This is the default.
- "Max" - use the largest magnitude value.
- a floating-point number - use that number as the length of the sample vector.
The arrow displayed in the legend is scaled to match the chosen length, relative to the maximum magnitude of the vector plot. This property is only used for legend items for vector plots, and is ignored for all other legend items.
Note: If the LABEL property is set, then the SAMPLE_MAGNITUDE will still be used to scale the length of the sample arrow, but will not be used to label the legend item. For example, if your vector data was in "miles per hour" but you wanted to display the length in "km/hr", you might set the SAMPLE_MAGNITUDE to 62, but then set the LABEL to "100 km/hr".
SAMPLE_WIDTH
The width of the line sample, in normalized units. The default value is 0.15.
For line plots, increasing the SAMPLE_WIDTH will also increase the number of plot symbols on the legend item. A sample width of 0 gives 1 plot symbol. A sample width of 0.01–0.19 gives 2 plot symbols, 0.20–0.39 gives 3 plot symbols, etc.
TEXT_COLOR
Set this property to a string or RGB vector that specifies the color of the text.
UNITS
Set this property to a string giving the units for the vector plot. This string will then be appended to the sample magnitude label in the legend item. If the LABEL property is set then this property is ignored. This property is only used for legend items for vector plots, and is ignored for all other legend items.
You can add Greek letters and mathematical symbols using a TeX-like syntax. These symbols need to be enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details on the available symbols.
Retrieving Individual Legend Items
Once a legend is created, the individual legend items can be retrieved using standard array indexing. Once a legend item is retrieved, you can change any of the properties on that legend item. For example:
t = FINDGEN(101)/10
p1 = PLOT(SIN(t), '-ro')
p2 = PLOT(COS(t), '-go', /OVERPLOT)
leg = LEGEND(TARGET=[p1,p2])
leg[0].label = "Sin"
leg[1].label = "Cos"
HELP, leg[0]
HELP, leg[1]
HELP, leg[0:1]
IDL prints:
<Expression> LEGENDITEM <19018>
<Expression> LEGENDITEM <19019>
<Expression> OBJREF = Array[2]
Additional Example
This example demonstrates how to add a legend to a vector plot.
m = MAP('Equirectangular', LIMIT=[0,-150,60,-45], $
LABEL_POSITION=0, COLOR='light gray', LABEL_COLOR='black')
m1 = MAPCONTINENTS(FILL_COLOR='light gray')
RESTORE, FILEPATH('globalwinds.dat', $
SUBDIR=['examples','data'])
vec = VECTOR(u, v, x, y, /OVERPLOT, LENGTH_SCALE=2)
leg = LEGEND(SAMPLE_MAGNITUDE=10, UNITS='$m s^{-1}$', $
POSITION=m.MapForward(-45,61), /DATA, $
VERTICAL_ALIGNMENT='bottom')
Note that we use the MapForward method to determine the position of the legend in the upper right of the map. Also note that we use the SAMPLE_MAGNITUDE property to override the default sample vector length.
Version History
|
8.0 |
Introduced |
|
8.1 |
Added the UVALUE property.
The THICK property was changed to accept a value between 0 and 10.
|
|
8.2 |
Added support for legends for vector plots. Added Legend Item properties: LABEL, SAMPLE_ANGLE, SAMPLE_MAGNITUDE, UNITS.
Changed behavior of POSITION keyword to use upper-right of legend.
|
|
8.2.3 |
Added the ability to use a stippling pattern for LINESTYLE.
|
| 8.6 |
Changed default font name and font size. |
See Also
!COLOR, MAP, MAPCONTINENTS, PLOT, PLOT3D, VECTOR