Resource Access

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

Detailed Description

This group contains methods 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 methods 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 GetResourceObject method 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.
let data_obj = viewport.GetResourceObject( "WaterTank/Level" );
 
...
 
// Use the stored data object to update the drawing with data.
if( data_obj != null )
  data_obj.SetDResource( null, new_water_level_value );

The AddPlotDataSample method 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.

---

Using Resource Wildcards

Functions that set resource or tags values support * and ? wildcards for pattern matching. The asterisk (*) matches any sequence of characters, and the question mark (?) matches any single character.

To enable wildcard matching, prefix the resource or tag name with "$!". For example, "$!Clear*" will target all tags with names beginning with "Clear".

When using wildcards in resource paths, the wildcards prefix must be added to each level of resource hierarchy where pattern matching is required. For example, the following string targets all nested elements with names beginning with "Element" inside parent objects with names beginning with "Group":

     $!Group∗/$!Element∗/LineWidth

NOTE: Wildcards can only be used for matching named object resources; they cannot be used for matching default attribute names (e.g. LineWidth, FillColor).

---

Functions
void	ChangeObject (String resource_path)
	Sends a change message the object without actually changing the object's properties. More...
double	GetDResource (String resource_name)
	Returns the current value of the object's D (double) resource. More...
GlgPoint	GetGResource (String resource_name)
	Returns the current value of the object's G (geometrical or color) resource. More...
String	GetSResource (String resource_name)
	Returns the current value of the object's S (string) resource. More...
boolean	HasResourceObject (String resource_name)
	Checks if the object's named resource exists. More...
boolean	SetDResource (String resource_name, double value)
	Sets a new value of the object's D (double) resource. More...
boolean	SetDResourceIf (String resource_name, double value, boolean if_changed)
	Sets a new value of the object's D (double) resource. More...
boolean	SetGResource (String resource_name, double x_value, double y_value, double z_value)
	Sets new values of the object's G (geometrical or color) resource. More...
boolean	SetGResourceFromPoint (String resource_name, GlgPoint g_value)
	Sets new values of the object's G (geometrical or color) resource. More...
boolean	SetGResourceFromPointIf (String resource_name, GlgPoint g_value, boolean if_changed)
	Sets new values of the object's G (geometrical or color) resource. More...
boolean	SetGResourceIf (String resource_name, double x_value, double y_value, double z_value, boolean if_changed)
	Sets new values of the object's G (geometrical or color) resource. More...
boolean	SetResourceFromObject (String resource_name, GlgObject value)
	Sets a new value of the object's resource to the value of contained in the provided data object of the same data type. More...
boolean	SetResourceFromObjectIf (String resource_name, GlgObject value, boolean if_changed)
	Sets the value of the object's data object to the value of another data object of the same data type. More...
boolean	SetSResource (String resource_name, String value)
	Replaces the string of the object's S (string) resource. More...
boolean	SetSResourceFromD (String resource_name, String format, double value)
	Sets the value of the object's S (string) resource from a double value, converting the value into a string using a C-style printf format string. More...
boolean	SetSResourceFromDIf (String resource_name, String format, double value, boolean if_changed)
	Sets the value of the object's S (string) resource from a double value, converting the value into a string using a C-style printf format string. More...
boolean	SetSResourceIf (String resource_name, String value, boolean if_changed)
	Replaces the string of the object's S (string) resource. More...

Function Documentation

ChangeObject()

void ChangeObject

(

String

resource_path

)

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

Parameters

resource_path

If null, the message is sent to the object the method is invoked on. Otherwise, the message is sent to the object's child specified by the resource path. The resource path is relative to the invoking object.

This method may be used to send a change message to 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 SetDResource, SetSResource or SetDResource methods.

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 a change message to a drawable object forces the object to redraw itself. 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.

GetDResource()

double GetDResource

(

String

resource_name

)

Returns the current value of the object's D (double) resource.

Parameters

resource_name

Specifies the resource path of the object's scalar resource to query.

Returns

Resource value or null if the resource was not found.

If a scalar resource with the given resource path exists, this method returns its value, otherwise it generates an error message and returns null.

GetGResource()

GlgPoint GetGResource

(

String

resource_name

)

Returns the current value of the object's G (geometrical or color) resource.

Parameters

resource_name

Specifies the resource path of the G resource to query.

Returns

A GlgPoint containing XYZ or RGB resource values.

If a G resource with the given resource path exists, this method returns its values in a GlgPoint object, otherwise it generates an error message and returns null.

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

GetSResource()

String GetSResource

(

String

resource_name

)

Returns the current value of the object's S (string) resource.

Parameters

resource_name

Specifies the resource path of the string resource to query.

Returns

Resource value or null if the resource was not found.

If a string resource with the given resource path exists, this method returns its value, otherwise it generates an error message and returns null.

HasResourceObject()

boolean HasResourceObject

(

String

resource_name

)

Checks if the object's named resource exists.

Parameters

resource_name

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.

SetDResource()

boolean SetDResource	(	String	resource_name,
		double	value
	)

Sets a new value of the object's D (double) resource.

Parameters

resource_name	Specifies the resource path of the scalar resource to be set. May use wildcards, see Using Resource Wildcards.
value	Specifies a new value.

Returns

Success or failure status.

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

See Resource Access Optimization for more.

SetDResourceIf()

boolean SetDResourceIf	(	String	resource_name,
		double	value,
		boolean	if_changed
	)

Sets a new value of the object's D (double) resource.

Parameters

resource_name	Specifies the resource path of the scalar resource to be set. May use wildcards, see Using Resource Wildcards.
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 SetDResource). 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 method sets it to a new value and returns true, otherwise it generates an error message and returns false.

See Resource Access Optimization for more.

SetGResource()

boolean SetGResource	(	String	resource_name,
		double	x_value,
		double	y_value,
		double	z_value
	)

Sets new values of the object's G (geometrical or color) resource.

Parameters

resource_name	Specifies the resource path of the geometrical or color resource to be set. May use wildcards, see Using Resource Wildcards.
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 method sets its new values and returns true, otherwise it generates an error message and returns false.

See Resource Access Optimization for more.

SetGResourceFromPoint()

boolean SetGResourceFromPoint	(	String	resource_name,
		GlgPoint	g_value
	)

Sets new values of the object's G (geometrical or color) resource.

Parameters

resource_name	Specifies the resource path of the geometrical or color resource to be set. May use wildcards, see Using Resource Wildcards.
g_value	A GlgPoint containing XYZ or RGB resource values.

Returns

Success or failure status.

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

See Resource Access Optimization for more.

SetGResourceFromPointIf()

boolean SetGResourceFromPointIf	(	String	resource_name,
		GlgPoint	g_value,
		boolean	if_changed
	)

Sets new values of the object's G (geometrical or color) resource.

Parameters

resource_name	Specifies the resource path of the geometrical or color resource to be set. May use wildcards, see Using Resource Wildcards.
g_value	A GlgPoint containing XYZ or RGB resource values.
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 SetGResourceFromPoint). 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 method sets its new values and returns true, otherwise it generates an error message and returns false.

See Resource Access Optimization for more.

SetGResourceIf()

boolean SetGResourceIf	(	String	resource_name,
		double	x_value,
		double	y_value,
		double	z_value,
		boolean	if_changed
	)

Sets new values of the object's G (geometrical or color) resource.

Parameters

resource_name	Specifies the resource path of the geometrical or color resource to be set. May use wildcards, see Using Resource Wildcards.
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 value is the same as the old one (equivalent to SetGResource). 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 method sets its new values and returns true, otherwise it generates an error message and returns false.

See Resource Access Optimization for more.

SetResourceFromObject()

boolean SetResourceFromObject	(	String	resource_name,
		GlgObject	value
	)

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

Parameters

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 method 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 Optimization for more.

SetResourceFromObjectIf()

boolean SetResourceFromObjectIf	(	String	resource_name,
		GlgObject	value,
		boolean	if_changed
	)

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

Parameters

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 SetResourceFromObject). 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 method 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.

The object type (and data type for the data object) of the resource specified by the resource path should match the type of the value object.

See Resource Access Optimization for more.

SetSResource()

boolean SetSResource	(	String	resource_name,
		String	value
	)

Replaces the string of the object's S (string) resource.

Parameters

resource_name	Specifies the resource path of the string resource to be set. May use wildcards, see Using Resource Wildcards.
value	Specifies a new string.

Returns

Success or failure status.

If a string resource with the given resource path exists, this method sets its the new value and returns true, otherwise it generates an error message and returns false.

See Resource Access Optimization for more.

SetSResourceFromD()

boolean SetSResourceFromD	(	String	resource_name,
		String	format,
		double	value
	)

Sets the value of the object's S (string) resource from a double value, converting the value into a string using a C-style printf format string.

Parameters

resource_name	Specifies the resource path of the string resource to be set. May use wildcards, see Using Resource Wildcards.
format	Specifies the C-style printf format to use (for example, "%.2f").
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 method 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.

See Resource Access Optimization for more.

SetSResourceFromDIf()

boolean SetSResourceFromDIf	(	String	resource_name,
		String	format,
		double	value,
		boolean	if_changed
	)

Sets the value of the object's S (string) resource from a double value, converting the value into a string using a C-style printf format string.

Parameters

resource_name	Specifies the resource path of the string resource to be set. May use wildcards, see Using Resource Wildcards.
format	Specifies the C-style printf format to use (for example, "%.2f").
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 SetSResourceFromD). 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 method 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.

See Resource Access Optimization for more.

SetSResourceIf()

boolean SetSResourceIf	(	String	resource_name,
		String	value,
		boolean	if_changed
	)

Replaces the string of the object's S (string) resource.

Parameters

resource_name	Specifies the resource path of the string resource to be set. May use wildcards, see Using Resource Wildcards.
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 SetSResource). 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 method sets its the new value and returns true, otherwise it generates an error message and returns false.

See Resource Access Optimization for more.