Public Member Functions | Properties
ColorScheme Class Reference

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

List of all members.

Public Member Functions

void AddBreak (double Value, uint Color)
 Adds a single break to the color scheme.
void Clear ()
 Clears all the breaks from the color scheme.
uint get_BreakColor (int Index)
 Gets the color of the specific color break.
double get_BreakValue (int Index)
 Gets the value of the specific color break.
string get_ErrorMsg (int ErrorCode)
 Gets the description of the given error code.
uint get_GraduatedColor (double Value)
 Calculates the color which corresponds to the specific value.
uint get_RandomColor (double Value)
 Generates random color based on the input value.
bool Remove (int Index)
 Removes color break with specified index.
void set_BreakColor (int Index, uint retval)
 Sets the color of break with the specified index.
void SetColors (uint Color1, uint Color2)
 Clears all the existing breaks and creates 2 breaks with the specified colors.
void SetColors2 (tkMapColor Color1, tkMapColor Color2)
 Clears all the existing breaks and creates 2 breaks with the specified colors.
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 colors.
void SetColors4 (PredefinedColorScheme Scheme)
 Clears all the existing breaks and creates new set of breaks specified by predefined color scheme.

Properties

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

Detailed Description

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

1. Color scheme consists of the number of color breaks defined by a single pair of value and color. Color breaks are automatically arranged in the increasing order in respect to their values. Therefore the new color break added with ColorScheme.AddBreak won't necessarily be placed in the end of the list. ColorScheme.set_BreakColor changes the color of a single break, while ColorScheme.SetColors (with overloads) provides a convenient shortcut for initialization of color 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 colors within the specified range and to do color interpolation respectively.

 ColorScheme scheme = some_scheme;

 // what is the color 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 automatiс 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

void ColorScheme.AddBreak ( double  Value,
uint  Color 
)

Adds a single break to the color scheme.

Parameters:
ValueThe value of the break. Must be within 0.0 to 1.0 range.
ColorThe color of the break.

Clears all the breaks from the color scheme.

uint ColorScheme.get_BreakColor ( int  Index)

Gets the color of the specific color break.

Parameters:
IndexThe index of the color break.
Returns:
The color of the break.
double ColorScheme.get_BreakValue ( int  Index)

Gets the value of the specific color break.

Parameters:
IndexThe index of the color break.
Returns:
The value of the color break (0.0-1.0).
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.
uint ColorScheme.get_GraduatedColor ( double  Value)

Calculates the color which corresponds to the specific value.

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

Parameters:
ValueThe value to calculate color for. Must be within [0.0, 1.0] range.
Returns:
The interpolated color.
Examples:
Segmentation.cs.
uint ColorScheme.get_RandomColor ( double  Value)

Generates random color based on the input value.

The calculation will be made as following:

  • 2 color breaks will be defined between which the value lies;
  • for each component of the color a random value will be generated which lies between the value of the same color component for the 2 adajcent breaks;
  • the resulting color will be calculated as the sum of 3 components.
Parameters:
ValueThe value to calculate color for. Must be within [0.0, 1.0] range.
Returns:
The random color.
Examples:
SplitByAttribute.cs.
bool ColorScheme.Remove ( int  Index)

Removes color break with specified index.

Parameters:
IndexThe index of color break to remove.
Returns:
True on successful removal and false otherwise.
void ColorScheme.set_BreakColor ( int  Index,
uint  retval 
)

Sets the color of break with the specified index.

Parameters:
IndexThe index of the break.
retvalThe new color to set.
void ColorScheme.SetColors ( uint  Color1,
uint  Color2 
)

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

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

Parameters:
Color1The color of the first break.
Color2The color of the second break.
void ColorScheme.SetColors2 ( tkMapColor  Color1,
tkMapColor  Color2 
)

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

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

Parameters:
Color1The color of the first break.
Color2The color of the second break.
Examples:
AddCategoryRange.cs, CreateBuffer.cs, CreatePolygonShapefile.cs, MinimalDistance.cs, Segmentation.cs, and SplitByAttribute.cs.
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 colors.

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

Parameters:
MinRedThe red component of color for the first color break (0-255).
MinGreenThe green component of color for the first color break (0-255).
MinBlueThe blue component of color for the first color break (0-255).
MaxRedThe red component of color for the second color break (0-255).
MaxGreenThe green component of color for the second color break (0-255).
MaxBlueThe blue component of color for the second color break (0-255).

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

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


Property Documentation

Gets or set the callback object to report errors.

string ColorScheme.Key [get, set]

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

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

Returns the number of breaks within color scheme.

 All Classes Files Functions Enumerations Properties