Chart Methods

This group lists Chart methods of the Intermediate API. More...

Detailed Description

This group lists Chart methods of the Intermediate API.

These methods provide extended chart functionality in addition to the Chart Methods of the Standard API.

Functions
boolean	AddPlotDataSample (double value, double time_stamp, boolean valid, float marker_visibility, boolean quick_mode)
	Adds a new data sample with the supplied values directly to the plot's data buffer. More...
GlgObject	CreateChartSelection (GlgObject plot, double x, double y, double dx, double dy, boolean screen_coord, boolean include_invalid, boolean x_priority)
	Selects the chart's data sample closest to the specified position. More...
String	CreateTooltipString (double x, double y, double dx, double dy, String format)
	Creates and returns a chart or axis tooltip string corresponding to the specified position in screen coordinates. More...
GlgObject	GetLegendSelection (double x, double y)
	Returns the plot object corresponding to the legend item at the specified position in the legend object the method is invoked on, if any. More...
double	PositionToValue (String resource_name, double x, double y, boolean outside_x, boolean outside_y)
	Returns a value corresponding to the specified position on top of the Chart or an Axis object. More...

Function Documentation

AddPlotDataSample()

boolean AddPlotDataSample	(	double	value,
		double	time_stamp,
		boolean	valid,
		float	marker_visibility,
		boolean	quick_mode
	)

Adds a new data sample with the supplied values directly to the plot's data buffer.

This method is used to enhance performance when prefilling a chart with a large number of data samples. For periodic updates, new data may be pushed into the plot's entry points using SetDResource or SetDTag.

If the plot uses a cache, and the cache is not empty, the new data sample will be taken from the plot's cache.

NOTE: The method adds a basic data sample, not an extended data sample.

Parameters

value	The datasample value.
time_stamp	The timestamp.
valid	The valid flag.
marker_visibility	The marker visibility in the range [0;1].
quick_mode	Enables a quick mode that bypasses chart autoscroll and autoscale logic for faster chart prefilling. It also disables all validity checks for increased performance of charts with large number of data samples. When the last data sample is added, a chart with the SCROLL X axis can be scrolled to show the last added sample by setting EndValue of the chart's X axis to the timestamp of the last data sample. For a chart with the SWEEP X axis, the UpdateChartTimeAxis method can be used to scroll the chart. The UpdateChartState method may also be used to update the chart's autoscale and scrollbars when done.

Returns

Success or failure status.

Note: It is recommended that the initial development is done with quick_mode=false, switching to quick_mode=true when all potential errors have been dealt with.

The examples_html5/realtime_chart/GlgRealTimeChart.js file in the GLG installation directory provides a coding example of prefilling a chart with data.

CreateChartSelection()

GlgObject CreateChartSelection	(	GlgObject	plot,
		double	x,
		double	y,
		double	dx,
		double	dy,
		boolean	screen_coord,
		boolean	include_invalid,
		boolean	x_priority
	)

Selects the chart's data sample closest to the specified position.

The method selects the data sample closest to the specified position in the chart the method is invoked on and returns a message object containing the selected sample's information.

Parameters

plot	An optional plot object: If it is not null, the method queries only the samples in that plot. If it is null, the method queries data samples in all plots of the chart and selects the sample closest to the specified position.
x,y	Specify the position inside the chart: If screen_coord=true, the position is defined in the screen coordinates of the chart's parent viewport. When the mouse position is used, add COORD_MAPPING_ADJ to the x and y screen coordinates of the mouse for precise mapping. If screen_coord=false, the x position is defined as an X or time value, and the y position is defined in relative coordinates in the range [0; 1] to allow the chart to process selection for plots with different ranges (0 corresponds to the Low range of each plot, and 1 to the High range).
dx,dy	Specify an extent around the point defined by the x and y parameters. The extent is defined in the same coordinates as x and y, depending on the value of the screen_coord parameter. Only the data samples located within the dx and dy distances of the specified position are considered for the selection.
screen_coord	Controls the way the x and y parameters are interpreted: If true, the x and y parameters supply screen coordinates in the chart's parent viewport. If false, x and y supply relative value, see description of the x and y parameters above.
include_invalid	If true, invalid data samples are considered for selection If false, invalid samples are never selected.
x_priority	If true, the method selects the data sample closest to the specified position in the horizontal direction with no regards to its distance from the specified position in the vertical direction. If false, a data sample with the closest distance from the specified position is selected.

Returns

The information about the selected data sample is returned in the form of a message object described in the Chart Selection Message Object section in the Appendix B of the GLG Programming Reference Manual.

The method returns null if no data sample matching the selection criteria was found.

CreateTooltipString()

String CreateTooltipString	(	double	x,
		double	y,
		double	dx,
		double	dy,
		String	format
	)

Creates and returns a chart or axis tooltip string corresponding to the specified position in screen coordinates.

The method can be invoked on either a Chart or Axis object to create the tooltip for.

Parameters

x,y	Specify a position on top of a chart or an axis in screen coordinates. When using the cursor position, add COORD_MAPPING_ADJ to the cursor's X and Y screen coordinates for precise mapping.
dx,dy	Specify the maximum extent in screen pixels around the specified position.
format	Provides a custom format for creating a tooltip string and uses the same syntax as the TooltipFormat attributes of the Chart and Axis objects. If it is set to null or an empty string, the format provided by the TooltipFormat attribute of the chart or the axis will be used. A special "<single_line>" tag may be prepended to the format string to force the method to remove all line breaks from the returned tooltip string. A "<chart_only>" tag may also be prepended to search only for a chart tooltip and disable search for the axes' tooltips when the method is invoked for a Chart object.

Returns

A Chart or Axis tooltip string containing information about the chart data sample or an axis position at the specified coordinates, or null if no tooltip was created.

If the method is invoked on a Chart object, and the specified position is within the chart's data area, the method selects a data sample closest to the specified position and returns a tooltip string containing information about the sample. The dx and dy parameters define the maximum extent for selecting a data sample, and the TooltipMode attribute of the chart defines the data sample selection mode: X or XY. null is returned if no data samples were found within the dx and dy distances of the specified position.

If the object parameter specifies an Axis, or if the object is a Chart and the specified position is on top of one of the chart's axes, the returned tooltip string contain information about the axis value corresponding to the selected position.

While the Chart object proves an integrated tooltip functionality that automatically displays the tooltip without any application involvement when a mouse is hovering over the chart, CreateTooltipString can be used to generate a string containing information about the data sample under the current mouse position that is displayed as the mouse continuously moves over the chart.

The DEMOS_HTML5/misc_demos/GlgRTChart.js file in the GLG installation directory demonstrates the use of the method to create a tooltip string that displays such cursor feedback information at the top of the chart.

GetLegendSelection()

GlgObject GetLegendSelection	(	double	x,
		double	y
	)

Returns the plot object corresponding to the legend item at the specified position in the legend object the method is invoked on, if any.

Parameters

x,y	Specifies the position in screen coordinates of the viewport containing the legend.

Returns

The plot corresponding to the item at the specified legend position, or null if no legend item was found.

See also GetSelectedPlot.

PositionToValue()

double PositionToValue	(	String	resource_name,
		double	x,
		double	y,
		boolean	outside_x,
		boolean	outside_y
	)

Returns a value corresponding to the specified position on top of the Chart or an Axis object.

For efficiency, if the returned object is not null, it can be returned to the internal cache via the object's ReleaseToCache method.

Parameters

resource_name	A resource path of a child Chart, Plot or Axis object, or null to query the Chart, Plot or Axis object the method is invoked on. The resource path is relative to the invoking object.
x,y	Specify a position in the screen coordinates of the parent viewport. When using the cursor position, add COORD_MAPPING_ADJ to the cursor's X and Y coordinates for precise mapping.
outside_x	If true, false will be returned for points outside the X extent of the chart or axis object.
outside_y	If true, false will be returned for points outside the Y extent of the chart or axis object.

Returns

GlgDouble object containing the value corresponding to the specified position:

• If object is a Plot, the method converts the specified position to a Y value in the Low/High range of the plot.
• If object is an Axis, the method converts the specified position to the axis value.
• If object is a Chart, the method converts the specified position to the X or time value of the chart's X axis.