The Legend class draws an annotation for line and/or marker styles with an optional title and/or border.
Header file: ncarg/hlu/Legend.h Class name: legendClass Class pointer: NhllegendClass Fortran class function: NHLFLEGENDCLASS Superclass: View Composite classes: <none>
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;
+---------------------------------------------------------------+ | 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 | |---------------------------------------------------------------| | 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 | |---------------------------------------------------------------| | 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 | +---------------------------------------------------------------+
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.
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.
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:
ExternalEdges.
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.
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:
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.
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.
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.
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.
NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?