Load, Setup and Display

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

Detailed Description

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

Functions
GlgBoolean	GlgConfigureWindow (GlgObject object, GlgLong x, GlgLong y, GlgLong width, GlgLong height, GlgConfigureMask mask, GlgObject parent)
	Sets the size and/or position of a viewport's window. More...
void	GlgDialogInitialDraw (GlgObject object, GlgObject parent)
	Displays a GLG drawing as a floating dialog for the first time after it has been created or loaded. More...
void	GlgDialogSetupHierarchy (GlgObject object, GlgObject parent)
	Provides an explicit request to set up the object hierarchy of a drawing displayed in a dialog window. More...
GlgAppContext	GlgInit (GlgBoolean tk_initialized, GlgAppContext app_context, int argc, char **argv)
	Initializes GLG Toolkit API. More...
void	GlgInitialDraw (GlgObject object)
	Draws a GLG viewport object for the first time after it has been created or loaded. More...
GlgObject	GlgLoadObject (char *filename)
	Loads an object from a GLG drawing file or a URL. More...
GlgObject	GlgLoadObjectFromImage (void *image, GlgLong size)
	Loads an object from a memory image. More...
GlgObject	GlgLoadWidgetFromFile (char *filename)
	Loads a GLG widget from a GLG drawing file or a URL. More...
GlgObject	GlgLoadWidgetFromImage (void *image, GlgLong size)
	Loads a GLG widget from a memory image. More...
GlgObject	GlgLoadWidgetFromObject (GlgObject object)
	Loads a widget from a GLG object. More...
int	GlgMain (int argc, char *argv[], GlgAppContext context)
	A prototype for the cross-platform program entry point that handles argc and argv parameters the same way on all platforms. More...
GlgLong	GlgMainLoop (GlgAppContext context)
	Implements an event polling loop in a platform independent way. More...
GlgBoolean	GlgReset (GlgObject object)
	Reinitializes the drawing by resetting the drawing hierarchy, then setting it up again and rendering the drawing. More...
void	GlgResetHierarchy (GlgObject object)
	Resets the object hierarchy. More...
void	GlgSetupHierarchy (GlgObject object)
	Provides an explicit request to set up the object hierarchy without rendering the object. More...
void	GlgTerminate (void)
	Terminates the application's use of the GLG Toolkit. More...
GlgBoolean	GlgUpdate (GlgObject object)
	Updates a drawing to show new resource values. More...

Function Documentation

GlgConfigureWindow()

GlgBoolean GlgConfigureWindow	(	GlgObject	object,
		GlgLong	x,
		GlgLong	y,
		GlgLong	width,
		GlgLong	height,
		GlgConfigureMask	mask,
		GlgObject	parent
	)

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

This function is new in the GLG release 4.5.

Parameters

object	Specifies the viewport to be configured.
x	Specifies X coordinate of the window origin.
y	Specifies Y coordinate of the window origin.
width	Specifies window width.
height	Specifies window height.
mask	Specifies bitwise flags that control the action to perform, set size, set position or both: GLG_POSITION_MASK Requests to set window position using x and y parameters and ignore the position defined by the viewport's control points. For top-level viewports, the x and y parameters specify position in screen coordinates relative to the origin of the screen. For child viewports and embedded dialog viewports, position parameters specify position relative to the origin of their parent viewport's window. GLG_SIZE_MASK Requests to set window size using width and height parameters and ignore the width and height defined by the viewport's control points. GLG_POSITION_AND_SIZE_MASK Requests to set both the size and position, is equivalent to: GLG_POSITION_MASK | GLG_SIZE_MASK GLG_RESET_POSITION_MASK Resets the position request to restore the position defined by the viewport's control points. GLG_RESET_SIZE_MASK Resets the size request to restore the width and height defined by the viewport's control points. The set and reset flags are exclusive and can't be used together for the same size or position attribute.
parent	Specifies an optional parent viewport for dialog viewports displayed via the GlgDialogSetupHierarchy or GlgDialogInitialDraw functions, or NULL otherwise.

Returns

Success or failure status.

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

GlgDialogInitialDraw()

void GlgDialogInitialDraw	(	GlgObject	object,
		GlgObject	parent
	)

Displays a GLG drawing as a floating dialog for the first time after it has been created or loaded.

Parameters

object	Specifies the viewport containing the dialog's drawing.
parent	Specifies the viewport of the main drawing the dialog will be a child of.

This function is similar to GlgInitialDraw, with the only difference that the drawing will be displayed as a child dialog of the main drawing specified by the parent parameter.

GlgConfigureWindow may be used to set the dialog's size and position.

GlgDialogSetupHierarchy()

void GlgDialogSetupHierarchy	(	GlgObject	object,
		GlgObject	parent
	)

Provides an explicit request to set up the object hierarchy of a drawing displayed in a dialog window.

Parameters

object	Specifies the viewport containing the dialog's drawing.
parent	Specifies the viewport of the main drawing the dialog will be a child of.

This function similar to GlgSetupHierarchy, with the only difference that the drawing will be set up as a child dialog of the main drawing specified by the parent parameter.

This method needs to be invoked only on the initial draw of the dialog. After the dialog has been set up, a generic GlgSetupHierarchy function may be used for all objects, including the dialog.

GlgInit()

GlgAppContext GlgInit	(	GlgBoolean	tk_initialized,
		GlgAppContext	app_context,
		int	argc,
		char **	argv
	)

Initializes GLG Toolkit API.

On Linux/Unix, this function is automatically invoked if the GLG library is deployed using one of the native GLG widget wrappers.

On Windows, the dynamically linked library (DLL) version of the GLG library automatically calls this function as well. If the static version of the GLG library is used, the function has to be explicitly called by the application.

In either case, it's always a good idea to explicitly call this function at the beginning of the application code, in which case it will also process command-line options recognized by the Toolkit and passed via the argc and argv parameters.

Parameters

tk_initialized	Toolkit initialization parameter. Use False for GTK and Windows. With the legacy X11 version of the GLG library, this parameter 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.
app_context	Application context initialization parameter. With the legacy X11 version of the GLG library, this argument specifies the Xt application context if it has already been created by the program. If NULL is passed, an application context will be created by this function. Otherwise, the provided application context will be used. With the GTK version of the GLG library, the argument is not used and must be NULL. On Windows, the argument specifies an 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. Application instance handle 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.
argc	Specifies the number of command line parameters. On Windows, it will be provided by the GlgMain cross-platform entry point, otherwise zero may be used.
argv	Specifies the command line parameter list. On Windows, it will be provided by the GlgMain cross-platform entry point, otherwise zero may be used.

Returns

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.

See Generic API Application Example for a cross-platform example of using this function.

GlgInitialDraw()

void GlgInitialDraw

(

GlgObject

object

)

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

Parameters

object

Specifies a viewport containing a GLG drawing.

The function displays a viewport's drawing in a platform-independent way on both Windows and Linux/Unix, and is part of the GLG Generic API.

The function creates a top level window and renders the viewport's drawing in it. Depending on the used version of the GLG library and the configuration settings, different rendering engines may be used for rendering graphics:

• GDI or OpenGL on Windows
• GTK, X11 or OpenGL on Linux/Unix.

If the GlgWrapper Widget is used on Linux/Unix, or the GLG Custom Control is used on Windows, this function is called automatically, and need not be explicitly called.

GlgInitialDraw is equivalent to the following sequence:

GlgSetupHierarchy( viewport );
GlgUpdate( viewport );

See Generic API Application Example for a cross-platform example of using this function.

GlgLoadObject()

GlgObject GlgLoadObject

(

char *

filename

)

Loads an object from a GLG drawing file or a URL.

Parameters

filename

Specifies the file or the URL to load the object from. For details of using URLs on Linux, see GlgGetURLCB.

Returns

The loaded object or NULL if loading failed.

This function loads an object from the specified file or URL and returns the object ID. If the file or the URL is not accessible or is not in the GLG save format, an error message is generated and NULL is returned.

If the object is loaded successfully, the reference count of the returned object is set to 1. The loaded object has to be explicitly dereferenced with GlgDropObject after it has been used to avoid memory leaks. See GlgReferenceObject for details on the reference counting.

GlgLoadObjectFromImage()

GlgObject GlgLoadObjectFromImage	(	void *	image,
		GlgLong	size
	)

Loads an object from a memory image.

Parameters

image	Specifies the address of the drawing image generated by the GLG Code Generation Utility gcodegen.
size	Specifies the image size. This is also generated by gcodegen.

Returns

The loaded object or NULL if loading failed.

This function loads an object from the specified drawing's memory image and returns the object ID. If the memory is corrupted, an error message is generated and NULL is returned.

If the object is loaded successfully, the reference count of the returned object is set to 1. The loaded object must be explicitly dereferenced with GlgDropObject after it has been used to avoid memory leaks.

See GlgReferenceObject function for details on the reference counting.

For information about the Code Generation Utility, see the GLG Programming Tools and Utilities chapter of the GLG Programming Reference Manual.

GlgLoadWidgetFromFile()

GlgObject GlgLoadWidgetFromFile

(

char *

filename

)

Loads a GLG widget from a GLG drawing file or a URL.

Parameters

filename

Specifies the name of the widget's drawing file or a URL. For details of using URLs on Linux, see GlgGetURLCB.

Returns

The loaded widget drawing or NULL if loading failed.

This function loads a drawing from a file or a URL 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, it may be dereferenced using GlgDropObject to avoid memory leaks. See GlgReferenceObject for details on the reference counting.

See Generic API Application Example for a cross-platform example of using this function.

GlgLoadWidgetFromImage()

GlgObject GlgLoadWidgetFromImage	(	void *	image,
		GlgLong	size
	)

Loads a GLG widget from a memory image.

Parameters

image	Specifies the address of the widget's drawing image generated by the GLG Code Generation Utility gcodegen.
size	Specifies the image size. This is also generated by gcodegen.

Returns

The loaded widget drawing or NULL if loading failed.

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 GlgDropObject to avoid memory leaks. See GlgReferenceObject for details on the reference counting.

GlgLoadWidgetFromObject()

GlgObject GlgLoadWidgetFromObject

(

GlgObject

object

)

Loads a widget from a GLG object.

Parameters

object

Specifies a GLG object to be used as a widget's drawing.

Returns

The loaded widget drawing or NULL if loading failed.

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.

After the viewport has been used, it may be dereferenced using GlgDropObject. See GlgReferenceObject for details on the reference counting.

For information about the Code Generation Utility, see the GLG Programming Tools and Utilities chapter of the GLG Programming Reference Manual.

GlgMain()

int GlgMain	(	int	argc,
		char *	argv[],
		GlgAppContext	context
	)

A prototype for the cross-platform program entry point that handles argc and argv parameters the same way on all platforms.

Parameters

argc	Number of command line parameters.
argv	Command line parameter list.
context	An application context: Windows: hInstance parameter of the WinMain entry point. X11 and Gtk: (GlgAppContext)0

Returns

Exit code on Windows, GLG_EXIT_OK on X11 and in Gtk.

On Linux/Unix, GlgMain supplies the main entry point.

On Windows, GlgMain supplies the WinMain entry point and parses its lpCmdLine argument to extract cross-platform argc and argv arguments.

To use GlgMain, include the GlgMain.h file and use GlgMain in the program as shown in the example below.

Example

The following C code demonstrates an example of a GLG application code that uses GLG Generic API to display a GLG drawing in a cross-platform way. This code can compiled and used without any changes in either the X11, Gtk or Windows environment:

#include "GlgMain.h"
 
int GlgMain( int argc, char * argv[], GlgAppContext context )
{
   // Initialize the Toolkit and let it process command-line arguments.
   GlgInit( False, app_context, argc, argv );       
 
   // Load and display a drawing.
   GlgObject viewport = GlgLoadWidgetFromFile( "drawing.g" );
   GlgInitialDraw( viewport );
 
   // Code to add an input callback and install a timer to update the drawing with data should be placed here.
   ...
   
   // Process events.
   int exit_code = GlgMainLoop();
 
   return exit_code;
}

The following is the C++ version of the example that displays a GLG drawing in a cross-platform way:

#include "GlgMain.h"
 
int GlgMain( int argc, char * argv[], GlgAppContext init_context )
{
   // Initialize the Toolkit and let it process command-line arguments.
   GlgSessionC glg_session( False, init_context, argc, argv );
 
   // Load and display a drawing.
   GlgObjectC viewport;
   viewport.LoadWidget( "drawing.g" );
   viewport.InitialDraw();
 
   // Process events.
   int exit_code = glg_session.MainLoop( glg_session.app_context );
 
   return exit_code;
}

GlgMainLoop()

GlgLong GlgMainLoop

(

GlgAppContext

context

)

Implements an event polling loop in a platform independent way.

Parameters

context

Specifies the application context returned by GlgInit.

Returns

Exit code on Windows, GLG_EXIT_OK on X11 and in GTK.

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

See Generic API Application Example for a cross-platform example of using this function.

GlgReset()

GlgBoolean GlgReset

(

GlgObject

object

)

Reinitializes the drawing by resetting the drawing hierarchy, then setting it up again and rendering the drawing.

Parameters

object

Specifies a viewport to reset.

Returns

True if the drawing has been successfully reinitialized, otherwise False.

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

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

GlgResetHierarchy()

void GlgResetHierarchy

(

GlgObject

object

)

Resets the object hierarchy.

Parameters

object

Specifies the object to be reset.

Resets the object hierarchy of a top-level viewport or drawing. If the object was displayed using the Generic API, this function must be called before destroying a top-level object with GlgDropObject.

This function should not be called for the top-level viewports used in the integrated GLG widgets, such as the GlgWrapper Widget or GLG Custom Control.

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

GlgSetupHierarchy()

void GlgSetupHierarchy

(

GlgObject

object

)

Provides an explicit request to set up the object hierarchy without rendering the 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 GlgUpdate, GlgSetupHierarchy sets up the object without repainting it.

GlgTerminate()

void GlgTerminate

(

void

)

Terminates the application's use of the GLG Toolkit.

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.

GlgUpdate()

GlgBoolean GlgUpdate

(

GlgObject

object

)

Updates a drawing to show new resource values.

Parameters

object

Specifies a viewport to update.

Returns

True if the drawing has been successfully updated, otherwise False.

If object is a light viewport, an update of its parent viewport will be performed. All resource changes are held until the GlgUpdate function is called or until the viewport's window receives an expose event. (That is, it must be redrawn because another window that was obscuring a part of the viewport's window has been moved. This causes the viewport to redraw itself, using its new data.)

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