The TRSCustomChart component is the base class for all chart types in the RiverSoftAVG Charting Component Suite. The TRSCustomChart component provides the common properties and methods for a chart type, including the
HorizontalAxis and
VerticalAxis to use for the chart,
Caption and Font , and most importantly, the
Values property.
The Values property is the most important property of a chart type and allows you to define the chart values at design-time or run-time. It provides all the information about an individual chart point, not only position but also Caption, Visibility, and Selected. Each chart type uses the RSChartPanel.TRSChartValues class appropriate to their chart type, e.g., a bar chart has a 1D value type, line charts have 2D value types, and shape charts use 2D value types with shape/image information.
 Note
|
Charts are TGraphicControl descendants for VCL and TControl descendants for FMX. Display charts on a chart panel (with integrated axes, legend, header, footers, etc) or stand-alone (allowing use of FMX effects or embedding within other controls). Set the Panel property to the RSChartPanel.TRSChartPanel you want the chart displayed inside or nil for stand-alone use.
|
Namespace: RSChartPanel
Delphi
|
type
TRSCustomChart = class(TGraphicControl)
end;
|
|
Name
|
Description
|
|
AxesHints
|
|
|
Brush
|
The Brush property, along with the Pen property, controls how the chart draws to the canvas. By changing the Brush's or Pen's values, you can change the appearance of the chart.
For example, by changing the Brush.Style property, you can change the pattern used to fill areas with a RSCharts|TRSAreaChart or pie slices with the RSCharts|TRSPieChart. Depending on the type of chart, the Brush property also controls the Color of the chart (e.g., for pie charts, setting the Color property or the Brush.Color property is equivalent.
Note
|
Some chart types use Brush and Pen values from the TRSChartValue descendant class itself. In which case, these properties are ignored.
|
|
|
Caption
|
Provides a string for describing or identifying the chart. The RSChartPanel.TRSChartPanel component will display the Caption in its Legend depending on LegendStyle and if the coShowInLegend is in the chart Options.
|
|
Color
|
Specifies what color the chart uses for its appearance. Depending on the chart type, the Color property will change the color of the Brush or of the Pen that the chart draws with.
For example, for a TRSAreaChart, the Color property changes the Brush color, which is used to fill the areas in the chart. For the TRSLineChart, the Color property changes the Pen Color, which is used to draw the lines in the chart. Note that if coColorEachPoint is in the Options property, the chart will use each individual TRSChartValue's Color property instead.
|
|
ColorList
|
Defines the color list to use when new chart values are created. When a chart value is created and a color is not specified, the object will get a new color based on the next color in the list. If the list is at the end, the new color will be the first color in the list.
Set the ColorList property directly to define your own custom color scheme. Set the ColorScheme property to use one of the predefined color lists.
Note
|
The new color list will be applied to the existing chart values.
|
|
|
ColorScheme
|
Defines the color scheme to use when new chart values are created. When a chart value is created and a color is not specified, the object will get a new color based on the next color in the color scheme.
Setting the ColorScheme property sets the RSChartPanel.TRSCustomChart.ColorList property. Set the ColorList property directly to define your own custom color scheme.
Note
|
The new color scheme will be applied to the existing chart values.
|
|
|
Cursor
|
Specifies the Cursor to display when the mouse is over the chart
|
|
FirstIndex
|
The FirstIndex and the LastIndex properties define the indices of the Values that are currently being drawn in the chart.
Usually, these properties are equivalent to 0 for the FirstIndex and Values.Count-1 for the LastIndex. However, when the TRSChartPanel component has been zoomed, these properties reflect the point just before the first point in the zoomed area and the point just after the last point in the zoomed area (this ensures the visual aspect of the chart by allowing, for example, lines to be drawn into and out of the zoomed area. The FirstIndex and LastIndex properties provide more efficient access to only the values that are currently being drawn.
Note
|
For charts that don't have an easy visual ordering (such as a shape chart where depending on sizes things can overlap), the FirstIndex and LastIndex will be the entire Values collection.
|
|
|
Font
|
Specifies the font used to draw each value's Caption. Captions are drawn if coLabelEachPoint is in the Options property. Set Font to specify the font to use for writing text in the chart.
 Tip
|
To change the font color in FMX, set the FontFill property
|
|
|
Group
|
Specifies the group that the chart belongs to. All charts with the same Group, use the GroupStyle property to work together. For example, bar charts can be stacked.
|
|
GroupIndex
|
Use the GroupIndex property to specify the ordering of the charts in a group at design time
|
|
GroupStyle
|
Defines the way that charts of the same Group are grouped visually.
|
|
HorizAxis
|
Specifies what type of HorizontalAxis the chart is bound to.
|
|
HorizontalAxis
|
Specifies the RSChartPanel.TRSChartAxis object that the chart is bound to for the horizontal (X) axis. This axis controls the range of values that will be drawn for the chart. The chart uses this axis to convert its internal Values into pixel values and vice versa.
You should never directly convert the chart's values to canvas coordinates, use the chart's HorizontalAxis and VerticalAxis to call the AxisToPixel method. A chart's values are consistent with the chart only and have nothing to do with the canvas. These values specify chart graphical elements in floating point format and ignore any visual issues, such as is the chart zoomed. Every chart is bound to a horizontal axis (top or bottom) and vertical axis (left or right) of the chart panel. The axes are responsible for tracking if the view is zoomed, what are the min and max values etc. Call the AxisToPixel method to convert your chart value into the correct canvas value.
|
|
LastIndex
|
The FirstIndex and the LastIndex properties define the indices of the Values that are currently being drawn in the chart.
Usually, these properties are equivalent to 0 for the FirstIndex and Values.Count-1 for the LastIndex. However, when the TRSChartPanel component has been zoomed, these properties reflect the point just before the first point in the zoomed area and the point just after the last point in the zoomed area (this ensures the visual aspect of the chart by allowing, for example, lines to be drawn into and out of the zoomed area. The FirstIndex and LastIndex properties provide more efficient access to only the values that are currently being drawn.
Note
|
For charts that don't have an easy visual ordering (such as a shape chart where depending on sizes things can overlap), the FirstIndex and LastIndex will be the entire Values collection.
|
|
|
Listeners
|
Tracks the RSChartPanel.IChartPanelListeners which are listening for changes to this chart. The TRSCustomChart class uses this list to automatically notify listeners when the chart or its values change.
Add a class to this list in order for it to receive change events from the chart.
|
|
LocalHorizontalAxis
|
Represents property LocalHorizontalAxis.
|
|
LocalVerticalAxis
|
Represents property LocalVerticalAxis.
|
|
OffsetVertical
|
Specifies how far above the origin of the axis (in chart units) the chart should start drawing.
|
|
OnChange
|
Occurs when the chart changes. Write an OnChange event handler to respond to when the chart (or any its Values) change.
|
|
OnVisibleChange
|
Occurs when the chart visibility changes. Write an OnVisibleChange event handler to respond to when the chart is shown or hidden
|
|
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
|
Controls the chart's appearance as well as behavior. See RSChartConsts|TChartOption for more information.
|
|
Panel
|
Specifies the Panel to draw the chart on. Set Panel to a TRSCustomChartPanel instance to draw the chart on the panel. The Parent of the chart will be automatically set to the panel.
Set Panel to nil to draw the chart by itself.
Tip
|
Drawing a chart on a chart panel allows more control displaying the chart, including zooming, legends, axes, etc. However, drawing a chart by itself is also useful and you can apply effects in FMX, such as TShadowEffect, for visual pizazz.
|
|
|
PanelColorScheme
|
Specifies which color scheme to use when new chart values are created with default color values. If Panel is not nil and this property is True, then the chart panel's ChartColorScheme is used. Otherwise, the ColorScheme is used
|
|
ParentFont
|
Determines where a chart looks for its font information. To have the chart use the same font as its Panel panel, set ParentFont to true. If ParentFont is false, the chart uses its own Font property. The charts by default set ParentFont to true so that all the charts on a chart panel present a uniform appearance. When the value of a chart's Font property changes, ParentFont becomes false automatically.
|
|
ParentSelectionColor
|
Determines where a chart looks for its color information for selected values. To have the chart use the same SelectionColor as its Panel panel, set ParentSelectionColor to true. If ParentSelectionColor is false, the chart uses its own SelectionColor property. The charts by default set ParentSelectioinColor to true so that all the charts on a chart panel present a uniform appearance. When the value of SelectionColor property changes, ParentSelectionColor becomes false automatically.
|
|
Pen
|
The Brush property, along with the Pen property, controls how the chart draws to the canvas. By changing the Brush's or Pen's values, you can change the appearance of the chart.
For example, by changing the Pen.Width property, you can change the line sizes for drawing the lines in a RSCharts|TRSAreaChart or between pie slices in the RSCharts|TRSPieChart . Depending on the type of chart, the Pen property also controls the Color of the chart.
Note
|
Some chart types use Brush and Pen values from the TRSChartValue descendant class itself. In which case, these properties are ignored.
|
|
|
Preview
|
A design-time property that controls how the chart streams its Values. When Preview is True (the default), the Values are not streamed out when the chart is saved. When Preview is False, the Values will be saved into the form file and automatically loaded at run-time. Anytime you change a Value at design-time, this property will become False. Set this property to True if you don't want the Values saved.
|
|
SelectionColor
|
Specifies the color for a selected value ( RSChartPanel.TRSChartValue.Selected )
|
|
State
|
Represents property State.
|
|
ValueLabelFormat
|
Specifies the format string for displaying TRSChartValue.Values floating-point number as a string
This property is used when the ValueLabelStyle is ltsValue, ltsCaptionNValue, etc.
|
|
ValueLabelStyle
|
Defines the style of the chart's labels, e.g., whether the labels are numeric, Caption, or a combination.
Use the ValueLabelFormat property to control the format of labels when they are numeric.
|
|
Values
|
Defines the collection of all points or values in a chart. A chart is made up of a collection of values ( RSChartPanel.TRSChartValue ), 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. The RSChartPanel.TRSChartValues collection defines the base collection class and common properties to all collection of values, such as DimensionCount, MaxValues, and MinValues.
Note
|
Note that the TRSChartValues collection provides built-in support for limiting the number of values in the collection (using the Limit property).
|
|
|
VertAxis
|
Specifies what type of VerticalAxis the chart is bound to.
|
|
VerticalAxis
|
Specifies the RSChartPanel.TRSChartAxis object that the chart is bound to for the vertical (Y) axis. This axis controls the range of values that will be drawn for the chart. The chart uses this axis to convert its internal Values into pixel values and vice versa.
You should never directly convert the chart's values to canvas coordinates, use the chart's HorizontalAxis and VerticalAxis to call the AxisToPixel method. A chart's values are consistent with the chart only and have nothing to do with the canvas. These values specify chart graphical elements in floating point format and ignore any visual issues, such as is the chart zoomed. Every chart is bound to a horizontal axis (top or bottom) and vertical axis (left or right) of the chart panel. The axes are responsible for tracking if the view is zoomed, what are the min and max values etc. Call the AxisToPixel method to convert your chart value into the correct canvas value.
|
|
Visible
|
Specifies whether the component appears onscreen.
Use the Visible property to control the visibility of the control at run time. If Visible is True, the control appears. If Visible is False, the control is not visible
|
|
VisibleCount
|
Returns the number of TRSChartValue that are visible for the chart
|
Top
|
|
Name
|
Description
|
|
Assign(TPersistent)
|
Represents method Assign(TPersistent).
|
|
AxisChanged(TRSChartAxis)
|
Represents method AxisChanged(TRSChartAxis).
|
|
BeginUpdate
|
Suspends screen repainting of the chart. The BeginUpdate method suspends screen repainting and change events until the EndUpdate method is called. Use BeginUpdate to speed processing and avoid flicker while items are added to or deleted from a collection.
|
|
Changed
|
Overloaded. Represents method Changed.
|
|
Changed(TRSChartValue)
|
Overloaded. Represents method Changed(TRSChartValue).
|
|
Clone
|
Creates a "deep" copy of the chart. It constructs a new chart of the correct type and then calls the Assign method to copy its properties to the new copy.
Caution
|
Note that the new TRSCustomChart has the same owner as the current chart. If there is no owner, you are responsible for freeing the new clone.
|
|
|
CMHitTest(TCMHitTest)
|
Represents method CMHitTest(TCMHitTest).
|
|
CMVisibleChanged(TMessage)
|
Represents method CMVisibleChanged(TMessage).
|
|
CreateBrush
|
Represents method CreateBrush.
|
|
CreateChartValues
|
Creates the RSChartPanel.TRSChartValues class for the Values property
Notes to Inheritors
|
Override this method to create your TRSChartValues descendant
|
|
|
CreateFont
|
Represents method CreateFont.
|
|
CreatePen
|
Represents method CreatePen.
|
|
CreatePreviewValues
|
Creates sample values for illustrating how the chart will look. This function is automatically called at design-time to fill the chart with sample values. It can also be called at run-time to add more values to the chart (i.e., the chart is not cleared first)
Note
|
Set the Preview property to false to have the design-time sample values show up at run-time
|
|
|
DoUpdateAxisInfo(TRSChartAxis)
|
Represents method DoUpdateAxisInfo(TRSChartAxis).
|
|
Draw(TCanvas,TCanvasRect)
|
Overloaded. Paints the chart to the specified Canvas in the specified location. The Draw method first calls the OnDrawing event, which signals that it is about to draw and allows users to stop the drawing before it occurs. Then, it calls the protected InternalDraw method to actually do the drawing. Finally, it calls the OnDraw event to signal the end of drawing of the chart.
Use the Draw method to paint the chart to any canvas and anywhere and with any size on the canvas.
Notes to Callers
|
The Draw Method uses the HorizontalAxis and VerticalAxis properties to convert the chart values into pixel coordinates. If you want to use a different axis (but not change the above properties), call the overloaded Draw method.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Draw(TCanvas,TCanvasRect,TRSChartAxis,TRSChartAxis,Boolean,Boolean)
|
Overloaded. Paints the chart to the specified Canvas in the specified location. The Draw Method uses the supplied TRSChartAxis (instead of the HorizontalAxis and VerticalAxis properties) to convert the chart values into pixel coordinates.
Unlike the regular Draw method, this method draws the axes as well (useful for when the chart is not connected to a panel).
Use the Draw method to paint the chart to any canvas and anywhere and with any size on the canvas.
|
DrawAxes(TCanvas,TCanvasRect,TRSChartAxis,TRSChartAxis)
Draws the specified axes to the Canvas
DrawGlyph(TCanvas,TCanvasRect)
Overloaded. Represents method DrawGlyph(TCanvas,TCanvasRect).
DrawGlyph(TCanvas,TRSChartValue,TCanvasRect)
Overloaded. Represents method DrawGlyph(TCanvas,TRSChartValue,TCanvasRect).
Drawing(TCanvas,TCanvasRect)
Calls the OnDrawing event and returns True if the draw process should continue.
This method is called before the InternalDraw method.
DrawLabel(TCanvas,String,TCanvasPixel,TCanvasPixel,Single)
Overloaded. Draws the text caption centered above the X, Y point without clipping.
Note
|
The Opacity is ignored in VCL
|
DrawLabel(TCanvas,String,TCanvasRect,Single)
Overloaded. Draws the text caption centered within the rectangle. The text is clipped
Note
|
The Opacity is ignored in VCL
|
DrawLabel(TCanvas,TRSChartValue,TCanvasPixel,TCanvasPixel)
Overloaded. Draws the text caption centered above the X, Y point without clipping.
DrawLabel(TCanvas,TRSChartValue,TCanvasRect)
Overloaded. Draws a label for the TRSChartValue on the canvas. The text of the label is controlled by the ValueLabelStyle property.
The label is drawn within the specified rectangle.
Drawn(TCanvas,TCanvasRect)
Calls the OnDraw event.
This method is called after the InternalDraw method.
EndUpdate
Re-enables screen repainting and change events. Use EndUpdate to re-enable screen repainting and change events that were turned off with the BeginUpdate method.
FormatValue(TRSChartValue,TRSLabelTextStyle)
Generates a label for the Value based on the TextStyle
GetAdjOffsetVertical
Returns the vertical offset ( OffsetVertical).
If coUseVerticalOffset is not in Options, this method always returns 0. If coUseVerticalOffset is in Options, the function returns the OffsetVertical value.
GetAxisCaption(TRSChartAxis,Integer,TRSChartValueType)
Returns a label for an axis ( RSChartPanel.TRSChartAxis ) based on the input Value. The Index specifies where to start looking in the chart Values (for optimization purposes) and decrements from there until the closest chart value is found.
GetChartType
Returns the chart type enumerated value for this class. Each chart class overrides this class function to return the RSChartConsts|TRSChartType enumerated value
GetColor
Overloaded. Represents method GetColor.
GetColor(TRSChartValue)
Overloaded. Returns the color of the chart value. The color of the TRSChartValue can change depending on the Options property as well as any other chart states (e.g., the TRSCandleStickChart class overrides this method to turn the color red or green depending on if the Open value is greater than the Closing Value)
GetCumulativeTotal(Integer,Integer,TRSCustomChartClass)
Determine the cumulative value at this index for all charts in the Group. The ValIndex specifies the TRSChartValue.Values dimension to compare.
Used for stacking charts.
GetCumulativeValue(Integer,Integer,TRSCustomChartClass)
Determine the cumulative value at this index for all charts below (spatially) this chart in the same Group. The ValIndex specifies the TRSChartValue.Values dimension to compare.
Used for stacking charts.
GetGroupDimension
Represents method GetGroupDimension.
GetValueColor
Returns a new chart color based on the ChartColorScheme and ChartColorList. Every time a chart is created, it is assigned a new color from the current ChartColorList.
InitializeChangeEvents
Initialize the OnChange events of structures. Use this method to assign event handlers for structures (e.g., Pen.OnChange := MyChangeMethod).
Notes to Inheritors
|
The constructor calls this method after it calls the InitializeChart method, which is where the structures should be actually created and initialized.
|
InitializeChart
Creates and initialize structures and values of chart. This method is the safe place to initialize chart values without change events occurring.
Notes to Inheritors
|
The constructor calls this method. Use this method to actually create and initialize properties. Do not assign event properties in this method (use the InitializeChangeEvents method instead)
|
InternalDraw(TCanvas,TCanvasRect)
Paints the chart graphic to the specified canvas at the specified rectangle. The InternalDraw method is called by the Draw method.
Descendant classes of TRSCustomChart override the InternalDraw method to actually paint themselves.
Notes to Inheritors
|
The default InternalDraw method implementation assigns the Brush, Pen , and Font to the Canvas.
|
InternalSelect(TCanvasRect,TRSChartSelectionAction)
Selects or deselects chart Values ( RSChartPanel.TRSChartValue ) based on whether they intersect with the selection rectangle (which is in pixel coordinates).
The base method converts the SelectionRect to chart coordinates (based on HorizontalAxis and VerticalAxis) and then selects values based on the TRSChartValue.Selectable method
IsSelectable(TCanvasRect)
Returns True if any value in the chart intersects with the SelectionRect
IsValuesStored
Represents method IsValuesStored.
IsVisible
Indicates whether the chart is visible. A chart is visible if its Visible property is True and both axes have been assigned.
Loaded
Represents method Loaded.
MouseHover(TCanvasRect)
Represents method MouseHover(TCanvasRect).
Notification(TComponent,TOperation)
Represents method Notification(TComponent,TOperation).
Paint
Represents method Paint.
PanelChanged
Represents method PanelChanged.
SaveCanvasResources(TCanvas,TBrush,TRSPen,TFont)
Represents method SaveCanvasResources(TCanvas,TBrush,TRSPen,TFont).
Select(TCanvasRect,TRSChartSelectionAction)
Selects or deselects chart Values ( RSChartPanel.TRSChartValue ) based on whether they intersect with the selection rectangle (which is in pixel coordinates).
The base method converts the SelectionRect to chart coordinates (based on HorizontalAxis and VerticalAxis) and then selects values based on the TRSChartValue.Selectable method
Notes to Inheritors
|
Descendant classes override the InternalSelect method
|
SelectionColorChanged
Represents method SelectionColorChanged.
SenderChanged(TObject)
Overloaded. Represents method SenderChanged(TObject).
SetCanvasResources(TCanvas,TBrush,TRSPen,TFont,Boolean,Boolean)
Overloaded. Represents method SetCanvasResources(TCanvas,TBrush,TRSPen,TFont,Boolean,Boolean).
SetCanvasResources(TCanvas,TRSChartValue,Boolean,Boolean)
Overloaded. Represents method SetCanvasResources(TCanvas,TRSChartValue,Boolean,Boolean).
SetColor(TCanvasColor)
Represents method SetColor(TCanvasColor).
SetOptions(TChartOptions)
Represents method SetOptions(TChartOptions).
UpdateAxisInfo(TRSChartAxis)
Represents method UpdateAxisInfo(TRSChartAxis).
UpdateColorScheme
Updates the values to the current color scheme. If PanelColorScheme is True then uses the Panel's color scheme
ValueSelectionChanged(TRSChartValue)
Represents method ValueSelectionChanged(TRSChartValue).
ValueVisibleChanged(TRSChartValue)
Represents method ValueVisibleChanged(TRSChartValue).
VisibleChanged
Represents method VisibleChanged.
WantsCaptions(TRSChartAxis)
Returns true if the chart prefers Captions over Values for its labels on the input Axis. This method provides a hint to the TRSChartAxis when LabelStyle is alsAutomatic.
Top
|
Name
|
Description
|
|
OnDraw
|
Occurs just after the chart is drawn. Write an OnDraw event handler to do an action just after the chart is drawn.
|
|
OnDrawing
|
Occurs just before the chart is drawn. Write an OnDrawing event handler to do an action just before the chart is drawn.
Note that the OnDrawing event handler can abort chart drawing by setting DoDraw to false.
|
|
OnValueChange
|
Occurs when a chart's value ( RSChartPanel.TRSChartValue ) changes. Write an OnChange event handler to respond to when the chart (or any its Values) change.
|
|
OnValueSelectionChange
|
Occurs when a chart value (TRSChartValue) is selected or deselected (either by the mouse or through the legend). Write an OnValueSelectionChange event handler to respond to when the TRSChartvalue is selected or not.
|
|
OnValueVisibleChange
|
Occurs when a chart's value ( RSChartPanel.TRSChartValue ) visibility changes. Write an OnValueVisibleChange event handler to respond to when the
chart value's visibility changes.
|
Top
|
To display a chart, you drop the component on a form and optionally connect its Panel property to the RSChartPanel.TRSChartPanel component where you want it to be displayed.
To display a chart:
| • | Drop a TRSCustomChart descendant component on a form |
| • | Optionally, drop a TRSChartPanel component where you want the chart to be displayed. (Note, more than one chart can share the same chart panel) |
| • | Connect the Panel property of the chart to the chart panel |
|
To add chart values (point, line, arrow, bar, etc) to the chart (at Design-Time):
| • | Select the TRSCustomChart descendant component |
| • | Click the ellipsis button (...) for the Values property of the chart. This action displays Delphi's Collection Editor for the RSChartPanel.TRSChartValues collection. |
| • | Edit each chart value properties to achieve the display you want.
|
|
To add chart values (point, line, arrow, bar, etc) to the chart (at Run-Time):
Delphi
|
var
Value: TRChartValue; // note, this type should be the same that the chart uses (e.g., TRS2DChartValue, TRSArrowChartValue, etc)
begin
// Add one value and configure
Value := MyChart.Values.Add;
Value.Color := clRed;
Value.Caption := 'Research';
Value.Value := 10.0;
end;
|
