This group contains methods used to load, set up and display a GLG drawing. More...

Detailed Description

This group contains methods used to load, set up and display a GLG drawing.

Functions
static void	AddGlobalListener (GlgCallbackType type, Function callback)
	ADVANCED: Adds a global listener for the TemplateLoad events. More...

boolean	ConfigureWindow (int x, int y, int width, int height, GlgConfigureMask mask, GlgObject parent)
	Sets the size and/or position of a viewport's window. More...

static int	GetPendingInstances ()
	Returns a number of subdrawing and subwindow objects that are waiting for their templates being loaded. More...

static int	GetPendingTemplates ()
	Returns a number of subdrawing and subwindow templates that are in the process of being loaded. More...

void	InitialDraw ()
	Draws a GLG viewport object for the first time after it has been created or loaded. More...

static void	LoadAsset (String url, GlgHTTPRequestResponseType request_type, Function callback, Object user_data, String user, String password)
	Loads an asset from a URL. More...

static GlgObject	LoadObject (Object data, String encoding, String base_path, GlgObject rebind_ref)
	Loads a GLG object from raw data using the specified encoding. More...

static void	LoadObjectFromURL (String url, String encoding, Function callback, Object user_data, function abort_func, GlgObject rebind_ref)
	Loads a GLG object from a URL using the specified encoding, with an ability to abort or rebind. More...

static GlgObject	LoadWidget (Object data, String encoding, String base_path)
	Loads a viewport named $Widget from raw data using the specified encoding. More...

static GlgObject	LoadWidgetFromObject (GlgObject glg_object)
	Finds a viewport named $Widget inside an object and returns it. More...

static void	LoadWidgetFromURL (String url, String encoding, Function callback, Object user_data, function abort_func)
	Loads a viewport named $Widget from a URL using the specified encoding. More...

boolean	Reset ()
	Reinitializes the viewport's drawing by resetting its drawing hierarchy, then setting it up again and rendering the drawing. More...

void	ResetHierarchy ()
	Resets the object hierarchy of the object. More...

static void	SetCanvasScale (double scale, double text_scale, double native_text_scale, double pixel_offset_scale, double screen_coord_scale)
	Specifies parameters of the coordinate scaling used to render GLG drawings in HTML canvas on mobile devices. More...

static void	SetCustomLoadFunc (Function custom_load_func)
	ADVANCED: Sets a custom load function callback. More...

static void	SetCustomURLFormatter (Function formatter_func)
	ADVANCED: Sets a custom URL formatter. More...

void	SetParentElement (String element_id)
	Specifies a parent DIV element to use for the viewport's drawing. More...

void	SetupHierarchy ()
	Provides an explicit request to set up the object hierarchy of the object without rendering it. More...

boolean	Update ()
	Updates the drawing of a viewport or a light viewport with the latest resource values. More...

void	UpdateSize ()
	Updates the size of the top viewport. More...

Function Documentation

◆ AddGlobalListener()

static void AddGlobalListener	(	GlgCallbackType	type,
		Function	callback
	)

static

ADVANCED: Adds a global listener for the TemplateLoad events.

The listener is used to perform any subdrawing initialization that needs to be done after their object hierarchy has been set up. See TemplateLoadCallback for more information, including alternative ways to handle TemplateLoad events.

For the GLG event listeners, see AddListener.

Parameters

type	Callback type: TEMPLATE_LOAD_CB.
callback	A callback function with the type signature matching the type signature of the TemplateLoadCallback entry point of GlgTemplateLoadListener. This function will be invoked to handle TemplateLoad events generated by subdrawings and subwindows when their templates are loaded.

◆ ConfigureWindow()

boolean ConfigureWindow	(	int	x,
		int	y,
		int	width,
		int	height,
		GlgConfigureMask	mask,
		GlgObject	parent
	)

Sets the size and/or position of a viewport's window.

The method is new in the GLG release 4.5. The method should be invoked only for the viewport objects, not the light viewports.

Parameters

x	Specifies X coordinate of the window origin in device pixels.
y	Specifies Y coordinate of the window origin in device pixels.
width	Specifies window width in device pixels.
height	Specifies window height in device pixels.
mask	Specifies flags that can be combined with bitwise OR to control the action to perform, set size, set position or both: POSITION_MASK requests to set window position using x and y parameters and ignore the position defined by the viewport's control points. For top-level viewports, the x and y parameters specify position in screen coordinates relative to the origin of the screen. For child viewports and embedded dialog viewports, position parameters specify position relative to the origin of their parent viewport's window. SIZE_MASK requests to set window size using width and height parameters and ignore the width and height defined by the viewport's control points. POSITION_AND_SIZE_MASK requests to set both the size and position, is equivalent to: POSITION_MASK \| SIZE_MASK GlgToolkit.GlgConfigureMask.SIZE_MASK @ SIZE_MASK Set size mask. GlgToolkit.GlgConfigureMask.POSITION_MASK @ POSITION_MASK Set position mask. RESET_POSITION_MASK resets the position request to restore the position defined by the viewport's control points. RESET_SIZE_MASK resets the size request to restore the width and height defined by the viewport's control points. The set and reset flags are exclusive and can't be used together for the same size or position attribute.
parent	Reserved, must be null.

Returns: Success or failure status.

Once the viewport's size or position is set using ConfigureWindow, the viewport's control points are no longer used for controlling the viewport's size and/or position. If only the viewport's position is set and not its size, the size will be still controlled by the viewport's control points, and vice versa if only the size is set and not the position. The mask parameter of the method contains options to restore the use of the control points for determining the viewport's size or position after it was set with ConfigureWindow.

Note: The method's x, y, width and height parameters must be integer values. Any non-integer parameter value should be truncated using the Math.trunc function to avoid exceptions when a debugging library with strict type checking is used.

◆ GetPendingInstances()

static int GetPendingInstances ( )

static

Returns a number of subdrawing and subwindow objects that are waiting for their templates being loaded.

Returns: The number of pending subdrawing and subwindow instances.

◆ GetPendingTemplates()

static int GetPendingTemplates ( )

static

Returns a number of subdrawing and subwindow templates that are in the process of being loaded.

Returns: The number of pending subdrawing and subwindow templates.

◆ InitialDraw()

void InitialDraw ( )

Draws a GLG viewport object for the first time after it has been created or loaded.

The method displays a viewport's drawing and is part of the GLG Generic API.

The method creates a top level window and renders the viewport's drawing in it.

InitialDraw is equivalent to the following sequence:

viewport.SetupHierarchy();

viewport.Update();

Follow this link for additional information on setting up subdrawings and subwindows.

◆ LoadAsset()

static void LoadAsset	(	String	url,
		GlgHTTPRequestResponseType	request_type,
		Function	callback,
		Object	user_data,
		String	user,
		String	password
	)

static

Loads an asset from a URL.

The asset data are loaded asynchronously and a callback is invoked when the data are ready.

Parameters

url	Asset URL.
request_type	A type of the asset to load: one of the values of the GlgHTTPRequestResponseType enum, such as GLG_DRAWING, TEXT, BLOB, UINT8_ARRAY, etc.
callback	A callback function to be invoked when the asset data has been loaded, with the following type signature: void callback( Object loaded_data, Object user_data, String load_path ); where: loaded_data is the loaded asset data in the requested format user_data is the user_data parameter passed to LoadAsset load_path is the full URL path used to load the asset.
user_data	An object that will be passed to the callback.
user	An optional username for HTTP Basic Authentication, enabling credential-based access to protected resources.
password	An optional password for HTTP Basic Authentication.

NOTE: Do not hardcode usernames or passwords as literal strings. For enhanced security, users should enter these credentials via a dialog box over an HTTPS connection.

The GLG HTML5 demos and examples in the GLG installation directory provide examples of using LoadAsset in various application scenarios.

◆ LoadObject()

static GlgObject LoadObject	(	Object	data,
		String	encoding,
		String	base_path,
		GlgObject	rebind_ref
	)

static

Loads a GLG object from raw data using the specified encoding.

The raw data may be obtained using the LoadAsset method with the GLG_DRAWING request type.

Parameters

data	The raw data to load the object from (Uint8Array).
encoding	Defines encoding to be used for string decoding, "ascii", "latin1" or "utf8". Pass null to use the default Latin1 encoding. The encoding is used to decode all input strings that do not have the UTF8 flag set. The S (string) data objects with the UTF8 flag are always decoded using UTF8.
base_path	An optional load path of the drawing object represented by the data parameter, or null. If any image, subdrawing or subwindow objects are present in the drawing, the images' ImagePath and the subdrawings' SourcePath attributes will be interpreted relative to the base_path.
rebind_ref	The reference object to use for rebinding if the loaded object will be used as a template via SetTemplate, or null otherwise.

Returns: The loaded object or null if loading fails.

◆ LoadObjectFromURL()

static void LoadObjectFromURL	(	String	url,
		String	encoding,
		Function	callback,
		Object	user_data,
		function	abort_func,
		GlgObject	rebind_ref
	)

static

Loads a GLG object from a URL using the specified encoding, with an ability to abort or rebind.

This method is similar to LoadAsset, but provides additional parameters to abort the loading process as soon as possible, as well as to perform data rebinding when the method is used to load a subdrawing or subwindow template.

Parameters

url	Defines a URL of the drawing.
encoding	Defines encoding to be used for string decoding, "ascii", "latin1" or "utf8". Pass null to use the default Latin1 encoding. The encoding is used to decode all input strings that do not have the UTF8 flag set. The S "S" (string) data objects with the UTF8 flag are always decoded using UTF8.
callback	A callback to be invoked when the GLG object has been loaded, with the following type signature: void callback( GlgObject loaded_object, Object user_data, String load_path ); where: loaded_object is the loaded GLG object user_data is the user_data parameter passed to LoadObjectFromURL load_path is the full URL path used to load the object.
user_data	User data to be passed to the callback.
abort_func	An optional function used to check if the load request was canceled while it was being processed, with the following type signature: void abort_callback( Object user_data ); where: user_data is the user_data parameter passed to LoadObjectFromURL. The function will be invoked when the browser finishes loading the object's raw data, but before deserializing it into a GLG object. If the function returns true, the load process will be aborted. If it returns false, the loading process will proceed to create GLG objects from the loaded raw data. Pass null to disable the abort callback.
rebind_ref	The reference object to use for rebinding if the loaded object will be used as a template, or null otherwise. This parameter is used when a subdrawing template object is explicitly loaded by an application code before being passed to SetTemplate.

◆ LoadWidget()

static GlgObject LoadWidget	(	Object	data,
		String	encoding,
		String	base_path
	)

static

Loads a viewport named $Widget from raw data using the specified encoding.

The raw data may be obtained using the LoadAsset method with the GLG_DRAWING request type.

Parameters

data	The raw data to load the widget from (Uint8Array).
encoding	Defines encoding to be used for string decoding, "ascii", "latin1" or "utf8". Pass null to use the default Latin1 encoding. The encoding is used to decode all input strings that do not have the UTF8 flag set. The S (string) data objects with the UTF8 flag are always decoded using UTF8.
base_path	An optional load path of the object represented by the data parameter, or null. If any image, subdrawing or subwindow objects are present in the drawing, the images' ImagePath and the subdrawings' SourcePath attributes will be interpreted relative to the base_path.

Returns: Loaded viewport or null if loading fails.

This method loads an object from raw data and searches it for a viewport object named $Widget. If the viewport is found, it references and returns it, otherwise it produces an error message and returns null.

◆ LoadWidgetFromObject()

static GlgObject LoadWidgetFromObject ( GlgObject glg_object )

static

Finds a viewport named $Widget inside an object and returns it.

Parameters

glg_object An object containing the $Widget viewport.

Returns: The found $Widget viewport or null if the search fails.

◆ LoadWidgetFromURL()

static void LoadWidgetFromURL	(	String	url,
		String	encoding,
		Function	callback,
		Object	user_data,
		function	abort_func
	)

static

Loads a viewport named $Widget from a URL using the specified encoding.

Parameters

url	Defines a URL of the drawing.
encoding	Defines encoding to be used for string decoding, "ascii", "latin1" or "utf8". Pass null to use the default Latin1 encoding. The encoding is used to decode all input strings that do not have the UTF8 flag set. The S (string) data objects with the UTF8 flag are always decoded using UTF8.
callback	A callback to be invoked when the widget has been loaded, with the following type signature: void callback( GlgObject viewport, Object user_data, String load_path ); where: viewport is the loaded widget viewport user_data is the user_data parameter passed to LoadWidgetFromURL load_path is the full URL path used to load the widget.
user_data	User data to be passed to the callback.
abort_func	An optional function used to check if the load request was canceled while it was being processed, with the following type signature: boolean abort_callback( Object user_data ); where: user_data is the user_data parameter passed to LoadWidgetFromURL The function will be invoked when the browser finishes loading the widget's raw data. If the function returns true, the load process will be aborted. If it returns false, loading process will proceed to create GLG objects from the loaded raw data. Pass null to disable the abort callback.

This method loads a drawing from a URL and searches the drawing for a viewport object named $Widget. If the viewport is found, it references and returns it, otherwise it produces an error message and returns null.

◆ Reset()

boolean Reset ( )

Reinitializes the viewport's drawing by resetting its drawing hierarchy, then setting it up again and rendering the drawing.

Calling Reset restores all volatile resource changes to the values the resources had when the widget was first drawn. It also discards currently displayed chart data, unless the chart Persistent attribute is set to true.

The method should be invoked only for the top-level viewports, not the child viewports or the light viewports.

Returns: true if the drawing has been successfully reinitialized, otherwise false.

◆ ResetHierarchy()

void ResetHierarchy ( )

Resets the object hierarchy of the object.

Resets the object hierarchy of a top-level viewport. If a viewport containing a drawing was displayed using the InitialDraw, this method erases the drawing.

Warning: Do not confuse this method with the Reset method, which is used to redraw a displayed drawing and to regenerate the object hierarchy.

◆ SetCanvasScale()

static void SetCanvasScale	(	double	scale,
		double	text_scale,
		double	native_text_scale,
		double	pixel_offset_scale,
		double	screen_coord_scale
	)

static

Specifies parameters of the coordinate scaling used to render GLG drawings in HTML canvas on mobile devices.

Parameters

scale	Specifies canvas coordinate scale. The screen coordinates used to draw graphics in the canvas will be bigger than the Cascading Style Sheet (CSS) pixel coordinates by the scale value. This is used for HTML pages with responsive design rendered on mobile devices with devicePixelRatio different from 1, or when browser zoom is in effect in a desktop browser, which changes devicePixelRatio as well. If the scale is set to 1 (default) when devicePixelRatio > 1, each GLG screen coordinate will correspond to several physical pixels. As a result, thin lines with LineWidth=1 will be rendered several physical pixels thick. The drawing will also be rendered in a small size (in the GLG screen coordinates) equal to the size of the GLG area in CSS pixels, which will not look good. Setting the scale to a value bigger than 1 increases canvas resolution by the specified scale. For example, specifying scale equal to devicePixelRatio on mobile devices causes each GLG screen coordinate to correspond to one physical pixel, resulting in very crisp rendering of thin lines. The drawing will also be rendered in a size in the GLG screen coordinates which is bigger (by the specified scale) than the size of the GLG area in CSS pixels. For example, if the width of the GLG area in CSS pixels is 300 and the value of devicePixelRatio=3 is passed as the scale parameter, the drawing will be rendered with width=900 in the GLG screen coordinates. The scale lower than devicePixelRatio can also be used to control the crispness of the rendering. For example, scale=2 can be used even if devicePixelRatio=3 to make lines a bit thicker for better visibility. If scale is set to a value different from 1, all values in the CSS pixel coordinates must be converted to the GLG screen coordinates by multiplying them by the scale before passing them to any GLG methods as GLG screen coordinates. For example, mouse_x and mouse_y cursor coordinates received by the Trace callback are in CSS pixels, and must be multiplied by the scale before using them as GLG screen coordinates. The x, y, width and height parameters of the ConfigureWindow method should also be in the GLG screen coordinates.
text_scale	Specifies a text scaling factor (default 1). When canvas resolution is increased by setting scale > 1, all fixed size text objects appear scaled down by the same scale because canvas text is rendered in screen coordinates, making text too small to be readable. The only exception is the resizable text objects with a TextScaling attribute that scales them on resize, since they are automatically scaled up when the drawing size in GLG screen coordinates is increased due to scale > 1. The text_scale parameter may be used to increase text size of non-scalable text to make it more readable. On mobile devices, text_scale may be set to a value which is less than the canvas' scale to avoid the text being too big.
native_text_scale	Specifies a scaling factor (default 1) for native text, such as text inside the buttons, checkboxes and other native HTML objects. The text in native HTML objects used in the drawing is scaled by the browser using CSS pixels and is not scaled down when canvas' scale > 1. As a result, the text may appear unproportional to the size of the text objects drawn in a GLG drawing canvas when canvas' scale > 1. The parameter may be set to a value < 1 to adjust text size of native objects to match the size of the text objects in the GLG drawing.
pixel_offset_scale	Specifies a scaling factor (default 1) for values in the GLG drawing that use pixel coordinates, such as pixel offsets of the GLG pixel offset transformations, MarkerSize, as well as the AchorOffset of text objects. Pixel offsets are used to control layout of GLG real-time charts. When fixed size text used by the chart axes increases due to the canvas' text_scale setting, the pixel offsets must be increased as well to allow more space for rendering chart axes labels. Setting pixel_offset_scale to the same value as text_scale adjusts the actual value of pixel offsets proportionally to the text scaling.
screen_coord_scale	Specifies a scaling factor (default 1) for fixed scale viewports that use screen coordinates. This parameter may be set to a value different from 1 to scale objects inside fixed scale viewports. When fixed scale viewports' sizes are controlled by the pixel offset transformations, screen_coord_scale may be set to the same value as pixel_offset_scale to scale content of these viewports proportionally to their sizes.

This method should be invoked at the beginning of the program code before the first GLG drawing has been set up or drawn. If the method is invoked just once, the canvases used to render GLG drawings will be scaled as an image when the browser zoom is used in desktop browsers, resulting in a pixelized image.

To avoid pixelization when browser content is zoomed, the method should be invoked on window resize events, as shown in the GLG demos and examples. On mobile devices, the resize even is not generated and canvases are always scaled as images.

Refer to the code of the GLG JavaScript Demos for examples of the method's usage.

◆ SetCustomLoadFunc()

static void SetCustomLoadFunc ( Function custom_load_func )

static

ADVANCED: Sets a custom load function callback.

The custom load function will be invoked to load data using a custom loading method instead of default loading from a URL. For example, an application may use axios.get as an alternative load method.

Parameters

custom_load_func A custom loading function.

The custom load function will be invoked every time GLG needs to load data, such as drawings, subdrawings or assets. When the data has been loaded, the function must call the provided done_callback callback with the request status and request data parameters.

The custom load function is not invoked for images. The SetCustomURLFormatter method may be used instead of SetCustomLoadFunc for customized loading of both drawings and images.

The custom load function is invoked to perform the actual data loading, with the following type signature:

boolean custom_load_func( String url, String http_response_type, GlgHTTPRequestResponseType glg_request_type, Function done_callback );

GlgToolkit.GlgHTTPRequestResponseType

GlgHTTPRequestResponseType

GLG responce type constants.

Definition: GlgObject.cs:24244

where:

url - the URL be loaded.
http_response_type - the XMLHttpRequest response type to be used for loading data.
glg_request_type - the GLG request type (one of the GlgHTTPRequestResponseType enum constants).
done_callback - the callback function to be invoked when the data has been loaded (see below).

The load function may return false to let GLG load the data, or return true to indicate that the function will load the data and will invoke done_callback when the data is ready.

When the data are ready, the load function must invoke the done function (the function it receives as the done_callback parameter). The done function has following type signature:

void done_func( int status, Object data );

and has to be invoked with the following parameters:

status - the returned status of XMLHttpRequest: 200 on success or a different value to indicate an error.
data Loaded data, or null in case of a load error.

◆ SetCustomURLFormatter()

static void SetCustomURLFormatter ( Function formatter_func )

static

ADVANCED: Sets a custom URL formatter.

The custom URL formatter may be used to load drawings, assets and images stored in a database instead of a web server's file system. The formatter is invoked for any URLs before the URL is used for loading, with the URL string passed as a parameter. The formatter can convert the URL string to map it to a different URL, for example, redirecting it to a database. The formatter returns the converted URL string that will be used for loading.

Parameters

formatter_func A custom URL formatter function.

The formatter is invoked to remap URL strings, with the following type signature:

String formatter_func( String url, boolean is_image );

where:

url the URL to be loaded.
is_image - true if the URL string is used to load an image, false otherwise.

The formatter may return null to use the original URL string as is, or return a modified URL string that points to a new location.

If both the custom URL formatter and the custom load function are supplied, the modified URL will be passed to the custom load function to be loaded.

◆ SetParentElement()

void SetParentElement ( String element_id )

Specifies a parent DIV element to use for the viewport's drawing.

Parameters

element_id The element ID for the getElementById method, for example "glg_area".

◆ SetupHierarchy()

void SetupHierarchy ( )

Provides an explicit request to set up the object hierarchy of the object without rendering it.

When invoked on a drawing which has been loaded but not yet displayed, the method sets up the drawing's object hierarchy to prepare the drawing for rendering. The drawing should contain either a top-level viewport object, or a group containing several top-level viewports.

After the initial draw (when the object hierarchy has already been set up), the method can be used to set up any type of object after its resources were changed. Unlike fref Update, SetupHierarchy sets up the object without repainting it.

Note: For drawings containing reference objects (subdrawings and subwindows), SetupHierarchy initiates the process of loading their templates, but does not wait for the load process to finish. The browser loads the templates asynchronously, and the Hierarchy listener is invoked for each subdrawing object when its template loaded. The Template Load listener is also invoked after each template has been loaded.

The Input listener also receives a message with Format="TemplateLoad" after each template has been loaded. The GetPendingTemplates and GetPendingInstances methods may be used to find if all subdrawings have finished loading their templates, in which case the methods return 0.

The SCADAViewer/HTML5/SCADAViewer/GlgViewer.js file in the GLG installation directory provides an example of using both the Hierarchy and Input listeners to handle subdrawings and subwindows.

◆ Update()

boolean Update ( )

Updates the drawing of a viewport or a light viewport with the latest resource values.

Returns: true if the drawing has been successfully updated, otherwise false.

If the object is a light viewport, an update of its parent viewport will be performed. All resource changes are held until the Update method is called.

Follow this link for additional information on setting up subdrawings and subwindows.

Note: Some drawing resources affect the object hierarchy of the drawing. For example, the Factor attribute of a series object controls the number of template instances that will be created by the series. If a number of instances is increased by setting the series' Factor, the new instances will be created and their resources can be accessed only after the Update or SetupHierarchy method is invoked. If the series object is not persistent, any change (either increase or decrease) of its Factor attribute recreates its instances, and either the Update or SetupHierarchy method should be called before accessing resources of the series' instances.

◆ UpdateSize()

void UpdateSize ( )

Updates the size of the top viewport.

This method is invoked on top viewports embedded in HTML to force an immediate size update to fit the parent DIV element after the DIV size change.

Detailed Description

Functions

Function Documentation

◆ AddGlobalListener()

◆ ConfigureWindow()

◆ GetPendingInstances()

◆ GetPendingTemplates()

◆ InitialDraw()

◆ LoadAsset()

◆ LoadObject()

◆ LoadObjectFromURL()

◆ LoadWidget()

◆ LoadWidgetFromObject()

◆ LoadWidgetFromURL()

◆ Reset()

◆ ResetHierarchy()

◆ SetCanvasScale()

◆ SetCustomLoadFunc()

◆ SetCustomURLFormatter()

◆ SetParentElement()

◆ SetupHierarchy()

◆ Update()

◆ UpdateSize()