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:
Collaboration graph

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"
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
}
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
ValueThe value of the break. Must be within 0.0 to 1.0 range.
ColorThe 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
IndexThe 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
IndexThe 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
ErrorCodeError 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
ValueThe 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
ValueThe 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
IndexThe 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
IndexThe index of the break.
retvalThe 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
Color1The colour of the first break.
Color2The 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
Color1The colour of the first break.
Color2The 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
MinRedThe red component of colour for the first colour break (0-255).
MinGreenThe green component of colour for the first colour break (0-255).
MinBlueThe blue component of colour for the first colour break (0-255).
MaxRedThe red component of colour for the second colour break (0-255).
MaxGreenThe green component of colour for the second colour break (0-255).
MaxBlueThe 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.