LabelBar class
The LabelBar class draws an annotation for fill styles with an optional title and/or border.Synopsis
Header file: ncarg/hlu/LabelBar.h Class name: labelBarClass Class pointer: NhllabelBarClass Fortran class function: NHLFLABELBARCLASS Superclass: View Composite classes: <none>
Class-defined types
Type name: NhlTlbLabelAlignmentMode Definition: typedef enum _NhllbLabelAlignmentMode { NhlBOXCENTERS = 0, /* "BoxCenters" */ NhlINTERIOREDGES = 1, /* "InteriorEdges" */ NhlEXTERNALEDGES = 2 /* "ExternalEdges" */ } NhllbLabelAlignmentMode; Type name: NhlTlbBoxSizingMode Definition: typedef enum _NhllbBoxSizingMode { NhlUNIFORMSIZING = 0, /* "UniformSizing" */ NhlEXPLICITSIZING = 1 /* "ExplicitSizing" */ } NhllbBoxSizingMode;
Resources
Local resources
+---------------------------------------------------------------+ | LabelBar Resource Set | |---------------------------------------------------------------| | NAME TYPE ACCESS | | CLASS DEFAULT | |===============================================================| | lbLabelBarOn NhlTBoolean RCSG | | lbLabelBarOn True | |---------------------------------------------------------------| | lbOrientation NhlTOrientation RCSG | | LbOrientation "Vertical" | |---------------------------------------------------------------| | lbJustification NhlTJustification RCSG | | LbJustification "BottomLeft" | |---------------------------------------------------------------| | lbBoxMajorExtentF NhlTFloat RCSG | | LbBoxMajorExtentF 1.0 | |---------------------------------------------------------------| | lbBoxMinorExtentF NhlTFloat RCSG | | LbBoxMinorExtentF 0.33 | |---------------------------------------------------------------| | lbBoxCount NhlTInteger RCSG | | LbBoxCount 16 | |---------------------------------------------------------------| | lbBoxSizing NhlTlbBoxSizingMode RCSG | | LbBoxSizing "UniformSizing" | |---------------------------------------------------------------| | lbAutoManage NhlTBoolean RCSG | | LbAutoManage True | |---------------------------------------------------------------| | lbLabelOffsetF NhlTFloat RCSG | | LbLabelOffsetF 0.1 | |---------------------------------------------------------------| | lbTitleOffsetF NhlTFloat RCSG | | LbTitleOffsetF 0.03 | |---------------------------------------------------------------| | lbLeftMarginF NhlTFloat RCSG | | LbLeftMarginF 0.05 | |---------------------------------------------------------------| | lbRightMarginF NhlTFloat RCSG | | LbRightMarginF 0.05 | |---------------------------------------------------------------| | lbBottomMarginF NhlTFloat RCSG | | LbBottomMarginF 0.05 | |---------------------------------------------------------------| | lbTopMarginF NhlTFloat RCSG | | LbTopMarginF 0.05 | |---------------------------------------------------------------| | lbMonoFillColor NhlTBoolean RCSG | | LbMonoFillColor False | |---------------------------------------------------------------| | lbFillColor NhlTColorIndex RCSG | | FillColor "Foreground" | |---------------------------------------------------------------| | lbFillColors NhlTColorIndexGenArray RCSG | | LbFillColors <dynamic> | |---------------------------------------------------------------| | lbMonoFillPattern NhlTBoolean RCSG | | LbMonoFillColor False | |---------------------------------------------------------------| | lbFillPattern NhlTFillIndex RCSG | | FillPattern "SolidFill" | |---------------------------------------------------------------| | lbFillPatterns NhlTFillIndexGenArray RCSG | | LbFillPatterns <dynamic> | |---------------------------------------------------------------| | lbFillDotSizeF NhlTFloat RCSG | | DotSizeF 0.0 | |---------------------------------------------------------------| | lbMonoFillScale NhlTBoolean RCSG | | LbMonoFillScale True | |---------------------------------------------------------------| | lbFillScaleF NhlTFloat RCSG | | FillScaleF 1.0 | |---------------------------------------------------------------| | lbFillScales NhlTFloatGenArray RCSG | | LbFillScales NULL | |---------------------------------------------------------------| | lbLabelStrings NhlTStringGenArray RCSG | | LbLabelStrings NULL | |---------------------------------------------------------------| | lbBoxFractions NhlTFloatGenArray RCSG | | LbBoxFractions NULL | |---------------------------------------------------------------| | lbLabelsOn NhlTBoolean RCSG | | lbLabelsOns True | |---------------------------------------------------------------| | lbLabelAutoStride NhlTBoolean RCSG | | LabelAutoStride False | |---------------------------------------------------------------| | lbLabelPosition NhlTPosition RCSG | | LbLabelPosition "Right" | |---------------------------------------------------------------| | lbLabelAngleF NhlTFloat RCSG | | TextAngleF 0.0 | |---------------------------------------------------------------| | lbLabelAlignment NhlTlbLabelAlignmentMode RCSG | | LbLabelAlignment "BoxCenters" | |---------------------------------------------------------------| | lbLabelDirection NhlTTextDirection RCSG | | TextDirection "Across" | |---------------------------------------------------------------| | lbLabelJust NhlTJustification RCSG | | TextJustification "CenterCenter" | |---------------------------------------------------------------| | lbLabelFont NhlTFont RCSG | | Font "pwritx" | |---------------------------------------------------------------| | lbLabelFontColor NhlTInteger RCSG | | FontColor "Foreground" | |---------------------------------------------------------------| | lbLabelFontHeightF NhlTFloat RCSG | | FontHeightF 0.02 | |---------------------------------------------------------------| | lbLabelFontAspectF NhlTFloat RCSG | | FontAspectF 1.0 | |---------------------------------------------------------------| | lbLabelFontThicknessF NhlTFloat RCSG | | FontThicknessF 1.0 | |---------------------------------------------------------------| | lbLabelFontQuality NhlTFontQuality RCSG | | FontQuality "High" | |---------------------------------------------------------------| | lbLabelConstantSpacingF NhlTFloat RCSG | | TextConstantSpacingF 0.0 | |---------------------------------------------------------------| | lbLabelFuncCode NhlTCharacter RCSG | | TextFuncCode ':' | |---------------------------------------------------------------| | lbLabelStride NhlTInteger RCSG | | LbLabelStride 1 | |---------------------------------------------------------------| | lbMaxLabelLenF NhlTFloat G | | LbMaxLabelLenF <dynamic> | |---------------------------------------------------------------| | lbMinLabelSpacingF NhlTFloat G | | LbMinLabelSpacingF <dynamic> | |---------------------------------------------------------------| | lbTitleString NhlTString RCSG | | LbTitleString <dynamic> | |---------------------------------------------------------------| | lbTitleOn NhlTBoolean RCSG | | lbTitleOn True | |---------------------------------------------------------------| | lbTitlePosition NhlTPosition RCSG | | LbTitlePosition "Top" | |---------------------------------------------------------------| | lbTitleExtentF NhlTFloat RCSG | | LbTitleExtentF 0.15 | |---------------------------------------------------------------| | lbTitleAngleF NhlTFloat RCSG | | TextAngleF 0.0 | |---------------------------------------------------------------| | lbTitleDirection NhlTTextDirection RCSG | | TextDirection "Across" | |---------------------------------------------------------------| | lbTitleFont NhlTFont RCSG | | Font "pwritx" | |---------------------------------------------------------------| | lbTitleFontColor NhlTInteger RCSG | | FontColor "Foreground" | |---------------------------------------------------------------| | lbTitleJust NhlTJustification RCSG | | TextJustification "CenterCenter" | |---------------------------------------------------------------| | lbTitleFontHeightF NhlTFloat RCSG | | FontHeightF 0.025 | |---------------------------------------------------------------| | lbTitleFontAspectF NhlTFloat RCSG | | FontAspectF 1.0 | |---------------------------------------------------------------| | lbTitleFontThicknessF NhlTFloat RCSG | | FontThicknessF 1.0 | |---------------------------------------------------------------| | lbTitleFontQuality NhlTFontQuality RCSG | | FontQuality "High" | |---------------------------------------------------------------| | lbTitleConstantSpacingF NhlTFloat RCSG | | TextConstantSpacingF 0.0 | |---------------------------------------------------------------| | lbTitleFuncCode NhlTCharacter RCSG | | TextFuncCode ':' | |---------------------------------------------------------------| | lbBoxLinesOn NhlTBoolean RCSG | | lbBoxLinesOn True | |---------------------------------------------------------------| | lbBoxLineColor NhlTInteger RCSG | | LineColor "Foreground" | |---------------------------------------------------------------| | lbBoxLineThicknessF NhlTFloat RCSG | | LineThicknessF 1.0 | |---------------------------------------------------------------| | lbBoxLineDashPattern NhlTInteger RCSG | | LineDashPattern 0 | |---------------------------------------------------------------| | lbBoxLineDashSegLenF NhlTFloat RCSG | | LineDashSegLenF 0.15 | |---------------------------------------------------------------| | lbPerimOn NhlTBoolean RCSG | | EdgesOn True | |---------------------------------------------------------------| | lbPerimColor NhlTInteger RCSG | | EdgeColor "Foreground" | |---------------------------------------------------------------| | lbPerimFill NhlTInteger RCSG | | FillPattern "HollowFill" | |---------------------------------------------------------------| | lbPerimFillColor NhlTInteger RCSG | | FillColor "Foreground" | |---------------------------------------------------------------| | lbPerimThicknessF NhlTFloat RCSG | | EdgeThicknessF 1.0 | |---------------------------------------------------------------| | lbPerimDashPattern NhlTInteger RCSG | | EdgeDashPattern 0 | |---------------------------------------------------------------| | lbPerimDashSegLenF NhlTFloat RCSG | | EdgeDashSegLenF 0.15 | |---------------------------------------------------------------| | lbFillBackground NhlTInteger RCSG | | FillBackgroundColor "Transparent" | |---------------------------------------------------------------| | lbFillLineThicknessF NhlTFloat RCSG | | FillLineThicknessF 1.0 | |---------------------------------------------------------------| | lbRasterFillOn NhlTBoolean RCSG | | LbRasterFillOn True | +---------------------------------------------------------------+
Composite resources
The LabelBar class has no composite class objects.
Superclass resources
You can set all View class resources for the LabelBar object.
Description
The LabelBar object formats a series of solid and/or pattern-filled boxes along with accompanying explanatory labels into a horizontal row or vertical column. It is designed to serve as the key for an associated plot, such as a contour plot, that employs pattern- or solid-fill areas. The labels, as well as an optional title, may be sized, angled, and positioned in a variety of ways. You may create a perimeter outlining or solid-filling the background of the area occupied by the LabelBar. When using pattern- filled boxes, you may solid-fill the background of the fill area. You can set the attributes of each LabelBar box individually using a number of array resources.
LabelBar elements
The LabelBar object provides resources to manage the following elements:
- Position, size, and shape
- Attributes of the filled boxes
- Attributes of the labels accompanying each box
- Attributes of the title
- Attributes of the perimeter line and the background area
Managing the LabelBar position, size, and shape
Direct management
If you create a LabelBar directly, you set its basic location and size using the resources of its View superclass, vpXF, vpYF, vpWidthF, and vpHeightF. However, the LabelBar may adjust its size (vpWidthF and vpHeightF) to accommodate the constraints imposed by some of its own resources. The NhlTJustification resource lbJustification specifies the point of the LabelBar object that is to remain fixed when size adjustments are made. If lbJustification has a value other thanTopLeft, the
position (vpXF and vpYF) may also change when size
adjustments occur.
The NhlTOrientation resource lbOrientation determines whether LabelBar arranges the boxes horizontally or vertically. Based on the value of this resource, LabelBar 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 lbAutoManage is set True, the LabelBar 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 if the angle of the LabelBar labels is modified.
When lbAutoManage is True, you have no direct control over the size of text used in the LabelBar. If you are working interactively, you may find it helpful to create a basic LabelBar layout close to the desired size with the lbAutoManage mode on, then switch it off to tune the text size precisely to your taste.
You can cause the LabelBar as a whole to appear or disappear from the view surface by manipulating the value of the boolean resource lbLabelBarOn.
Management as an annotation
More typically, LabelBar objects are created as
annotations for a plot object such
as ContourPlot. If not disabled by the plot object
class, you can automatically instantiate a LabelBar
object simply by setting the PlotManager resource pmLabelBarDisplayMode
to any value other than NoCreate. The
ContourPlot object does this by default.
As an intrinsic annotation of the PlotManager, the LabelBar 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 the justification resource belongs to the LabelBar itself, while the remaining resources belong to the PlotManager class. You control the size using the PlotManager resources pmLabelBarWidthF and pmLabelBarHeightF. These resources behave the same as vpWidthF and vpHeightF do when you are controlling the LabelBar directly.The PlotManager class modifies the behavior of certain LabelBar resources. The ContourPlot class modifies the behavior of others. Otherwise, you can set and retrieve LabelBar resources instantiated with a ContourPlot just as you would if you created the LabelBar directly.
Layout of the LabelBar interior
Within the perimeter of the LabelBar, there is an optional title, the LabelBar boxes themselves, and next to each box an optional label. Surrounding these elements you can specify a margin on each side using the resources lbLeftMarginF, lbRightMarginF, lbBottomMarginF, lbTopMarginF. 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 lbTitleExtentF. You can specify a space between the title extent and the other LabelBar elements using the resource lbTitleOffsetF. Between the boxes and the labels you can also specify a space using the resource lbLabelOffsetF.
LabelBar boxes
You set the number of boxes using the resource, lbBoxCount. All the array resources belonging to the LabelBar are sized in relation to the number of boxes.
When lbAutoManage is True, the resource lbBoxMinorExtentF determines what fraction of the distance across the minor axis (after subtracting the margins) is occupied by the boxes. If lbAutoManage is False, it still specifies this same fraction initially, but may no longer after the LabelBar size is adjusted based on the text heights of the labels and the title.
The boxes, placed end to end, occupy 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
- an amount equal to the font height of the labels if lbLabelAlignment is
set to
ExternalEdges.
If the NhlTlbBoxSizingMode
resource lbBoxSizing is set
to ExplicitSizing, the array resource lbBoxFractions
sets the beginning and end of each box as a fraction of the distance
along the length of the major axis reserved for the boxes. In this
case the lbBoxMajorExtentF
fractional value is applied to each box based on the size available to
it.
You can control the color, the fill pattern, and the scale of the fill pattern of the boxes either individually or uniformly as a group. If the boxes are to be differentiated, you would not want to control all three resources as a group. Individual control is through the array resources, lbFillColors, lbFillPatterns, and lbFillScales while control as a group is through the scalar resources lbFillColor, lbFillPattern, and lbFillScaleF. You choose the scalar resources by setting the boolean resources lbMonoFillColor, lbMonoFillPattern, and lbMonoFillScale True; the array resources by setting them False.
The resource lbFillBackground specifies a background color for the fill of the boxes. It only has an effect when the fill pattern is not solid or hollow and the fill color is not transparent. Note that lbFillBackground also applies to the background of the fill pattern used to fill the perimeter area around the boxes and behind the title and the labels.
You can also control the rendering of the lines that define the perimeters of the individual boxes. You turn these lines on and off using the boolean resource lbBoxLinesOn. You can control the color, thickness, dash pattern, and the dash segment length of these lines using the resources lbBoxLineColor, lbBoxLineThicknessF, lbBoxLineDashPattern, and lbBoxLineDashSegLenF.
LabelBar labels
You choose whether or not to label the boxes by setting the boolean resource lbLabelsOn True or False. The actual label strings are set using the array resource lbLabelStrings.
You can place the labels on either side of the boxes or center them
over the boxes using the NhlTPosition resource lbLabelPosition. If
you set lbLabelPosition
position to a value inappropriate for the orientation
(e.g. Bottom when lbOrientation is
Vertical), it is automatically coerced to a valid
value. Using the NhlTlbLabelAlignmentMode resource
lbLabelAlignment,
you can align the labels to the centers of the boxes, to the interior
edges of the boxes, or to all edges including both endpoints of the
boxes. If the LabelBar has too many boxes for there
to be a reasonably sized label for each box, you can set the lbLabelStride resource
in order to label only every nth box.
The labels have a complete set of text attribute resources. When lbAutoManage is True, however, the resources lbLabelFontHeightF or lbLabelJust are set automatically. In this case, LabelBar adjusts the font height and justification such that the labels fit the available space and remain properly aligned with their boxes. If the lbLabelAngleF resource is varied, LabelBar ensures that the labels do not overlap one another. If lbAutoManage is set False, the LabelBar 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 lbLabelAngleF resource is set to certain ranges of values.
A serious drawback of the lbAutoManage 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 LabelBar boxes. Although a stride can be set
through the labels using lbLabelStride, it must be manually
reset each time the box count changes significantly. A more recently
developed resource, lbLabelAutoStride,
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 lbAutoManage must be set
False in order for lbLabelAutoStride to have a
noticeable effect.
The LabelBar title
You turn the LabelBar title on and off using the
boolean resource, lbTitleOn. You set the text
of the title using the resource, lbTitleString. Any
time you set lbTitleString and do not explicitly set
lbTitleOn at the same time, lbTitleOn is
automatically set True. You set the title's position with the NhlTPosition
resource lbTitlePosition. 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 lbAutoManage is True, the title is automatically sized to fit the available space as determined by the LabelBar viewport and the lbTitleExtentF resource. Attempts to set the lbTitleFontHeightF resource are ignored. You can influence the title's size indirectly, however. When lbAutoManage is set False, you can set lbTitleFontHeightF directly. If necessary, the LabelBar instance will increase the size of its viewport to accommodate the full extent of the title string.
The LabelBar perimeter and background
You can draw an outline around the perimeter of the LabelBar by setting the boolean resource lbPerimOn 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 lbPerimColor, lbPerimThicknessF, lbPerimDashPattern, and lbPerimDashSegLenF.
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 lbPerimFill and
lbPerimFillColor. The resource
lbFillBackground specifies a
background color for the fill. It only has an effect when lbPerimFill specifies a fill pattern other
than Solid or HollowFill, and the lbPerimFillColor is not
Transparent. Note that lbFillBackground also applies to the
background of the fill patterns used within the
LabelBar boxes.
Support functions
The LabelBar object does not define any support functions, but it inherits all support functions available to the View class.Status
The LabelBar may display incorrectly if its View width or height is modified while the LabelBar is turned off (lbLabelBarOn set False). This is likely to happen if you add a ContourPlot as an overlay to another plot while pmLabelBarDisplayMode is set to "never", then subsequently change pmLabelBarDisplayMode to "conditional" or "always". If you are going to be using the LabelBar, turn it on before changing its size; set pmLabelBarDisplayMode to "conditional" or "always" before adding a ContourPlot as an overlay.
See also
- NhlCreate function
- NhlSetValues function
- NhlGetValues function
- PlotManager object