LabelCategory Class Reference

Represents visualization options for labels displayed on the map. More...

Collaboration diagram for LabelCategory:
Collaboration graph

Public Member Functions

void Deserialize (string newVal)
 Restores the state of the object from the string. More...
 
string Serialize ()
 Returns the state of the object in the XML-formatted string. More...
 

Properties

tkLabelAlignment Alignment [get, set]
 Gets or sets the horizontal and vertical alignment of labels. More...
 
bool Enabled [get, set]
 Gets or sets the value which indicates whether the category will be used in the process of shapefile drawing. More...
 
string Expression [get, set]
 Gets or sets expression which defines shapes that belong to this category. More...
 
bool FontBold [get, set]
 Gets or sets a boolean value which indicates whether font is bold. More...
 
uint FontColor [get, set]
 Gets or sets font color of labels. More...
 
uint FontColor2 [get, set]
 Gets or sets the second font color More...
 
tkLinearGradientMode FontGradientMode [get, set]
 Gets or sets the gradient for the font of labels. More...
 
bool FontItalic [get, set]
 Gets or sets a boolean value which indicates whether font is italic. More...
 
string FontName [get, set]
 Gets or sets font name to draw labels with. More...
 
uint FontOutlineColor [get, set]
 Gets or sets the outline color of the font. More...
 
bool FontOutlineVisible [get, set]
 Gets or sets a boolean value which indicates whether outline of the font is visible. More...
 
int FontOutlineWidth [get, set]
 Gets or sets the width in pixels of the font outline More...
 
int FontSize [get, set]
 Gets or sets the size of the font More...
 
int FontSize2 [get, set]
 Gets or sets the maximum font size fo the category. More...
 
bool FontStrikeOut [get, set]
 Gets or sets a boolean value which indicates whether font is striked out. More...
 
int FontTransparency [get, set]
 Gets or sets the transparency of the font. Values from 0 (opaque) to 255 (transparent) are accepted. More...
 
bool FontUnderline [get, set]
 Gets or sets a boolean value which indicates whether the font is underlined. More...
 
uint FrameBackColor [get, set]
 Gets or sets the back color of the frame. More...
 
uint FrameBackColor2 [get, set]
 Gets or sets the end color of the frame gradient. More...
 
tkLinearGradientMode FrameGradientMode [get, set]
 Gets or sets the gradient mode for the label's frame. More...
 
uint FrameOutlineColor [get, set]
 Gets or set the outline color of the label's frame. More...
 
tkDashStyle FrameOutlineStyle [get, set]
 Gets or sets the outline color of the label's frame. More...
 
int FrameOutlineWidth [get, set]
 Gets or sets the width of the label's frame outline. More...
 
int FramePaddingX [get, set]
 Gets or sets the horizontal distance from text to the border of label's frame More...
 
int FramePaddingY [get, set]
 Gets or sets the vertical distance from text to the border of label's frame More...
 
int FrameTransparency [get, set]
 Gets or sets the transparency of the label's frame. Values from 0 to 255 are accepted. More...
 
tkLabelFrameType FrameType [get, set]
 Gets or sets the shape of the label's frame More...
 
bool FrameVisible [get, set]
 Gets or sets a boolean value which indicates whether label's frame will be drawn. More...
 
uint HaloColor [get, set]
 Gets or sets the color of the halo around the text of the label. More...
 
int HaloSize [get, set]
 Gets or sets the width of the halo around the text of the label. More...
 
bool HaloVisible [get, set]
 Gets or sets a boolean value which indicates whether a halo around text will be drawn. More...
 
tkLabelAlignment InboxAlignment [get, set]
 Gets or sets the alignment of text within label's frame. More...
 
tkLineLabelOrientation LineOrientation [get, set]
 Gets or sets the orientation of the label relative to the polyline it belongs to. More...
 
object MaxValue [get, set]
 Gets or sets the maximum value for the specified label category in case an LabelCategory.Expression contains a range of values. More...
 
object MinValue [get, set]
 Gets or sets the minimum value for the specified label category in case an LabelCategory.Expression contains a range of values. More...
 
string Name [get, set]
 Gets or sets the name of the category. The names must not be unique. More...
 
double OffsetX [get, set]
 Gets or sets the horizontal offset in pixels which is used to draw labels. More...
 
double OffsetY [get, set]
 Gets or sets the vertical offset in pixels which is used to draw labels. More...
 
int Priority [get, set]
 The property isn't implemented. More...
 
uint ShadowColor [get, set]
 Gets or sets a color of shadow for the text of the label. More...
 
int ShadowOffsetX [get, set]
 Gets or sets the horizontal distance between text of the label and its shadow. More...
 
int ShadowOffsetY [get, set]
 Gets or sets the horizontal distance between text of the label and its shadow. More...
 
bool ShadowVisible [get, set]
 Gets or sets a boolean value which indicates whether shadow of the label will be visible. More...
 
bool Visible [get, set]
 Gets or sets a boolean value which indicates whether shapes that belongs to the category will be visible. More...
 

Detailed Description

Represents visualization options for labels displayed on the map.

dot_inline_dotgraph_46.png

Graph description

  1. The following elements of label appearance can be set:
  • the text itself;
  • the outline of text;
  • the halo around the text;
  • the shadow of the text;
  • frame around text.

Here are properties that define the appearance of each of the listed elements. For good visual experience it usually makes sense not to show all the decorations at once, but choose either halo, shadow, outline or frame. The main purpose of all these decorations is to provide some contrast for the text of labels, as parts of map may have the same color as the text of labels. Halo and frame are usually the best candidates for it.

dot_inline_dotgraph_47.png

Here is code that demonstrates how to set some of these options.

// font options
ct.FontName = "Courier New";
ct.FontSize = 10;
// now let's set the halo
ct.HaloVisible = true;
ct.HaloSize = 4;
// turns off the frame
ct.FrameVisible = false;
  1. There are properties which specify the position of each label relative to its base point set by Label.x, Label.y:
  • alignment;
  • vertical and horizontal offset;
  • orientation relative to the line (it is used in the process of label generation only).

And properties which define position of text relative to frame border:

  • InboxAlignment;
  • FramePaddingX;
  • FramePaddingY.

Here are some examples of their usage.

// place the label to the right of the base point and on the same level vertically
ct.Alignment = tkLabelAlignment.laCenterRight;
ct.OffsetX = 10; // 10 pixels to the right
ct.OffsetY = -5; // 5 pixels up
// displays frame
ct.FrameVisible = true;
ct.InboxAlignment = laTopLeft; // text will be aligned by top-left side of the frame
ct.FramePaddingX = 20; // additional 20 pixels will be between vertical border of the frame and text

See Visualization categories for information on how to map particular labels to the visualization category.

New API 4.8:
Added in version 4.8
Examples:
ImageLabels.cs, and LabelSelection.cs.

Member Function Documentation

◆ Deserialize()

void LabelCategory.Deserialize ( string  newVal)

Restores the state of the object from the string.

Parameters
newValA string generated by LabelCategory.Serialize() method.

◆ Serialize()

string LabelCategory.Serialize ( )

Returns the state of the object in the XML-formatted string.

Use LabelCategory.Deserialize() to restore the state.

Returns
Serialized string

Property Documentation

◆ Alignment

tkLabelAlignment LabelCategory.Alignment
getset

Gets or sets the horizontal and vertical alignment of labels.

◆ Enabled

bool LabelCategory.Enabled
getset

Gets or sets the value which indicates whether the category will be used in the process of shapefile drawing.

◆ Expression

string LabelCategory.Expression
getset

Gets or sets expression which defines shapes that belong to this category.

◆ FontBold

bool LabelCategory.FontBold
getset

Gets or sets a boolean value which indicates whether font is bold.

◆ FontColor

uint LabelCategory.FontColor
getset

Gets or sets font color of labels.

Examples:
ImageLabels.cs.

◆ FontColor2

uint LabelCategory.FontColor2
getset

Gets or sets the second font color

◆ FontGradientMode

tkLinearGradientMode LabelCategory.FontGradientMode
getset

Gets or sets the gradient for the font of labels.

◆ FontItalic

bool LabelCategory.FontItalic
getset

Gets or sets a boolean value which indicates whether font is italic.

◆ FontName

string LabelCategory.FontName
getset

Gets or sets font name to draw labels with.

The names of fonts or font families like "Arial" should be passed.

◆ FontOutlineColor

uint LabelCategory.FontOutlineColor
getset

Gets or sets the outline color of the font.

See also
FontOutlineVisible

◆ FontOutlineVisible

bool LabelCategory.FontOutlineVisible
getset

Gets or sets a boolean value which indicates whether outline of the font is visible.

See also
FontOutlineColor, FontOutlineWidth

◆ FontOutlineWidth

int LabelCategory.FontOutlineWidth
getset

Gets or sets the width in pixels of the font outline

See also
FontOutlineVisible

◆ FontSize

int LabelCategory.FontSize
getset

Gets or sets the size of the font

◆ FontSize2

int LabelCategory.FontSize2
getset

Gets or sets the maximum font size fo the category.

New API 4.9.4:
Added in version 4.9.4

◆ FontStrikeOut

bool LabelCategory.FontStrikeOut
getset

Gets or sets a boolean value which indicates whether font is striked out.

◆ FontTransparency

int LabelCategory.FontTransparency
getset

Gets or sets the transparency of the font. Values from 0 (opaque) to 255 (transparent) are accepted.

◆ FontUnderline

bool LabelCategory.FontUnderline
getset

Gets or sets a boolean value which indicates whether the font is underlined.

◆ FrameBackColor

uint LabelCategory.FrameBackColor
getset

Gets or sets the back color of the frame.

Examples:
LabelSelection.cs.

◆ FrameBackColor2

uint LabelCategory.FrameBackColor2
getset

Gets or sets the end color of the frame gradient.

See also
FrameGradientMode

◆ FrameGradientMode

tkLinearGradientMode LabelCategory.FrameGradientMode
getset

Gets or sets the gradient mode for the label's frame.

Use gmNone value to disable gradient.

◆ FrameOutlineColor

uint LabelCategory.FrameOutlineColor
getset

Gets or set the outline color of the label's frame.

◆ FrameOutlineStyle

tkDashStyle LabelCategory.FrameOutlineStyle
getset

Gets or sets the outline color of the label's frame.

◆ FrameOutlineWidth

int LabelCategory.FrameOutlineWidth
getset

Gets or sets the width of the label's frame outline.

◆ FramePaddingX

int LabelCategory.FramePaddingX
getset

Gets or sets the horizontal distance from text to the border of label's frame

◆ FramePaddingY

int LabelCategory.FramePaddingY
getset

Gets or sets the vertical distance from text to the border of label's frame

◆ FrameTransparency

int LabelCategory.FrameTransparency
getset

Gets or sets the transparency of the label's frame. Values from 0 to 255 are accepted.

◆ FrameType

tkLabelFrameType LabelCategory.FrameType
getset

Gets or sets the shape of the label's frame

◆ FrameVisible

bool LabelCategory.FrameVisible
getset

Gets or sets a boolean value which indicates whether label's frame will be drawn.

◆ HaloColor

uint LabelCategory.HaloColor
getset

Gets or sets the color of the halo around the text of the label.

◆ HaloSize

int LabelCategory.HaloSize
getset

Gets or sets the width of the halo around the text of the label.

◆ HaloVisible

bool LabelCategory.HaloVisible
getset

Gets or sets a boolean value which indicates whether a halo around text will be drawn.

◆ InboxAlignment

tkLabelAlignment LabelCategory.InboxAlignment
getset

Gets or sets the alignment of text within label's frame.

This property is commonly used for the alignment of multi-line labels.

◆ LineOrientation

tkLineLabelOrientation LabelCategory.LineOrientation
getset

Gets or sets the orientation of the label relative to the polyline it belongs to.

◆ MaxValue

object LabelCategory.MaxValue
getset

Gets or sets the maximum value for the specified label category in case an LabelCategory.Expression contains a range of values.

The property is used internally.

◆ MinValue

object LabelCategory.MinValue
getset

Gets or sets the minimum value for the specified label category in case an LabelCategory.Expression contains a range of values.

The property is used internally.

◆ Name

string LabelCategory.Name
getset

Gets or sets the name of the category. The names must not be unique.

◆ OffsetX

double LabelCategory.OffsetX
getset

Gets or sets the horizontal offset in pixels which is used to draw labels.

When labels are subject to the rotation, "horizontal" means "along text width".

See also
Labels.AutoOffset property

◆ OffsetY

double LabelCategory.OffsetY
getset

Gets or sets the vertical offset in pixels which is used to draw labels.

When labels are subject to the rotation, "vertical" means "along text height".

See also
Labels.AutoOffset property

◆ Priority

int LabelCategory.Priority
getset

The property isn't implemented.

◆ ShadowColor

uint LabelCategory.ShadowColor
getset

Gets or sets a color of shadow for the text of the label.

See also
ShadowVisible, ShadowOffsetX, ShadowOffsetY

◆ ShadowOffsetX

int LabelCategory.ShadowOffsetX
getset

Gets or sets the horizontal distance between text of the label and its shadow.

When labels are subject to the rotation, "horizontal" means "along text width"

See also
ShadowOffsetY, ShadowVisible

◆ ShadowOffsetY

int LabelCategory.ShadowOffsetY
getset

Gets or sets the horizontal distance between text of the label and its shadow.

When labels are subject to the rotation, "vertical" means "along text height"

See also
ShadowOffsetX, ShadowVisible

◆ ShadowVisible

bool LabelCategory.ShadowVisible
getset

Gets or sets a boolean value which indicates whether shadow of the label will be visible.

See also
ShadowColor, ShadowOffsetX, ShadowOffsetY

◆ Visible

bool LabelCategory.Visible
getset

Gets or sets a boolean value which indicates whether shapes that belongs to the category will be visible.

Examples:
LabelSelection.cs.