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/Motif and Microsoft Windows.
This chapter contains three sections. The first two describe the task of loading and displaying a GLG drawing in a window in the X Windows/Motif and Microsoft Windows environments. The third section of this chapter describes the GLG Generic API, a platform-independent set of functions for loading and displaying a GLG drawing. The source code of the applications created using the Generic API is portable between the two windowing systems.
The Microsoft Windows version of the GLG Toolkit also includes the GLG ActiveX Control, an ActiveX component providing GLG functionality using the OLE (Object Linking and Embedding) protocol for Microsoft Windows. The GLG ActiveX control allows GLG drawings to be embedded and used in a wide variety of user applications and environments supporting ActiveX controls, such as Visual Basic, Visual C++, etc. For more information, see Using the ActiveX Control on page 169.
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 151 for more information.
The Java version of the toolkit uses either the GLG Java Bean or GLG Generic API provided by the GlgObject class to load and display the drawing. See Using the Java version of the GLG Toolkit on page 189 for more information.
This section describes how to use the C/C++ version of the GLG library in the Unix and X Windows environment. Refer to GLG C++ Bindings on page 151 for details on the GLG C++ classes. Refer to Microsoft Windows and GLG Custom Control on page 24 for a description of using GLG in the Microsoft Windows environment.
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 Details of using GLG Standard API for C and C++.
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:
To create a GLG Wrapper Widget instance, use XtCreateWidget and specify the class variable GlgWrapperWidgetClass and either the XtNglgDrawingFile, XtNglgDrawingObject , or XtNglgDrawingImage resource.
To destroy a GLG Wrapper Widget, use XtDestroyWidget and specify the widget ID of the GLG wrapper.
To manipulate objects in a viewport of the GLG Wrapper Widget, use
XglgGetWidgetViewport
to create an object ID.
These steps are described in detail in the sections that follow.
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.
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,... );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 23.
There are three resources of the GLG Wrapper Widget you can use to define the source of the GLG drawing to be displayed:
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.
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.
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 H and V Resources of Details of using GLG Standard API for C and C++.) 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>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.
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.
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.
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.
For more information about the input, select and trace callbacks, refer to Callback Events on page 85 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 85 of this manual for details.
When a GLG Wrapper Widget is realized with a GLG drawing in it, the following sequence of events occurs:
The GLG drawing (supplied by the XtNglgDrawingFile or XtNglgDrawingImage resource) is loaded.
All current values of XtNglgHResource <N> resources are applied to the drawing.
The XtNglgHInitCB callback is invoked (if supplied).
The drawing hierarchy is set up.
All current values of XtNglgVResource <N> resources are applied to the drawing.
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.
When creating a GlgWrapper widget instance, the following resources are retrieved from the argument list or from the resource database:
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 20.) To obtain this object ID from the widget, use the XglgGetWidgetViewport function.
GlgObject XglgGetWidgetViewport( widget ) Widget 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.
This section describes how to use the C/C++ version of the GLG library in the Microsoft Windows environment using the Win32 API. Refer to GLG C++ Bindings on page 151 for details of the GLG C++ and MFC classes. Refer to Using the ActiveX Control on page 169 for a description of using the GLG ActiveX control.
The GLG Custom Control is a Windows wrapper designed to display and operate GLG drawings using a low-level Win32 API interface. It allows embedding GLG dynamic graphical objects into the Microsoft Windows interface hierarchy as a custom window control (a window with a custom window type) using a native Windows API. 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 Microsoft 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 ) to use with the rest of 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:
To create a GLG Custom Control instance, load the GLG drawing and use CreateWindow . Other functions from the GLG API are used to set up the drawing hierarchy and display the drawing.
To destroy a GLG Custom Control, use DestroyWindow and specify the Window ID of the control.
To manipulate objects in a viewport of the GLG Wrapper Widget, use
GlgGetWindowViewport
to create an object ID.
These steps are described in detail in the sections that follow.
There are four steps involved in displaying a GLG drawing within the Microsoft Windows environment:
Read a GLG drawing into the program. This can be done from a file, with GlgLoadWidgetFromFile , or from memory, with GlgLoadWidgetFromImage .
Use GlgSetDefaultViewport to identify the viewport to be used as the drawing widget.
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 .
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.
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 H and V Resources of Details of using GLG Standard API for C and C++.
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.
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 20.) 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.
At the end of a program's execution, you should use the DestroyWindow Microsoft Windows function to close the GLG Custom Control in an orderly fashion. By default, this is done for you when you exit the program.
The GLG Custom Control provides a window procedure to work with the Microsoft 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 Microsoft Windows programming manuals. It is included in the Microsoft Windows version of the GLG API library.
This section describes the GLG Generic API for C. Refer to GLG C++ Bindings on page 151 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 or the GLG Wrapper Widget. 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 simple GLG Generic API may be ported from Microsoft Windows to the X Windows environment by simply recompiling the code. The supplied demos and other coding examples of GLG generic API may be compiled and run under both Microsoft Windows and X Windows environments.
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.
The GLG Generic API includes the following functions:
GlgInit initializes the Toolkit.
GlgTerminate terminates the Toolkit and frees any allocated memory.
GlgLoadWidgetFromFile loads a GLG Widget drawing from a file.
GlgLoadWidgetFromImage loads a GLG Widget drawing from a generated memory image.
GlgLoadWidgetFromObject extracts a GLG widget drawing from a GLG object.
GlgSetupHierarchy sets up a GLG Widget's drawing hierarchy.
GlgResetHierarchy resets a GLG Widget's drawing hierarchy in preparation for being dereferenced with GlgDropObject .
GlgInitialDraw draws a GLG Widget for the first time.
GlgAddCallback adds input and selection callbacks to a GLG drawing.
GlgAddWorkProc adds a work procedure.
GlgRemoveWorkProc removes an active work procedure.
GlgAddTimeOut adds an interval timer.
GlgRemoveTimeOut removes an active interval timer.
GlgSleep suspends program's execution.
GlgBell produces a bell sound.
GlgRand generates a random number.
GlgSetDefaultViewport sets a default drawing to be used by the GLG Wrapper Widget or GLG Custom Control.
For detailed descriptions of these functions, see page 30.
Two functions of the GLG Extended API are often used with the GLG Generic API:
GlgReferenceObject increments the reference count of an object.
GlgDropObject decrements the reference count of an object.
For description of these functions, see The GLG Extended API.
To define an application program's entry point in a generic way, include the header file, GlgMain.h , 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.
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 GlgInitialDraw function creates a top-level window and display the GLG drawing in it in a cross-platform way. This code may be compiled and run on both Unix and Microsoft Windows environment. 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.
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"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;Specifies the type of a callback to be added, such as GLG_SELECT_CB, GLG_INPUT_CB, GLG_TRACE_CB or GLG_TRACE2_CB. See Callback Events of Handling Input Events for a description of callback functions. There are also special callbacks used with the GLG Wrapper Widget; see page 21.
Specifies client data to be passed to the callback function when it is called. See Callback Events of Handling Input Events for a description of this data.
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 input and one selection callback 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. The input callback must be added to the top level viewport of the drawing. Several 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 any particular selection.
For details on the form and use of callback functions, see Callback Events of Handling Input Events.
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;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.
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;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.
Produces a bell sound in a platform-independent way.
void GlgBell( viewport ) GlgObject viewport;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.
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.
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:
generates extended diagnostic output. A verbose mode may also be set by setting the GLG_VERBOSE environment variable to True.
disables OpenGL driver in favor of the native windowing driver.
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:
Draws a GLG widget for the first time after it has been created or loaded.
void GlgInitialDraw( viewport ) GlgObject 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.
Loads a GLG widget from a file.
GlgObject GlgLoadWidgetFromFile( filename ) char * 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.
Loads a GLG widget from a memory image.
GlgObject GlgLoadWidgetFromImage( image_address, image_size ) void * image_address; GlgLong image_size;Specifies the address of the widget's drawing image generated by the GLG Code Generation Utility.
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 .
Loads a widget from a GLG object.
GlgObject GlgLoadWidgetFromObject( object ) GlgObject 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.
Implements an event polling loop in a platform independent way.
GlgLong GlgMainLoop( app_context ) GlgAppContext app_context;Produces a random number in a platform-independent way.
double GlgRand( low, high ) double low; double high;Specifies a viewport of a GLG Widget.
This function must be called before destroying a GLG widget with GlgDropObject when the Generic API is used. If the GLG Wrapper Widget or GLG Custom Control are used, this function must not be called.
Warning: Do not confuse this function with the GlgReset function of the standard API. This function is used for a specialized memory management role when the Generic API is in use. GlgReset is used to redraw a displayed drawing and to regenerate the object hierarchy.
Sets a default drawing to be used by the GLG Wrapper Widget or the GLG Custom Control.
void GlgSetDefaultViewport( viewport ) GlgObject viewport;Specifies a GLG viewport object to be used as a widget. The viewport object may be loaded using GlgLoadWidgetFromFile , GlgLoadWidgetFromImage , or GlgLoadWidgetFromObject functions. It may also be created programmatically using functions from the GLG Extended API.
One instance of a viewport may be used to create only one GLG Custom Control or GLG Wrapper Widget since every control or wrapper widget needs its own copy of the viewport. To create several wrapper widgets or custom controls with the same drawing, use GlgCopyObject to create individual drawing instances for each control or widget and then select them using GlgSetDefaultViewport before creating each control or widget. This function references the viewport object.
Provides an explicit request to set up the object hierarchy.
void GlgSetupHierarchy( viewport ) GlgObject viewport;Specifies a viewport of a GLG Widget.
Usually, the hierarchy is set up automatically when the widget is drawn the first time. You need to call this function only if you need to change some hierarchy-dependent resources (V resources) before the widget is drawn. For example, you may want to fill a graph with values before displaying it. In this case, this function must be called explicitly to set up the hierarchy, then the appropriate resources are set and the widget is displayed.
Suspends the application execution for a specified interval in a platform independent way.
void GlgSleep( sleep_interval ) GlgLong sleep_interval;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 .
Both the demonstration and regular versions of the GLG Toolkit come with example programs which show how to create a GLG widget with a bar graph and then animate it with random data.
There are several versions of the example programs:
The version whose name ends with capital "G" uses the GLG Generic API which can be used on both X Windows and Microsoft Windows.
The version ending with "X" shows an example using the GLG Wrapper Widget.