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.

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;
     

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:

Field

A 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:

FieldIndex	The index of the field in the attribute table to take values from.
Color	The 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.

void Charts.ClearFields

(

)

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:

newVal

Serialized 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:

hdc	The handle of the device context.
x	The position of the left corner of the drawing in pixels.
y	The position of the top corner of the drawing in pixels.
hideLabels	When set to true the labels won't be drawn.
BackColor	The 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.

bool Charts.Generate

(

tkLabelPositioning

Type

)

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:

Type	The 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:

Chart

The 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:

ErrorCode

The 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:

FieldIndex

The 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:

Index	The index to insert the field at.
Field	The 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:

Index	The index to insert the field at.
FieldIndex	The index of the field from the attribute table (.dbf) to take values from.
Color	The 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:

Filename

The 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:

OldIndex	The old index of the field.
NewIndex	The 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:

Index

The 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:

Filename

The 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:

BoundingBox	The rectangle to select charts within (in screen coordinates).
Tolerance	The tolerance in pixels. The bounding box will be expanded by this values.
SelectMode	The selection mode.
Indices	The 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.

tkChartType Charts.ChartType [get, set]

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

ICallback Charts.GlobalCallback [get, set]

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.

int Charts.LastErrorCode [get]

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.

tkSavingMode Charts.SavingMode [get, set]

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.

tkChartValuesStyle Charts.ValuesStyle [get, set]

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.

tkVerticalPosition Charts.VerticalPosition [get, set]

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.