NCL Website header
NCL Home > Documentation > HLUs > Classes

Legend class

The Legend class draws an annotation for line and/or marker styles with an optional title and/or border.

Synopsis

Header file:		ncarg/hlu/Legend.h
Class name:		legendClass
Class pointer:		NhllegendClass
Fortran class function:	NHLFLEGENDCLASS
Superclass:		View
Composite classes:	<none>

Class-defined types

Type name:		NhlTlgLabelAlignmentMode
Definition:
typedef enum _NhllgLabelAlignmentMode {
	NhlITEMCENTERS		= 0,	/* "ItemCenters" */
	NhlABOVEITEMS		= 1,	/* "AboveItems"  */
	NhlBELOWITEMS		= 2	/* "BelowItems"  */
} NhllgLabelAlignmentMode;

Type name:		NhlTlgItemPlacementMode
Definition:
typedef enum _NhllgItemPlacementMode {
	NhlUNIFORMPLACEMENT	= 0,	/* "UniformPlacement" */
	NhlEXPLICITPLACEMENT	= 1	/* "ExplicitPlacement" */
} NhllgItemPlacementMode;


Resources

Local resources

+---------------------------------------------------------------+
|			Legend Resource Set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| lgLegendOn			NhlTBoolean		RCSG	|
|       LgLegendOn                      True                    |
|---------------------------------------------------------------|
| lgOrientation                 NhlTOrientation		RCSG	|
|       LgOrientation                   "Vertical"              |
|---------------------------------------------------------------|
| lgJustification               NhlTJustification	RCSG	|
|       LgJustification                 "BottomLeft"            |
|---------------------------------------------------------------|
| lgBoxMajorExtentF		NhlTFloat		RCSG	|
|       LgBoxMajorExtentF               0.5                     |
|---------------------------------------------------------------|
| lgBoxMinorExtentF		NhlTFloat		RCSG	|
|       LgBoxMinorExtentF               0.6                     |
|---------------------------------------------------------------|
| lgItemCount                   NhlTInteger		RCSG	|
|       LgItemCount                     16                      |
|---------------------------------------------------------------|
| lgItemOrder		        NhlTIntegerGenArray     RCSG	|
|       LgItemOrder                     NULL                    |
|---------------------------------------------------------------|
| lgItemPlacement		NhlTlgItemPlacementMode	RCSG	|
|       LgItemPlacement                 "UniformPlacement"      |
|---------------------------------------------------------------|
| lgBoxBackground		NhlTColorIndex		RCSG	|
|       FillBackgroundColor             "Transparent"           |
|---------------------------------------------------------------|
| lgAutoManage			NhlTBoolean		RCSG	|
|       LgAutoManage                    True                    |
|---------------------------------------------------------------|
| lgLabelOffsetF		NhlTFloat		RCSG	|
|       LgLabelOffsetF                  0.02                    |
|---------------------------------------------------------------|
| lgTitleOffsetF		NhlTFloat		RCSG	|
|       LgTitleOffsetF                  0.03                    |
|---------------------------------------------------------------|
| lgLeftMarginF			NhlTFloat		RCSG	|
|       LgLeftMarginF                   0.05                    |
|---------------------------------------------------------------|
| lgRightMarginF		NhlTFloat		RCSG	|
|       LgRightMarginF                  0.05                    |
|---------------------------------------------------------------|
| lgBottomMarginF		NhlTFloat		RCSG	|
|       LgBottomMarginF                 0.05                    |
|---------------------------------------------------------------|
| lgTopMarginF			NhlTFloat		RCSG	|
|       LgTopMarginF                    0.05                    |
|---------------------------------------------------------------|
| lgMonoItemType		NhlTBoolean		RCSG	|
|       LgMonoItemType                  True                    |
|---------------------------------------------------------------|
| lgItemType			NhlTMarkLineMode	RCSG	|
|       LgItemType                      "Lines"                 |
|---------------------------------------------------------------|
| lgItemTypes			NhlTMarkLineModeGenArrayRCSG	|
|       LgItemTypes                     <dynamic>               |
|---------------------------------------------------------------|
| lgMonoDashIndex		NhlTBoolean		RCSG	|
|       LgMonoDashIndex                 True                    |
|---------------------------------------------------------------|
| lgDashIndex                   NhlTDashIndex		RCSG	|
|	LineDashPattern			"SolidLine"		|
|---------------------------------------------------------------|
| lgDashIndexes			NhlTDashIndexGenArray	RCSG	|
|	LgDashIndexes			<dynamic>		|
|---------------------------------------------------------------|
| lgMonoMarkerIndex		NhlTBoolean		RCSG	|
|	LgMonoMarkerIndex		True			|
|---------------------------------------------------------------|
| lgMarkerIndex			NhlTMarkerIndex		RCSG	|
|	MarkerIndex			"default"		|
|---------------------------------------------------------------|
| lgMarkerIndexes		NhlTMarkerIndexGenArray	RCSG	|
|	LgMarkerIndexes			<dynamic>		|
|---------------------------------------------------------------|
| lgLineLabelStrings		NhlTStringGenArray	RCSG	|
|	LgLineLabelStrings		<dynamic>		|
|---------------------------------------------------------------|
| lgMonoLineColor		NhlTBoolean		RCSG	|
|       LgMonoLineColor                 False                   |
|---------------------------------------------------------------|
| lgLineColor			NhlTColorIndex		RCSG	|
|	LineColor			"Foreground"		|
|---------------------------------------------------------------|
| lgLineColors			NhlTColorIndexGenArray	RCSG	|
|	LgLineColors			<dynamic>		|
|---------------------------------------------------------------|
| lgMonoMarkerColor		NhlTBoolean		RCSG	|
|	LgMonoMarkerColor		False			|
|---------------------------------------------------------------|
| lgMarkerColor			NhlTColorIndex		RCSG	|
|	MarkerColor			"Foreground"		|
|---------------------------------------------------------------|
| lgMarkerColors		NhlTColorIndexGenArray	RCSG	|
|	LgMarkerColors			<dynamic>		|
|---------------------------------------------------------------|
| lgMonoLineDashSegLen		NhlTBoolean		RCSG	|
|	LgMonoLineDashSegLen		True			|
|---------------------------------------------------------------|
| lgLineDashSegLenF		NhlTFloat		RCSG	|
|	LineDashSegLenF			0.15			|
|---------------------------------------------------------------|
| lgLineDashSegLens		NhlTFloatGenArray	RCSG	|
|	LgLineDashSegLens		NULL			|
|---------------------------------------------------------------|
| lgMonoLineThickness		NhlTBoolean		RCSG	|
|	LgMonoLineThickness		True			|
|---------------------------------------------------------------|
| lgLineThicknessF		NhlTFloat		RCSG	|
|	LineThicknessF			1.0			|
|---------------------------------------------------------------|
| lgLineThicknesses		NhlTFloatGenArray	RCSG	|
|	LgLineThicknesses		<dynamic>		|
|---------------------------------------------------------------|
| lgMonoMarkerThickness		NhlTBoolean		RCSG	|
|	LgMonoMarkerThickness		True			|
|---------------------------------------------------------------|
| lgMarkerThicknessF		NhlTFloat		RCSG	|
|	MarkerThicknessF		1.0			|
|---------------------------------------------------------------|
| lgMarkerThicknesses		NhlTFloatGenArray	RCSG	|
|	LgMarkerThicknesses		<dynamic>		|
|---------------------------------------------------------------|
| lgMonoLineLabelFontHeight	NhlTBoolean		RCSG	|
|	LgMonoLineLabelFontHeight	True			|
|---------------------------------------------------------------|
| lgLineLabelFontHeightF	NhlTFloat		RCSG	|
|	FontHeightF			0.01			|
|---------------------------------------------------------------|
| lgLineLabelFontHeights	NhlTFloatGenArray	RCSG	|
|	LgLineLabelFontHeights		<dynamic>		|
|---------------------------------------------------------------|
| lgMonoMarkerSize		NhlTBoolean		RCSG	|
|	LgMonoMarkerSize		True			|
|---------------------------------------------------------------|
| lgMarkerSizeF			NhlTFloat		RCSG	|
|	MarkerSizeF			0.01			|
|---------------------------------------------------------------|
| lgMarkerSizes			NhlTFloatGenArray	RCSG	|
|	LgMarkerSizes			<dynamic>		|
|---------------------------------------------------------------|
| lgLabelStrings		NhlTStringGenArray	RCSG	|
|	LgLabelStrings			<dynamic>		|
|---------------------------------------------------------------|
| lgItemPositions		NhlTFloatGenArray	RCSG	|
|	LgItemPositions			NULL			|
|---------------------------------------------------------------|
| lgMonoLineLabelFontColor 	NhlTBoolean		RCSG	|
|	LgMonoLineLabelFontColor	False			|
|---------------------------------------------------------------|
| lgLineLabelFontColor		NhlTColorIndex		RCSG	|
|	FontColor			"Foreground"		|
|---------------------------------------------------------------|
| lgLineLabelFontColors		NhlTColorIndexGenArray	RCSG	|
|	LgLineLabelFontColors		<dynamic>		|
|---------------------------------------------------------------|
| lgLineLabelsOn		NhlTBoolean		RCSG	|
|	LgLineLabelsOn			True			|
|---------------------------------------------------------------|
| lgLineLabelFont		NhlTFont		RCSG	|
|	Font				"pwritx"		|
|---------------------------------------------------------------|
| lgLineLabelFontAspectF	NhlTFloat		RCSG	|
|	FontAspectF			1.0			|
|---------------------------------------------------------------|
| lgLineLabelFontThicknessF	NhlTFloat		RCSG	|
|	FontThicknessF			1.0			|
|---------------------------------------------------------------|
| lgLineLabelFontQuality	NhlTFontQuality		RCSG	|
|	FontQuality		  	"High"			|
|---------------------------------------------------------------|
| lgLineLabelConstantSpacingF	NhlTFloat		RCSG	|
|	TextConstantSpacingF		0.0			|
|---------------------------------------------------------------|
| lgLineLabelFuncCode		NhlTCharacter		RCSG	|
|	TextFuncCode			':'			|
|---------------------------------------------------------------|
| lgLabelsOn			NhlTBoolean		RCSG	|
|	LgLabelsOn			True			|
|---------------------------------------------------------------|
| lgLabelAutoStride		NhlTBoolean		RCSG	|
|       LabelAutoStride                 False                   |
|---------------------------------------------------------------|
| lgLabelPosition		NhlTPosition		RCSG	|
|	LgLabelPosition			"Right"  		|
|---------------------------------------------------------------|
| lgLabelAngleF			NhlTFloat		RCSG	|
|	TextAngleF			0.0			|
|---------------------------------------------------------------|
| lgLabelAlignment		NhlTlgLabelAlignmentModeRCSG	|
|	LgLabelAlignment		"ItemCenters"		|
|---------------------------------------------------------------|
| lgLabelDirection		NhlTTextDirection	RCSG	|
|	TextDirection			"Across"		|
|---------------------------------------------------------------|
| lgLabelJust			NhlTJustification	RCSG	|
|	TextJustification		"CenterCenter"		|
|---------------------------------------------------------------|
| lgLabelFont			NhlTFont		RCSG	|
|	Font				"pwritx"		|
|---------------------------------------------------------------|
| lgLabelFontColor		NhlTColorIndex		RCSG	|
|       FontColor	                "Foreground"            |
|---------------------------------------------------------------|
| lgLabelFontHeightF		NhlTFloat		RCSG	|
|	FontHeightF			0.02			|
|---------------------------------------------------------------|
| lgLabelFontAspectF		NhlTFloat		RCSG	|
|	FontAspectF			1.0			|
|---------------------------------------------------------------|
| lgLabelFontThicknessF		NhlTFloat		RCSG	|
|	FontThicknessF			1.0			|
|---------------------------------------------------------------|
| lgLabelFontQuality		NhlTFontQuality		RCSG	|
|	FontQuality	  		"High"			|
|---------------------------------------------------------------|
| lgLabelConstantSpacingF	NhlTFloat		RCSG	|
|	TextConstantSpacingF		0.0			|
|---------------------------------------------------------------|
| lgLabelFuncCode		NhlTCharacter		RCSG	|
|	TextFuncCode			':'			|
|---------------------------------------------------------------|
| lgLabelStride			NhlTInteger		RCSG	|
|       LgLabelStride                   1                       |
|---------------------------------------------------------------|
| lgTitleString			NhlTString		RCSG	|
|	LgTitleString			<dynamic>		|
|---------------------------------------------------------------|
| lgTitleOn			NhlTBoolean		RCSG	|
|	LgTitleOn			True			|
|---------------------------------------------------------------|
| lgTitlePosition		NhlTPosition		RCSG	|
|	LgTitlePosition			"Top"			|
|---------------------------------------------------------------|
| lgTitleExtentF		NhlTFloat		RCSG	|
|	LgTitleExtentF			0.15			|
|---------------------------------------------------------------|
| lgTitleAngleF			NhlTFloat		RCSG	|
|	TextAngleF			0.0			|
|---------------------------------------------------------------|
| lgTitleDirection		NhlTTextDirection	RCSG	|
|	TextDirection			"Across"		|
|---------------------------------------------------------------|
| lgTitleFont			NhlTFont		RCSG	|
|	Font				"pwritx"		|
|---------------------------------------------------------------|
| lgTitleFontColor		NhlTColorIndex		RCSG	|
|	FontColor			"Foreground"		|
|---------------------------------------------------------------|
| lgTitleJust			NhlTJustification	RCSG	|
|	TextJustification		"CenterCenter"		|
|---------------------------------------------------------------|
| lgTitleFontHeightF		NhlTFloat		RCSG	|
|	FontHeightF			0.025			|
|---------------------------------------------------------------|
| lgTitleFontAspectF		NhlTFloat		RCSG	|
|	FontAspectF			1.0			|
|---------------------------------------------------------------|
| lgTitleFontThicknessF		NhlTFloat		RCSG	|
|	FontThicknessF			1.0			|
|---------------------------------------------------------------|
| lgTitleFontQuality		NhlTFontQuality		RCSG	|
|	FontQuality			"High"			|
|---------------------------------------------------------------|
| lgTitleConstantSpacingF	NhlTFloat		RCSG	|
|	TextConstantSpacingF		0.0			|
|---------------------------------------------------------------|
| lgTitleFuncCode		NhlTCharacter		RCSG	|
|	TextFuncCode			':'			|
|---------------------------------------------------------------|
| lgBoxLinesOn			NhlTBoolean		RCSG	|
|	LgBoxLinesOn			False			|
|---------------------------------------------------------------|
| lgBoxLineColor		NhlTColorIndex		RCSG	|
|	LineColor 			"Foreground"		|
|---------------------------------------------------------------|
| lgBoxLineThicknessF		NhlTFloat		RCSG	|
|	LineThicknessF	  		1.0			|
|---------------------------------------------------------------|
| lgBoxLineDashPattern		NhlTDashIndex		RCSG	|
|	LineDashPattern			"SolidLine"		|
|---------------------------------------------------------------|
| lgBoxLineDashSegLenF		NhlTFloat		RCSG	|
|	LineDashSegLenF			0.15			|
|---------------------------------------------------------------|
| lgPerimOn			NhlTBoolean		RCSG	|
|	EdgesOn				False			|
|---------------------------------------------------------------|
| lgPerimColor			NhlTColorIndex		RCSG	|
|	EdgeColor			"Foreground"		|
|---------------------------------------------------------------|
| lgPerimFill			NhlTFillIndex		RCSG	|
|	FillPattern			"HollowFill"		|
|---------------------------------------------------------------|
| lgPerimFillColor		NhlTColorIndex		RCSG	|
|	FillColor			"Background"		|
|---------------------------------------------------------------|
| lgPerimThicknessF		NhlTFloat		RCSG	|
|	EdgeThicknessF			1.0			|
|---------------------------------------------------------------|
| lgPerimDashPattern		NhlTDashIndex		RCSG	|
|	EdgeDashPattern			"SolidLine"		|
|---------------------------------------------------------------|
| lgPerimDashSegLenF		NhlTFloat		RCSG	|
|	EdgeDashSegLenF			0.15			|
+---------------------------------------------------------------+

Composite resources

The Legend class has no composite class objects.

Superclass resources

You can set all View class resources for the Legend object.


Description

The Legend object formats a series of lines and/or markers of varying styles (Legend 'items') along with accompanying explanatory labels into a horizontal row or vertical column. It is designed to serve as a "key" for an associated plot object. The labels, as well as an optional title, may be sized, angled, and positioned in a variety of ways. You may create a rectangular perimeter outlining of the area occupied by the Legend. The area inside this perimeter may be filled providing a background for the Legend object. Solid-filled or hollow boxes may surround each Legend item. You can set a number of the attributes of the Legend items individually using array resources.

Legend elements

The Legend object provides resources to manage the following elements:

  • Position, size, and shape
  • Attributes of the Legend items
  • Attributes of the labels accompanying the items
  • Attributes of the title
  • Attributes of the perimeter line and the background area

Managing the legend position, size, and shape

Direct management

If you create a Legend directly, you set its basic location and size using the resources of its View superclass, vpXF, vpYF, vpWidthF, and vpHeightF. However, the Legend may adjust its size (vpWidthF and vpHeightF) to accommodate the constraints imposed by some of its own resources. The NhlTJustification resource lgJustification specifies the point of the Legend object that is to remain fixed when size adjustments are made. If lgJustification has a value other than TopLeft, the position (vpXF and vpYF) may also change when size adjustments occur.

The NhlTOrientation resource lgOrientation determines whether the Legend object arranges the Legend items in a vertical column or in a horizontal row. Note that lgOrientation relates to the arrangement of the group of objects, rather than the orientation of the individual items in the group. When lgOrientation is Vertical, Legend items that are lines are oriented horizontally. Based on value of this lgOrientation Legend defines its major axis to be the axis parallel to the direction of orientation and the minor axis as the axis orthogonal to the direction of orientation.

If the boolean resource, lgAutoManage is set True, the Legend controls the size of its elements such that it can remain as close as possible to the size specified by its View resources. The length of the minor axis will remain as specified by the appropriate View resource value (either vpWidthF or vpHeightF depending on the orientation). The major axis grows or shrinks only when if the angle of the Legend labels is modified.

When lgAutoManage is True, you have no direct control over the size of text used in the Legend. If you are working interactively, you may find it helpful to create a basic Legend layout close to the desired size with the lgAutoManage mode on, then switch it off to tune the text size precisely to your taste. Even when lgAutoManage is False, text size scales when you change the size of the Legend object, unless you explicitly set the text size at the same time.

You can cause the Legend as a whole to appear or disappear from the view surface, by manipulating the value of the boolean resource lgLegendOn.

Management as an annotation

More typically, Legend objects are created as annotations for plot objects such as ContourPlot or XyPlot. If not disabled by the plot object class, you can automatically instantiate a Legend object simply by setting the PlotManager resource pmLegendDisplayMode to any value other than NoCreate. ContourPlot and XyPlot create a Legend objects by default.

As an intrinsic annotation of the PlotManager, the Legend object's View class resources can no longer be accessed directly. You now must control the size and location using resources that mostly belong to the PlotManager class. You set the location using resources that follow the PlotManager Location Control Model, as follows:

Note that most of these resources belong to the PlotManager class, but the justification resource belongs to the Legend. Instead of using vpWidthF and vpHeightF to adjust the size, you now use the PlotManager resources pmLegendWidthF and pmLegendHeightF.

The PlotManager class modifies the behavior of certain Legend resources. The ContourPlot class modifies the behavior of others. The XyPlot class modifies still others. Otherwise, you can set and retrieve Legend resources just as you would if you instantiated the Legend directly.

Layout of the legend interior

Within the perimeter of the Legend, there is an optional title, the Legend items (lines or markers), and next to each item an optional label. Surrounding these elements you can specify a margin on each side using the resources lgLeftMarginF, lgRightMarginF, lgBottomMarginF, lgTopMarginF. If there is a title, it may be placed inside the margin along any of the edges, parallel to either axis. The amount of room allotted to the title is specified using the resource lgTitleExtentF. You can specify a space between the title extent and the other Legend elements using the resource lgTitleOffsetF. Between the items and the labels you can also specify a space using the resource lgLabelOffsetF.

The legend items

A Legend may consist either of marker items or line items or a combination of both. You set the number of items using the resource, lgItemCount. All the array resources belonging to the Legend are sized relative to the number of items.

Associated with each Legend item is a rectangular space called the item box. All Legend items are located in the center of their item box. Line items extend from one end of the item box to the other along the minor axis. Marker items, if made large enough, may extend outside the borders of their item box. You can make the outline of the item box visible by setting the resource lgBoxLinesOn True.

When lgAutoManage is True, the resource lgBoxMinorExtentF determines what fraction of the distance across the minor axis (after subtracting the margins) is occupied by the legend item box. If lgAutoManage is False, it still specifies this same fraction initially, but may no longer after the Legend size is adjusted based on the text heights of the labels and the title.

The item boxes placed in a column or row occupy all the extent of the major axis that remains after subtracting:

  • the margins,
  • the space occupied by the title if it is enabled and placed along one of the minor axis sides,
  • any space added to accommodate angled labels,
  • and the equivalent of the font height of the labels if lgLabelAlignment is set to ExternalEdges.
The resource lgBoxMajorExtentF, which should be set to a value greater than 0.0 and less than or equal to 1.0, specifies what fraction of the space allotted to each item box the box actually occupies. If lgBoxMajorExtentF is 0.5, for example, each item box is separated from its neighboring boxes by a space equal to its size. Note that adjustments to lgBoxMajorExtentF have no effect on the Legend items themselves, whether markers or lines.

If the NhlTlgItemPlacementMode resource lgItemPlacement is set to ExplicitPlacement, the array resource lgItemPositions sets the position of the center of each items as a fraction of the distance along the portion of the major axis extent reserved for Legend items. Using this resource you can create separate groupings of related items within a single Legend object.

You can also set the array resource lgItemOrder to adjust the order of appearance of the items. (Available in version 5.1.0 and later.)

The Legend object provides a number of resources for controlling the attributes of the items. Some attributes have both a scalar resource and an associated array resource. With the array resource you can control the attribute value for each item individually, while with the scalar resource you can set the attribute for all items to a uniform value. By convention, the name of the array resource is the plural form of the name of the scalar resource. A boolean resource, whose name is formed by adding the prefix Mono to the scalar resource name, specifies which of the two resources is to be used. (If the scalar name contains the suffix "F", indicating a float type resource, it is discarded before forming the plural or adding the Mono prefix.)

Here are the resources that allow individual control of item attributes:

lgItemType, lgItemTypes, lgMonoItemType
This NhlTMarkLineMode resource sets the type of a Legend item, either to line, marker, or both.
lgDashIndex, lgDashIndexes, lgMonoDashIndex
Sets the dash pattern index for line item types.
lgLineColor, lgLineColors, lgMonoLineColor
Sets the HLU color index of line items.
lgLineThicknessF, lgLineThicknesses, lgMonoLineThickness
Sets the thickness of the line for line items.
lgMarkerIndex, lgMarkerIndexes, lgMonoMarkerIndex
Sets the marker index for marker item types.
lgMarkerColor, lgMarkerColors, lgMonoMarkerColor
Sets the HLU color index of marker items.
lgMarkerThicknessF, lgMarkerThicknesses, lgMonoMarkerThickness
Sets the thickness of the line used for marker symbols (if the symbol is not taken from one of the filled fonts).
lgMarkerSizeF, lgMarkerSizes, lgMonoMarkerSize
Specifies the height used for the marker symbol for marker items.
lgLineLabelStrings
Sets the internal line label text for line items.
(Do not confuse with lgLabelStrings, used for the label that describes each Legend item.)
lgLineLabelFontHeightF, lgLineLabelFontHeights, lgMonoLineLabelFontHeight
Specifies the font height used for the internal line labels.
lgLineLabelFontColor, lgLineLabelFontColors, lgMonoLineLabelFontColor
Specifies the color used for the internal line labels for line items.

In addition, Legend supports a number of scalar-only resources for controlling other attributes of the Legend items. These resources apply uniformly to all items of the correct type. lgLineDashSegLenF controls the segment length used for line item dash patterns. Note that the dash segment length for line items does not scale when the size of the Legend object changes. This is because the appearance of the Legend lines needs to be dependent on the plot object using the Legend as an annotation, and not upon the current size of the Legend itself.

lgLineLabelsOn is a boolean flag that specifies whether line items should be drawn with internal labels. You may set all the remaining text attributes of the internal line labels using the resources lgLineLabelFont, lgLineLabelFontAspectF, lgLineLabelFontThicknessF, lgLineLabelFontQuality, lgLineLabelConstantSpacingF, and lgLineLabelFuncCode.

If you set the boolean resource lgBoxLinesOn True, you can draw the perimeter outline of each Legend item box. You can control the color, thickness, dash pattern, and the dash segment length of these perimeter lines using the resources lgBoxLineColor, lgBoxLineThicknessF, lgBoxLineDashPattern, and lgBoxLineDashSegLenF. You can also use the resource lgBoxBackground to specify a solid fill color for the background of these boxes.

Legend labels

You choose whether or not to provide an explanatory label to accompany the Legend items by setting the boolean resource lgLabelsOn True or False. The actual label strings are set using the array resource lgLabelStrings.

You can place the labels on either side of the items or center them on items using the NhlTPosition resource lgLabelPosition. If you set lgLabelPosition position to a value inappropriate for the orientation (e.g. Bottom when lgOrientation is Vertical), it is automatically coerced to a valid value. Using the NhlTlgLabelAlignmentMode resource lgLabelAlignment, you can align the labels to the centers of the items, or above or below the items. If you set lgLabelPosition to Center, you should set lgLabelAlignment to AboveItems or BelowItems unless you want the labels to appear on top of the Legend items.

If the Legend has too many items for there to be a reasonably sized label for each item, you can set the lgLabelStride resource in order to label only every n'th box.

The labels have a complete set of text attribute resources. When lgAutoManage is True, however, the resources lgLabelFontHeightF or lgLabelJust are set automatically. In this case, Legend adjusts the font height and justification such that the labels fit the available space and remain properly aligned with their boxes. If the lgLabelAngleF resource is varied, Legend ensures that the labels do not overlap one another. If lgAutoManage is set False, the Legend viewport expands if necessary to accommodate the full label text entent. However, in this mode, there are no checks to prevent the labels from overlapping, and the justification must be set manually in order for the labels to appear properly aligned if the lgLabelAngleF resource is set to certain ranges of values.

A serious drawback of the lgAutoManage resource is that, while it prevents the labels from overlapping, it does nothing to prevent text from becoming unreasonably small when there are more than a few Legend boxes. Although a stride can be set through the labels using lgLabelStride, it must be manually reset each time the box count changes significantly. A more recently developed resource, lgLabelAutoStride, provides an alternative means of avoiding label overlap without reducing the text size. When this resource is set True, a stride is automatically set in such a way that overlap is avoided. Note that lgAutoManage must be set False in order for lgLabelAutoStride to have a noticeable effect.

The legend title

You turn the Legend title on and off using the boolean resource, lgTitleOn. You set the text of the title using the resource, lgTitleString. Any time you set lgTitleString and do not explicitly set lgTitleOn at the same time, lgTitleOn is automatically set True. You set the title's position with the NhlTPosition resource lgTitlePosition. The only restriction on the title's position is that it cannot be set to Center.

Like the labels, the title has a full set of text attribute resources. If lgAutoManage is True, the title is automatically sized to fit the available space as determined by the Legend viewport and the lgTitleExtentF resource. Attempts to set the lgTitleFontHeightF resource are ignored. You can influence the title's size indirectly, however. When lgAutoManage is set False, you can set lgTitleFontHeightF directly. If necessary, the Legend instance will increase the size of its viewport to accommodate the full extent of the title string.

The legend perimeter

You can draw an outline around the perimeter of the Legend by setting the boolean resource lgPerimOn True. You can control all attributes of the perimeter, including line color, line thickness, line dash pattern, and the dash segment length, using the resources lgPerimColor, lgPerimThicknessF, lgPerimDashPattern, and lgPerimDashSegLenF.

You can fill the interior area defined by the perimeter (in other words, the area around the boxes and behind the title and labels), using the resources lgPerimFill and lgPerimFillColor.


Support functions

The Legend object does not define any support functions, but it inherits all support functions available to the View class.

Status


See also