Public Member Functions | Properties
Charts Class Reference

Provides functionality for generation and managing the charts on the map. More...

List of all members.

Public Member Functions

bool AddField (ChartField Field)
 Adds a field to the chart.
void AddField2 (int FieldIndex, uint Color)
 Adds a field to the chart.
void Clear ()
 Clears the informtion about individual charts like position and visibility.
void ClearFields ()
 Removes all fields which define bars or sectors of the chart.
void Deserialize (string newVal)
 Restores the state of the charts from the serialized string.
bool DrawChart (IntPtr hdc, float x, float y, bool hideLabels, uint BackColor)
 Draws a chart on the specified device context. Can be used for displaying of map legend.
bool Generate (tkLabelPositioning Type)
 Generates a chart for every shape of the parent shapefile.
Chart get_Chart (int Chart)
 Gets a reference to the chart with the specified index.
string get_ErrorMsg (int ErrorCode)
 Gets the description of the specified error code.
ChartField get_Field (int FieldIndex)
 Gets a reference to the field of the chart with the specified index.
bool InsertField (int Index, ChartField Field)
 Inserts a field which represents single bar or sector of the chart.
bool InsertField2 (int Index, int FieldIndex, uint Color)
 Inserts a field which represents single bar or sector of the chart.
bool LoadFromXML (string Filename)
 Loads charts data from the XML file generated by Charts.SaveToXML.
bool MoveField (int OldIndex, int NewIndex)
 Changes the position of a field (bar or sector) in the list which affects the order of drawing.
bool RemoveField (int Index)
 Removes the field which corresponds to the bar or the sector of the chart.
bool SaveToXML (string Filename)
 Saves the state of the charts to the XML file.
bool Select (Extents BoundingBox, int Tolerance, SelectMode SelectMode, ref object Indices)
 Returns the indices of charts which are displayed within specified rectangle on the screen.
string Serialize ()
 Serializes the state of the charts to the string.

Properties

bool AvoidCollisions [get, set]
 Gets or set a boolen value which indicates whether charts can overlap each other.
int BarHeight [get, set]
 Gets or sets the maximum height of the bar chart in pixels.
int BarWidth [get, set]
 Gets or sets the width of a single bar of the chart in pixels.
string Caption [get, set]
 Gets or sets the text string for description of the chart data.
tkChartType ChartType [get, set]
 Gets or sets the type of the charts.
int CollisionBuffer [get, set]
 Gets or sets the minimal distance between individual charts when Charts.AvoidCollisions is set to true.
int Count [get]
 Returns the number of charts which is equal to the number of shapes in the parent shapefile.
bool DynamicVisibility [get, set]
 Gets or sets a value which indicates whether charts will be visible for all scales or in the given range of scales only.
ICallback GlobalCallback [get, set]
 Gets or sets a callback object to display progress and error information.
int IconHeight [get]
 Gets the minimal height of the image to display a single chart.
int IconWidth [get]
 Gets the minimal width of the image to display a single chart.
string Key [get, set]
 Gets or sets a string value associated with the object.
int LastErrorCode [get]
 Gets the code of the last error which took place inside the current instance of the class.
uint LineColor [get, set]
 Gets or sets the color of the chart outline.
double MaxVisibleScale [get, set]
 Get or sets the maximum scale the charts are displayed when dynamic visibility is turned on.
double MinVisibleScale [get, set]
 Gets or sets the minimal scale the charts are displayed when dynamic visibility is turned on.
int NormalizationField [get, set]
 Gets or sets the index of field upon which the values of other fields will be divided before displaying charts.
int NumFields [get]
 Gets the number of fields which correspond to the bars of sectors depending on chart type.
int OffsetX [get, set]
 Gets or sets the horizontal offset for drawing charts.
int OffsetY [get, set]
 Gets or set the vertical offset for drawing charts.
int PieRadius [get, set]
 Gets or sets the radius of the pie chart in pixels.
int PieRadius2 [get, set]
 Gets or sets the radius of the largest chart when Charts.UseVariableRadius is turned on.
double PieRotation [get, set]
 Gets or set the rotation of the pie chart.
tkSavingMode SavingMode [get, set]
 Gets or sets the mode for serialization of charts. Affects Charts.SaveToXML method.
int SizeField [get, set]
 Gets or sets the index of field which affect the radius of charts when Charts.UseVariableRadius is set to true.
double Thickness [get, set]
 Gets or sets the value which affects 3D display of the charts.
double Tilt [get, set]
 Gets or sets the tilt of the charts when 3D display is on.
short Transparency [get, set]
 Gets or set the transparency of charts (0-255).
bool Use3DMode [get, set]
 Gets or sets a boolean value which indicates whether 3D mode will be used for charts drawing.
bool UseVariableRadius [get, set]
 Gets or sets the value which indicates whether all pie charts will have the same or varying radius.
bool ValuesFontBold [get, set]
 Gets or sets the value which indicates whether data labels for charts will be bold.
uint ValuesFontColor [get, set]
 Gets or sets the color of the chart's data labels.
bool ValuesFontItalic [get, set]
 Gets or sets the value which indicates whether data labels for charts will be italic.
string ValuesFontName [get, set]
 Gets or sets the font name for data labels of charts. The names of font families like "Arial" can be used.
int ValuesFontSize [get, set]
 Gets or set the size of chart's labels.
uint ValuesFrameColor [get, set]
 Gets or sets the color of the frame for chart labels.
bool ValuesFrameVisible [get, set]
 Gets or sets a boolean value which indicates whether the frame of chart's labels is visible.
tkChartValuesStyle ValuesStyle [get, set]
 Gets or sets the style of the chart's labels.
bool ValuesVisible [get, set]
 Gets or sets the value which indicates whether labels with values of the fields will be drawn near each chart.
tkVerticalPosition VerticalPosition [get, set]
 Gets or sets the position of charts in the map drawing order.
string VisibilityExpression [get, set]
 Gets or sets the expression which defines the subset of charts which will be displayed on the map.
bool Visible [get, set]
 Turns on or off the visibility of charts.

Detailed Description

Provides functionality for generation and managing the charts on the map.

dot_inline_dotgraph_34.png

Graph description

The charts obtain their data from the fields of attribute table of the shapefile. A single bar or sector of the chart is mapped to a certain field by means of ChartField class. The number of fields to be displayed can be changed by Charts.AddField, Charts.RemoveField. The fields should be of numeric types, either double or integer.

Two types of charts are available:

  1. Pie charts:
    • are suitable when it's necessary to display the parts of the whole phenomemon, like the percentage of land use by type (urban, forest, agricultural, etc.);
    • it's possible to set varying width for the charts depending of the certain field, which can give an idea about the values for different shapes on comparative scale;
  2. Bar charts:
    • they can be used to display virtually any numeric data;
    • it still makes sense to display fields with the same units of measure;
charts.png

To generate charts one basically needs:

  1. To specify a set of fields which will be included (see Charts.AddField and Charts.AddField2).

  2. To define the positions of the charts relative to the parent shape.
    • Charts.Generate method is the only one to do this job;
    • for large shapefile this procedure can be time consuming, therefore there are means for caching this data to avoid additional recalculations;
    • it's possible to change the generated positions of the individual charts (see Chart.PositionX, Chart.PositionY).

  3. To set the display options of the charts. The options include:
    • the size of charts (Charts.PieRadius for pie charts and Charts.BarHeight for bar charts; the values of these 2 types of charts don't affect each other);
    • the color of the charts fill and outline;
    • labels with the values from the underlying table, which correspond to particular bar or sector.
 private void GenerateCharts(Shapefile sf)
 {
     sf.Charts.AddField2(0, 255);    // index of field, color
     sf.Charts.AddField2(1, 255);
     sf.Charts.Generate(tkLabelPositioning.lpCentroid);
     sf.Charts.ChartType = tkChartType.chtBarChart;
 }

Individual charts can be accessed using Charts.get_Chart() property. It's possibe to change their properties like visibility or position. Chart.ScreenExtents property return screen coordinates occupied by particular chart which provides a convenient way for hightlighting or mouse dragging operation on the chart.

By default charts are drawn for each shape of the shapefile, but if only a subset of shapes require charts it's possible to set Charts.VisibilityExpression, or toggle the visibility of individual charts (Chart.Visible). Though the number of individual charts will always be equal to the number of shapes in the shapefile, which means that charts will be automatically added and removed after corresponding editing operation in the parent shapefile. It's not possible to set different visualization options or the number of fields for individual charts.

It's not possible to use charts independantly of the shapefile layer. But it's possible to create a dummy shapefile, populate it with data and display any charts at any location.

New API 4.8:
Added in version 4.8
Examples:
Segmentation.cs.

Member Function Documentation

bool Charts.AddField ( ChartField  Field)

Adds a field to the chart.

The field will be represented as bar or sector depending on chart type.

Parameters:
FieldA field to add.
Returns:
True on success or false otherwise.
Examples:
IntersectionLength.cs.
void Charts.AddField2 ( int  FieldIndex,
uint  Color 
)

Adds a field to the chart.

Parameters:
FieldIndexThe index of the field in the attribute table to take values from.
ColorThe color of the sector or bar for visualization of a field.
Examples:
Segmentation.cs.
void Charts.Clear ( )

Clears the informtion about individual charts like position and visibility.

To restore the charts a call of Charts.Generate() is needed. The fields will remain untouched by this method.

Removes all fields which define bars or sectors of the chart.

void Charts.Deserialize ( string  newVal)

Restores the state of the charts from the serialized string.

Parameters:
newValSerialized string generated by Charts.Serialize().
bool Charts.DrawChart ( IntPtr  hdc,
float  x,
float  y,
bool  hideLabels,
uint  BackColor 
)

Draws a chart on the specified device context. Can be used for displaying of map legend.

Parameters:
hdcThe handle of the device context.
xThe position of the left corner of the drawing in pixels.
yThe position of the top corner of the drawing in pixels.
hideLabelsWhen set to true the labels won't be drawn.
BackColorThe back color of the device context. Shoud be provided to ensure correct alpha blending when transparence is set.
Returns:
True on success and false otherwise.

Generates a chart for every shape of the parent shapefile.

This method is time consuming for large shapefiles, therfore consider the serialization of charts data after first generation.

Parameters:
TypeThe position of chart relative to the parent shape.
Returns:
True on success and false otherwise.
Examples:
IntersectionLength.cs, and Segmentation.cs.
Chart Charts.get_Chart ( int  Chart)

Gets a reference to the chart with the specified index.

Parameters:
ChartThe index of the chart to extract.
Returns:
The reference to the chart of NULL reference on failure.
string Charts.get_ErrorMsg ( int  ErrorCode)

Gets the description of the specified error code.

Parameters:
ErrorCodeThe error code returned by Charts.LastErrorCode.
Returns:
The description of error.
ChartField Charts.get_Field ( int  FieldIndex)

Gets a reference to the field of the chart with the specified index.

Parameters:
FieldIndexThe index of the field.
Returns:
The reference to the chart field or NULL reference on failure.
bool Charts.InsertField ( int  Index,
ChartField  Field 
)

Inserts a field which represents single bar or sector of the chart.

Parameters:
IndexThe index to insert the field at.
FieldThe chart field object to insert.
Returns:
True on success and false otherwise.
bool Charts.InsertField2 ( int  Index,
int  FieldIndex,
uint  Color 
)

Inserts a field which represents single bar or sector of the chart.

Parameters:
IndexThe index to insert the field at.
FieldIndexThe index of the field from the attribute table (.dbf) to take values from.
ColorThe color of the fill.
Returns:
True on success and false otherwise.
bool Charts.LoadFromXML ( string  Filename)

Loads charts data from the XML file generated by Charts.SaveToXML.

Parameters:
FilenameThe filename to load data from.
Returns:
True on successful loading and false otherwise.
bool Charts.MoveField ( int  OldIndex,
int  NewIndex 
)

Changes the position of a field (bar or sector) in the list which affects the order of drawing.

Parameters:
OldIndexThe old index of the field.
NewIndexThe new index of the field.
Returns:
bool Charts.RemoveField ( int  Index)

Removes the field which corresponds to the bar or the sector of the chart.

Parameters:
IndexThe index of the field to remove.
Returns:
True on success and false otherwise.
bool Charts.SaveToXML ( string  Filename)

Saves the state of the charts to the XML file.

Charts.SavingMode defines the particular data which will be serialized.

Parameters:
FilenameThe filename to save into.
Returns:
True on success and false otherwise.
bool Charts.Select ( Extents  BoundingBox,
int  Tolerance,
SelectMode  SelectMode,
ref object  Indices 
)

Returns the indices of charts which are displayed within specified rectangle on the screen.

Parameters:
BoundingBoxThe rectangle to select charts within (in screen coordinates).
ToleranceThe tolerance in pixels. The bounding box will be expanded by this values.
SelectModeThe selection mode.
IndicesThe array of integer type with indices of the selected charts.
Returns:
True if at least one chart was selected and false otherwise.
string Charts.Serialize ( )

Serializes the state of the charts to the string.

Returns:
The serialized string.

Property Documentation

bool Charts.AvoidCollisions [get, set]

Gets or set a boolen value which indicates whether charts can overlap each other.

Setting this property to true will prevent the drawing of overlapping charts and hence some charts can be left undrawn. The default value is true.

int Charts.BarHeight [get, set]

Gets or sets the maximum height of the bar chart in pixels.

The value set will be used to display the maximum value of the field. The bar height for smaller values will be proportionally smaller.

Examples:
IntersectionLength.cs.
int Charts.BarWidth [get, set]

Gets or sets the width of a single bar of the chart in pixels.

string Charts.Caption [get, set]

Gets or sets the text string for description of the chart data.

It can be used for clarification of the map's legend.

Gets or sets the type of the charts.

Bar and pie charts are available. All charts of the shapefile are of the same type.

Examples:
IntersectionLength.cs, and Segmentation.cs.
int Charts.CollisionBuffer [get, set]

Gets or sets the minimal distance between individual charts when Charts.AvoidCollisions is set to true.

This allows to arrange charts in more sparse pattern to make them more readable. Naturally the larger this distance is, the smaller is the number of charts which can be drawn on screen simutaneously.

int Charts.Count [get]

Returns the number of charts which is equal to the number of shapes in the parent shapefile.

bool Charts.DynamicVisibility [get, set]

Gets or sets a value which indicates whether charts will be visible for all scales or in the given range of scales only.

See also:
Charts.MaxVisibleScale, Charts.MinVisibleScale

Gets or sets a callback object to display progress and error information.

int Charts.IconHeight [get]

Gets the minimal height of the image to display a single chart.

The property can be used for interctive selection of charts and for drawing of legend.

int Charts.IconWidth [get]

Gets the minimal width of the image to display a single chart.

The property can be used for interctive selection of charts and for drawing of legend.

string Charts.Key [get, set]

Gets or sets a string value associated with the object.

Gets the code of the last error which took place inside the current instance of the class.

The use of this property will clear the error until the next error occurs.

uint Charts.LineColor [get, set]

Gets or sets the color of the chart outline.

double Charts.MaxVisibleScale [get, set]

Get or sets the maximum scale the charts are displayed when dynamic visibility is turned on.

double Charts.MinVisibleScale [get, set]

Gets or sets the minimal scale the charts are displayed when dynamic visibility is turned on.

int Charts.NormalizationField [get, set]

Gets or sets the index of field upon which the values of other fields will be divided before displaying charts.

It can be used to display the data in percents for bar charts. For example, if a chart displays groups of population for a cities, then normalization field can be the total population of the cities, so that percentages between different towns can be compared on the same scale.

int Charts.NumFields [get]

Gets the number of fields which correspond to the bars of sectors depending on chart type.

int Charts.OffsetX [get, set]

Gets or sets the horizontal offset for drawing charts.

Positive values will move charts to the right. This value affects all the charts. Use Chart.PositionX to move individual charts.

int Charts.OffsetY [get, set]

Gets or set the vertical offset for drawing charts.

Positive values will move charts up. This value affects all the charts. Use Chart.PositionY to move individual charts.

int Charts.PieRadius [get, set]

Gets or sets the radius of the pie chart in pixels.

Examples:
Segmentation.cs.
int Charts.PieRadius2 [get, set]

Gets or sets the radius of the largest chart when Charts.UseVariableRadius is turned on.

double Charts.PieRotation [get, set]

Gets or set the rotation of the pie chart.

This property is no implemented.

Gets or sets the mode for serialization of charts. Affects Charts.SaveToXML method.

int Charts.SizeField [get, set]

Gets or sets the index of field which affect the radius of charts when Charts.UseVariableRadius is set to true.

In most cases this field doesn't included in the chart itself.

double Charts.Thickness [get, set]

Gets or sets the value which affects 3D display of the charts.

This value corresponds to the "height" for pie charts and "depth" for bar charts.

See also:
Charts.Use3DMode.
Examples:
Segmentation.cs.
double Charts.Tilt [get, set]

Gets or sets the tilt of the charts when 3D display is on.

See also:
Charts.Use3DMode.
short Charts.Transparency [get, set]

Gets or set the transparency of charts (0-255).

The values range from 0(tranparent) to 255(opaque). The data labels aren't affected by this value.

bool Charts.Use3DMode [get, set]

Gets or sets a boolean value which indicates whether 3D mode will be used for charts drawing.

bool Charts.UseVariableRadius [get, set]

Gets or sets the value which indicates whether all pie charts will have the same or varying radius.

When set to true, the radius of the individual charts will depend upon the value in Charts.SizeField.

bool Charts.ValuesFontBold [get, set]

Gets or sets the value which indicates whether data labels for charts will be bold.

uint Charts.ValuesFontColor [get, set]

Gets or sets the color of the chart's data labels.

bool Charts.ValuesFontItalic [get, set]

Gets or sets the value which indicates whether data labels for charts will be italic.

string Charts.ValuesFontName [get, set]

Gets or sets the font name for data labels of charts. The names of font families like "Arial" can be used.

int Charts.ValuesFontSize [get, set]

Gets or set the size of chart's labels.

uint Charts.ValuesFrameColor [get, set]

Gets or sets the color of the frame for chart labels.

bool Charts.ValuesFrameVisible [get, set]

Gets or sets a boolean value which indicates whether the frame of chart's labels is visible.

Gets or sets the style of the chart's labels.

bool Charts.ValuesVisible [get, set]

Gets or sets the value which indicates whether labels with values of the fields will be drawn near each chart.

Examples:
IntersectionLength.cs, and Segmentation.cs.

Gets or sets the position of charts in the map drawing order.

string Charts.VisibilityExpression [get, set]

Gets or sets the expression which defines the subset of charts which will be displayed on the map.

bool Charts.Visible [get, set]

Turns on or off the visibility of charts.

Examples:
IntersectionLength.cs, and Segmentation.cs.
 All Classes Files Functions Enumerations Properties