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.

The Chart methods of the C API contain additional methods that can be used to manipulate a Chart object.

Functions
GlgObject	CreateChartSelection (GlgObjectC *plot, double x, double y, double dx, double dy, GlgBoolean screen_coord, GlgBoolean include_invalid, GlgBoolean x_priority)
	Selects a this chart's data sample closest to the specified position and returns a message object containing the selected sample's information. More...
char *	CreateTooltipString (double x, double y, double dx, double dy, char *format)
	Creates and returns a chart or axis tooltip string based on the mouse position. More...
GlgBoolean	PositionToValue (char *resource_name, double x, double y, GlgBoolean outside_x, GlgBoolean outside_y, double *value)
	Returns a value corresponding to the specified position on top of this Chart or Axis object. More...

Function Documentation

CreateChartSelection()

GlgObject CreateChartSelection	(	GlgObjectC *	plot,
		double	x,
		double	y,
		double	dx,
		double	dy,
		GlgBoolean	screen_coord,
		GlgBoolean	include_invalid,
		GlgBoolean	x_priority
	)

Selects a this chart's data sample closest to the specified position and returns a message object containing the selected sample's information.

This is a wrapper for GlgCreateChartSelection.

Parameters

plot	An optional plot object. If it is not NULL, the method queries only the samples in that plot, otherwise 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 GLG_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.

The returned message is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned message.

CreateTooltipString()

char* CreateTooltipString	(	double	x,
		double	y,
		double	dx,
		double	dy,
		char *	format
	)

Creates and returns a chart or axis tooltip string based on the mouse position.

Creates and returns a tooltip string corresponding to the specified position in screen coordinates inside of this Chart or Axis object. This is a wrapper for GlgCreateTooltipString.

Parameters

x,y	Specify a position on top of a chart or an axis in screen coordinates. When using the cursor position, add GLG_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 corresponding to the specified position, or NULL if no tooltip was created. The returned string must be freed using GlgFree.

If the this object is a Chart, 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 this object is an Axis, or if the this 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/RealTime_StripChart/stripchart.c file in the GLG installation directory demonstrates the use of the corresponding C function to create a tooltip string that displays such cursor feedback information at the top of the chart.

PositionToValue()

GlgBoolean PositionToValue	(	char *	resource_name,
		double	x,
		double	y,
		GlgBoolean	outside_x,
		GlgBoolean	outside_y,
		double *	value
	)

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

This is a wrapper for GlgPositionToValue.

Parameters

resource_name	Specifies a resource path for accessing a child chart, plot or axis object inside this object. NULL may be used if this object is a Chart, Plot or Axis object.
x,y	Specify a position in the screen coordinates of the parent viewport. When using the cursor position, add GLG_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.
value	A pointer to the returned value.

Returns

Success or failure status.

For a Plot object, the method converts the specified position to a Y value in the Low/High range of the plot and returns the value through the value pointer.

For an Axis object, the method converts the specified position to the axis value and returns the value.

For a Chart object, the method converts the specified position to the X or time value of the chart's X axis and returns the value.