Resource Access

This group contains functions for getting and setting resource values, as well as checking if a named resource exits. More...

Detailed Description

This group contains functions for getting and setting resource values, as well as checking if a named resource exits.

Resource Access Performance Optimization

If NULL is passed as the resource_name parameter of functions for setting and querying resources, the data object supplied by the object parameter will be used directly, avoiding an overhead of a resource search. This can be used to optimize performance when the same resource is accessed repeatedly. The GlgGetResourceObject function of the Intermediate API may be used to obtain an object ID of a data object once and then use it repeatedly.

For example:

// Store a data object for repeated use.
GlgObject data_obj = GlgGetResourceObject( viewport, "WaterTank/Level" );
 
...
 
// Use the stored data object to update the drawing with data.
if( data_obj )
  GlgSetDResource( data_obj, NULL, new_water_level_value );

The GlgAddDataSampleNode function of the Intermediate API can also be used instead of setting values of chart entry points to prefill a chart with a large number of data samples.

Functions
void	GlgChangeObject (GlgObject object, char *resource_path)
	Sends a change message to an object without actually changing the object's properties. More...
GlgBoolean	GlgGetDResource (GlgObject object, char *resource_name, double *value)
	Returns the current value of a D (double) resource. More...
GlgBoolean	GlgGetGResource (GlgObject object, char *resource_name, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) resource. More...
GlgBoolean	GlgGetSResource (GlgObject object, char *resource_name, char **value)
	Returns the current value of a S (string) resource. More...
GlgBoolean	GlgHasResourceObject (GlgObject object, char *resource_name)
	Checks if a named resource exists. More...
GlgBoolean	GlgSetDResource (GlgObject object, char *resource_name, double value)
	Sets a new value of a D (double) resource. More...
GlgBoolean	GlgSetDResourceIf (GlgObject object, char *resource_name, double value, GlgBoolean if_changed)
	Sets a new value of a D (double) resource. More...
GlgBoolean	GlgSetGResource (GlgObject object, char *resource_name, double x_value, double y_value, double z_value)
	Sets new values of a G (geometrical or color) resource. More...
GlgBoolean	GlgSetGResourceIf (GlgObject object, char *resource_name, double x_value, double y_value, double z_value, GlgBoolean if_changed)
	Sets new values of a G (geometrical or color) resource. More...
GlgBoolean	GlgSetResourceFromObject (GlgObject object, char *resource_name, GlgObject value)
	Sets a new value of a data resource to the value of contained in the provided data object of the same data type. More...
GlgBoolean	GlgSetResourceFromObjectIf (GlgObject object, char *resource_name, GlgObject value, GlgBoolean if_changed)
	Sets the value of the data object to the value of another data object of the same data type. More...
GlgBoolean	GlgSetSResource (GlgObject object, char *resource_name, char *value)
	Replaces the string of an S (string) resource. More...
GlgBoolean	GlgSetSResourceFromD (GlgObject object, char *resource_name, char *format, double value)
	Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string. More...
GlgBoolean	GlgSetSResourceFromDIf (GlgObject object, char *resource_name, char *format, double value, GlgBoolean if_changed)
	Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string. More...
GlgBoolean	GlgSetSResourceIf (GlgObject object, char *resource_name, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) resource. More...

Function Documentation

GlgChangeObject()

void GlgChangeObject	(	GlgObject	object,
		char *	resource_path
	)

Sends a change message to an object without actually changing the object's properties.

Parameters

object	The object to send the message to.
resource_path	If NULL, the message is sent to the object specified by the object parameter. Otherwise, the message is sent to the object's child specified by the resource path. The resource path is relative to the object parameter.

This function may be used to send a change message an object's attribute. Sending the message to an object attribute is equivalent to setting the attribute to the same value as its current value using one of the GlgSetDResource, GlgSetSResource or GlgSetDResource functions.

For example, sending the message to the Factor attribute of a volatile series object forces the series to recreate its instances without actually changing the value of the Factor. If the change message is sent to the ImageFile attribute of an image object, the image will reload the image file (the image's EnableCache attribute should be set to NO to disable cache for images that need to be reloaded).

Sending the change message to a drawable object forces the object to redraw. If the message is sent to an object like a polygon or a text object, the area of the object's bounding box gets invalidated and redrawn. If an object is a viewport, it redraws its content.

GlgGetDResource()

GlgBoolean GlgGetDResource	(	GlgObject	object,
		char *	resource_name,
		double *	value
	)

Returns the current value of a D (double) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the scalar resource to query.
value	Specifies a pointer used to return the resource value.

Returns

Success or failure status.

If a scalar resource with the given resource path exists, this function copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GlgGetGResource()

GlgBoolean GlgGetGResource	(	GlgObject	object,
		char *	resource_name,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

Returns the current value of a G (geometrical or color) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the G resource to query.
x_value	Specifies a pointer used to return the X value of a geometrical resource or an R component of the color resource.
y_value	Specifies a pointer used to return the Y value of a geometrical resource or a G component of the color resource.
z_value	Specifies a pointer used to return the Z value of a geometrical resource or a B component of the color resource.

Returns

Success or failure status.

If a G resource or with the given resource path exists, this function copies its current three values to the addresses specified with the x_value, y_value and z_value pointers and returns True. Otherwise, it generates an error message and returns False.

GlgGetSResource()

GlgBoolean GlgGetSResource	(	GlgObject	object,
		char *	resource_name,
		char **	value
	)

Returns the current value of a S (string) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to query.
value	Specifies a pointer used to return the resource value.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function copies the string pointer into the address specified by value pointer and returns True, otherwise it generates an error message and returns False.

Warning: The returned pointer points to GLG internal data structures and should not be modified. The pointer is valid only immediately after a call to GlgGetSResource. To store the returned string, create a copy of it using GlgStrClone.

GlgHasResourceObject()

GlgBoolean GlgHasResourceObject	(	GlgObject	object,
		char *	resource_name
	)

Checks if a named resource exists.

Parameters

object	Specifies a GLG object whose resource to query.
resource_name	Specifies the resource path of the resource object to query.

Returns

True if a resource object with the given resource path exists, otherwise returns False without generating an error message.

GlgSetDResource()

GlgBoolean GlgSetDResource	(	GlgObject	object,
		char *	resource_name,
		double	value
	)

Sets a new value of a D (double) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the name of the scalar resource to be set.
value	Specifies a new value.

Returns

Success or failure status.

If a scalar resource with the given resource path exists, this function sets it to a new value and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetDResourceIf()

GlgBoolean GlgSetDResourceIf	(	GlgObject	object,
		char *	resource_name,
		double	value,
		GlgBoolean	if_changed
	)

Sets a new value of a D (double) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the scalar resource to be set.
value	Specifies a new value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetDResource). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed. The parameter is ignored when updating chart entry points to allow plotting straight lines when the plotted value does not change over time.

Returns

Success or failure status.

If a scalar resource with the given resource path exists, this function sets it to a new value and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetGResource()

GlgBoolean GlgSetGResource	(	GlgObject	object,
		char *	resource_name,
		double	x_value,
		double	y_value,
		double	z_value
	)

Sets new values of a G (geometrical or color) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the geometrical or color resource to be set.
x_value	Specifies the new X value.
y_value	Specifies the new Y value.
z_value	Specifies the new Z value.

Returns

Success or failure status.

If a G resource with the given resource path exists, this function sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetGResourceIf()

GlgBoolean GlgSetGResourceIf	(	GlgObject	object,
		char *	resource_name,
		double	x_value,
		double	y_value,
		double	z_value,
		GlgBoolean	if_changed
	)

Sets new values of a G (geometrical or color) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the geometrical or color resource to be set.
x_value	Specifies the new X value.
y_value	Specifies the new Y value.
z_value	Specifies the new Z value.
if_changed	If set to False, the graphical updates will be performed even if the new values are the same as the old one (equivalent to GlgSetGResource). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a G resource with the given resource path exists, this function sets its new values and returns True, otherwise it generates an error message and returns False.

See Resource Access Performance Optimization for more.

GlgSetResourceFromObject()

GlgBoolean GlgSetResourceFromObject	(	GlgObject	object,
		char *	resource_name,
		GlgObject	value
	)

Sets a new value of a data resource to the value of contained in the provided data object of the same data type.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the name of the D, S or G resource to be set.
value	An object of the matching data type containing the new value.

Returns

Success or failure status.

If a resource of a matching type at the given resource path exists, the function sets the value of the resource to a value defined by the value object and returns True, otherwise it generates an error message and returns False.

The object type and data type of the resource specified by the resource path should match the corresponding types of the value object.

See Resource Access Performance Optimization for more.

GlgSetResourceFromObjectIf()

GlgBoolean GlgSetResourceFromObjectIf	(	GlgObject	object,
		char *	resource_name,
		GlgObject	value,
		GlgBoolean	if_changed
	)

Sets the value of the data object to the value of another data object of the same data type.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the name of the resource to be set.
value	Specifies the object containing the new value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetResourceFromObject). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a resource of a matching type at the given resource path exists, the function sets the value of the resource to a value defined by the value object and returns True, otherwise it generates an error message and returns False.

The object type and data type of the resource specified by the resource path should match the corresponding types of the value object.

See Resource Access Performance Optimization for more.

GlgSetSResource()

GlgBoolean GlgSetSResource	(	GlgObject	object,
		char *	resource_name,
		char *	value
	)

Replaces the string of an S (string) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
value	Specifies a new string.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function creates a copy of the input string, sets that copy as the new value of the resource and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.

GlgSetSResourceFromD()

GlgBoolean GlgSetSResourceFromD	(	GlgObject	object,
		char *	resource_name,
		char *	format,
		double	value
	)

Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
format	Specifies the printf-style format to use when setting the resource string.
value	Specifies the numerical value to be converted to a string according to the specified format.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function sets it to a new string containing the value parameter formatter using the format argument and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.

GlgSetSResourceFromDIf()

GlgBoolean GlgSetSResourceFromDIf	(	GlgObject	object,
		char *	resource_name,
		char *	format,
		double	value,
		GlgBoolean	if_changed
	)

Sets the string of an S (string) resource from a double value, converting the value into a string using a printf format string.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
format	Specifies the printf-style format to use when setting the resource string.
value	Specifies the numerical value to be converted to a string according to the specified format.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetSResourceFromD). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function sets it to a new string containing the value parameter formatted using the format argument and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.

GlgSetSResourceIf()

GlgBoolean GlgSetSResourceIf	(	GlgObject	object,
		char *	resource_name,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) resource.

Parameters

object	Specifies a GLG object.
resource_name	Specifies the resource path of the string resource to be set.
value	Specifies a new string.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one (equivalent to GlgSetSResource). Setting if_changed=True optimizes performance of applications that set resource values regardless whether the values have changed.

Returns

Success or failure status.

If a string resource with the given resource path exists, this function creates a copy of the input string, sets that copy as the new value of the resource and returns True, otherwise it generates an error message and returns False.

The memory associated with the old string is automatically freed.

See Resource Access Performance Optimization for more.