1 Integrating GLG Drawings into a Program
The GLG Graphics Builder is a flexible and powerful tool for the creation and animation of GLG drawings. The GLG Toolkit also provides a variety of ways to incorporate GLG drawings into your applications and supplies several facilities designed to draw and control a GLG drawing from within a user's application program at run time.
The steps for integrating a GLG drawing into a program are straightforward, and most of them are platform-independent:
- 1. Create a GLG drawing in the GLG Builder using one of the File, New, Widget options and add graphical objects, such as predefined components from the Palettes menu or graphical primitives with dynamic actions.
The drawing is encapsulated in a GLG widget, which is a top-level viewport named $Widget with its HasResources attribute set to YES. The drawing is saved in a file with a .g extension. In addition to creating a drawing interactively with the GLG Graphics Builder, it may also be created programmatically at run time using the GLG Extended API Library.
- 2. Load the saved drawing (.g file) into a program and display it in a window. This can be done either using the cross-platform GLG Generic API, or via platform-specific containers:
C/C++The GLG Generic API Library is a platform-independent solution for applications that need source code portability. The GlgInitialDraw method of the Generic API performs all platform-specific initialization, creates a window and displays a drawing in it. Cross-platform methods for handling user interaction are also provided. An application developed using the Generic API can be compiled and executed with no source code changes on both Unix/Linux and Windows.
On Windows, the GLG Custom Control, the GlgControlC MFC class or the GLG ActiveX Control can be used to display a drawing in the C/C++ program.
In Unix/Linux and X Windows environment, several flavors of the GLG Wrapper Widget are provided for integration in the X Windows C/C++ programs.
Qt and GTK wrapper widgets are also provided for integrating drawings into these environments on both Windows and Unix/Linux platforms (refer to the Qt and GTK Integration section on page 48 for more information).
JavaA GLG Java Bean is used to integrate GLG drawings in a Java application, both Swing and JavaFX. The GLG Bean is available as a heavyweight (GlgJBean) or lightweight (GlgJLWBean) Swing component. The GLG Java Class library provides a 100% pure Java version of the GLG Run Time engine.
The GLG Graphics Server class library can be used with the JavaEE Framework to develop server-side AJAX-based applications for web and mobile applications using Java Servlet technology.
C#/.NETA native Windows Form User Control is provided as the GlgControl class, and the GLG .NET DLL provides the GLG Run Time engine for the .NET Framework. The GLG .NET DLL can be used in a cross-platform way using Mono on Linux. On Windows, C#/.NET applications can also use the GLG ActiveX Control.
VB.NET and VB6VB.NET applications can use either the C#-based GLG User Control or the GLG ActiveX Control. The GLG ActiveX Control can also be used in VB6 applications.
- 3. Animate the drawing with real-time data by setting either resources or tags defined in the drawing. This is done using methods of the GLG Standard API.
- 4. Handle user interaction, such as button clicks, mouse click actions, etc.
The following sections of this chapter provide details about each of these steps, and about issues important to GLG Toolkit programmers.
Creating a Widget Drawing
To use a GLG drawing in a program, it has to be encapsulated in a GLG Widget by placing the drawing in a viewport named $Widget. Most drawings are created with the GLG Graphics Builder. Any GLG drawing with a viewport at the top level of its resource hierarchy can become a GLG widget, simply by defining the name of that viewport to be $Widget. The viewport's HasResources attribute must be set to YES in order for its resources to appear inside the viewport.
A drawing can also be created from a program, using the GLG Extended API. The Extended API is described in detail in GLG Intermediate and Extended API on page 121.
If you save a GLG drawing into a file, there are three different file formats it may use:
Displaying a Drawing
Before a drawing can be displayed by a program, it must be loaded into memory. There are three ways to do this:
- A drawing may be stored in a separate file. This lets the user of an application customize the appearance of the widget by editing the file using the GLG Graphics Builder.This option is also very convenient in the development stage, allowing you to modify the drawing without additional compile/debug cycles.
Animating a Drawing with Real-Time Data
A program animates a GLG drawing with application data by setting drawing's resources or tags using methods of the GLG Standard API. These functions are described in Animating a GLG Drawing with Data Using the Standard API on page 63.
Resources are hierarchical and can be used to set properties of specific objects in the drawing when the content of the drawing is known in advance. Tags are global and can be used to animate an arbitrary drawing without knowing its content or resource hierarchy. Tags can be assigned by end users in the GLG HMI Configurator or the GLG Builder to specify the tag source of the process database used to animate a particular dynamic parameter. At run time, an application can query a list of tags defined in the drawing and use information in each tag to obtain data from the process database, animating the drawing with the retrieved data.
A SimpleViewer example provides a sample implementation of a generic GLG viewer that animates an arbitrary drawing using tags. The example provides source code for various programming environments (C/C++/C#.NET/Java/VB.NET). A SCADA_Viewer example provides a sample framework for a more elaborate viewer that also handles drawing navigation, object commands, popup menus and dialogs, as well as alarm display and acknowledgement.
Controlling a Drawing from a Program
A GLG drawing is controlled from a program in the same way it is controlled from the GLG Graphics Builder: by setting and querying resources. Resources can be used to change values of any object properties, from a fill color to object visibility, to a number of plots in a chart. Methods for querying or setting resource values are provided in the GLG Standard API.
The GLG Intermediate API provides additional methods that can be used to traverse all objects defined in the drawing to discover the structure of the drawing, constraint object attributes, perform coordinate conversion or implement custom object manipulation, such as dragging objects with the mouse.
Finally, the GLG Extended API provides methods for creating drawings programmatically at run time. It includes methods for creating objects, adding or deleting objects from the drawing, as well as creating and attaching dynamics to objects.
The Intermediate and Extended APIs are described in GLG Intermediate and Extended API on page 121.
Handling User Input
If the drawing is to accept input from a user, some extra steps must be taken to build it. You may need to add input objects (such as buttons or text boxes) to the drawing, or attach actions (such as a mouse click or a mouse over) to objects in the drawing. The ProcessMouse attribute of a viewport must be set to the desired set of action types to activate processing of actions attached to objects in the drawing.
At run-time, user interaction is handled in the input callback, which is a callback function supplied by the programmer and executed by the GLG Toolkit in response to various possible user actions. A select callback can be used for simplified object selection, and a trace callback can be used to access low-level events of the native windowing system.
A number of pre-built input objects is provided, accessible in the GLG Graphics Builder via the Palettes menu. Custom input objects may also be created as described in the Input Objects of the GLG User's Guide.
Object selection, custom event and command action handling is described in Integrated Features of the GLG Drawing of the GLG User's Guide. The structure of a callback function is described in Handling User Input and Other Events of this manual.
H and V Resources
In the static picture of the GLG drawing architecture that was sketched in the introductory chapters of this guide, all resources are of equal status. All resources are attributes of some object, and they can all be modified or created as the need arises. However, while a drawing is in flux (while it is being drawn, for example), some resources need to be treated differently than others. Because of this need, two different categories of resources exist: those that affect simple values and those that affect the resource hierarchy itself.
The H (hierarchy) and V (value) drawing resources differ in when they are processed by the widget. The H resources are processed before creating the drawing hierarchy, while the V resources are processed after it has been established. The H resources can affect the structure of the hierarchy itself, for example by controlling the number of objects in a series, while the V resources are processed after the specified number of objects in the drawing hierarchy have been created.
A series object, for example, replicates its template object to produce a number of instances. The series' factor defines how many objects appear in that series. Referencing the eighth object in a series makes no sense before the instances of objects are created. The value of the series factor is another example of an H resource. Setting the factor value with a V resource would work, but would introduce inefficiency, since the drawing hierarchy would first be created with the number of series instances defined by the old value, then destroyed and the new number of instances would be created. Other example of H resources are the non-global attributes of a series template. The template is replicated at the time of hierarchy setup, and its attributes have to be set before the hierarchy is set up in order for the instances to inherit the template's attribute values. All H resources are processed before the drawing hierarchy is created, which guarantees that all resources depending on the number of objects in the drawing hierarchy are accessible.
V resources are used for setting resources that depend on the structure of the drawing hierarchy or that do not exist or are inaccessible before creating the hierarchy. Consider an example where the GLG Toolkit, in a program called "example," reads a bar graph with 10 data samples from a drawing file. We'd like to change the number of data samples to 100 and to have the color of the 25th data sample appear red when the widget is displayed.
Using H and V Properties of Native Controls
Let's start with setting the value of the "DataGroup/Factor" resource of the widget to 100. Because this resource affects the hierarchy of the drawing, we use an H resource. Using the X Windows protocol for setting resource values, we might use a line in the configuration file such as:example*XtNglgHResource0 "DataGroup/Factor d 100"
Using the OCX control for Microsoft Windows, it would be:
HProperty0: DataGroup/Factor d 100
Using a V resource to set this value would make the GLG Toolkit create a drawing with 10 data samples, discard it, and create another drawing with 100 data samples. Careful use of H and V resources can avoid this kind of inefficiency.
Now we want to set the color of the 25th data sample to be red. However, the original drawing has only 10 data samples; so the 25th data sample does not exist in the drawing. Because of the 25th data sample does not exist until all the H resources are processed, its color cannot be set using H resources. Trying to do so generates an error message saying that the resource cannot be accessed.
To change the color of a graphical object, you only change the value of a data object in the hierarchy; you do not change the hierarchy. Therefore, a V resource is appropriate for this purpose. These are treated after the specified data sample has been created and is accessible. The line in the configuration file for our example program would then look like this:example*XtNglgVResource0 "DataGroup/DataSample24/FillColor g 1. 0. 0."
Note that since the index is zero-based, the number 24 is used to access the 25th data sample.
Using the OCX control for Microsoft Windows, it would be:
VProperty0: DataGroup/DataSample24/FillColor g 1. 0. 0.
To set the resources that do not depend on the number of objects in the drawing hierarchy, you may use either H or V resources. For example, you can set a background color of the widget's drawing using either kind of resource. Note, however, that many resource names depend on the structure of the resource hierarchy to be accurately interpreted.
Handling H and V Resources in the Program Code
When the GLG API is used to set drawing resources, the same considerations apply. To increase the efficiency of your application program and avoid errors, insure that all the H resources that need setting are set first, before the V resources. In our example above, the Factor resource should be set first, then the GlgUpdate function should be called, and then the V resources set:GlgSetDResource( drawing, "BarGraph/DataGroup/Factor", 100. ); GlgUpdate( drawing ); GlgSetGResource( drawing, "BarGraph/DataGroup/DataSample24/FillColor", 1., 0., 0. );
The GLG Toolkit contains a small number of utility programs for use by an application programmer:
Generates a variety of data streams used for testing and prototyping. It is primarily used inside the GLG Graphics Builder for animating the drawing with simulated data in the Run mode.
Creates a memory image of a GLG drawing in the C language format. The output of the utility is a file with .c extension, containing the image of the drawing in a form of the C source code. The output file can be compiled into the program's executable, making it possible to create a single program executable and eliminate a need to distribute additional drawing files.
Converts drawing files from one GLG format to another; can also be used to change resources of a drawing in a batch mode using the -command or -script command line options.
A GLG drawing file may have one of three different formats: binary, ASCII, or extended. Binary drawings are the fastest to load from the memory image, but ASCII drawings are more portable. The extended format is used to port drawings to different versions of the toolkit.
These tools are described in detail in GLG Programming Tools and Utilities on page 385.
Generic Logic, Inc.