GLG Toolkit, JavaScript Library Documentation

• Overview
• Terminology: Classes, Interfaces and Enums
• Global and Instance Methods
• Predefined Constants
• Standard, Intermediate and Extended APIs
• Type Checking and Debugging
• Global Configuration Resources
• GLG JavaScript Library Layout
• Modular Version of the GLG JavaScript Library
• Free Community Edition
• Debugging Libraries
• Using GLG Drawings Created in Various System Locales

Overview

The GLG JavaScript Library is a JavaScript object engine that renders GLG objects in the Web environment via HTML5 and JavaScript. The GLG JavaScript Library provides the same functionality as the corresponding GLG class libraries for Java, C# and C++, with minor differences related to the JavaScript syntax. This allows to share not only the drawings but also the programming logic between the desktop and Web versions of an application.

The Toolkit takes care of the low-level details of the rendering process, such as optimized damage repair, screen-resolution independent coordinate conversion, transparent zooming and panning, double-buffering and other coding-intensive driver-level tasks. It provides a high-level graphical object model which allows an application developer to concentrate on the logic of the application, speeding up the development process and dramatically increasing the developer's productivity.

The Toolkit contains the Graphics Builder, a graphical editor used to create graphical objects and define their attributes and dynamic properties without tedious programming. The resulting drawing is then saved into a file and loaded into a web-based application using the supplied GLG JavaScript library. A simplified HMI Configurator for end users is also provided.

Terminology: Classes, Interfaces and Enums

Even though the JavaScript is a dynamically typed language, this documentation uses "class" and "type" terms for describing GLG objects as well as their methods and parameters. For example, the GlgObject "class" is a JavaScript object that provides methods that can be applied to an instance of GlgObject of any type, such as a polygon or a viewport.

A few utility "classes", such as GlgPoint, GlgCube, GlgTraceData, etc., are used to pass data to and from the GLG object engine. There are also several helper classes, such as GlgInputListener, GlgTraceListener, etc., that define type signatures of various callback functions.

Similar to the way it is used in other languages, the term "interface" is used to describe an object with a predefined set of methods.

When describing API methods, each parameter of a method as well as its return value lists their expected "types" in a way similar to how it is done for the strongly typed languages. This makes it easier to document each method's input and output. Passing a parameter of a wrong "type" will cause a run time exception, see i_debug.

Most constants are organized into groups based on their usage. Each group uses a separate JavaScript object, which is called an "enum", see i_constants for more information.

Global and Instance Methods

Description of each "class" in this online documentation provides a list of its instance methods, which are invoked on the object instance. For example:

viewport.Update();

A "class" description also contains global methods that are invoked on the GLG handle object that represents an instance of the GLG Toolkit library and is obtained via a "new GlgToolkit()" call at the application start-up. These methods are listed with the "static" prefix to distinguish them from the instance methods. For example:

let GLG = new GlgToolkit();
GLG.LoadWidgetFromURL( "drawing.g", null, LoadCallback, null );

Each method's description includes expected parameter types, as well as a type of the returned value. For example, the GetResourceObject method that expects a string parameter and returns a GLG object, is documented as:

GlgObject GetResourceObject( String resource_name );

See Programming Notes for more information on using the GLG JavaScript API.

Predefined Constants

For methods that use predefined integer constants, the constants are grouped using an "enum" term, with the "enum" name listed as a type. For example, the GetObjectType method returns an integer object type using constants defined in the GlgObjectType "enum", which is an object containing GLG object type constants. The method is documented as:

GlgObjectType GetObjectType();

All "enums" are defined as properties of the global GLG handle object, which makes it easier to find constants using auto-completion. See the Constants and Enums section for more information and examples.

Additionally, there are a few constants (such as version number constants, as well as coordinate mapping and GIS constants), that are also properties of the global GLG handle object.

Standard, Intermediate and Extended APIs

The Toolkit provides three levels of a programming interface: Standard, Intermediate and Extended APIs.

• Standard API(Glg.js and either GlgToolkit.js or GlgToolkit.mod.js files) provides methods for loading the drawing created in the Graphics Builder, displaying and updating it with dynamic data, as well as handling user interaction (selecting objects with the mouse, pressing buttons, etc.)
  
  
• Extended API (GlgExt.js and either GlgToolkitExt.js or GlgToolkitExt.mod.js files) provides methods for creating objects programmatically, as well as methods for extended object manipulation (adding or deleting objects at run time, dragging objects with the mouse, traversing the object hierarchy, querying a list of object resources, etc.), supplying an application with all the functionality available in the Graphics Builder at run-time.
  
  
• Intermediate API (GlgInt.js and either GlgToolkitInt.js or GlgToolkitInt.mod.js files) provides all functionality of the Extended API the dynamic object creation at run time.

See Programming Notes for information on using the GLG JavaScript API.

Type Checking and Debugging

Supplying a non-integer value for an integer parameter (such as the index parameter of the GetElement method), is an error, and will generate an exception if the supplied debugging version of the GLG library is used. The debugging library performs type checking of all method parameters and generates an exception if an incorrect parameter type is detected. It is recommended that the debugging library is used for the development, and a production library is used only for the deployment, after thorough testing of all code branches.

When debugging GLG java script in a web browser, the default error handler logs GLG errors to the browser console. The ThrowExceptionOnError method can be used to throw exception on error to assist debugging.

Global Configuration Resources

Global configuration resources may be used to control some aspects of the GLG Toolkit run-time behavior. Refer to the Appendix A: Global Configuration Resources chapter of the GLG Programming Reference Manual for a list of the global configuration resources.

GLG JavaScript Library Layout

The GLG JavaScript Library consist of two components:

• Glg<suffix>.js script file contains the GLG object engine.
• GlgToolkit<suffix>.js file provides API binding.

There are several variants of the above files with different suffixes described in the next sections.

The gunzip.min.js ZLib library is used with the GLG JavaScript library for uncompressing compressed files.

Modular Version of the GLG JavaScript Library

Starting with the GLG release 4.5, both modular and non-modular versions of the GLG JavaScript Library are provided. The modular version uses the GlgToolkit.mod.js file with an additional .mod suffix. For example, GlgToolkit.mod.js is the modular version that is imported as a module, while GlgToolkit.js is the non-modular version that is inserted in an HTML file as a script.

Free Community Edition

GlgCE.js and either GlgToolkitCE.js or GlgToolkitCE.mod.js files provide a free Community Edition of the GLG JavaScript Library and includes all GLG APIs.

Debugging Libraries

Debugging version of each library is provided to make it easier to detect errors during application development. The name of the debugging library is formed by adding the Debug suffix to the library name: GlgDebug.js, GlgIntDebug.js, GlgExtDebug.js and GlgCEDebug.js.

The debugging library uses the same GlgToolkit<*>.js file without the Debug suffix as the deployment library.

Using GLG Drawings Created in Various System Locales

In JavaScript, the UTF-8 encoding is used to import strings containing non-ASCII characters in different languages. To load GLG drawings contaning these characters in a JavaScript program, the drawings have to be converted to UTF-8 using the GLG drawing converter.

Refer to the Deploying GLG Drawings Created in Different System Locales section of the Using the JavaScript Version of the Toolkit chapter of the GLG Programming Reference Manual for more information.