Represents a list of visualization categories which determine the appearance of the shapefile. More...

Collaboration diagram for ShapefileCategories:

Public Member Functions
ShapefileCategory	Add (string Name)
	Creates a new visualization category, adds it to the list and returns its reference to the caller. More...

void	Add2 (ShapefileCategory Category)
	Adds the category to the collection. More...

bool	AddRange (int FieldIndex, tkClassificationType ClassificationType, int numClasses, object MinValue, object MaxValue)
	Creates the specified number of visualization categories and expressions for them. More...

void	ApplyColorScheme (tkColorSchemeType Type, ColorScheme ColorScheme)
	Applies color scheme to the visualization categories. More...

void	ApplyColorScheme2 (tkColorSchemeType Type, ColorScheme ColorScheme, tkShapeElements ShapeElement)
	Applies color scheme to the visualization categories. More...

void	ApplyColorScheme3 (tkColorSchemeType Type, ColorScheme ColorScheme, tkShapeElements ShapeElement, int CategoryStartIndex, int CategoryEndIndex)
	Applies color scheme to the visualization categories. More...

void	ApplyExpression (int CategoryIndex, int startRowIndex=-1, int endRowIndex=-1)
	Maps particular shapes to the category based on ShapefileCategory.Expression. More...

void	ApplyExpressions ()
	Maps shapes to the visualization categories based in ShapefileCategory.Expression. More...

void	Clear ()
	Removes all the categories from the list. More...

void	Deserialize (string newVal)
	Restores the state of the object from the string. More...

bool	Generate (int FieldIndex, tkClassificationType ClassificationType, int numClasses)
	Generates visualization categories by certain attribute More...

bool	Generate2 (string FieldName, tkClassificationType ClassificationType, int numClasses)
	Generates categories based on specified field. More...

bool	GeneratePolygonColors (ColorScheme Scheme=null)
	Applies specific coloring to polygon layer based on 2 rules: More...

int	get_CategoryIndex (ShapefileCategory Category)
	Gets index of the specified category within a collection. More...

int	get_CategoryIndexByName (string categoryName)
	Gets index of category by its name. The comparison is case-sensitive. More...

string	get_ErrorMsg (int ErrorCode)
	Gets the description of the specific error code. More...

ShapefileCategory	get_Item (int Index)
	Returns the category with the specified index. More...

ShapefileCategory	Insert (int Index, string Name)
	Creates a new visualization category and inserts it at specified position of the list. More...

bool	Insert2 (int Index, ShapefileCategory Category)
	Inserts a category at the specified index in the collection. More...

bool	MoveDown (int Index)
	Moves the specified category down the list by swapping it with the succeeding category. More...

bool	MoveUp (int Index)
	Moves the specified category up the list by swapping it with the preceding category. More...

bool	Remove (int Index)
	Removes the specified category. More...

string	Serialize ()
	Saves the state of the object to the string. More...

void	set_Item (int Index, ShapefileCategory pVal)
	Replaces the category with the specified index with the new one. More...

Properties
string	Caption `[get, set]`
	The name of the classification scheme to display in the legend. More...

int	ClassificationField `[get, set]`
	Gets or sets the index of classification that was used to generate categories. More...

int	Count `[get]`
	Returns the number of the categories in the list. More...

ICallback	GlobalCallback `[get, set]`
	Gets or sets the callback object which is used to return to the client the information about progress and errors. More...

string	Key `[get, set]`
	A text string associated with the instance of the class. Any value can be stored by developer in this property. More...

int	LastErrorCode `[get]`
	Retrieves the numeric code of the last error that took place in the class. More...

Shapefile	Shapefile `[get]`
	A reference to the parent shapefile. More...

Detailed Description

Represents a list of visualization categories which determine the appearance of the shapefile.

Provides methods for:

managing categories: ShapefileCategories.Add, ShapefileCategories.Insert(), ShapefileCategories.Remove, ShapefileCategories.Clear();
generation of categories based on the specified attribute: ShapefileCategories.Generate();
mapping of categories to particular shapes: ShapefileCategories.ApplyExpressions();
setting of common color scheme for the range of categories: ShapefileCategories.ApplyColorScheme().
accessing particular categories: ShapefileCategories.get_Item().

Here is a diagram for the ShapefileCategories class.

Graph description

New API 4.8:: Added in version 4.8

Member Function Documentation

◆ Add()

ShapefileCategory ShapefileCategories.Add ( string Name )

Creates a new visualization category, adds it to the list and returns its reference to the caller.

It's the responsibility of the developer to map the new category to the particular shape by either:

specifying ShapefileCategory.Expression and calling ShapefileCategories.ApplyExpression();
by using Shapefile.set_ShapeCategory() property;

Parameters

Name	The name of the new category. It must not be unique.

Returns: The reference to the newly created category or NULL reference on failure.

Examples: MinimalDistance.cs, and PointIcons.cs.

◆ Add2()

void ShapefileCategories.Add2 ( ShapefileCategory Category )

Adds the category to the collection.

Parameters

Category The category.

New API 4.9.4:: Added in version 4.9.4

◆ AddRange()

bool ShapefileCategories.AddRange	(	int	FieldIndex,
		tkClassificationType	ClassificationType,
		int	numClasses,
		object	MinValue,
		object	MaxValue
	)

Creates the specified number of visualization categories and expressions for them.

The method can be useful to override generation routine provided in ShapefileCategories.GenerateCategories() which always generate categories covering the full range of values of the specified field. This method can define the range of values explicitly, therefore certain values can be excluded from classification or on contrary categories can be added for the values which aren't yet present in the table.

Parameters

FieldIndex	The index of the field to build classification by.
ClassificationType	The type of the classification.
numClasses	The number of categories to add. If ClassificationType equals ctUniqueValues this value will be skipped.
MinValue	The minimal value of the field to include in the classification.
MaxValue	Th maximum value of the field to include in the classification.

Returns: True on successful adding and false otherwise.

Examples: AddCategoryRange.cs.

◆ ApplyColorScheme()

void ShapefileCategories.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.

Examples: CreateBuffer.cs, and MinimalDistance.cs.

◆ ApplyColorScheme2()

void ShapefileCategories.ApplyColorScheme2	(	tkColorSchemeType	Type,
		ColorScheme	ColorScheme,
		tkShapeElements	ShapeElement
	)

Applies color scheme to the visualization categories.

Parameters

Type	The method of interpolation.
ColorScheme	The color scheme to take colors from.
ShapeElement	The element of the shape symbology to apply colors to.

◆ ApplyColorScheme3()

void ShapefileCategories.ApplyColorScheme3	(	tkColorSchemeType	Type,
		ColorScheme	ColorScheme,
		tkShapeElements	ShapeElement,
		int	CategoryStartIndex,
		int	CategoryEndIndex
	)

Applies color scheme to the visualization categories.

Parameters

Type	The method of interpolation.
ColorScheme	The color scheme to take colors from.
ShapeElement	The element of the shape symbology to apply colors to.
CategoryStartIndex	The index of the first category to apply colors to.
CategoryEndIndex	The index of the last category to apply colors to.

Examples: AddCategoryRange.cs.

◆ ApplyExpression()

void ShapefileCategories.ApplyExpression	(	int	CategoryIndex,
		int	startRowIndex = `-1`,
		int	endRowIndex = `-1`
	)

Maps particular shapes to the category based on ShapefileCategory.Expression.

The mapping between the category and shapes can be changed by Shapefile.set_ShapeCategory property. The row index parameters are zero-based and bounds-inclusive, meaning that if you want to apply expressions on a single row, you have to specifiy its row index as startRowIndex and endRowIndex.

Parameters

CategoryIndex	The index of the category.
startRowIndex	Starting row index to apply expressions on. Negative values translate to the first row.
endRowIndex	Last row index to apply expressions on. Negative values translate to the last row.

◆ ApplyExpressions()

void ShapefileCategories.ApplyExpressions ( )

Maps shapes to the visualization categories based in ShapefileCategory.Expression.

The mapping between the category and shapes can be changed by Shapefile.set_ShapeCategory property.

Examples: AddCategoryRange.cs, CreateBuffer.cs, MinimalDistance.cs, PointIcons.cs, and SplitByAttribute.cs.

◆ Clear()

void ShapefileCategories.Clear ( )

Removes all the categories from the list.

◆ Deserialize()

void ShapefileCategories.Deserialize ( string newVal )

Restores the state of the object from the string.

Parameters

newVal A string generated by ShapefileCategories.Serialize() method.

◆ Generate()

bool ShapefileCategories.Generate	(	int	FieldIndex,
		tkClassificationType	ClassificationType,
		int	numClasses
	)

Generates visualization categories by certain attribute

Parameters

FieldIndex	The index of the field to generate categories by.
ClassificationType	The type of classification.
numClasses	Number of classes to generate. The parameter is omitted in case unique values classification is used.

Returns: True on successful generation and false otherwise.

Examples: CreateBuffer.cs, MinimalDistance.cs, and SplitByAttribute.cs.

◆ Generate2()

bool ShapefileCategories.Generate2	(	string	FieldName,
		tkClassificationType	ClassificationType,
		int	numClasses
	)

Generates categories based on specified field.

Parameters

FieldName	Name of the field.
ClassificationType	Type of the classification.
numClasses	The number classes.

Returns: True on success.

New API 4.9.4:: Added in version 4.9.4

◆ GeneratePolygonColors()

bool ShapefileCategories.GeneratePolygonColors ( ColorScheme Scheme = null )

Applies specific coloring to polygon layer based on 2 rules:

each polygon fill color must be different from the colors of all adjacent polygons;
the minimum overall number of colors must be used.

Parameters

Scheme Color scheme to take colors from. If the number of color breaks is smaller than the number of polygon colors, interpolation with ColorScheme.GetGraduatedColor method will be used.

The coloring assumptions used by the method correspond to the formulation of Four color theorem. But simple greedy algorithm used by the method usually employs somewhat more colors (5-6), although provides much better performance than precise implementations.

Returns: True on success.

New API 4.9.2:: Added in version 4.9.2

◆ get_CategoryIndex()

int ShapefileCategories.get_CategoryIndex ( ShapefileCategory Category )

Gets index of the specified category within a collection.

Parameters

Category Category to find index for.

Returns: Index of category.

New API 4.9.1:: Added in version 4.9.1

◆ get_CategoryIndexByName()

int ShapefileCategories.get_CategoryIndexByName ( string categoryName )

Gets index of category by its name. The comparison is case-sensitive.

Parameters

categoryName Category name to find index for.

Returns: Index of category.

New API 4.9.1:: Added in version 4.9.1

◆ get_ErrorMsg()

string ShapefileCategories.get_ErrorMsg ( int ErrorCode )

Gets the description of the specific error code.

Parameters

ErrorCode The error code returned by ShapefileCategories.LastErrorCode

Returns: The string with the description

◆ get_Item()

ShapefileCategory ShapefileCategories.get_Item ( int Index )

Returns the category with the specified index.

Parameters

Index The index of the category to retrieve.

Returns: The reference to the category or NULL reference on failure.

◆ Insert()

ShapefileCategory ShapefileCategories.Insert	(	int	Index,
		string	Name
	)

Creates a new visualization category and inserts it at specified position of the list.

Parameters

Index	The index to insert category at.
Name	The name of the new category.

Returns: Reference to the new category or NULL reference on failure.

◆ Insert2()

bool ShapefileCategories.Insert2	(	int	Index,
		ShapefileCategory	Category
	)

Inserts a category at the specified index in the collection.

Parameters

Index	The index.
Category	The category to be inserted.

Returns: True on success.

New API 4.9.4:: Added in version 4.9.4

◆ MoveDown()

bool ShapefileCategories.MoveDown ( int Index )

Moves the specified category down the list by swapping it with the succeeding category.

Parameters

Index The index of the category to move down.

Returns: True on success and false otherwise.

◆ MoveUp()

bool ShapefileCategories.MoveUp ( int Index )

Moves the specified category up the list by swapping it with the preceding category.

Parameters

Index The index of the category to move.

Returns: True on success and false otherwise.

◆ Remove()

bool ShapefileCategories.Remove ( int Index )

Removes the specified category.

Parameters

Index The index of the category to remove.

Returns: True on success and false otherwise.

◆ Serialize()

string ShapefileCategories.Serialize ( )

Saves the state of the object to the string.

Returns: A string with serialized state.

◆ set_Item()

void ShapefileCategories.set_Item	(	int	Index,
		ShapefileCategory	pVal
	)

Replaces the category with the specified index with the new one.

Parameters

Index	The index of the category to replace.
pVal	The new category.

Property Documentation

◆ Caption

string ShapefileCategories.Caption

getset

The name of the classification scheme to display in the legend.

◆ ClassificationField

int ShapefileCategories.ClassificationField

getset

Gets or sets the index of classification that was used to generate categories.

New API 4.9.3:: Added in version 4.9.3

◆ Count

int ShapefileCategories.Count

get

Returns the number of the categories in the list.

Examples: SplitByAttribute.cs.

◆ GlobalCallback

ICallback ShapefileCategories.GlobalCallback

getset

Gets or sets the callback object which is used to return to the client the information about progress and errors.

An instance of the class which implements ICallback interface should be passed. The class must be implemented by caller.

Deprecated:: v4.9.3 Use GlobalSettings.ApplicationCallback instead.

◆ Key

string ShapefileCategories.Key

getset

A text string associated with the instance of the class. Any value can be stored by developer in this property.

◆ LastErrorCode

int ShapefileCategories.LastErrorCode

get

Retrieves the numeric code of the last error that took place in the class.

The usage of this property clears the error code.

◆ Shapefile

Shapefile ShapefileCategories.Shapefile

get

A reference to the parent shapefile.

NULL reference will be returned in case the categories aren't associated with a shapefile.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ Add()

◆ Add2()

◆ AddRange()

◆ ApplyColorScheme()

◆ ApplyColorScheme2()

◆ ApplyColorScheme3()

◆ ApplyExpression()

◆ ApplyExpressions()

◆ Clear()

◆ Deserialize()

◆ Generate()

◆ Generate2()

◆ GeneratePolygonColors()

◆ get_CategoryIndex()

◆ get_CategoryIndexByName()

◆ get_ErrorMsg()

◆ get_Item()

◆ Insert()

◆ Insert2()

◆ MoveDown()

◆ MoveUp()

◆ Remove()

◆ Serialize()

◆ set_Item()

Property Documentation

◆ Caption

◆ ClassificationField

◆ Count

◆ GlobalCallback

◆ Key

◆ LastErrorCode

◆ Shapefile