<< Click here to display Table of Contents >> Navigation: Code Documentation > RSCharting > RSChartPanel > Classes:

TRSChartValue Class

Contents

Defines one point/pie/bar/etc in a chart. A chart is made up of a collection of values ( RSChartPanel.TRSChartValues), where each TRSChartValue descendant defines the information for one point, one pie slice, one shape, etc for the chart. The TRSChartValue class defines the base value class and common properties to all values, including Caption, Color , and Values.

Tip

To copy one value to another:

•	Create the new value, either by using the class constructor or the Add method of the collection

•	Use the Assign method to copy properties from the old value to the newly created value. Note, that all TRSChartValue descendants can be assigned to each other. The assign method will only copy methods that are shared by the values.

Notes to Inheritors

The following steps will describe what and why you need to do to create a descendant class. However, please see the source code in the RSCharts unit for specific examples.

•

First, you need to decide how many dimensions you need for your descendant class. The TRSChartValue class provides access to the X, Y, and Z dimension for a value (The RSCharts|TRS2DChartValue class exposes the Y dimension. Likewise, the RSCharts|TRS3DChartValue class exposes the Z dimension). To provide automatic support of these dimensions, the TRSChartValue class stores all three dimensions in the Values property, which provides access to protected array field ( RSChartConsts|TRSChartValueTypeArray ). Descendant classes can redefine the size of this protected array field to hold any other RSChartConsts|TRSChartValueType (double) properties.

•	Add any other properties you need

•	Override the Assign method to copy the properties (you don't need to do it for the Values property.

•	Override the RSChartPanel.TRSChartValues collection

•	Finally, create your descendant chart class and override the protected CreateChartValues method to create your new value collection class.

Namespace: RSChartPanel

TGCollectionItem
RSChartPanel.TRSChartValue
RSBarCharts.TRSBarChartValue
RSCharts.TRS2DChartValue
RSCharts.TRSPieChartValue

Delphi

type
TRSChartValue = class(TGCollectionItem)
end;

	Name	Description
	Create(TCollection)	Initializes a new instance of the TRSChartValue class.

Top

Name

Description

AsDateTime

Provides access to the Value property as a TDateTime value.

Notes to Inheritors
Usually this property provides access to the first dimension (X) of the value array. However, descendant classes can change which dimension this property accesses.

AsDateTimes[Integer]

Represents property AsDateTimes[Integer].

Caption

Provides a caption or description of the chart value. This value will only be drawn if coLabelEachPoint is in the chart's Options property.

Collection

Specifies the RSChartPanel.TRSChartValues instance to which this Item belongs. Each TRSChartValue belongs to the TRSChartValues collection which creates it. The Collection property points to the collection object to which the value belongs.

Color

Specifies the color of this individual value, e.g., the color of the bar or the point or the shape. When coColorEachPoint is in the RSChartPanel.TRSCustomChart.Options property, this color is drawn by the chart. When coColorEachPoint is not in the the Options property, the Color of the chart is used.

Opacity

Specifies the opacity of the value when drawn. The opacity is a value between 0 (invisible) and 1 (fully opaque). Any value in-between controls the transparency of the value.

Important Note
This is an FMX only feature. Any value > 0 is drawn fully opaque in the VCL version

Options

Represents property Options.

Scale

Specifies the scale factor for the value. A scale factor of 1 (default) draws the value at its normal size within the chart. Change the scale factor to shrink or grow the value within the chart (for drawing purposes only)

Selected

Determines whether the chart value is selected. Use the Selected property to select or deselect a chart value. Selected chart values are displayed with the SelectionColor of the chart panel.

Tag

Provides user-defined storage that is associated with the value

Value

Returns the main (or only) dimension in a chart value - which dimension is returned is based on the chart type. A chart value, depending on the chart type, can contain 1 or more dimensional values that define the chart value.

For example, each chart value in a bar chart contains 1 value (defining the height of the bar), line chart values contains 2 dimensions: X and Y, and shape chart values contain 4 dimensions: X, Y, Width, and Height. The ValueCount property returns the number of dimensions in the chart value. Use the Values property to access each dimension in the chart value (Note that TRSChartValue descendant classes expose properties, such as X and Y, which are safer to access the specific dimension of the value. You should not count on a specific dimension index to contain a specific property).

Notes to Inheritors
To change which dimension is returned by this Value, override the GetDefValue and SetDefValue methods

ValueCount

Returns the number of dimensions in the chart value. A chart value, depending on the chart type, can contain 1 or more dimensional values that define the chart value.

Use the Values property to access each dimension in the chart value. The Value property in comparison returns the main (or only) dimension in a chart value - which dimension is returned is based on the chart type.

Caution
Note that TRSChartValue descendant classes expose properties, such as X and Y, which are safer to access the specific dimension of the value. You should not count on a specific dimension index to contain a specific property

Values[Integer]

Returns the value for the dimension in the chart value. A chart value, depending on the chart type, can contain 1 or more dimensional values that define the chart value.

Caution
Note that TRSChartValue descendant classes expose properties, such as X and Y, which are safer to access the specific dimension of the value. You should not count on a specific dimension index to contain a specific property

The ValueCount will equal the DimensionCount of the collection.

Visible

Determines whether the chart value is visible or not. Use the Visible property to change the visibility of the chart value. Even if the Visible property is True, the chart value may still not be visible if the chart axis is zoomed.

Provide access to the first dimension of the Values property. The X, Y, and Z properties provide access to the first three dimensions of the Values property.

Use the X, Y, and Z property to access the coordinates of a point.

Notes to Inheritors

These properties have protected visibility in the class, but descendant classes (e.g., RSCharts|TRS2DChartValue and TRS3DChartvalue ) publish the properties to provide more explanatory access to the dimensions of the Values property.

Remember to also publish the XAsDateTime, YAsDateTime, and ZAsDateTime properties

XAsDateTime

Provide access to the first dimension of the Values property. The X, Y, and Z properties provide access to the first three dimensions of the Values property.

Use the X, Y, and Z property to access the coordinates of a point.

Notes to Inheritors

Remember to also publish the XAsDateTime, YAsDateTime, and ZAsDateTime properties

Provide access to the second dimension of the Values property. The X, Y, and Z properties provide access to the first three dimensions of the Values property.

Use the X, Y, and Z property to access the coordinates of a point.

Notes to Inheritors

Remember to also publish the XAsDateTime, YAsDateTime, and ZAsDateTime properties

YAsDateTime

Provide access to the second dimension of the Values property. The X, Y, and Z properties provide access to the first three dimensions of the Values property.

Use the X, Y, and Z property to access the coordinates of a point.

Notes to Inheritors

Remember to also publish the XAsDateTime, YAsDateTime, and ZAsDateTime properties

Provide access to the third dimension of the Values property formatted as a TDateTime. The XAsDateTime, YAsDateTime, and ZAsDateTime properties provide access to the first three dimensions of the Values property formatted as a TDateTime

Notes to Inheritors

Remember to also publish the X, Y, and Z properties

ZAsDateTime

Provide access to the third dimension of the Values property. The X, Y, and Z properties provide access to the first three dimensions of the Values property.

Use the X, Y, and Z property to access the coordinates of a point.

Notes to Inheritors

Remember to also publish the XAsDateTime, YAsDateTime, and ZAsDateTime properties

Top

	Name	Description
	Assign(TPersistent)	Represents method Assign(TPersistent).
	GetAsDateTime(Integer)	Represents method GetAsDateTime(Integer).
	GetDefValue	Returns the "default" value for the chart, e.g., Y for 2D charts. This method is called by the Value property. The GetDefValue and SetDefValue methods use the RSChartPanel.TRSChartValues.DefaultDimension to figure out which Values dimension to read and write.
	GetDisplayName	Represents method GetDisplayName.
	GetIntValue(Integer)	Represents method GetIntValue(Integer).
	GetValue(Integer)	Represents method GetValue(Integer).
	Loaded	Represents method Loaded.
	Selectable(TRSRect,TRSChartSelectionAction)	Overloaded. Returns true if the value is within the selection rectangle. Descendant classes override this method to signal whether the value is selected or not.
	Selectable(TRSRect,TRSRect,TRSChartSelectionAction)	Overloaded. Returns True if the Value should be selected. This depends on the Selected state and if the value rectangle intersects with the selection rectangle.
	SelectionChanged	Represents method SelectionChanged.
	SetAsDateTime(Integer,TDateTime)	Represents method SetAsDateTime(Integer,TDateTime).
	SetColor(TCanvasColor)	Represents method SetColor(TCanvasColor).
	SetDefValue(TRSChartValueType)	Sets the "default" value for the chart, e.g., X for 2D charts. This method is called by the Value property. Change the GetDefValue and SetDefValue methods for TRSChartValue descendants that don't have their default dimension as 0.
	SetIntValue(Integer,Integer)	Represents method SetIntValue(Integer,Integer).
	SetValue(Integer,TRSChartValueType)	Represents method SetValue(Integer,TRSChartValueType).
	ValueChanged(Integer)	Represents method ValueChanged(Integer).
	ValuesToString(String,Boolean)	Returns a comma-delimited string of the floating-point values of the Value. The Fmt property specifies how to format the floating-point values (see FormatFloat function from Delphi's help). The Parentheses property controls if parentheses are put around the comma-delimited string.
	VisibleChanged	Represents method VisibleChanged.

Top

	Name	Description
	FValues	Represents field FValues.

Top

Usually, you do not instantiate a TRSChartValue class directly. Use the methods of the TRSChartValues collection (or a descendant).

The following code adds 3 donut slices to the chart:

Delphi

var
   Value: TRSDonutChartExValue;  // note, this type should be the same that the chart uses (e.g., TRS2DChartValue, TRSArrowChartValue, etc)
begin
   // Add first point as a full circle outer ring
   Value := RSDonutChart1.Values.Add;
   Value.Color := clRed;
   Value.StartAngle := 0.0;
   Value.SweepAngle := 360;
   // Add second point, inside the first
   Value := RSDonutChart1.Values.Add;
   Value.Color := clGreen;
   Value.StartAngle := 10.0; // 10-40 degrees
   Value.SweepAngle := 30;
   Value.InnerRadius := 0.50
   Value.OuterRadius := 0.75
   // Add third point, twice as large as second
   Value := RSDonutChart1.Values.Add;
   Value.Color := clNavy;
   Value.StartAngle := 90.0; // 90-270
   Value.SweepAngle := 180;
   Value.InnerRadius := 0.50
   Value.OuterRadius := 0.75

   // Draw the donut slices starting at 12:00 and go counter-clockwise
   RSDonutChart1.Offset := 90;
end;

Reference

•	RSChartPanel.TRSChartValues

•	RSChartPanel.TRSCustomChart

•	RSChartPanel

Comments (0)