PREV NEXT

Generic Logic, Inc. www.genlogic.com


2 Using the C/C++ version of the Toolkit

2.1 Displaying a GLG Drawing

The first step in operating a GLG drawing from a program is to display that drawing. GLG drawings are environment and platform-independent, as are many of the aspects of controlling and modifying the drawings. The task of displaying the drawings in a display window, however, is peculiar to the windowing system and environment in use.

This chapter describes the task of creating and displaying a GLG drawing in C and C++ programs used in different windowing environments: X Windows on Unix/Linux and Windows.

This chapter contains three sections:

The Windows version of the GLG Toolkit also includes the GLG ActiveX Control, an ActiveX component providing full GLG functionality. The GLG ActiveX control allows GLG drawings to be embedded and used in a variety of user applications and environments supporting ActiveX controls, such as VB.NET, C++ and C#/.NET. For more information, see Using the ActiveX Control on page 245.

C++ applications may also use provided C++ classes to instantiate a GLG drawing as a class in a C++ program. The GLG Toolkit provides classes for instantiating a GLG drawing in both Xt, Motif and MFC environments, as well as cross-platform classes that use GLG Generic API and may be used in either environment. See GLG C++ Bindings on page 221 for more information.

The provided Qt and GTK integration examples demonstrate how to deploy GLG drawings in the Qt and GTK applications.

The Java version of the toolkit uses either the GLG Java Bean or the GLG Generic API provided by the GlgObject class to load and display the drawing.

The C#/.NET version uses either the native .NET GlgControl or the GLG Generic API. Refer to Using the Java and C# Versions of the Toolkit on page 279 for more information.

The JavaScript version of the toolkit uses the GLG Generic API to load and display the drawing on a web page in HTML.

X Windows and GLG Wrapper Widget

This section describes how to use the C/C++ version of the GLG library in the Linux/Unix and
X Windows environment. Refer to GLG C++ Bindings on page 221 for details on the GLG C++ classes. Refer to the GLG Custom Control for Windows section on page 38 for a description of using GLG on Windows.

The GLG Wrapper Widget is a widget wrapper around the GLG library used to embed GLG drawings into existing Xt and Motif interfaces. After the wrapper widget is instantiated in an application's widget hierarchy, it loads and displays a GLG drawing, providing the GLG API to update the display with new data and access GLG objects in the drawing.

There are three basic steps involved in displaying a GLG drawing within an X Windows graphical environment. The first step is creating a GLG Wrapper Widget to contain the drawing. The GLG Toolkit provides both a Motif version of this widget, which inherits its attributes from the XmManager Motif class, and the Xt version of the widget, which inherits its attributes from the simpler Constraint class.

The two versions of the GLG Wrapper Widget are nearly identical in usage. The only difference is that the Xt version of the wrapper widget doesn't support native Motif input objects (buttons, scrollbars, etc.), which will be displayed as empty boxes when displayed in the Xt version of the widget. Use the Motif version when Motif compliance is necessary for your application, or if your drawing includes native input widgets. If neither of these are true, you can use the Xt version. You choose whether to use the Motif or the Xt version of the GLG Wrapper Widget at link time, by specifying either the Motif or Xt-based GLG library. The Xt-based GLG library is provided for Linux and certain other platforms. For information about linking with GLG libraries, see Integrating GLG Drawings into a Program.

After the widget is created and the drawing displayed, a program must acquire a viewport handle (or object ID) to use with the rest of the GLG API. Finally, when the program's execution is completed, it must close the widget and drawing. Briefly, the tools for these steps are as follows:

These steps are described in detail in the sections that follow.

Creating the Wrapper Widget

An application program creates a GLG Wrapper Widget the same way it creates any other widget. Use the XtCreateWidget function from the X Toolkit, and the GlgWrapperWidgetClass from the GLG Toolkit.

Graphical objects to be displayed inside the widget are defined by a supplied GLG drawing. The drawing used for a widget defines the type of the widget and its appearance.

Synopsis

To create a GLG Wrapper Widget with the XtCreateWidget function, use the following arrangement of include files in your program:

#include <X11/StringDefs.h>
#include <X11/Intrinsic.h>
#include "GlgWrapper.h"

Create the widget with a call to the X toolkit:

widget = XtCreateWidget( name, glgWrapperWidgetClass,... );

Wrapper Widget Resources

The Xt version of the GLG Wrapper Widget is a subclass of the Xt Constraint class, while the Motif version is a subclass of the XmManager class. Like other widgets, the GLG Wrapper Widget is controlled by querying and setting resources.

Warning: The resources of an X widget like the GLG Wrapper Widget are part of a different set of resources from the resources of a GLG drawing. The structure is similar, but the application is different. X resources refer to the data structure that makes up an entire screen, while the GLG resources only refer to the animated drawing. The two sets do interact; you can use the X resources of the GLG Wrapper Widget to set values for the GLG drawing resources. However, the two must not be confused.

The following sections describe the resources of the GLG Wrapper Widget. The entire list of resources is summarized in the table on page 37.

Loading the Drawing

There are three resources of the GLG Wrapper Widget you can use to define the source of the GLG drawing to be displayed:

XtNglgDrawingFile
A character string specifying the name of the GLG drawing file.
XtNglgDrawingObject
An object ID of an already-loaded viewport object to be used by the GLG Wrapper Widget. The drawing might have been loaded from a file or an image, or generated with the GLG Extended API.
XtNglgDrawingImage
A long integer specifying the memory address of the drawing's memory image. This must be used in conjunction with XtNglgImageSize, which must contain an integer defining the size of that memory image. This is acquired from the gcodegen utility.

NOTE:
XtNglgDrawingImage does not work with compressed drawing files. Save drawings with the drawing compression option disabled to use them as images.

One of these three resources must be defined when a GLG Wrapper Widget is created. If all three are defined, XtNglgDrawingFile is used. If the file cannot be read, a warning message is generated, then XtNglgDrawingImage is used as a fall back resource. If none of these resources are defined or none of them are readable, an Xt error message is generated.

The drawing specified by the XtNglgDrawingFile or XtNglgDrawingImage resource must have a viewport named $Widget at the top level of the drawing's hierarchy. If this condition is not satisfied, the drawing is not recognized as a valid drawing for the GLG Wrapper Widget. The HasResources flag of the viewport should be set to YES. For information about drawing resources, see Structure of a GLG Drawing.

The GLG Wrapper Widget manages the geometry of GLG graphical objects inside it, including any children GLG widgets represented by viewport objects. When the geometry of the widget is changed, it rubberbands all contained objects accordingly.

Setting the Drawing Resources

The GLG Wrapper Widget allows access to all the resources of the GLG drawing it contains in two different ways. After a drawing is displayed, you can use functions from the GLG API to manipulate drawing resources. The manipulation can happen either within the same process that started the GLG Wrapper Widget or from a remote process.

You can also set initial values for drawing resources using the resources of the GLG Wrapper Widget itself. Because the resource hierarchy of a drawing is infinitely variable, it is not feasible to allocate a separate GLG Wrapper Widget resource for every corresponding GLG drawing resource. Instead, the wrapper widget has a fixed number of dynamic resources which are not associated with any particular drawing resource but are simply used as entry points to access the drawing resource hierarchy.

You can also use the XtSetArgs function to manipulate the drawing resources through the GLG Wrapper Widget resources. However, this is a clumsy mechanism for an application program, and is not recommended. Using the GLG API gives an application program much finer control over when the drawing is updated and does not incur Xt resource setting overhead.

The GLG Wrapper Widget contains two sets of twenty resources, named XtNglgHResource0 to XtNglgHResource19 and from XtNglgVResource0 to XtNglgVResource19. (The difference between H and V resources is discussed in the H and V Resources section of Integrating GLG Drawings into a Program.) These resources contain character strings which in turn contain the names and values of GLG drawing resources. The strings have the following syntax:

<resource_name>  <resource_type>  <values>
<resource_name>
The name of the GLG drawing resource, including the complete path (omitting the "$Widget"). For example, "XLabelGroup/XLabel4/String" accesses the text string of the fifth label on the X axis in a graph widget.
<resource_type>
The type of the resource and can be one of the following:
d Indicates the resource value is represented by a single floating point number (a scalar), like a line width, a font number or a value of a data sample
s The resource value is a string, like a text string of a label text object
g The resource value is a set of three floating point numbers, like a geometrical point with X, Y and Z coordinates or a color, in which case the three components represent the color's Red, Green, and Blue values.
<values>
A value or a set of values for the resource. The values given depend on the resource type.

The following strings are examples of specifying resources:

	"DataGroup/DataSample3/Value d 2.5"
	"DataGroup/DataSample5/Value d 4"
	"XLabelGroup/XLabel4/String s April"
	"DataGroup/DataSample6/FillColor g 0.5 0 0.9"

The GLG Wrapper Widget does not need forty different dynamic resources of this type. In one sense, it would be adequate to have just one, and call it repeatedly. However, it is often useful to be able to keep the initial values of drawing resource in the X resource database, or in the X configuration files. Having many of these dynamic resources allows an application program to set several different drawing resources from the X resource database.

In the event that there are not enough GLG Wrapper Widget dynamic resources for your purpose, you can use the XtNglgHInitCB and XtNglgVInitCB callbacks to set the initial resources using functions of the GLG API.

Callback Resources

The XtNglgHInitCB callback is called after the viewport object containing the widget's drawing has been created, but before the drawing hierarchy is created, allowing you to set H resources from the callback function itself. You can use the GLG API functions to do this, although you cannot modify the drawing itself with the Extended API from within one of these callback functions.

Setting H resources in this callback before the hierarchy is created eliminates the possible inefficiencies that arise when setting an H resource overrides an already existing part of the object hierarchy. The call_data parameter of the callback is not used.

The XtNglgVInitCB callback is called after the widget's drawing hierarchy has been created, but before its graphical objects are drawn, allowing you to set V resources that depend on the number of objects in the hierarchy. These resources may be used to set the attributes of the created instances of objects for the initial appearance.

The XtNglgSelectCB callback is invoked after each mouse click event and provides a list of objects selected with the mouse.

The XtNglgInputCB callback is invoked after each user interaction with objects in the drawing and provides additional information which may be used to handle input events.

Trace callbacks (XtNglgTraceCB and XtNglgTrace2CB) can be used in addition to the input and selection callbacks to handle low-level events. If attached, these callbacks are invoked for any native event received by any of the drawing's viewports. The trace callback is invoked just before processing the event by the select and input callbacks, and the trace2 callback is invoked after the event has been processed.

The XtNglgHierarchyCB callback is invoked when SubWindow or SubDrawing objects in the widget's drawing load their templates. The callback is invoked twice: before the hierarchy setup of the template and after the hierarchy setup but before the template is drawn.

For more information about the input, select, trace and hierarchy callbacks, refer to Callback Events on page 103 of this manual.

The Motif version of the GLG Wrapper Widget also provides Motif-style XtNglgMotifSelectCB and XtNglgMotifInputCB callbacks, which receive the GlgInputCBStruct and GlgSelectCBStruct callback structures as parameters. These structures are defined in the GlgWrapper.h include file and provide a Motif-style callback interface. The GlgInputCBStruct structure contains message_obj parameter, and the GlgSelectCBStruct structure contains the selection_list parameter, providing the same functionality as the other styles of these callbacks. Refer to Callback Events on page 103 of this manual for details.

Sequence of Events

When a GLG Wrapper Widget is realized with a GLG drawing in it, the following sequence of events occurs:

1. The GLG drawing (supplied by the XtNglgDrawingFile or XtNglgDrawingImage resource) is loaded.
2. All current values of XtNglgHResource<N> resources are applied to the drawing.
3. The XtNglgHInitCB callback is invoked (if supplied).
4. The drawing hierarchy is set up.
5. All current values of XtNglgVResource<N> resources are applied to the drawing.
6. The XtNglgVInitCB callbacks is invoked (if supplied).

Setting the XtNglgDrawingFile and XtNglgDrawingImage resources after the widget has been realized loads the new drawing and discards all changes made to the old drawing. After reloading a new drawing file or image, the widget executes the same initialization sequence described above. Note that applying the current values of the GLG Wrapper Widget resources may generate an error message if some of the drawing resources specified are not applicable for the new drawing. To avoid the error message, set the offending wrapper widget resource to NULL.

Summary of GLG Wrapper Widget Resources

When creating a GlgWrapper widget instance, the following resources are retrieved from the argument list or from the resource database:

GLG Wrapper Widget Resource Summary
Name
Type
Default
Description
XtNglgDrawingFile
String
NULL
Name of the file containing a GLG drawing.
XtNglgDrawingImage
XtPointer
NULL
Address of the memory image of a GLG drawing.
XtNglgImageSize
long
0
Size of the memory image.
XtNglgHResource0
XtNglgHResource1
...
XtNglgHResource19
String
String
 
String
NULL
NULL
 
NULL
Entry points for accessing
H resources of graphical objects in the drawing.
XtNglgVResource0
XtNglgVResource1
...
XtNglgVResource19
String
String
 
String
NULL
NULL
 
NULL
Entry points for accessing
V resources of graphical objects in the drawing.
XtNglgHInitCB
XtCallback list
NULL
Callback list for setting initial values of H resources using convenience functions.
XtNglgVInitCB
XtCallback list
NULL
Callback list for setting initial values of V resources using convenience functions.
XtNglgSelectCB
XtCallback list
NULL
Callback list for selecting objects in the widget.
XtNglgMotifSelectCB
XtCallback list
NULL
Callback list for selecting objects in the widget, Motif-style callback structure format.
XtNglgInputCB
XtCallback list
NULL
Callback list for the input activity in the widget.
XtNglgMotifInputCB
XtCallback list
NULL
Callback list for the input activity in the widget, Motif-style callback structure format.
XtNglgTraceCB
XtCallback list
NULL
Callback list for trace callbacks.
XtNglgTrace2CB
XtCallback list
NULL
Callback list for trace2 callbacks.
XtNglgHierarchyCB
XtCallback list
NULL
Callback list for hierarchy callbacks.

Obtaining a Viewport Handle

To use any of the functions from the GLG API, you must get an object ID for the main viewport of the drawing. This is the one called $Widget. (See page 34.) To obtain this object ID from the widget, use the XglgGetWidgetViewport function.

GlgObject XglgGetWidgetViewport( widget )
	Widget widget;
Parameters
widget
The Xt widget ID that specifies the GLG Wrapper Widget.

The GLG Wrapper Widget contains a viewport. The viewport manages all aspects of the drawing widget's behavior and appearance. When accessing resources or performing any other operations on a GLG drawing, the object ID returned by XglgGetWidgetViewport is passed as a "handle" identifying the viewport. The viewport is created only after the GLG Wrapper Widget has been realized, so this function returns NULL if called before then.

Closing the Wrapper Widget

To close the GLG Wrapper Widget gracefully, use the XtDestroyWidget function from the X Toolkit. It accepts only one argument, the widget ID returned by the XtCreateWidget function.

XtDestroyWidget( widget )
	Widget widget;

GLG Custom Control for Windows

This section describes how to use the C/C++ version of the GLG library on Windows using the Win32 API. Refer to GLG C++ Bindings on page 221 for details of the GLG C++ and MFC classes. Refer to Using the ActiveX Control on page 245 for a description of using the GLG ActiveX control.

The GLG Custom Control is a Windows wrapper designed for embedding GLG drawings in the programs using a Win32 API. It allows embedding GLG drawings into the Windows interface hierarchy as a custom window control (a window with a custom window type). The GLG Custom Control manages the geometry of GLG graphical objects in it, including any child GLG widgets represented by nested viewport objects. When the geometry of the Control window changes, it proportionally resizes all the GLG objects inside it.

The first step in displaying a GLG drawing in the Windows environment is creating a window data structure to contain that drawing. This is the GLG Custom Control. After the window is created and the drawing displayed, a program must acquire a viewport handle (or object ID) which is used for updating the drawing with data via the GLG API. Finally, when the program's execution is completed, it must close the window and drawing. Briefly, the tools for these steps are as follows:

These steps are described in detail in the sections that follow.

Creating the GLG Custom Control

There are four steps involved in displaying a GLG drawing within the Microsoft Windows environment:

1. Read a GLG drawing into the program. This can be done from a file, with GlgLoadWidgetFromFile, or from memory, with GlgLoadWidgetFromImage.
2. Use GlgSetDefaultViewport to identify the viewport to be used as the drawing widget.
3. Create a Custom Control using the drawing. This is done with the CreateWindow function from the Microsoft Windows API. The Microsoft Windows class of the GLG Custom Control is GlgControl.
4. Use GlgInitialDraw to draw the initial drawing. You can delay this step until after you use GlgGetWindowViewport to create a widget ID for the GLG drawing. At that point, you can use either GlgInitialDraw or a combination of GlgSetupHierarchy and GlgUpdate.

The following example shows how to create a GLG Custom Control:

#include "GlgApi.h"

HWND GlgControl;
GlgObject drawing;
drawing = GlgLoadWidgetFromFile( "BarGraph.g" );
GlgSetDefaultViewport( drawing );
GlgControl = CreateWindow( "GlgControl", "GlgControlTest",  WS_VISIBLE 
| WS_CHILD | WS_BORDER, 50, 50, 100, 150, 
parent, NULL, hInstance, NULL );
(LPVOID) GlgInitialDraw( drawing );

Note that only one GLG Custom Control can be attached to each instance of the loaded drawing. To display several copies of a drawing, you must load or copy several instances of it into memory, creating each control with the CreateWindow function.

Setting Initial Resources

A GLG drawing represents a hierarchy of graphical objects. This hierarchy is created when the drawing is used in a GLG Custom Control. If your application needs to change a resource that affects the structure of a drawing's resource hierarchy, the most efficient way is to do it before the drawing hierarchy is created (that is, before using the drawing to create a GLG Custom Control).

For example, if you want to change the number of bars in a bar graph's drawing, you should do it before using the drawing for creating a GLG Custom Control:

HWND GlgControl;
GlgObject BarGraphDrawing;
BarGraphDrawing = GlgLoadWidgetFromFile( "BarGraph.g" );
/* Setting the number of bars in the bar graph to 30. */
GlgSetDResource( BarGraphDrawing, "DataGroup/Factor", 30. );
GlgControl = CreateWindow( "GlgControl", "BarGraph Custom Control", 
WS_VISIBLE | WS_CHILD | WS_BORDER, 50, 50, 100, 150, 
parent, NULL, hInstance, NULL );
GlgInitialDraw( BarGraphDrawing );

Resources that must be set before creating the hierarchy include factors of series objects, templates of series objects, Global attribute flags and some others. These are called H resources, and are described in the H and V Resources section of Integrating GLG Drawings into a Program.

Some resources, like attributes of an individual instance of the series object's template, may be accessed only after the drawing hierarchy is created. These are the V resources. For example, setting an initial value of the first bar in the bar graph must be done after the bar instances are created:

double GetData();
HWND GlgControl;
GlgObject BarGraphDrawing;
BarGraphDrawing = GlgLoadWidgetFromFile( "BarGraph.g" );
GlgControl = CreateWindow( "GlgControl", "BarGraph Custom Control", 
WS_VISIBLE | WS_CHILD | WS_BORDER, 50, 50, 100, 150, 
parent, NULL, hInstance, NULL );
GlgSetupHierarchy( BarGraphDrawing );
/* Setting the value of the first data sample for the initial 
appearance. */
GlgSetDResource( BarGraphDrawing, "DataGroup/EntryPoint", GetData() );
GlgUpdate( BarGraphDrawing ); /* Draw control's graphics */

The rest of the resources may be changed at any time, although remember that if you want to change some resources for the initial appearance of the control, do it before the call to the GlgUpdate or GlgInitialDraw functions.

Obtaining a Viewport Handle

To use any of the functions from the GLG API, you must get an object ID for the main viewport of the drawing. This is the one called $Widget. (See page 34.) To obtain this object ID from the widget, use the GlgGetWindowViewport function.

GlgObject GlgGetWindowViewport( glg_control_window )
	HWND glg_control_window;

The glg_control_window argument is the Window ID returned by the CreateWindow function. If a window other than a GLG Custom Control is passed as a parameter, the result is undefined. The viewport handle is the return value of this function.

A viewport is a GLG Toolkit object which manages all aspects of the GLG Custom Control's behavior and appearance. When accessing resources or performing any other operations on the Control, the viewport handle is passed as a parameter to the functions of the GLG API Library.

Closing the Custom Control

At the end of a program's execution, you should use the DestroyWindow Windows function to close the GLG Custom Control in an orderly fashion. By default, this is done for you when you exit the program.

Messages

The GLG Custom Control provides a window procedure to work with the Windows environment.

The GLG Custom Control creates its own color palette and handles palette related messages. However, Microsoft Windows sends palette messages to the top level window only, therefore the application program must be responsible for propagating these messages to the GLG Custom Control. A similar situation obtains with some focus messages, as shown in the example below.

An example of how messages are propagated to the GLG Custom Control is shown in the following example:

extern HWND GlgControl;    /* A children window. */
LRESULT CALLBACK MyWindowProc( hWnd, iMessage, wParam, lParam )
	HWND hWnd; 
	UINT iMessage; 
	WPARAM wparam;
	LPARAM lparam;
{
	switch( iMessage )
	{
		/* Propagate palette messages to the Control. */
		case WM_PALETTECHANGED:
		case WM_QUERYNEWPALETTE:
			if( GlgControl )
	   		   return
				 GlgControlWindowProc( GlgControl, iMessage, wParam, 
lParam );
		/* Let the Control know about focus change, etc. */
		case WM_SETFOCUS:
		case WM_KILLFOCUS:
		case WM_CANCELMODE:
			if( GlgControl )
	   		   GlgControlWindowProc( GlgControl, iMessage, wParam, lParam 
);
			break;
		... /* Some other application specific cases. */
	}
	return DefWindowProc( hWnd, iMessage, wParam, lParam );
}

The GlgControlWindowProc function has the standard arrangement of windows procedure parameters, whose definitions can be found in Windows programming manuals. It is included in the Windows version of the GLG API library.

Loading and Displaying a GLG Drawing using Generic API

The GLG Generic API can be used to load the drawing into a program and display it in a cross-platform way, freeing the programmer from a need to use platform-specific native integration code. An application written using the simple GLG Generic API can be compiled and run on either Windows or Unix/Linux without any changes to the source code. GLG demos and most of the coding examples use the GLG Generic API and may be compiled and run under both Windows and Unix/Linux X Windows environments.

The following example loads and displays a GLG drawing using the GLG Generic API:

#include "GlgApi.h"
#include "GlgMain.h"

int GlgMain( argc, argv, InitialAppContext )
	int argc;
	char * argv[];
	GlgAppContext InitialAppContext;
{
	GlgObject viewport;

	GlgInit( False, InitialAppContext, argc, argv );

	viewport = GlgLoadWidgetFromFile( "bar1.g" );
	GlgInitialDraw( viewport );

	return GlgMain( InitialAppContext );
}

The GlgMain.h include file defines a cross-platform program entry point, GlgMain.

The GlgInitialDraw function creates a top-level window and displays a GLG drawing in it in a cross-platform way. This code may be compiled and run on both Unix/Linux and Windows platforms. Refer to the GLG programming examples in the examples directory for a complete example of an application that loads, displays and updates GLG drawing with data.

Alternatively, a call to GlgInitialDraw can be split into two equivalent calls, GlgSetupHierarchy and GlgUpdate, to perform any required initialization before displaying the drawing:

GlgSetDResource( viewport, "Chart/NumPlots", 3.);
GlgSetupHierarchy( viewport );  /* Creates 3 plots in the chart. */

/* Set any required plot properties. */
GlgSetDResource( viewport, "Chart/Plots/Plot#2/LineWidth", 3. );
GlgUpdate( viewport );  /* Display the drawing. */

Refer to the The GLG Generic API section on page 51 for the list of Generic API methods, and to GLG C++ Bindings on page 221 for information on using the C++ version of the GLG Generic API.

Coding Examples of Displaying and Animating a GLG Drawing

Subdirectories examples_c_cpp/animation and examples_c_cpp/BarGraph2D in the GLG installation directory contain examples of loading, displaying and animating a GLG drawing using both the Generic API and the native windowing system controls:

Compiling and running Example Programs

Visual Studio projects are provided in each directory for building demos and most of the examples on Windows. On Unix/Linux, makefiles for building demos and examples are provided in the src subdirectory of the GLG installation directory. Refer to the Building GLG Demos and Examples section below for more information.

2.2 Compiling and Linking GLG Programs

Building GLG Demos and Examples

Visual Studio Projects for Windows

On Windows, Visual Studio projects are provided for all GLG demos and most of the example programs. The project files are located in each demo or example directory. To build, simply open a project file in the Visual Studio, select the desired platform (Win32 or x64) and build the solution.

The sample projects use the GLG library in a form of a DLL. Refer to the Using Static GLG Libraries section on page 46 for information about using GLG static libraries.

Makefiles for Unix/Linux

On Unix/Linux, makefiles for building demos and examples are provided in the src subdirectory of the GLG installation directory:

To build a project on Unix/Linux, copy one of the above mentioned makefiles into the project's directory, edit it to define a path to the GLG installation directory and other platform options listed at the beginning of the makefile, then change to the project's directory and use make to build the project using makefile:

cd <project_dir>
make

To use makefile2, rename makefile2 to makefile in the project directory or use the -f option:

cd <project_dir>
make -f makefile2

Using Constant Strings

By default, C++ bindings use constant strings. This may be changed by defining the CONST_CHAR_PTR macro with a value of 0 before including the GlgClass.h file.

The C API uses non-constant strings by default. This can be changed by defining the GLG_C_CONST_CHAR_PTR macro with the value of 1 before including the GlgApi.h file.

Linking with the GLG Libraries

The details of the process of linking an application program with the GLG Toolkit library depends on the operating system and windowing environment where the application will run.

X Windows on UNIX/Linux

The libglg library supplied with the GLG Toolkit contains all functions described in this guide, including the GLG Standard Library and GLG Generic API Library. There are several versions of the library for different programming environments:

For applications that use map server functionality, the libglg_map map server library and the libtiff1 library are also required.

All libraries are provided in the lib subdirectory of the GLG Toolkit installation. The GLG libraries must be included in the link list before the X and Motif libraries. Sample makefiles provided in the src subdirectory of the GLG installation contain additional platform-dependent libraries that may be selected by uncommenting them depending on the platform (refer to the Makefiles for Unix/Linux section on page 43 for more information).

If a static Motif library is used instead of the default shared library, the following libraries must also be included: libXmu, libXft, libXext and libXp. On Solaris and AIX, some extra system libraries (libnsl and libsocket for Solaris, and libiconv for AIX) must also be included, as shown in the sample makefiles.

The linking process also requires libz2, libjpeg3, libpng4 and libfreetype5 libraries and related system libraries. On Linux, these libraries are provided by the OS, but a static version of the libraries is also provided in the lib/syslib directory of the GLG Toolkit installation for reference. On other Unix systems, these libraries are included in the lib directory.

The following line shows a sample of the link statement for the GLG program using the Standard API and the Map Server on Linux platform:

... -lglg -lglg_map -lXm -lXt -lX11 -lz -ljpeg -lpng -ltiff \

-lfreetype -lm -ldl -lpthread ...

If an application does not use the Map Server and GIS functionality, the libglg_map library may be replaced with the libglg_map_stub stub, and the libtiff library may be omitted. The following line shows a fragment of the link statement for the GLG program using the Standard API without the Map Server and GIS functionality:

... -lglg -lglg_map_stub -lXm -lXt -lX11 -lz -ljpeg -lpng \

-lfreetype -lm -ldl -lpthread ...

The GLG Extended Library is called libglg_ext. It requires the Standard API library (libglg) as well as all libraries described above. The following two lines show examples of linking with and without the Map Server and GIS functionality:

... -lglg_ext -lglg -lglg_map -lXm -lXt -lX11 -lz -ljpeg -lpng -ltiff \

-lfreetype -lm -ldl -lpthread ...
... -lglg_ext -lglg -lglg_map_stub -lXm -lXt -lX11 -lz -ljpeg -lpng \

-lfreetype -lm -ldl -lpthread ...

The GLG Extended Library can be omitted if an application does not use any of the Extended API functions.

The GLG Intermediate Library libglg_int may be used instead of the GLG Extended Library libglg_ext.

On platforms that support both the 32 and 64 bit executables, the 64 bit versions of libraries and utilities are provided in the lib_64 directory.

Windows

Using GLG DLLs

The DLL version of the GLG Standard Library is called Glg.dll. To use it, link your application with the Glg.lib library.

The GLG Intermediate Library DLL is called GlgIn.dll and includes the GLG Standard API. This means you don't have to link with the Glg.lib if using GlgIn.dll. Link only with the GlgIn.lib library to use the Intermediate API DLL.

The GLG Extended Library DLL is called GlgEx.dll and includes the GLG Standard and Extended APIs. This means you don't have to link with the Glg.lib if using GlgEx.dll. Link only with the GlgEx.lib library to use the Extended API DLL.

Using Static GLG Libraries

Under Microsoft Windows, an application can be linked with either a static or dynamic GLG library. Two versions of static libraries are provided: one compiled with the multi-threaded DLL (/MD) option, and another compiled with the multi-threaded (/MT) option. The libraries compiled with the /MT option use the MT suffix to differentiate them from the libraries compiled with /MD, for example: GlgLibMT.lib vs. GlgLib.lib. A version of the library matching the compilation options of the application code should be used for linking with the GLG static libraries.

The static versions of the GLG Standard API Library are called GlgLib.lib and GlgLibMT.lib.

The static versions of the GLG Intermediate Library are called GlgInLib.lib and GlgInLibMT.lib. They also require linking with the corresponding version of the GLG Standard Library: GlgLib.lib or GlgLibMT.lib.

The static versions of the GLG Extended Library are called GlgExLib.lib and GlgExLibMT.lib. They also require linking with the corresponding version of the GLG Standard Library: GlgLib.lib or GlgLibMT.lib.

The project files supplied with the Toolkit use dynamic linking with the GLG DLLs by default. In order to use the static version of the GLG libraries, define GLG_STATIC in your code:

#define GLG_STATIC 

This must appear before the GlgApi.h file, or it may be specified as a preprocessor definition in the project's settings.

To use the static GLG library, an application code must also include a call to the GlgInit method, passing an explicit application instance as the application context parameter. (If the dynamic library is used, this is done automatically by the DLL's DllMain entry point.)

Using OpenGL in Application Executables

The same application executable may be run in either the OpenGL rendering mode or the native windowing system (GDI) mode. Refer to the Command-line Options section on page 267 of the GLG User's Guide and Builder Reference Manual for information on the command-line options that specify rendering mode to be used at run-time.

Refer to the OpenGL or GDI (Native Windowing System) Renderer section on page 27 of the GLG User's Guide and Builder Reference Manual for information on the OpenGL and GDI drivers.

If the graphics card supports OpenGL version 3.00 and above, a shader-based Core profile may be used for rendering. Refer to the OpenGL Versions, Compatibility and Core Profiles section on page 29 of the GLG User's Guide and Builder Reference Manual for more information on OpenGL versions.

Refer to the OpenGL on Linux Laptops with NVidia Optimus / Bumblebee section on page 31 of the GLG User's Guide and Builder Reference Manual for a detailed description of the libraries used by both hardware and software OpenGL renderers.

Refer to the OpenGL Setup and Diagnostics section on page 31 of the GLG User's Guide and Builder Reference Manual for setup and diagnostic options of the OpenGL driver.

OpenGL Libraries

The hardware renderer on Unix/Linux systems uses the libGL and libGLU libraries provided by the graphics card vendor. These libraries are dynamically loaded by the Toolkit and do not need to be linked in the application executable. If an application uses OpenGL calls itself, it can link the OpenGL libraries, and the Toolkit will use the linked-in libraries.

On Linux, the libGL library from the libgl1-mesa-glx package provides support for hardware acceleration. The libGL library from the libgl1-mesa-swx11 package supports only the software renderer.

For the low-priority software renderer on Unix/Linux, GLG uses the libOSMesa library, as well as the libGLU library which provides some utility functions.

On Linux, the GLG editors use the libOSMesa library provided by the GLG installation in the glg/lib directory for the software renderer. If the libGLU library is not provided by the hardware renderer, the libtess_util library from the glg/lib directory is also used instead of the libGLU library.

The GLG editors and demos are configured to automatically use the libOSMesa library from the GLG installation. If a GLG application wants to use libOSMesa library from the glg/lib directory for the software renderer, it should include glg/lib in LDD_LOAD_PATH or copy the libraries to a place where they will be found by the linker.

An application can also set the GLG_OPENGL_MESA_LIB_PATH environment variable or the GlgOpenGLMesaLibPath global configuration resource to point to the libOSMesa library to be used. Alternatively, -glg-mesa-lib-path command-line option may be used to point to the libOSMesa library. If the GLG_DIR environment variable is set, the library will also be searched in the $GLG_DIR/lib directory.

If the hardware OpenGL is not used, the software OpenGL also needs the libtess_util library. The library will be searched in the directory where the libOSMesa library is located. To specify a different location, use either the GLG_OPENGL_TESS_LIB_PATH environment variable, the GlgOpenGLTessLibPath global configuration resource, or the -glg-mesa-lib-path command-line option.

On Windows, OpenGL uses Opengl32.dll and Glu32.dll libraries. These libraries are always present, but they support the hardware-accelerated renderer only if drivers for a graphics card with the OpenGL support are installed. Otherwise, only the software renderer is enabled. If hardware acceleration is enabled by the graphics card, the OpenGL libraries on Windows support both hardware and software-based rendering, with no additional libraries required.

On both Linux/Unix and Windows, all OpenGL libraries are dynamically loaded at run time if they are available, so that the executable may be used even if the libraries are absent.

Qt and GTK Integration

The GLG Toolkit provides the Qt, GTK and GTKMM integration files in the integration directory which contains a separate subdirectory for each of the environments. Each subdirectory contains an integration example with a source code of a specialized GLG widget for the corresponding environment: QtGLGWidget, GTKGlgWidget and GTKMMGlgWidget. All files required to build the project are also provided.

In the Linux/Unix environment, the libglg_x11 library described above must be used with the integration, since both Qt and GTK do not use Xt.

In the Microsoft Windows environment, the standard GLG library is used with the integration.

Error Processing and Debugging

Default Error Handler

C/C++ Error Handler

All GLG library errors are reported using the GLG default error handler. In the X Windows environment, it prints an error message on the console, and under Microsoft Windows, displays a message box with an error message. On both platforms the default handler also emits an audio beep and logs the error into the glg_error.log file.

Log File Location

The log file will be created in the directory specified by the following environment variables:

GLG_LOG_DIR_<Major>_<Minor>
GLG_LOG_DIR
GLG_DIR_<Major>_<Minor>
GLG_DIR

The environmental variables are searched in the order they are listed above. The <Major> and <Minor> are replaced by the major and minor version numbers, for example GLG_DIR_3_6. If neither variable is defined, the current directory will be used.

Java, C# and JavaScript Error Handler

In the Java version, the errors are printed on the standard output stream or in the Java Console, and the errors are not logged in a file.

The C#/.NET version displays an error message box, beeps and logs the errors into the glg_error.log file, the same as the C/C++ version.

In the JavaScript version, the errors are printed on the browser console and are not logged in a file.

Map Server Error Handler

The Map Server errors are logged in the glm_error.log file, which will be created in the directory specified by the GLM_LOG_DIR_<Major>_<Minor> and GLM_LOG_DIR environment variables. If they are not set, either GLG_LOG_DIR or GLG_DIR versions of environment variables listed above are used to determine the directory in which the Map Server log file will be created. If neither environment variable is defined, the current directory is used.

Installing a Custom Error Handler

To intercept errors or to change this behavior, you may install a custom error handler using the GlgSetErrorHandler function. (This is part of the standard GLG API; see the Animating a GLG Drawing with Data Using the Standard API.). Severe internal errors (like invalid object handles) will still be logged into the glg_error.log file, but errors involved with the use of the GLG Toolkit, like not being able to set or get a resource, will not.

In the X Windows environment, the XtError function is used to report widget-related errors (such as an error setting the wrapper widget's resource). You can use XSetErrorHandler function to install a custom error handler for Xt errors. The XSetErrorHandler function can be used to install a custom error handler for X Windows errors.

Debugging C/C+ Errors

To stop on error in a debugger, set a breakpoint in the GlgDefaultErrorHandler C function. If a custom error handler is installed as described above, the breakpoint can be set in the custom handler function instead of the default error handler.

2.3 The GLG Generic API

This section describes the GLG Generic API for C. Refer to GLG C++ Bindings on page 221 for information on using the C++ version of the GLG Generic API.

If it is important for your application to be cross-platform compatible (or if you don't want to learn another windowing API), you may use the GLG Generic API instead of the GLG Custom Control on WIndows or the GLG Wrapper Widget for Unix/Linux. It contains a generic, platform independent API for creating and manipulating a GLG Widget, as well as a small set of functions for cross-platform development. An application written using the GLG Generic API may be ported between Windows and the Unix/Linux environment by simply recompiling the code. The supplied demos and other coding examples of GLG Generic API may be compiled and run under both Windows and X Windows Unix/Linux environments.

The GLG Generic API is a subset of the GLG Standard API that provides functions for initializing the Toolkit's run time environment, loading a drawing and displaying it in a program using the capabilities of the native windowing system: Windows or X Windows on Unix/Linux. After loading and displaying the drawing, it is animated using the rest of the functions of the GLG Standard API, which are also cross-platform. A coding example of using the Generic API is provided in the Loading and Displaying a GLG Drawing using Generic API section on page 42.

Though the functions provided are all platform-independent, the GLG Generic API library is not intended as a complete cross-platform development library. Instead, it supplies a small set of functions which are sufficient for a platform-independent use of GLG drawings and the GLG Toolkit. It is up to the application developer to write the rest of the application in a platform-independent way.

Function Summary

The GLG Generic API includes the following functions:

These functions are described in detail in the following pages.

Two functions of the GLG Extended API are often used with and are included in the GLG Generic API:

For description of these functions, see GLG Intermediate and Extended API.

Generic Program Entry Point

To define a cross-platform application program's entry point both Unix/Linux and Windows environments, include the GlgMain.h header file at the beginning of the program and define the GlgMain function in the following way:

#include "GlgApi.h"
#include "GlgMain.h"

int GlgMain( argc, argv, InitialAppContext )
	int argc;
	char * argv[];
	GlgAppContext InitialAppContext;
{
	GlgInit( False, InitialAppContext, argc, argv );

	... /* Place code here. */
}

The defined GlgMain function will be called when the program is started. The argc and argv parameters are analogous to the corresponding parameters of the standard main() function. The InitialAppContext parameter must be passed to the GlgInit function as shown above.

GLG Generic API Function Descriptions

In order to use any of the functions in the GLG Generic API, you must include the following header file in your program:

#include "GlgApi.h"

GlgAddCallback

Adds a callback function to a GLG Widget.

void GlgAddCallback( viewport, callback_type, callback, client_data )
	GlgObject viewport;
	GlgCallbackType callback_type;
	GlgCallbackProc callback;
	GlgAnyType client_data;
Parameters
viewport
Specifies the viewport of a GLG Widget. For the GLG_INPUT_CB callback, it may be a light viewport.
callback_type
Specifies the type of a callback to be added, such as GLG_SELECT_CB, GLG_INPUT_CB, GLG_TRACE_CB, GLG_TRACE2_CB or GLG_HIERARCHY_CB. See 1, 2, 3
callback
Specifies a callback function to be called.
client_data
Specifies client data to be passed to the callback function when it is called. See 1, 2

This function adds a selection or input callback to a GLG Widget. A callback is a user-supplied function that is called by the GLG Toolkit upon some action. A selection callback is issued when a user selects an object in the widget's drawing area. An input callback function is invoked when a viewport input handler has received some data.

Only one callback of each callback type may be added to one widget or an individual viewport. Any subsequent invocations of this function will overwrite the previous value of the callbacks. To remove a callback, call GlgAddCallback with NULL as a value of the callback parameter.

Callbacks must be added before the drawing's hierarchy is set up. Several input and selection callbacks may be added to different viewports on different levels of the drawing hierarchy. However, only the first encountered callback on the lowest level of the hierarchy will be called.

For details on the form and use of callback functions, see the Callback Events section of Handling User Input and Other Events.

GlgAddTimeOut

Adds an interval timer in a platform-independent way.

GlgLong GlgAddTimeOut( app_context, interval, timer_callback, 
client_data )
	GlgAppContext app_context;
	GlgLong interval;
	GlgTimerProc timer_callback;
	GlgAnyType client_data;
Parameters
app_context
Specifies the application context returned by the GlgInit function.
interval
Specifies the time interval in milliseconds.
timer_callback
Specifies a procedure to be called when the time expires.
client_data
Specifies the client data to be passed to the specified procedure when it is called.

This function adds a procedure which is called when the specified time interval expires. It returns the timer ID which can be used with GlgRemoveTimeOut. The interval timer is called only once and is removed immediately after it has been called. The GlgRemoveTimeOut function may be used to remove an active timeout. If you want the timer procedure to be called continuously, the timer procedure itself should call GlgAddTimeOut.

The following is a prototype for a timer procedure function:

typedef void (*GlgTimerProc)( client_data, timer_id )
	GlgAnyType client_data;
	GlgLong * timer_id;

The timer_id parameter is the same as the one returned by the GlgAddTimeOut function. The client_data argument is the same as the one supplied in the GlgAddTimeOut function.

GlgAddWorkProc

Adds a work procedure in a platform-independent way.

GlgLong GlgAddWorkProc( app_context, work_proc, client_data )
	GlgAppContext app_context;
	GlgWorkProc work_proc;
	GlgAnyType client_data;
Parameters
app_context
Specifies the application context returned by the GlgInit function.
work_proc
Specifies a work procedure function to be called repeatedly.
client_data
Specifies client data to be passed to the work procedure when it is called.

This function adds a work procedure to a widget. A work procedure is simply a function to be called repeatedly while the application is waiting for an event. It returns a work procedure ID that can be used by GlgRemoveWorkProc.

The following code is the prototype for a work procedure function:

typedef GlgBoolean (*GlgWorkProc)( client_data )
	GlgAnyType client_data;

The client_data argument provides user-defined data to the work procedure. It is defined by the call to GlgAddWorkProc.

If a work procedure returns TRUE, it is removed and will not be called again. If it returns FALSE, it will be called continuously until the application calls the GlgRemoveWorkProc function. You can register several work procedures and they will be performed one at a time. Work procedures must return quickly to avoid response time delays.

GlgBell

Produces a bell sound in a platform-independent way.

void GlgBell( viewport )
	GlgObject viewport;
Parameters
viewport
Specifies a viewport or a light viewport. This viewport object must be displayed; it specifies the display at which to produce the bell. On Microsoft Windows, this parameter is ignored and may be NULL.

GlgInit

Initializes the GLG Toolkit.

GlgAppContext GlgInit( tk_initialized, app_context, argc, argv )
	GlgBoolean tk_initialized;
	GlgAppContext app_context;
	int argc;
	char ** argv;
Parameters
tk_initialized
Specifies whether or not X Toolkit was already initialized by the program. It allows using the GLG Toolkit in an application that creates its own application context. If this parameter is FALSE, the X Toolkit will be initialized by the function. Otherwise, it is assumed that the program has already initialized it.
This parameter is for use only in the X Windows environment and must be FALSE on Microsoft Windows.
app_context
For X Windows, this argument specifies the Xt application context if one has already been created by the program. If NULL is passed, an application context will be created by this function. Otherwise it uses the passed application context.
In Microsoft Windows environment, the argument specifies an application instance handle, which is supplied by a parameter of the GlgMain or WinMain program entry points. In an MFC application, a call to AfxGetInstanceHandle function may be used to obtain application instance handle. If the GLG library is used in the form of a DLL, the application instance handle is obtained automatically and the value of NULL may be used for the argument. If a static GLG library is used, an application instance handle must be supplied explicitly.
argc
Specifies the number of command line parameters. Use zero on Microsoft Windows.
argv
Specifies the command line parameter list. NULL may be used on Microsoft Windows.

If the function creates an application context, it returns the created context, otherwise it returns the application context that was passed to it. The return value is later used with some other functions of the GLG Generic API.

In the X Windows environment, this function is not needed if the GLG is deployed in the form of the GLG Wrapper Widget, which invokes the function automatically. Under Microsoft Windows, this function has to be called only if your program is linked with the static version of the GLG API library. The dynamically linked library (DLL) version calls this function automatically. In both cases, the function may be called explicitly to process command line options recognized by the Toolkit, such as:

-verbose
generates extended diagnostic output. A verbose mode can also be set by setting the GLG_VERBOSE environment variable to True. The output is saved in the glg_error.log file. On Unix/Linux, the output is also displayed in the terminal.
-glg-debug-opengl
generates extended diagnostic output for the OpenGL driver. The output can also be activated by setting the GLG_DEBUG_OPENGL environment variable to True. The output is saved in the glg_error.log file. On Unix/Linux, the output is also displayed in the terminal.
-glg-disable-error-dialogs
Disables error and warning message dialogs on Windows. Alternatively, the dialogs can also be disabled by setting the GLG_DISABLE_ERROR_DIALOGS environment variable to True. The messages will still be logged in the glg_error.log file.
-glg-disable-opengl
disables OpenGL driver in favor of the native windowing driver.
-glg-enable-opengl
enables OpenGL driver if present. The OpenGL driver will be used only for the viewports which have their OpenGLHint attribute set to ON.

The OpenGL driver may also be enabled or disabled by setting either the GlgOpenGLMode global configuration resource or the GLG_OPENGL_MODE environment variable to the following values:

 0 - disable the OpenGL driver
 1 - enable the OpenGL driver
-1 - don't change the default setting.

GlgInitLocale

Sets the program locale.

GlgBoolean GlgInitLocale( locale )
	char * locale;
Parameters
locale
Specifies program locale. The value of NULL may be passed to use the current system locale.

The function invokes setlocale( LC_ALL, locale ) and performs any other platform-dependent locale initialization activity. On Unix platforms, this function must be used before the GlgInit function.

GlgInitialDraw

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

void GlgInitialDraw( viewport )
	GlgObject viewport;
Parameters
viewport
Specifies the viewport of a GLG Widget.

This function is used when a GLG Widget is created. Creating the widget, in this case, means constructing the internal data structures that are the widget. The widget must still be rendered with GLGInitialDraw to be seen by a user. If the GLG Wrapper Widget is used in the X environment, this function is called automatically, and need not be explicitly called.

GlgLoadWidgetFromFile

Loads a GLG widget from a file.

GlgObject GlgLoadWidgetFromFile( filename )
	char * filename;
Parameters
filename
Specifies the name of the widget's drawing file.

This function loads a drawing from a file and searches the drawing for a viewport object named "$Widget." If the viewport is found, it references and returns a handle to it, otherwise it produces an error message and returns NULL. After the viewport has been used to create a GLG Wrapper Widget or GLG Custom Control, it may be dereferenced using the GlgDropObject function to avoid memory leaks.

GlgLoadWidgetFromImage

Loads a GLG widget from a memory image.

GlgObject GlgLoadWidgetFromImage( image_address, image_size )
	void * image_address;
	GlgLong image_size;
Parameters
image_address
Specifies the address of the widget's drawing image generated by the GLG Code Generation Utility.
image_size
Specifies the image size. This is also generated by codegen.

This function loads a drawing from the drawing image and searches the drawing for a viewport named "$Widget." If the viewport is found, it references and returns it, otherwise it produces an error message and returns NULL. After the viewport has been used, it may be dereferenced using the GlgDropObject function.

NOTE: this function does not work with compressed drawing files. Save drawings with the drawing compression option disabled to use them with GlgLoadWidgetFromImage.

GlgLoadWidgetFromObject

Loads a widget from a GLG object.

GlgObject GlgLoadWidgetFromObject( object )
	GlgObject object;
Parameters
object
Specifies a GLG object to be used as a widget's drawing.

This function searches the object to be used as a drawing for a viewport named "$Widget." If the viewport is found, it references and returns it, otherwise it produces an error message and returns NULL. This function could be used to load a widget created by using the GLG Extended API, or to load a sub-section of an already loaded drawing. After the viewport has been used, it may be dereferenced using the GlgDropObject function.

GlgMainLoop

Implements an event polling loop in a platform independent way.

GlgLong GlgMainLoop( app_context )
	GlgAppContext app_context;
Parameters
app_context
Specifies the application context returned by the GlgInit function.

On Microsoft Windows, the return value of this function may be used as the return value of the GlgMain function.

GlgRand

Produces a random number in a platform-independent way.

double GlgRand( low, high )
	double low;
	double high;
Parameters
low, high
Specify the low and high range of the random numbers generated.

This function produces a random number in the specified range by using the platform's rand function.

GlgRemoveTimeOut

Removes a timer procedure.

void GlgRemoveWorkProc( timer_id )
	GlgLong timer_id;
Parameters
timer_id
Specifies the ID of the timer procedure to be removed. The ID was returned by GlgAddTimeOut.

This function removes an active timer. If the timer has already been removed and is not active, the results are undefined.

GlgRemoveWorkProc

Removes a work procedure.

void GlgRemoveWorkProc( workproc_id )
	GlgLong workproc_id;
Parameters
workproc_id
Specifies an id of the work procedure to be removed. The id was returned by GlgAddWorkProc.

This function removes an active work procedure. If the work procedure has already been removed and is not active, the results are undefined.

GlgResetHierarchy

Resets the object hierarchy.

void GlgResetHierarchy( object )
	GlgObject object;
Parameters
viewport
Specifies an object to be reset.

Resets the object hierarchy of a top-level viewport or drawing. This function must be called before destroying a top-level object with GlgDropObject when the object was displayed using the Generic API. This function should not be called for viewports used in the GLG integrated containers, such as the GLG Wrapper Widget or GLG Custom Control.

Warning: Do not confuse this function with the GlgReset function of the standard API. GlgReset is used to redraw a displayed drawing and to regenerate the object hierarchy.

GlgSetupHierarchy

Provides an explicit request to set up the object hierarchy.

void GlgSetupHierarchy( object )
	GlgObject object;
Parameters
object
Specifies an object to be set up.

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 the GlgUpdate method, GlgSetupHierarchy sets up the object without repainting it.

GlgSleep

Suspends the application execution for a specified interval in a platform independent way.

void GlgSleep( sleep_interval )
	GlgLong sleep_interval;
Parameters
sleep_interval
Specifies a sleep interval in milliseconds.

GlgTerminate

Terminates the application's use of the GLG Toolkit.

void GlgTerminate( void )

This function destroys all created GLG structures and frees allocated memory, flushing the internal memory pools. No GLG functions may be called after a call to GlgTerminate.

1Copyright 1988-1997, Sam Leffler. Copyright 1991-1997 Silicon Graphics, Inc.
2Copyright 1995-2002 Jean-loup Gailly and Mark Adler.
3Copyright 1991-1998, Thomas G. Lane, The Independent JPEG Group.
4Copyright 2004, 2006-2014 Glenn Randers-Pehrson.
5Copyright 1996-2000 by David Turner, Robert Wilhelm, and Werner Lemberg, FreeType Team.

Generic Logic, Inc.
www.genlogic.com
PREV NEXT