Property Editor - Label Object
The Label Property Editor provides a dialogue to edit the properties of a label object. Each class object can have one or more label objects to define how the text are rendered along with the geometry features in the class. The Label Property Editor contains a sample window to show up how the label will be rendered.
The properties of the Label Property Editor are divided into the groups, each group is represented by a separate tab sheet. The Label Property Editor contains the following property groups and parameters:
Rendering
The Rendering tab allows to set the properties related to the rendering of the label object.
- Text - Text Expression for Label Features. Overrides values obtained from the LABEL ITEM of the Layer AND the TEXT of the Class
- Font - The font alias (as defined in the fontset file) to use for labeling. This parameter is bindable. For more information about the label attribute binding see: Using the MapServer Label and Style Property Binding
- Size - The size of the labels. This parameter is bindable. For more information about the label attribute binding see: Using the MapServer Label and Style Property Binding
- Min. Size - The minimum font size to use when the scale dependent sizing is enabled (i.e.. by specifying the symbolscale parameter in Style tab of the Layer Property Editor)
- Max. Size - The maximum font size to use when the scale dependent sizing is enabled (i.e.. by specifying the symbolscale parameter in Style tab of the Layer Property Editor)
- Encoding - Supported encoding format to be used for labels to show international characters. If the format is not supported, the label will not be drawn. Required for displaying international characters in MapServer. See MapServer Character Encoding for more information
- Colour - Colour to use for drawing the labels. The colour can be selected with the Colour Selector control. This parameter is bindable. For more information about the label attribute binding see: Using the MapServer Label and Style Property Binding
- Outline Colour - Colour to draw a one pixel outline around the text. The colour can be selected with the Colour Selector control. This parameter is bindable. For more information about the label attribute binding see: Using the MapServer Label and Style Property Binding
- Shadow Colour - Colour of drop shadow. The colour can be selected with the Colour Selector control
- Shadow Size X - Horizontal offset of the shadow in pixels
- Shadow Size Y - Vertical offset of the shadow in pixels
Note: As of MapServer 6.0 the label BACKGROUND COLOUR was depreciated and replaced with label styles
Display
The Display tab provides properties to specify whether the labels should be displayed or not.
- Min. Feature Size - Minimum size a feature must be to be labelled. Given in pixels. For line features the overall length of the displayed line is used, for polygons features the smallest dimension of the bounding box is used. Available for cached labels only
- Auto Min. Feature Size - Labels will be rendered if they fit within the dimension of the feature. Available only for cached labels
- Min Distance - The minimum distance between duplicate labels. Given in pixels. Available only for cached labels
- Display Partials - Specify whether the text can run off the edge of the map. Available only for cached labels
- Repeat Distance - The label will be repeated on every line of a multi-line shape and will be repeated multiple times along a given line at an interval of repeat distance pixels
- Force - Forces labels for a particular class on, regardless of collisions. Available only for cached labels
- Closest scale - The closest scale at which the label is drawn when setting up the scale dependent rendering. Clicking on the button we can set the current scale of the map
- Farthest scale - The farthest scale at which the label is drawn when setting up the scale dependent rendering. Clicking on the button we can set the current scale of the map
- Expression - Expression that determines when the label is to be displayed. For more information see the expression setting on the Class Property Editor dialogue
Position
The parameters related to the position of the labels.
- Position - Position of the label relative to the labelling point. Possible values are:
- MS_UL - Upper-Left
- MS_UC - Upper-Centred
- MS_UR - Upper-Right
- MS_CL - Centred-Left
- MS_CC - Centred
- MS_CR - Centred-Right
- MS_LL - Lower-Left
- MS_LC - Lower-Centred
- MS_LR - Lower-Right
- MS_AUTO - MapServer calculates the label position and will try to avoid overlapping labels. Available only for cached labels
- X Offset - Horizontal offset values for labels, relative to the lower left hand corner of the label and the label point. Given in pixels. In the case of rotated text specify the values as if all labels are horizontal and any rotation will be compensated for
- Y Offset - Vertical offset values for labels, relative to the lower left hand corner of the label and the label point. Given in pixels. In the case of rotated text specify the values as if all labels are horizontal and any rotation will be compensated for
- AngleMode - Specifies how the label should be rotated. The possible values:
- MS_AUTO - Allows MapServer to compute the angle. Valid for line layers only
- MS_AUTO2 - Same as MS_AUTO, except no logic is applied to try to keep the text from being rendered in reading orientation (i.e. the text may be rendered upside down). Useful when adding text arrows indicating the line direction
- MS_FOLLOW - Allows to compute a curved label for appropriate linear features
- MS_NONE - No special rotation mode should be applied
Note: Curved labels are not aware of label styles with the current version of MapServer
- Buffer - Padding, in pixels, around labels. Useful for maintaining spacing around text to enhance readability. Available only for cached labels. Default is 0
- Angle - Angle, given in degrees, to draw the label. This parameter is bindable. For more information about the label attribute binding see: Using the MapServer Label and Style Property Binding
- Priority - The priority parameter takes an integer value between 1 (lowest) and 10 (highest). The default value is 1. Labels are stored in the label cache and rendered in order of priority, with the highest priority levels rendered first. This parameter is bindable. For more information about the label attribute binding see: Using the MapServer Label and Style Property Binding
- Align - Specifies text alignment for multi-line labels (see Wrap) Note that the alignment algorithm is far from precise, so don't expect fabulous results (especially for right alignment) if you're not using a fixed width font. Possible values are:
- MS_ALIGN_LEFT - Left Alignment
- MS_ALIGN_CENTER - Centre Alignment
- MS_ALIGN_RIGHT - Right Alignment
- Wrap - Character that represents an end-of-line condition in label text, thus resulting in a multi-line label. Interacts with MAXLENGTH for conditional line wrapping after a given number of characters
- MaxLength - This parameter interacts with the 'wrap' parameter so that line breaks only occur after the defined number of characters according to the table below
|
maxlength = 0
|
maxlength > 0
|
maxlength < 0
|
wrap = ‘char’
|
always wrap at the WRAP character
|
newline at the first WRAP character after MAXLENGTH characters
|
hard wrap (always break at exactly MAXLENGTH characters)
|
no wrap
|
no processing
|
skip label if it contains more than MAXLENGTH characters
|
hard wrap (always break at exactly MAXLENGTH characters)
|
Styles
MapServer 6.0 introduced the Label Styles. In the Styles tab we can add one or more geometry styles behind the label. This can be useful to have shields and other cartographical symbols behind labels.
The configured styles are displayed in the left of the tab page. New style can be added by pressing the 'Add Style' button.
By selecting a style in the list we can use the 'Edit Style' button to display the corresponding Style Property Editor and use the 'Remove Style' button to remove the selected style. In case if multiple labels are specified, we can use the 'Move Up' and 'Move Down' buttons to change the rendering order of the labels.
Within the Style Property Editor the parameter Geom. Transformation is used to set whether the style is a point symbol (labelpnt) or a bounding rectangle (labelpoly). Styling the label symbol is then achieved with regular symbol styling techniques.