ColorScheme Class Reference

Provides methods for random colour generation and colour interpolation based on the specific set of colour breaks. More...

Collaboration diagram for ColorScheme:

Public Member Functions
void	AddBreak (double Value, uint Color)
	Adds a single break to the colour scheme. More...
void	Clear ()
	Clears all the breaks from the colour scheme. More...
uint	get_BreakColor (int Index)
	Gets the colour of the specific colour break. More...
double	get_BreakValue (int Index)
	Gets the value of the specific colour break. More...
string	get_ErrorMsg (int ErrorCode)
	Gets the description of the given error code. More...
uint	get_GraduatedColor (double Value)
	Calculates the colour which corresponds to the specific value. More...
uint	get_RandomColor (double Value)
	Generates random colour based on the input value. More...
bool	Remove (int Index)
	Removes colour break with specified index. More...
void	Reverse ()
	Reverses the order of color breaks in the color scheme. More...
void	set_BreakColor (int Index, uint retval)
	Sets the colour of break with the specified index. More...
void	SetColors (uint Color1, uint Color2)
	Clears all the existing breaks and creates 2 breaks with the specified colours. More...
void	SetColors2 (tkMapColor Color1, tkMapColor Color2)
	Clears all the existing breaks and creates 2 breaks with the specified colours. More...
void	SetColors3 (short MinRed, short MinGreen, short MinBlue, short MaxRed, short MaxGreen, short MaxBlue)
	Clears all the existing breaks and creates 2 breaks with the specified colours. More...
void	SetColors4 (PredefinedColorScheme Scheme)
	Clears all the existing breaks and creates new set of breaks specified by predefined colour scheme. More...

Properties
ICallback	GlobalCallback [get, set]
	Gets or set the callback object to report errors. More...
string	Key [get, set]
	Gets or sets the string value associated with the instance of the class. More...
int	LastErrorCode [get]
	Gets the code of the last error which occurred within this instance of class. More...
int	NumBreaks [get]
	Returns the number of breaks within colour scheme. More...

Detailed Description

Provides methods for random colour generation and colour interpolation based on the specific set of colour breaks.

1. Colour scheme consists of the number of colour breaks defined by a single pair of value and colour. Colour breaks are automatically arranged in the increasing order in respect to their values. Therefore the new colour break added with ColorScheme.AddBreak won't necessarily be placed in the end of the list. ColorScheme.set_BreakColor changes the colour of a single break, while ColorScheme.SetColors (with overloads) provides a convenient shortcut for initialization of colour scheme with several breaks.

    ColorScheme scheme = new ColorScheme();
    
   // quick init, adds 2 breaks at once
   scheme.SetColors2(tkMapColor.Red, tkMapColor.Yellow);
    
   //let's do the same "manually"
   scheme.AddBreak(0.0, Convert.ToUInt32(tkMapColor.Red));
   scheme.AddBreak(1.0, Convert.ToUInt32(tkMapColor.Yellow));

   
   
2. ColorScheme.get_RandomColor and ColorScheme.get_GraduatedColor are the central methods to generate the random colours within the specified range and to do colour interpolation respectively.
   

    ColorScheme scheme = some_scheme;
    
   // what is the colour in the middle between red and yellow?
   uint color = scheme.get_GraduatedColor(0.5);
    
   // gets some random color between red and yellow
   uint color2 = scheme.get_RandomColor(0.5);

   
   
3. The instance of class can be used to set colors of shapefile categories in fully automatic way (ShapefileCategories.ApplyColorScheme), as well as for setting the colors of shapefile categories, label categories or chart bars in more controlled, "manual" fashion.

// lets' define scheme
ColorScheme scheme = some_scheme;
 
// here is shapefile with 8 visualization categories
Shapefile sf = some_shapefile;
sf.Categories.Generate(0, tkClassificationType.ctNaturalBreaks, 8);   // 0 is field index; 8 - number of categories
   
// 1. Let's apply colors automatically
sf.Categories.ApplyColorScheme(tkColorSchemeType.ctSchemeGraduated, scheme);
 
// 2. Let's do the same "manually"
sf.Categories.Clear();
for (int i = 0; i < sf.Categories.Count; i++)
{   
    uint color = scheme.get_GraduatedColor((double)(i + 1)/ (double)sf.Categories.Count);  // value between 0.0 and 1.0 as argument
    sf.Categories.get_Item(i).DrawingOptions.FillColor = color;
}

New API 4.8:

Added in version 4.8

Examples

AddCategoryRange.cs, CreateBuffer.cs, CreatePolygonShapefile.cs, MinimalDistance.cs, Segmentation.cs, and SplitByAttribute.cs.

Member Function Documentation

AddBreak()

void ColorScheme.AddBreak	(	double	Value,
		uint	Color
	)

Adds a single break to the colour scheme.

Parameters

Value	The value of the break. Must be within 0.0 to 1.0 range.
Color	The colour of the break.

Clear()

void ColorScheme.Clear

(

)

Clears all the breaks from the colour scheme.

get_BreakColor()

uint ColorScheme.get_BreakColor

(

int

Index

)

Gets the colour of the specific colour break.

Parameters

Index

The index of the colour break.

Returns

The colour of the break.

get_BreakValue()

double ColorScheme.get_BreakValue

(

int

Index

)

Gets the value of the specific colour break.

Parameters

Index

The index of the colour break.

Returns

The value of the colour break (0.0-1.0).

get_ErrorMsg()

string ColorScheme.get_ErrorMsg

(

int

ErrorCode

)

Gets the description of the given error code.

Parameters

ErrorCode

Error code returned by ColorScheme.LastErrorCode.

Returns

The description of the error.

get_GraduatedColor()

uint ColorScheme.get_GraduatedColor

(

double

Value

)

Calculates the colour which corresponds to the specific value.

In cases when the value isn't equal to the value of the existing break, colour interpolation will be made.

Parameters

Value

The value to calculate colour for. Must be within [0.0, 1.0] range.

Returns

The interpolated colour.

get_RandomColor()

uint ColorScheme.get_RandomColor

(

double

Value

)

Generates random colour based on the input value.

The calculation will be made as following:

• 2 colour breaks will be defined between which the value lies;
• for each component of the colour a random value will be generated which lies between the value of the same colour component for the 2 adjacent breaks;

• the resulting colour will be calculated as the sum of 3 components.

Parameters

Value

The value to calculate colour for. Must be within [0.0, 1.0] range.

Returns

The random colour.

Examples

SplitByAttribute.cs.

Remove()

bool ColorScheme.Remove

(

int

Index

)

Removes colour break with specified index.

Parameters

Index

The index of colour break to remove.

Returns

True on successful removal and false otherwise.

Reverse()

void ColorScheme.Reverse

(

)

Reverses the order of color breaks in the color scheme.

New API 4.9.4:

Added in version 4.9.4

set_BreakColor()

void ColorScheme.set_BreakColor	(	int	Index,
		uint	retval
	)

Sets the colour of break with the specified index.

Parameters

Index	The index of the break.
retval	The new colour to set.

SetColors()

void ColorScheme.SetColors	(	uint	Color1,
		uint	Color2
	)

Clears all the existing breaks and creates 2 breaks with the specified colours.

The values of the breaks will be 0.0 for the first one and 1.0 for the second.

Parameters

Color1	The colour of the first break.
Color2	The colour of the second break.

SetColors2()

void ColorScheme.SetColors2	(	tkMapColor	Color1,
		tkMapColor	Color2
	)

Clears all the existing breaks and creates 2 breaks with the specified colours.

The values of the breaks will be 0.0 for the first one and 1.0 for the second.

Parameters

Color1	The colour of the first break.
Color2	The colour of the second break.

Examples

CreatePolygonShapefile.cs, MinimalDistance.cs, Segmentation.cs, and SplitByAttribute.cs.

SetColors3()

void ColorScheme.SetColors3	(	short	MinRed,
		short	MinGreen,
		short	MinBlue,
		short	MaxRed,
		short	MaxGreen,
		short	MaxBlue
	)

Clears all the existing breaks and creates 2 breaks with the specified colours.

The values of the breaks will be 0.0 for the first one and 1.0 for the second.

Parameters

MinRed	The red component of colour for the first colour break (0-255).
MinGreen	The green component of colour for the first colour break (0-255).
MinBlue	The blue component of colour for the first colour break (0-255).
MaxRed	The red component of colour for the second colour break (0-255).
MaxGreen	The green component of colour for the second colour break (0-255).
MaxBlue	The blue component of colour for the second colour break (0-255).

SetColors4()

void ColorScheme.SetColors4

(

PredefinedColorScheme

Scheme

)

Clears all the existing breaks and creates new set of breaks specified by predefined colour scheme.

The number of the newly added breaks depends on the colour scheme chosen, usually 2-3.

Property Documentation

GlobalCallback

ICallback ColorScheme.GlobalCallback

getset

Gets or set the callback object to report errors.

Deprecated:

v4.9.3 Use GlobalSettings.ApplicationCallback instead.

Key

string ColorScheme.Key

getset

Gets or sets the string value associated with the instance of the class.

LastErrorCode

int ColorScheme.LastErrorCode

get

Gets the code of the last error which occurred within this instance of class.

NumBreaks

int ColorScheme.NumBreaks

get

Returns the number of breaks within colour scheme.