This group contains miscellaneous utility methods. More...

Detailed Description

This group contains miscellaneous utility methods.

Functions
static void	Bell ()
	Emits an audio beep. More...

static void	BellExt (double volume, double frequency, double duration)
	Emits a beeping sound with the specified parameters. More...

static String	ConcatResNames (String resource_name1, String resource_name2)
	Creates a composite resource path from two components. More...

static String	CreateIndexedName (String template_name, int resource_index)
	Creates a string with a name of an enumerated resource. More...

static boolean	EnableTimerXforms (boolean state)
	ADVANCED: Enables or disables all timer transformations defined inside GLG drawings. More...

boolean	Equals (GlgObject object)
	Performs equality comparison between the object passed as the method parameter and the object the method is invoked on. More...

static String	GetLibraryVersion ()
	Returns GLG API library version as a string. More...

static boolean	GetModifierState (GlgModifierType modifier)
	Returns the current state of a modifier. More...

Object	GetNativeComponent (String resource_name, GlgComponentQueryType type)
	ADVANCED: Returns a native component used to render the viewport. More...

static GlgObject	GetReference (GlgObject object)
	Creates a reference to a GlgObject that may be used outside of a callback function. More...

static String	GetStackTraceAsString ()
	Returns current stack trace as a string. More...

static boolean	IsDemo ()
	Queries the type of the GLG library. More...

static boolean	ObjectsEqual (GlgObject object1, GlgObject object2)
	Performs equality comparison between two GLG objects. More...

static String	PrintfD (String format, double value)
	C-style printf method for formatting double values. More...

static String	PrintfI (String format, int value)
	C-style printf method for formatting integer values. More...

static String	PrintfS (String format, String value)
	C-style printf method for formatting strings. More...

static double	Rand (double low, double high)
	Returns a random number in the specified range. More...

static	ReleaseToCache (Object object)
	ADVANCED: Releases an object to a cache for reuse, minimizing garbage collection. More...

boolean	SetCursorType (String resource_name, GlgCursorType cursor_type)
	Sets cursor for the viewport's drawing or one of its child viewports. More...

void	SetFocus (String resource_name)
	Sets the keyboard focus to the object's viewport. More...

static void	ThrowExceptionOnError (boolean user_error, boolean internal_error, boolean detect_null_strings)
	Controls throwing an exception on an error to assist debugging. More...

Function Documentation

◆ Bell()

static void Bell ( )

static

Emits an audio beep.

See BellExt for more control over the audio beep parameters.

◆ BellExt()

static void BellExt	(	double	volume,
		double	frequency,
		double	duration
	)

static

Emits a beeping sound with the specified parameters.

The Bell method uses this method with the following parameters:

BellExt( 0.03, 520, 0.1 );

GlgToolkit.GlgObject.BellExt

static void BellExt(double volume, double frequency, double duration)

Emits a beeping sound with the specified parameters.

Definition: GlgObject.cs:13699

Parameters

volume	The sound volume.
frequency	The sound frequency.
duration	The sound duration in seconds.

◆ ConcatResNames()

static String ConcatResNames	(	String	resource_name1,
		String	resource_name2
	)

static

Creates a composite resource path from two components.

This method is provided to mimic C/C++ API in cases when the C/C++ GLG code is converted to JavaScript.

Parameters

resource_name1	Specifies the first resource path component.
resource_name2	Specifies the second resource path component.

Returns: Created resource path.

This method creates and returns a resource path formed by concatenating the two components with the / character between them. The method checks if a trailing / separator is already present in the first string, and adds it only if the separator is not present.

Either argument may be null, in which case the returned string will precisely equal the input value of the other argument.

Examples

The following code:

let resource_path = GLG.ConcatResNames( "DataGroup", "DataSample2" );

console.log( "resource_path: " + resource_path );

produces the following output:

resource_path = DataGroup/DataSample2

Multiple calls to ConcatResNames may be used to create composite paths from more than two components:

let temp_name = GLG.ConcatResNames( "DataGroup", "DataSample2" );
let resource_path = GLG.ConcatResNames( temp_name, "Value" );
console.log( "resource_path: " + resource_path );

producing the following output:

resource_path: DataGroup/DataSample2/Value

◆ CreateIndexedName()

static String CreateIndexedName	(	String	template_name,
		int	resource_index
	)

static

Creates a string with a name of an enumerated resource.

This method is provided to mimic C/C++ API in cases when the C/C++ GLG code is converted to JavaScript.

Parameters

template_name	A character string containing the template name to be expanded. This name uses the % character to define the expansion position.
resource_index	Specifies the number to use for expanding the % character in the template name.

Returns: Created resource name.

This method creates and returns a resource name by replacing the first (leftmost) occurrence of the % expansion character within the template name with the number corresponding to the resource_index parameter. If the template name does not contain the expansion character, the number is added to the end of the name.

Examples

The following code:

for( let i=0; i<3; ++i )
{
   let name = GLG.CreateIndexedName( "XLabelGroup/XLabel%/String", i );
   console.log( "Name: " + name );
}

produces the following output:

Name: XLabelGroup/XLabel0/String
Name: XLabelGroup/XLabel1/String
Name: XLabelGroup/XLabel2/String

CreateIndexedName may be used repeatedly if a template name has more than one expansion character. For example, the following code:

let name1 = GLG.CreateIndexedName( "Chart%/Plots/Plot#%/Value", 4 );
let name2 = GLG.CreateIndexedName( name1, 3 );
console.log( "Name:" + name2 );

produces the following output:

Name: Chart4/Plots/Plot#3/Value

◆ EnableTimerXforms()

static boolean EnableTimerXforms ( boolean state )

static

ADVANCED: Enables or disables all timer transformations defined inside GLG drawings.

This method may be used to temporarily disable time transformation in some advanced usage scenarios.

Parameters

state The new enabled state.

Returns: Previous value of the enabled state.

◆ Equals()

boolean Equals ( GlgObject object )

Performs equality comparison between the object passed as the method parameter and the object the method is invoked on.

Parameters

object The GlgObject to compare with.

Returns: true if the passed object represents the same internal GLG object as the object the method is invoked on.

◆ GetLibraryVersion()

static String GetLibraryVersion ( )

static

Returns GLG API library version as a string.

The string uses the "N1.N2" format, where N1 is replaced with MAJOR_VERSION and N2 is replaced with MINOR_VERSION, for example, "4.5".

Returns: The string that represents the major and minor version of the GLG JavaScript library.

◆ GetModifierState()

static boolean GetModifierState ( GlgModifierType modifier )

static

Returns the current state of a modifier.

Parameters

modifier

Specifies the modifier to query, may be one of the following constants:

Returns: The current modifier state.

◆ GetNativeComponent()

Object GetNativeComponent	(	String	resource_name,
		GlgComponentQueryType	type
	)

ADVANCED: Returns a native component used to render the viewport.

The method provides an access to native components used to render the viewport, making it possible to set their native properties.

Parameters

resource_name A resource path of a child viewport, or null to query the viewport the method is invoked on. The resource path is relative to the invoking object.

type

The type of a component to retrieve:

WIDGET_QUERY returns the native component used to render the viewport.
SHELL_QUERY returns the top-level DIV element used to host the GLG drawing.
CHILD_WIDGET_QUERY returns native subcomponents of the native toggle button (check box) and list viewports. For these viewport types WIDGET_QUERY returns the DIV container that holds elements used to render these native widgets, while CHILD_WIDGET_QUERY returns the check box's Label element or the DIV element used to scroll the list.
CHILD_WIDGET2_QUERY returns native subcomponents of the native toggle button (check box) and list viewports. For these viewport types WIDGET_QUERY returns the DIV container that holds elements used to render these native widgets, while CHILD_WIDGET2_QUERY returns the check box (Input Checkbox) or the list (Select) element.
SHELL_TITLE_QUERY returns the DIV element used to render the title of viewports with the DIALOG_SHELL and APPLICATION_SHELL settings of the ShellType attributes.
SHELL_CLOSE_BUTTON_QUERY returns the Button element representing the Close (X) button inside the title of the DIALOG_SHELL and APPLICATION_SHELL viewports.

Returns: The retrieved native component.

◆ GetReference()

static GlgObject GetReference ( GlgObject object )

static

Creates a reference to a GlgObject that may be used outside of a callback function.

Parameters

object GlgObject to reference.

Returns: GlgObject that equals to the object parameter and may be used outside of a callback function.

Any object obtained inside a callback without a call to a GLG method that returns an object is not valid outside of a callback. GetReference method should be used to assign such an object to a variable used outside the callback, as shown in the below example:

let StoredGlgObject = null;
 
function TraceCallback( viewport, trace_info )
{
   // Incorrect: can't assign an object received in a callback to a variable outside the callback.
   StoredGlgObject = viewport;
   StoredGlgObject = trace_info.viewport;
 
   // Correct: using GetReference to assign an object received in a callback to a variable outside the callback.
   StoredGlgObject = GLG.GetReference( trace_viewport );
   StoredGlgObject = GLG.GetReference( trace_info.viewport );
 
   // Correct: storing a GLG object received from a call to a GLG API method.
   StoredGlgObject = trace_info.viewport.GetResourceObject( "FillColor" );
}

Note: The only exception from the above rule is a load callback: the loaded object is owned by the application code and can be stored in a variable that is used outside the callback.

◆ GetStackTraceAsString()

static String GetStackTraceAsString ( )

static

Returns current stack trace as a string.

Returns: Stack trace string.

◆ IsDemo()

static boolean IsDemo ( )

static

Queries the type of the GLG library.

Returns: true if the Community Edition version of the library is used.

◆ ObjectsEqual()

static boolean ObjectsEqual	(	GlgObject	object1,
		GlgObject	object2
	)

static

Performs equality comparison between two GLG objects.

Parameters

object1	The first object to check, may be null.
object2	The second object to check, may be null.

Returns: true if both objects represents the same internal GLG object or are both null.

◆ PrintfD()

static String PrintfD	(	String	format,
		double	value
	)

static

C-style printf method for formatting double values.

Parameters

format	C-style format string.
value	Double value to be formatted.

Returns: Formatted string.

◆ PrintfI()

static String PrintfI	(	String	format,
		int	value
	)

static

C-style printf method for formatting integer values.

Parameters

format	C-style format string.
value	Integer value to be formatted.

Returns: Formatted string.

◆ PrintfS()

static String PrintfS	(	String	format,
		String	value
	)

static

C-style printf method for formatting strings.

Parameters

format	C-style format string.
value	String value to be formatted.

Returns: Formatted string.

◆ Rand()

static double Rand	(	double	low,
		double	high
	)

static

Returns a random number in the specified range.

Parameters

low	The low limit.
high	The high limit.

Returns: Generated random number.

◆ ReleaseToCache()

static ReleaseToCache ( Object object )

static

ADVANCED: Releases an object to a cache for reuse, minimizing garbage collection.

Parameters

object An object to be released to the cache, must be an instance of GlgObject, GlgPoint, GlgCube, GlgInteger, GlgMatrixData, or GlgMinMax objects.

The method can be used with any GlgObject, GlgPoint, GlgCube, GlgInteger, GlgMatrixData, or GlgMinMax objects that were obtained by a call to a GLG API method. It cannot be used with objects obtained inside callbacks and stored using an assignment operator without a call to a GLG method.

The method can yield performance improvements for applications with loops that invoke a large number of GLG methods returning GLG objects.

Since all GLG objects are wrappers around the internal representation of the GLG objects, releasing an instance of a wrapper to a cache does not affect the internal GLG object the wrapper represents.

Note: releasing a GlgCube releases its GlgPoint objects.

The following examples demonstrate correct uses of the method:

// Traverse all objects in a viewport.
let size = viewport.GetSize();
for( let i=0; i<size; ++i )
{ 
   let object = viewport.GetElement( i );   // GLG Object
 
   // Apply some action to the object. 
   ...
 
   GLG.ReleaseToCache( object ); 
}
 
// Traverse all points of a polygon. 
let size = polygon.GetSize(); 
for( let i=0; i<size; ++i ) 
{
   // Get polygon point values as GlgPoint.
   let point = polygon.GetElement( i ).GetGResource( null );
 
   // Examine point's x, y and z values as needed. 
   ...
 
   GLG.ReleaseToCache( point ); 
}

The example below shows both valid and invalid uses of the method:

function TraceCallback( viewport, trace_info ) 
{ 
   // Incorrect: can't release an object received in a callback. 
   let trace_viewport = trace_info.viewport;
   GLG.ReleaseToCache( trace_viewport );
 
   // Correct: releasing an object obtained by calling a GLG method. 
   let fill_color = trace_info.viewport.GetResourceObject( "FillColor" ); 
   GLG.ReleaseToCache( fill_color );
 
   // Incorrect: the object is used after being released. 
   var line_width = trace_info.viewport.GetResourceObject( "LineWidth" );
   GLG.ReleaseToCache( line_width ); 
   line_width.SetDResource( null, 3 ); 
}

◆ SetCursorType()

boolean SetCursorType	(	String	resource_name,
		GlgCursorType	cursor_type
	)

Sets cursor for the viewport's drawing or one of its child viewports.

Parameters

resource_name	A resource path of a child viewport, or null to set cursor for the viewport the method is invoked on. The resource path is relative to the invoking object.
cursor_type	One of the system cursor types to be used: DEFAULT_CURSOR CROSSHAIR_CURSOR WAIT_CURSOR HAND_CURSOR MOVE_CURSOR.

Returns: Success or failure status.

The specified cursor will be used when the mouse moves inside the viewport the cursor is assigned to. The drawing's hierarchy must be set up in order to set cursor type.

◆ SetFocus()

void SetFocus ( String resource_name )

Sets the keyboard focus to the object's viewport.

If the target object is a viewport, the focus is set to this viewport, otherwise the focus is set to the target object's parent viewport.

Parameters

resource_name A resource path of a target child object, or null to use the object the method is invoked on. The resource path is relative to the invoking object.

◆ ThrowExceptionOnError()

static void ThrowExceptionOnError	(	boolean	user_error,
		boolean	internal_error,
		boolean	detect_null_strings
	)

static

Controls throwing an exception on an error to assist debugging.

Parameters

user_error	Set to true to throw exceptions on application errors, such as "Can't find resource".
internal_error	Set to true to throw exceptions on internal GLG errors.
detect_null_strings	Set to true to detect null strings being used as values of resources that are GLG data objects of S (String) type. Setting values of these attributes to null strings causes exceptions much later, when the objects are drawn. Setting this parameter to true makes it possible to detect such errors right at the line of code where the resource value is set.

Detailed Description

Functions

Function Documentation

◆ Bell()

◆ BellExt()

◆ ConcatResNames()

◆ CreateIndexedName()

◆ EnableTimerXforms()

◆ Equals()

◆ GetLibraryVersion()

◆ GetModifierState()

◆ GetNativeComponent()

◆ GetReference()

◆ GetStackTraceAsString()

◆ IsDemo()

◆ ObjectsEqual()

◆ PrintfD()

◆ PrintfI()

◆ PrintfS()

◆ Rand()

◆ ReleaseToCache()

◆ SetCursorType()

◆ SetFocus()

◆ ThrowExceptionOnError()