NCL Website header
NCL Home > Documentation > HLUs > Classes

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 than TopLeft, 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.
The resource lbBoxMajorExtentF should be a value greater than 0.0 and less than or equal to 1.0 that specifies what fraction of the space allotted to each box the box actually occupies. If lbBoxMajorExtentF is 0.5, for example, each box is separated from its neighboring boxes by a space equal to the space it occupies.

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