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	AddDataSampleNode (GlgDataSampleNode node, boolean quick_mode)
	Adds a data sample node 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...
static GlgDataSampleNode	CreateDataSampleNode (GlgObject plot, boolean extended)
	Creates a data sample node to be used with the AddDataSampleNode method. 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...
static void	FreeDataSampleNode (GlgObject plot, GlgDataSampleNode node)
	Returns a data sample node to the plot cache for reuse, if possible. 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...
static GlgDataSample	GetNodeDataSample (GlgDataSampleNode node)
	Returns the datasample contained in the node. 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...
GlgDouble	PositionToValueObj (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

AddDataSampleNode()

boolean AddDataSampleNode	(	GlgDataSampleNode	node,
		boolean	quick_mode
	)

Adds a data sample node directly to the plot's data buffer.

This method is used to quickly prefill a chart with a large number of samples.

Parameters

node

A data sample node containing the data sample to be added. CreateDataSampleNode may be used to create data sample nodes.

quick_mode

Enables a quick mode that bypasses chart autoscroll and autoscale logic for faster chart prefilling, and also disables all validity checks for increased performance. 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.

This method is used to enhance performance of 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.

It is recommended that the initial development is done with the quick mode disabled, enabling it when all potential errors have been dealt with.

The examples_java/RealTimeChart/GlgChart.java file in the GLG installation directory provides a coding example of prefilling a chart with data using AddDataSampleNode.

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.

CreateDataSampleNode()

static GlgDataSampleNode CreateDataSampleNode ( GlgObject  plot, boolean  extended  )

static

Creates a data sample node to be used with the AddDataSampleNode method.

The method returns a cached data sample node if available, otherwise it creates a new one and returns it.

A data sample node contains a GlgDataSample object that may be retrieved from the node using GetNodeDataSample. Properties of the data sample must be filled before adding it to the plot using AddDataSampleNode.

Unused data sample nodes that were not added to a chart may be returned to a cache using FreeDataSampleNode.

Parameters

plot

An optional plot the data sample node will be added to. If plot is provided, a new data sample node will be taken from the plot's cache, if possible: If the plot doesn't use a cache, this parameter may be set to null. If the plot uses cache, the method returns a data sample node from the cache, if available: If the plot cache is empty, or if the plot parameter is null, the datasample node will be taken from a global cache. If the global cache is empty, a newly created datasample node will be returned.

extended

The type of the data sample to be created inside the node: true to create an extended data sample (GlgDataSampleExt) false to create a basic data sample (GlgDataSample).

Returns

A new node containing a data sample of the requested type.

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_JAVA/GlgRealTimeChart.java 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.

FreeDataSampleNode()

static void FreeDataSampleNode ( GlgObject  plot, GlgDataSampleNode  node  )

static

Returns a data sample node to the plot cache for reuse, if possible.

The node and its datasample should not be accessed by the program after the node has been released.

Parameters

plot	An optional plot the data sample node belongs to. If provided (not null), the data sample node will be returned to the plot's cache if it is enabled. Otherwise, the node will be released to the global cache.
node	The data sample node to be freed.

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.

GetNodeDataSample()

static GlgDataSample GetNodeDataSample ( GlgDataSampleNode  node )

static

Returns the datasample contained in the node.

Parameters

node	The data sample node to query.

Returns

Depending on the type of the data sample contained in the node, returns either GlgDataSample or GlgDataSampleExt that can be added to a chart after filling up the data sample's fields.

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.

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

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

PositionToValueObj()

GlgDouble PositionToValueObj	(	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.

This is more efficient version of the fref PositionToValue method that uses cached GlgDouble objects for return values. 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.