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

Collaboration diagram for Charts:

Public Member Functions
bool	AddField (ChartField Field)
	Adds a field to the chart. More...

void	AddField2 (int FieldIndex, uint Color)
	Adds a field to the chart. More...

void	Clear ()
	Clears the information about individual charts like position and visibility. More...

void	ClearFields ()
	Removes all fields which define bars or sectors of the chart. More...

void	Deserialize (string newVal)
	Restores the state of the charts from the serialized string. More...

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. More...

bool	Generate (tkLabelPositioning Type)
	Generates a chart for every shape of the parent shapefile. More...

Chart	get_Chart (int Chart)
	Gets a reference to the chart with the specified index. More...

string	get_ErrorMsg (int ErrorCode)
	Gets the description of the specified error code. More...

ChartField	get_Field (int FieldIndex)
	Gets a reference to the field of the chart with the specified index. More...

bool	InsertField (int Index, ChartField Field)
	Inserts a field which represents single bar or sector of the chart. More...

bool	InsertField2 (int Index, int FieldIndex, uint Color)
	Inserts a field which represents single bar or sector of the chart. More...

bool	LoadFromXML (string Filename)
	Loads charts data from the XML file generated by Charts.SaveToXML. More...

bool	MoveField (int OldIndex, int NewIndex)
	Changes the position of a field (bar or sector) in the list which affects the order of drawing. More...

bool	RemoveField (int Index)
	Removes the field which corresponds to the bar or the sector of the chart. More...

bool	SaveToXML (string Filename)
	Saves the state of the charts to the XML file. More...

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. More...

string	Serialize ()
	Serializes the state of the charts to the string. More...

Properties
bool	AvoidCollisions `[get, set]`
	Gets or set a boolean value which indicates whether charts can overlap each other. More...

int	BarHeight `[get, set]`
	Gets or sets the maximum height of the bar chart in pixels. More...

int	BarWidth `[get, set]`
	Gets or sets the width of a single bar of the chart in pixels. More...

string	Caption `[get, set]`
	Gets or sets the text string for description of the chart data. More...

tkChartType	ChartType `[get, set]`
	Gets or sets the type of the charts. More...

int	CollisionBuffer `[get, set]`
	Gets or sets the minimal distance between individual charts when Charts.AvoidCollisions is set to true. More...

int	Count `[get]`
	Returns the number of charts which is equal to the number of shapes in the parent shapefile. More...

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. More...

ICallback	GlobalCallback `[get, set]`
	Gets or sets a callback object to display progress and error information. More...

int	IconHeight `[get]`
	Gets the minimal height of the image to display a single chart. More...

int	IconWidth `[get]`
	Gets the minimal width of the image to display a single chart. More...

string	Key `[get, set]`
	Gets or sets a string value associated with the object. More...

int	LastErrorCode `[get]`
	Gets the code of the last error which took place inside the current instance of the class. More...

uint	LineColor `[get, set]`
	Gets or sets the color of the chart outline More...

double	MaxVisibleScale `[get, set]`
	Get or sets the maximum scale the charts are displayed when dynamic visibility is turned on. More...

double	MinVisibleScale `[get, set]`
	Gets or sets the minimal scale the charts are displayed when dynamic visibility is turned on. More...

int	NormalizationField `[get, set]`
	Gets or sets the index of field upon which the values of other fields will be divided before displaying charts. More...

int	NumFields `[get]`
	Gets the number of fields which correspond to the bars of sectors depending on chart type. More...

int	OffsetX `[get, set]`
	Gets or sets the horizontal offset for drawing charts. More...

int	OffsetY `[get, set]`
	Gets or set the vertical offset for drawing charts. More...

int	PieRadius `[get, set]`
	Gets or sets the radius of the pie chart in pixels. More...

int	PieRadius2 `[get, set]`
	Gets or sets the radius of the largest chart when Charts.UseVariableRadius is turned on. More...

double	PieRotation `[get, set]`
	Gets or set the rotation of the pie chart. More...

tkSavingMode	SavingMode `[get, set]`
	Gets or sets the mode for serialization of charts. Affects Charts.SaveToXML method. More...

int	SizeField `[get, set]`
	Gets or sets the index of field which affect the radius of charts when Charts.UseVariableRadius is set to true. More...

double	Thickness `[get, set]`
	Gets or sets the value which affects 3D display of the charts. More...

double	Tilt `[get, set]`
	Gets or sets the tilt of the charts when 3D display is on. More...

short	Transparency `[get, set]`
	Gets or set the transparency of charts (0-255). More...

bool	Use3DMode `[get, set]`
	Gets or sets a boolean value which indicates whether 3D mode will be used for charts drawing. More...

bool	UseVariableRadius `[get, set]`
	Gets or sets the value which indicates whether all pie charts will have the same or varying radius. More...

bool	ValuesFontBold `[get, set]`
	Gets or sets the value which indicates whether data labels for charts will be bold. More...

uint	ValuesFontColor `[get, set]`
	Gets or sets the colour of the chart's data labels. More...

bool	ValuesFontItalic `[get, set]`
	Gets or sets the value which indicates whether data labels for charts will be italic. More...

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. More...

int	ValuesFontSize `[get, set]`
	Gets or set the size of chart's labels. More...

uint	ValuesFrameColor `[get, set]`
	Gets or sets the colour of the frame for chart labels. More...

bool	ValuesFrameVisible `[get, set]`
	Gets or sets a boolean value which indicates whether the frame of chart's labels is visible. More...

tkChartValuesStyle	ValuesStyle `[get, set]`
	Gets or sets the style of the chart's labels. More...

bool	ValuesVisible `[get, set]`
	Gets or sets the value which indicates whether labels with values of the fields will be drawn near each chart. More...

tkVerticalPosition	VerticalPosition `[get, set]`
	Gets or sets the position of charts in the map drawing order. More...

string	VisibilityExpression `[get, set]`
	Gets or sets the expression which defines the subset of charts which will be displayed on the map. More...

bool	Visible `[get, set]`
	Turns on or off the visibility of charts. More...

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:

Pie charts:
- are suitable when it's necessary to display the parts of the whole phenomenon, 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;
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:

To specify a set of fields which will be included (see Charts.AddField and Charts.AddField2).
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).
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 colour 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, colour
    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 possible to change their properties like visibility or position. Chart.ScreenExtents property return screen coordinates occupied by particular chart which provides a convenient way for highlighting 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 independently 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

◆ AddField()

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.

◆ AddField2()

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 colour of the sector or bar for visualization of a field.

Examples: Segmentation.cs.

◆ Clear()

void Charts.Clear ( )

Clears the information 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.

◆ ClearFields()

void Charts.ClearFields ( )

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

◆ Deserialize()

void Charts.Deserialize ( string newVal )

Restores the state of the charts from the serialized string.

Parameters

newVal Serialized string generated by Charts.Serialize().

◆ DrawChart()

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 colour of the device context. Should be provided to ensure correct alpha blending when transparency is set.

Returns: True on success and false otherwise.

◆ Generate()

bool Charts.Generate ( tkLabelPositioning Type )

Generates a chart for every shape of the parent shapefile.

This method is time consuming for large shapefiles, therefore 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.

◆ get_Chart()

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.

◆ get_ErrorMsg()

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.

◆ get_Field()

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.

◆ InsertField()

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.

◆ InsertField2()

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 colour of the fill.

Returns: True on success and false otherwise.

◆ LoadFromXML()

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.

◆ MoveField()

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

◆ RemoveField()

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.

◆ SaveToXML()

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.

◆ Select()

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.

◆ Serialize()

string Charts.Serialize ( )

Serializes the state of the charts to the string.

Returns: The serialized string.

Property Documentation

◆ AvoidCollisions

bool Charts.AvoidCollisions

getset

Gets or set a boolean 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.

◆ BarHeight

int Charts.BarHeight

getset

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.

◆ BarWidth

int Charts.BarWidth

getset

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

◆ Caption

string Charts.Caption

getset

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

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

◆ ChartType

tkChartType Charts.ChartType

getset

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.

◆ CollisionBuffer

int Charts.CollisionBuffer

getset

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 simultaneously.

◆ Count

int Charts.Count

get

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

◆ DynamicVisibility

bool Charts.DynamicVisibility

getset

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

◆ GlobalCallback

ICallback Charts.GlobalCallback

getset

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

Deprecated:: v4.9.3 Use GlobalSettings.ApplicationCallback instead.

◆ IconHeight

int Charts.IconHeight

get

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

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

◆ IconWidth

int Charts.IconWidth

get

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

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

◆ Key

string Charts.Key

getset

Gets or sets a string value associated with the object.

◆ LastErrorCode

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.

◆ LineColor

uint Charts.LineColor

getset

Gets or sets the color of the chart outline

◆ MaxVisibleScale

double Charts.MaxVisibleScale

getset

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

◆ MinVisibleScale

double Charts.MinVisibleScale

getset

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

◆ NormalizationField

int Charts.NormalizationField

getset

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 percentage 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.

◆ NumFields

int Charts.NumFields

get

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

◆ OffsetX

int Charts.OffsetX

getset

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.

◆ OffsetY

int Charts.OffsetY

getset

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.

◆ PieRadius

int Charts.PieRadius

getset

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

Examples: Segmentation.cs.

◆ PieRadius2

int Charts.PieRadius2

getset

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

◆ PieRotation

double Charts.PieRotation

getset

Gets or set the rotation of the pie chart.

This property is no implemented.

◆ SavingMode

tkSavingMode Charts.SavingMode

getset

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

◆ SizeField

int Charts.SizeField

getset

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.

◆ Thickness

double Charts.Thickness

getset

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.

◆ Tilt

double Charts.Tilt

getset

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

See also: Charts.Use3DMode.

◆ Transparency

short Charts.Transparency

getset

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

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

◆ Use3DMode

bool Charts.Use3DMode

getset

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

◆ UseVariableRadius

bool Charts.UseVariableRadius

getset

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.

◆ ValuesFontBold

bool Charts.ValuesFontBold

getset

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

◆ ValuesFontColor

uint Charts.ValuesFontColor

getset

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

◆ ValuesFontItalic

bool Charts.ValuesFontItalic

getset

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

◆ ValuesFontName

string Charts.ValuesFontName

getset

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

◆ ValuesFontSize

int Charts.ValuesFontSize

getset

Gets or set the size of chart's labels.

◆ ValuesFrameColor

uint Charts.ValuesFrameColor

getset

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

◆ ValuesFrameVisible

bool Charts.ValuesFrameVisible

getset

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

◆ ValuesStyle

tkChartValuesStyle Charts.ValuesStyle

getset

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

◆ ValuesVisible

bool Charts.ValuesVisible

getset

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.

◆ VerticalPosition

tkVerticalPosition Charts.VerticalPosition

getset

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

◆ VisibilityExpression

string Charts.VisibilityExpression

getset

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

◆ Visible

bool Charts.Visible

getset

Turns on or off the visibility of charts.

Examples: IntersectionLength.cs, and Segmentation.cs.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ AddField()

◆ AddField2()

◆ Clear()

◆ ClearFields()

◆ Deserialize()

◆ DrawChart()

◆ Generate()

◆ get_Chart()

◆ get_ErrorMsg()

◆ get_Field()

◆ InsertField()

◆ InsertField2()

◆ LoadFromXML()

◆ MoveField()

◆ RemoveField()

◆ SaveToXML()

◆ Select()

◆ Serialize()

Property Documentation

◆ AvoidCollisions

◆ BarHeight

◆ BarWidth

◆ Caption

◆ ChartType

◆ CollisionBuffer

◆ Count

◆ DynamicVisibility

◆ GlobalCallback

◆ IconHeight

◆ IconWidth

◆ Key

◆ LastErrorCode

◆ LineColor

◆ MaxVisibleScale

◆ MinVisibleScale

◆ NormalizationField

◆ NumFields

◆ OffsetX

◆ OffsetY

◆ PieRadius

◆ PieRadius2

◆ PieRotation

◆ SavingMode

◆ SizeField

◆ Thickness

◆ Tilt

◆ Transparency

◆ Use3DMode

◆ UseVariableRadius

◆ ValuesFontBold

◆ ValuesFontColor

◆ ValuesFontItalic

◆ ValuesFontName

◆ ValuesFontSize

◆ ValuesFrameColor

◆ ValuesFrameVisible

◆ ValuesStyle

◆ ValuesVisible

◆ VerticalPosition

◆ VisibilityExpression

◆ Visible