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

Detailed Description

This group lists Chart functions of the Intermediate API.

These functions provide extended chart functionality in addition to the Chart Functions of the Standard API.

Functions
GlgBoolean	GlgAddDataSampleNode (GlgObject plot, GlgDataSampleNode *node, GlgBoolean quick_mode)
	Adds a data sample node directly to a plot's data buffer. More...

GlgObject	GlgCreateChartSelection (GlgObject object, GlgObject plot, double x, double y, double dx, double dy, GlgBoolean screen_coord, GlgBoolean include_invalid, GlgBoolean x_priority)
	Selects a chart's data sample closest to the specified position and returns a message object containing the selected sample's information. More...

GlgDataSampleNode *	GlgCreateDataSampleNode (GlgObject plot, GlgBoolean extended)
	Creates a data sample node structure to be used with the GlgAddDataSampleNode function. More...

char *	GlgCreateTooltipString (GlgObject object, double x, double y, double dx, double dy, char *format)
	Creates and returns a chart or axis tooltip string corresponding to the specified position in screen coordinates. More...

void	GlgFreeDataSampleNode (GlgObject plot, GlgDataSampleNode *node)
	Returns a data sample node to the plot cache for reuse, if possible. More...

GlgObject	GlgGetLegendSelection (GlgObject object, double x, double y)
	Returns the plot object corresponding to the legend item at the specified position, if any. More...

GlgDataSample *	GlgGetNodeDataSample (GlgDataSampleNode *node)
	Returns the node's data sample. More...

GlgBoolean	GlgPositionToValue (GlgObject object, 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 a Chart or an Axis object. More...

Function Documentation

◆ GlgAddDataSampleNode()

GlgBoolean GlgAddDataSampleNode	(	GlgObject	plot,
		GlgDataSampleNode *	node,
		GlgBoolean	quick_mode
	)

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

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

Parameters

plot A chart's plot to add datasample to.

node A data sample node containing the data sample to be added. GlgCreateDataSampleNode 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 time stamp of the last data sample.

For a chart with the SWEEP X axis, the GlgUpdateChartTimeAxis function can be used to scroll the chart.

The GlgUpdateChartState function may also be used to update the chart's autoscale and scrollbars when done.

Returns: Success or failure status.

This function 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 GlgSetDResource or GlgSetDTag.

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 DEMOS/RealTime_StripChart/stripchart.c file in the GLG installation directory provides a coding example of prefilling a chart with data using GlgAddDataSampleNode.

◆ GlgCreateChartSelection()

GlgObject GlgCreateChartSelection	(	GlgObject	object,
		GlgObject	plot,
		double	x,
		double	y,
		double	dx,
		double	dy,
		GlgBoolean	screen_coord,
		GlgBoolean	include_invalid,
		GlgBoolean	x_priority
	)

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

Parameters

object	A chart object. If the plot parameter is NULL, the function queries data samples in all plots of the chart and selects the sample closest to the specified position.
plot	An optional plot object. If it is not NULL, the function queries only the samples in that plot.
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 function 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 function returns NULL if no data sample matching the selection criteria was found.

The returned message object must be dereferenced using GlgDropObject when finished.

◆ GlgCreateDataSampleNode()

GlgDataSampleNode* GlgCreateDataSampleNode	(	GlgObject	plot,
		GlgBoolean	extended
	)

Creates a data sample node structure to be used with the GlgAddDataSampleNode function.

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

A data sample node contains a GlgDataSample structure that may be retrieved from the node using GlgGetNodeDataSample. Fields of the data sample structure must be filled before adding it to the plot using GlgAddDataSampleNode.

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

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, and a newly created datasample node will be returned.
If the plot uses cache, the method returns a data sample node from the cache, if available. If the plot 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.

◆ GlgCreateTooltipString()

char* GlgCreateTooltipString	(	GlgObject	object,
		double	x,
		double	y,
		double	dx,
		double	dy,
		char *	format
	)

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

Parameters

object	A Chart or Axis object to create the tooltip for.
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 function 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 function 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. The returned string must be freed using GlgFree.

If the object parameter specifies a Chart, and the specified position is within the chart's data area, the function 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, GlgCreateTooltipString 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 function to create a tooltip string that displays such cursor feedback information at the top of the chart.

◆ GlgFreeDataSampleNode()

void GlgFreeDataSampleNode	(	GlgObject	plot,
		GlgDataSampleNode *	node
	)

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

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 freed.
node	The data sample node to be freed.

◆ GlgGetLegendSelection()

GlgObject GlgGetLegendSelection	(	GlgObject	object,
		double	x,
		double	y
	)

Returns the plot object corresponding to the legend item at the specified position, if any.

Parameters

object	A Legend object.
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.

◆ GlgGetNodeDataSample()

GlgDataSample* GlgGetNodeDataSample ( GlgDataSampleNode * node )

Returns the node's data sample.

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 pointer that can be added to a chart after filling up the data sample's fields.

◆ GlgPositionToValue()

GlgBoolean GlgPositionToValue	(	GlgObject	object,
		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 a Chart or an Axis object.

Parameters

object	If resource_name is NULL, specifies a Chart, a Plot or an Axis object, otherwise it specifies a container object containing a chart, a plot or an axis.
resource_name	Specifies a resource path of a child chart, plot or axis object relative to the container 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.

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

If object is an Axis, the function converts the specified position to the axis value and returns the value.

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