Labels categories

Functions
LabelCategory	Labels.AddCategory (string Name)
	Adds a visualization category for labels. More...
void	Labels.ApplyCategories ()
	Maps labels to the visualization categories. More...
void	Labels.ApplyColorScheme (tkColorSchemeType Type, ColorScheme ColorScheme)
	Applies color scheme to the visualization categories. More...
void	Labels.ApplyColorScheme2 (tkColorSchemeType Type, ColorScheme ColorScheme, tkLabelElements Element)
	Applies color scheme to the visualization categories. More...
void	Labels.ApplyColorScheme3 (tkColorSchemeType Type, ColorScheme ColorScheme, tkLabelElements Element, int CategoryStartIndex, int CategoryEndIndex)
	Applies color scheme to the visualization categories. More...
void	Labels.ClearCategories ()
	Removes all the visualization categories. More...
bool	Labels.GenerateCategories (int FieldIndex, tkClassificationType ClassificationType, int numClasses)
	Generates visualization categories for labels based on certain field from the attribute table of the parent shapefile. More...
LabelCategory	Labels.get_Category (int Index)
	Gets the visualization category (LabelCategory) with the specified index. More...
LabelCategory	Labels.InsertCategory (int Index, string Name)
	Inserts a new visualization category at the given position of the list. More...
bool	Labels.MoveCategoryDown (int Index)
	Moves a specified label category down in the list. More...
bool	Labels.MoveCategoryUp (int Index)
	Moves a specified label category up in the list. More...
bool	Labels.RemoveCategory (int Index)
	Removes a visualization category with specified index. More...
void	Labels.set_Category (int Index, LabelCategory pVal)
	Sets the visualization category at the given position in the list. More...

Properties
int	Labels.NumCategories [get]
	Number of visualization categories associated with this instance of class. More...

Detailed Description

Here is a list of properties and methods to work with visualization categories for labels represented by LabelCategory class. This module is a part of the documentation of Labels class.

Graph description

A visualization category is designed to provide a common visualization options for a group of labels with similar attributes.

Visualization categories can be added in several ways.

1. Automatic generation. This example demonstrates how to create 6 categories with frame color ranging from orange to blue.

Shapefile sf = some_shapefile;
sf.Labels.FrameVisible = true;  // this option will be used inherited by newly generated categories
 
if (sf.Labels.GenerateCategories(0, tkClassificationType.ctNaturalBreaks, 6))   // 0 - index of field
{
   ColorScheme scheme = new ColorScheme();
   scheme.SetColors2(tkMapColor.Orange, tkMapColor.Blue);
   sf.Labels.ApplyColorScheme2(tkColorSchemeType.ctSchemeGraduated, scheme, tkLabelElements.leFrameBackground);
}

2. Manual creation. In this scenario particular labels can be attributed to the category by:

• specification of expression;
• assigning Label.Category property.

In this example a new category with yellow background will be created and objects with area greater than 100 units will be mapped to it.

LabelCategory ct2 = sf.Labels.AddCategory("yellow");
if (ct2 != null)
{
   ct2.FrameBackColor = Convert.ToUInt32(tkMapColor.Yellow);
   ct2.Expression = "[Area] > 100";
   sf.Labels.ApplyCategories();     // this will set Label.Category property
}

This time a category with gray background will be added and then all the labels with even index will be attributed to it.

LabelCategory ct = sf.Labels.AddCategory("gray");
if (ct != null)
{
   ct.FrameBackColor = Convert.ToUInt32(tkMapColor.Gray);
   int index = sf.Labels.NumCategories - 1;    // it was added as the last one
   for (int i = 0; i < sf.Labels.Count; i = i + 2)
   {
       sf.Labels.get_Label(i, 0).Category = index;  // 0 is the index of part
   }
}

Don't forget to redraw the map in the end (AxMap.Redraw).

Function Documentation

AddCategory()

LabelCategory Labels.AddCategory

(

string

Name

)

Adds a visualization category for labels.

Use LabelCategory.Expression or Label.Category to map specific labels to the newly created category.

Parameters

Name	The name of the new category

Returns

The reference to the new category.

Examples

ImageLabels.cs, and LabelSelection.cs.

ApplyCategories()

void Labels.ApplyCategories

(

)

Maps labels to the visualization categories.

LabelCategory.Expression property is analysed. Afterwards Label.Category property is changed for all labels whose attributes comply with the expression.

ApplyColorScheme()

void Labels.ApplyColorScheme	(	tkColorSchemeType	Type,
		ColorScheme	ColorScheme
	)

Applies color scheme to the visualization categories.

Parameters

Type	The method of interpolation.
ColorScheme	Color scheme to take colors from.

ApplyColorScheme2()

void Labels.ApplyColorScheme2	(	tkColorSchemeType	Type,
		ColorScheme	ColorScheme,
		tkLabelElements	Element
	)

Applies color scheme to the visualization categories.

Allows to choose the part of label to apply colors to.

Parameters

Type	The method of interpolation.
ColorScheme	Color scheme object to borrow colors from.
Element	The element of the label to apply colors to. Labels.ApplyColorScheme is shortcut for using leDefault option.

ApplyColorScheme3()

void Labels.ApplyColorScheme3	(	tkColorSchemeType	Type,
		ColorScheme	ColorScheme,
		tkLabelElements	Element,
		int	CategoryStartIndex,
		int	CategoryEndIndex
	)

Applies color scheme to the visualization categories.

Parameters

Type	The method of interpolation.
ColorScheme	Color scheme object to borrow colors from.
Element	The element of the label to apply colors to. Labels.ApplyColorScheme is shortcut for using leDefault option.
CategoryStartIndex	The index of the first visualization category to apply colors to.
CategoryEndIndex	The index of the last visualization category to apply colors to.

ClearCategories()

void Labels.ClearCategories

(

)

Removes all the visualization categories.

GenerateCategories()

bool Labels.GenerateCategories	(	int	FieldIndex,
		tkClassificationType	ClassificationType,
		int	numClasses
	)

Generates visualization categories for labels based on certain field from the attribute table of the parent shapefile.

Use Labels.ApplyCategories to map particular labels to the generated categories based on the LabelCategory.Expression property.

Parameters

FieldIndex	The index of field from the attribute table.
ClassificationType	The type of classification.
numClasses	Number of categories to be generated. It will be ignored for ctUniqueValues.

Returns

True on successful generation and false otherwise.

get_Category()

LabelCategory Labels.get_Category

(

int

Index

)

Gets the visualization category (LabelCategory) with the specified index.

Parameters

Index

The index of the category to get.

Returns

The reference to the category or null in case of the incorrect index.

InsertCategory()

LabelCategory Labels.InsertCategory	(	int	Index,
		string	Name
	)

Inserts a new visualization category at the given position of the list.

Parameters

Index	The index to insert the new category at. Should be greater or equal to 0 and less then Labels.numCategories.
Name	The name of the new category.

Returns

The reference to the newly created category.

MoveCategoryDown()

bool Labels.MoveCategoryDown

(

int

Index

)

Moves a specified label category down in the list.

Parameters

Index

The index of the category to move.

Returns

True on successful operation and false otherwise.

MoveCategoryUp()

bool Labels.MoveCategoryUp

(

int

Index

)

Moves a specified label category up in the list.

Parameters

Index

The index of the category to move.

Returns

True on successful operation and false otherwise.

RemoveCategory()

bool Labels.RemoveCategory

(

int

Index

)

Removes a visualization category with specified index.

Parameters

Index

The index of category to be removed.

Returns

True on successful removal and false otherwise.

set_Category()

void Labels.set_Category	(	int	Index,
		LabelCategory	pVal
	)

Sets the visualization category at the given position in the list.

In fact the method replaces the category at the given index with the new one.

Parameters

Index	The index to set the category at. It should be less then Labels.NumCategories.
pVal	The reference to the category to set.

Properties

NumCategories

int Labels.NumCategories

get

Number of visualization categories associated with this instance of class.