PREV NEXT

Generic Logic, Inc. www.genlogic.com


2.10 GLG C++ Bindings

C++ bindings allow you to use the GLG Toolkit with C++ applications as a C++ class library. The bindings are implemented in such a way that every GLG object may be used as a C++ object, and other C++ classes may be derived from it as needed. The source code for the C++ bindings is provided, allowing compiling and using the bindings with any C++ compiler. The underlying GLG library does not depend on a C++ compiler used and may be used with any of them.

As with the GLG C API, the C++ bindings provide you with several ways of using them. If you are programming in a Motif or a Microsoft Windows environment, you can use native features of the corresponding platform, such as GlgWrapperC class for a Motif widget or MFC CWnd derived GlgControlC Class on Microsoft Windows.

If you want to write a cross-platform C++ program that can be compiled without changes in ether Linux/Unix or Windows environment, you may use GlgObjectC class, which uses the generic API and not depend on the windowing system. The InitialDraw() method of the class provides a platform-independent API for creating a window with a GLG drawing displayed inside it.

The C++ API methods mimic the methods of the GLG C API. This chapter provides only a brief description of each API method; refer to Animating a GLG Drawing with Data Using the Standard API on page 63 for a detailed description of each method's functionality. Refer to Handling User Input and Other Events on page 103 for details of the Input callback. Refer to GLG Intermediate and Extended API on page 121 for a detailed description of the Intermediate and Extended API methods.

Standard, Intermediate and Extended API Macros

The C++ bindings for all GLG APIs (Standard, Intermediate and Extended) are implemented in a single source code file, GlgClass.cpp. The GlgClass.h include file provides declarations for all classes and methods used by the C++ bindings. To use methods of the Standard, Intermediate or Extended API, the application has to link with the corresponding GLG library.

The following preprocessor macros control the use of the GLG API libraries in the C++ bindings:

GLG_CPP_STANDARD_API
Activates methods of the Standard API and disables Intermediate and Extended API methods.
GLG_CPP_INTERMEDIATE_API
Activates methods of the Standard and Intermediate APIs and disables the Extended API.
GLG_CPP_EXTENDED_API
Activates methods of the Standard, Intermediate and Extended APIs.

To enable a required API, define one of the macros before including the GlgClass.h file. Passing a defined symbol to a compiler using the -D option is the most convenient way of defining a macro. In the Visual Studio environment, a preprocessor symbol can be defined in the project settings.

Only one of the API macros should be defined. If no API macro is defined, the Extended API will be activated by default, which can result in linking errors if the program is not linked with the Extended API library.

Handling of Constant Strings

Starting with the GLG version 3.3, strings passed as parameters to the GLG C++ methods are considered constant (const char *) by default to avoid compilation warnings. This is accomplished by the CONST_CHAR_PTR preprocessor macro which is defined as True by default.

The macro can be set to False for compatibility with the previous releases, or for performance optimization using writable strings where this option is available. The macro has to be defined before including the GlgClass.h file, in the same way as the API macros described above.

In the method prototypes listed below, the optional const modifier is not shown for string and string array parameters.

C++ API Files and Libraries

The C++ API consists of the following files:

GlgClass.h

Include file, located in the GLG include directory, declares all GLG C++ classes.

GlgClass.cpp

Source file, located in the GLG source directory (named "src"), has to be compiled with the project.

stdafx.h

Include stub file, is needed on UNIX only to make the source code generic. It allows you to get around the special handling that Visual C++ provides for this file in case of precompiled headers.

No additional libraries are required for GLG C++ bindings.

Using GLG Objects

No matter which C++ API you use in your application, platform-specific or generic, you always use the main GlgObjectC C++ class. In the Motif environment, the GlgWrapperC widget class is derived from the GlgObjectC class and inherits its methods. In Microsoft Windows environment, the GlgControlC class is derived from CWnd to inherit its window functionality, but it has a viewport object of the GlgObjectC class as it's publicly accessible attribute that provides GLG functionality.

The GlgObjectC class is the central class of the GLG C++ API. It keeps an object ID of the associated GLG object as one of its data members, in the same way as MFC's CWnd class keep a window ID of the associated window.

The GlgObjectC class has several constructors, allowing several ways of creating of the associated GLG object: by loading it from a file, loading from a generated memory image, or by referencing a named resource inside another GLG object.

There is also a default constructor with no arguments, which creates a GlgObjectC class with a NULL GLG object. The GLG object may be associated with this instance of the class later, by using several available Load() methods, which allow loading it from a file, memory image or associating a reference of some named resource of another object. If a Load() method is used for a class instance which already has an associated GLG object, it is dissociated from the previous object and associated with the new one.

The GlgObjectC class also provides an overloaded assignment operator, which associates the left hand side class instance with a reference to the same GLG object of the right hand class instance. Any previous associations are discarded.

There are type converters to and from GlgObject ID, which allows assigning the GlgObject ID to a class and using both the GlgObject ID and the instance of the GlgObjectC class interchangeably.

The GlgObject ID is used as a return value of some methods of the class, allowing you to avoid returning temporary instances of the class or class pointers, both of which may lead to memory leaks or dangling pointers. The GlgObject return value may then be assigned to an instance of the class as in the following example:

GlgObjectC car( "car.g" );
GlgObjectC wheel = car.GetResourceObject( "Wheel0" );

In this example, the object from "car.g" drawing file gets loaded and associated with a car class instance. Then the first wheel of the car gets associated with the wheel class instance. The above example may be rewritten using constructors only:

GlgObjectC car( "car.g" );
GlgObjectC wheel( car, "Wheel0" );

Notice that the wheel class instance is associated with an GLG object which is the part of another object. You cannot add that wheel object to the car object again, because it is already a part of it. You can use the Copy() method to create a new copy of a wheel object and associate that new copy with the class instance:

wheel.Copy();
wheel.SetResource( "Name", "SpareWheel" ); // Use distinct name
car.Add( wheel );

The same thing can also be accomplished by using a copy constructor:

{
	GlgObjectC spare_wheel( wheel );
	spare_wheel.SetResource( "Name", "SpareWheel" );
	car.Add( spare_wheel );
}

Automatic Referencing and Dereferencing

The GlgObjectC class provides automatic referencing and dereferencing of the associated GLG object, freeing the developer from keeping track of temporary objects. For example, the spare_wheel object in the above example gets automatically dereferenced in its destructor when it goes out of scope after being added to a car.

Some methods, such as CreateTagList, create and return a new GLG object (a list of tags in the case of CreateTagList). The return value of these methods has to be explicitly dereferenced using the Drop method to avoid memory leaks, as shown in the following example:

GlgObjectC tag_list = drawing.CreateTagList( True );
tag_list.Drop();
ProcessTags( tag_list );

In the above example, the tag list object created by CreateTagList gets extra referenced when it is assigned to the tag_list variable. Therefore, it is safe to dereference it by calling the Drop method right after the call to CreateTagList, even though the tag list is still used in the program. The tag list will be destroyed when the tag_list variable goes out of scope (unless the tag list is referenced inside the ProcessTags method by assigning it to a global variable to keep the tag list).

In addition to the explicit Reference() and Drop() methods , the GlgObjectC class also implements overloaded increment (++) and decrement (--) operators providing the same functionality. Note that calling the Drop() method explicitly without referencing the object first may cause destruction of the object and a crash due to an invalid GLG object ID.

Comparison Operators

The IsNull() method returns TRUE if there is no GLG object associated with the class instance (NULL GlgObjectC ID). There is also an overloaded logical negation operator which performs the same function: !object yields TRUE when the there is no associated GLG object.

Notice an interesting usage of double negation: !!object returns TRUE when there is a GLG object associated with the class instance.

The Same() method of the GlgObjectC class provides a logical equality operator: it returns TRUE if the instances of the class is associated with the same GLG object as the instance of the class passed as a parameter.

Using Input and Selection Callbacks

The input and selection callbacks are virtual methods of all three main GLG API classes: GlgObjectC, GlgWrapperC and GlgControlC. To use these callbacks, derive your class from any of these classes and provide your implementation of Input() and Selection() callbacks that overrides the ones of the base class. Use the EnableCallbacks() method of the base class to enable the callbacks. Refer to the programming examples described below for more details.

Miscellaneous Utility Classes

The GlgSessionC class handles initialization of the GLG Toolkit. One instance of this class has to be created to initialize the Toolkit. In some cases the initialization may be skipped, as describer later.

In the Motif environment, the Toolkit is initialized automatically when the Create() method of the Wrapper Widget class is invoked.

In the Microsoft Windows environment, the toolkit is initialized automatically if a .dll version of the library is used, or when a Create() method of the GlgControlC class is invoked.

In both cases, the initialization may be skipped only if there are no other GLG calls were issued before invoking the Create() method. An explicit initialization is mandatory when the Generic C++ API is used. It is always safe to use explicit initialization in either case.

The MainLoop() method of the GlgSessionC class also provides a generic interface to the window system specific event loop.

The GlgLinkC class is derived from the GlgObjectC class and provides additional ICC functionality for communicating between GLG processes using link objects. The class provides methods for establishing a link to a GLG ICC viewport server. The rest of functionality for setting resources and updating through a link is inherited from it's base GlgObjectC class.

Programming Examples

The examples_c_cpp directory contains source code examples for both C and C++. On Windows, the examples_mfc directory contains MFC examples.

List of Classes and Methods in the GLG C++ Bindings

GlgSessionC

Provides an interface for initializing the GLG Toolkit.

Data Members:
GlgAppContext app_context;

Application context returned by GlgInit().

Methods:
GlgSessionC( void );

Default constructor.

GlgSessionC( GlgBoolean initialized, GlgAppContext application_context,
int argc = 0, char ** argv = NULL );

Constructor: calls GlgInit().

virtual ~GlgSessionC( void );

Destructor.

GlgAppContext GetAppContext( void );

Returns the application context.

GlgBoolean MainLoop( void );

Provides a generic interface to the event loop.

void Create( GlgBoolean initialized = False, GlgAppContext application_context = NULL,
int argc = 0, char ** argv = NULL );

Calls GlgInit().

GlgObjectC

This is the main class of the GLG C++ bindings. It has the functionality of the regular and Extended API.

Data Members:
GlgObject glg_obj;

An object ID of associated GLG object.

GlgObject suspend_obj;

Suspension information object. Is not NULL if the object was suspended for editing.

Methods:
GlgObjectC( void );

Default constructor: Creates a null object.

GlgObjectC( GlgObjectType type, char * name = NULL,
GlgAnyType data1 = NULL, GlgAnyType data2 = NULL,
GlgAnyType data3 = NULL, GlgAnyType data4 = NULL );

Constructor: creates a new object of the type using default attributes.

GlgObjectC( char * filename );

Constructor: loads an object from a file.

GlgObjectC( long object_data[], long object_data_size );

Constructor: loads an object from a generated memory image.

GlgObjectC( GlgObjectC& object,
GlgCloneType clone_type = GLG_FULL_CLONE );

Copy constructor: creates a copy of the object. The type of copying is defined by a clone_type parameter. Default type is GLG_FULL_CLONE.

GlgObjectC( GlgObjectC& object, char * resource_name );

Constructor: associates with a named resource object inside another and references it.

GlgObjectC( GlgObject object );

Constructor: creates a C++ class from GlgObject to allow assigning GlgObject to a GlgObjectC object class:

		GlgObjectC object = GetResourceObject( ... );
GlgObjectC( GlgObjectC * object );

Constructor: creates a C++ class from a GlgObjectC pointer. This constructor is needed by some C++ compilers for proper handling of temporary objects.

virtual ~GlgObjectC( void );

Destructor: Deletes or dereferences the GLG object.

operator GlgObject( void );

Type converter to GlgObject.

GlgObjectC& operator= ( const GlgObjectC& object );

Assignment operator: associates the GLG object and references it.

GlgObjectC& operator++( void ); // prefix ++
GlgObjectC& operator++( int ); // postfix ++
GlgObjectC& operator--( void ); // prefix --
GlgObjectC& operator--( int ); // postfix --

Overloaded ++; --, both infix and postfix. Overloaded to reference/dereference.

void Reference( void );
void Drop( void );

Explicit reference/dereference.

GlgBoolean Save( char * filename );

Saves the associated GLG object into a file.

GlgBoolean Load( char * filename, char * object_name = NULL );

Explicit Load(). Replaces the associated GLG object with the loaded one. Two sets of overloaded load functions: one for loading the whole drawing or its named components, and another for extracting just the "$Widget" viewport.

Loads an object from a file. If object_name is not NULL, extracts and loads just that named resource of the object.

GlgBoolean Load( void * object_data, long object_data_size, char * object_name = NULL );

Loads an object from a generated memory image.

GlgBoolean Load( GlgObjectC& object, char * object_name = NULL );

Associates with an object inside another object and references it. If object_name is NULL, uses the parameter object itself.

GlgBoolean LoadWidget( char * filename );

Loads a "$Widget" viewport from a file.

GlgBoolean LoadWidget( void * object_data, long object_data_size );

Loads a "$Widget" viewport from a generated memory image.

GlgBoolean LoadWidget( GlgObjectC& object );

Loads a "$Widget" viewport from another object.

void LoadNullObject( void );

Dissociates and sets the GLG object ID to NULL.

void Create( GlgObjectType type, char * name = NULL,
GlgAnyType data1 = NULL, GlgAnyType data2 = NULL,
GlgAnyType data3 = NULL, GlgAnyType data4 = NULL );

Replaces the current object with a created object.

void Copy( GlgCloneType clone_type = GLG_FULL_CLONE );

Replaces the current object with a copy of it.

GlgBoolean GetResource( char * resource_name, double * value ); // D-type
GlgBoolean GetResource( char * resource_name, char ** s_value ); // S-type
GlgBoolean GetResource( char * resource_name, double * x_value,
double * y_value, double * z_value ); // G-type
GlgBoolean GetTag( char * tag_source, double * value ); // D-type
GlgBoolean GetTag( char * tag_source, char ** s_value ); // S-type
GlgBoolean GetTag( char * tag_source,
double * x_value, double * y_value, double * z_value ); // G-type

Get resource or tag values.

GlgBoolean SetResource( char * resource_name, double value );      // D-type
GlgBoolean SetResource( char * resource_name, char * s_value );   // S-type
GlgBoolean SetResource( char * resource_name,
double x_value, double y_value, double z_value);    // G-type
GlgBoolean SetResource( char * resource_name, double value, GlgBoolean if_changed );      // D-type
GlgBoolean SetResource( char * resource_name, char * s_value, GlgBoolean if_changed );    // S-type
GlgBoolean SetResource( char * resource_name,
double x_value, double y_value, double z_value, GlgBoolean if_changed );        // G-type
GlgBoolean SetTag( char * tag_source, double value, GlgBoolean if_changed );                 // D-type
GlgBoolean SetTag( char * tag_source, char * s_value, GlgBoolean if_changed );                   // S-type
GlgBoolean SetTag( char * tag_source,
double x_value, double y_value, double z_value, GlgBoolean if_changed );        // G-type

Set resource or tag values. For tags, all tags with the specified tag_source will be set to the supplied values.

GlgBoolean SetResource( char * resource_name, char * format, double value );
GlgBoolean SetResource( char * resource_name, char * format, double value,
GlgBoolean if_changed );
GlgBoolean SetTag( char * tag_source, char * format, double value, GlgBoolean if_changed );

Set S resource or tag from a double value according to the specified format.

GlgBoolean SetResource( char * resource_name, GlgObjectC& object );

Set resource from object.

GlgBoolean HasResourceObject( char * resource_name );

Checks if a named resource exists.

GlgBoolean HasTagName( char * tag_name );
GlgBoolean HasTagSource( char * tag_source );

Checks if a tag with the specified tag name or tag source exists.

GlgObject CreateTagList( GlgBoolean unique_tags );

Creates and returns a list of the object's tags.

Since the method creates a new object, its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

GlgObject CreateAlarmList( void );

Creates and returns a list of alarms attached to the object.

Since the method creates a new object, its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

GlgObject GetGlgObject( void );

Returns an object ID of the associated GLG object.

void SetGlgObject( GlgObject object );

Low-level object manipulation function: sets the associated GLG object.

GlgBoolean IsNull( void );
GlgBoolean operator!( void );

NULL check to use after Load/GetResourceObject/etc.

GlgBoolean Same( GlgObjectC& object );

Returns TRUE if the object refers to the same object ID as the parameter object.

void InitialDraw( void );
void SetupHierarchy( void );
void ResetHierarchy( void );
GlgBoolean Reset( void );

Other viewport-related GLG API functions.

GlgBoolean Sync( void );

Flushes all graphic requests and waits for their completion.

GlgBoolean Update( void );

Updates the viewport's graphic with the new data.

void EnableCallback( GlgCallbackType callback_type, GlgObject callback_viewport = NULL );

Enables selection and input callbacks of the object. If callback_viewport is not NULL, adds GLG callbacks to it, otherwise adds it to this object (which must be a viewport).

virtual void Input( GlgObjectC& callback_viewport, GlgObjectC& message );
virtual void Select( GlgObjectC& callback_viewport, char ** name_array );
virtual void Trace( GlgObjectC& callback_viewport, GlgTraceCBStruct * trace_info );
virtual void Trace2( GlgObjectC& callback_viewport, GlgTraceCBStruct * trace_info );
virtual void Hierarchy( GlgObjectC& callback_viewport, GlgHierarchyCBStruct * hierarchy_info );

Virtual callback functions to be overridden by a derived class.

GlgBoolean SetZoom( char * resource_name, GlgLong type, double value )

Performs a zoom or pan operation specified by the type parameter. If the resource_name parameter is null, the viewport itself is zoomed. Otherwise, the zoom operation will be performed on its child viewport specified by the resource_name parameter. The value parameter defines the zoom factor or pan distance. Refer to the GlgSetZoom section on page 96 for a complete list of all zoom and pan types.

GlgBoolean SetZoomMode( char * resource_name, GlgObjectC * zoom_object,
char * zoom_object_name )

Sets or resets a viewport's zoom mode by supplying a GIS or Chart object to be zoomed. In the Drawing Zoom Mode (default), the drawing displayed in the viewport is zoomed and panned. If the GIS Zoom Mode is set, any zooming and panning operation performed by the GlgSetZoom method will zoom and pan the map displayed in the viewport's GIS Object, instead of being applied to the viewport's drawing. In the Chart Zoom Mode, the content of the chart is zoomed and panned. If the resource_name parameter is null, the zoom mode of the viewport itself will be set. Otherwise, the zoom mode will be set for its child viewport specified by the resource_name parameter. If the zoom_name parameter is not null, it specifies the resource path of a GIS or Chart object relative to the zoom_object parameter, or relative to the viewport if the zoom_object parameter is null. The method may be invoked with zoom_object=null and zoom_object_name=null to reset the zoom mode to the default Drawing Zoom Mode.

GlgBoolean Print( char * filename="out.ps", double x=-1000., double y=-1000.,
double width = 2000., double height = 2000.,
GlgBoolean portrait = True, GlgBoolean stretch = True );

Printing method.

GlgBoolean SaveImage( char * resource_name, char * filename, GlgImageFormat format )

Method for saving an image of the visible area of the drawing's viewport.

GlgBoolean SaveImageCustom( char * resource_name, char * filename, GlgImageFormat format,
GlgLong x, GlgLong y, GlgLong width, GlgLong height, GlgLong gap )

Method for saving an unclipped image of the whole drawing.

void MetaDraw( char * filename="out.meta",
double x=-1000., double y=-1000., double width = 2000., double height = 2000.,
GlgBoolean portrait = True, GlgBoolean stretch = True );

GLG Metafile support.

GlgBoolean Print( CDC * dc,
double x=-1000., double y=-1000., double width = 2000., double height = 2000.,
GlgBoolean portrait = True, GlgBoolean stretch = True );

MICROSOFT WINDOWS ONLY: Native windows printing, GLG controlled page layout.

void OnPrint( CDC * dc );

MICROSOFT WINDOWS ONLY: Native window printing, windows-controlled page layout.

void OnDrawMetafile( CDC * dc );

MICROSOFT WINDOWS ONLY: Native window printing with clipping disabled.

GlgAnyType SendMessage( char * resource_name, char * message, GlgAnyType param1,
GlgAnyType param2, GlgAnyType param3, GlgAnyType param4 )

Sends a message specified by the message parameter. If the resource_name parameter is null, the message is sent to the object itself. Otherwise, the message is sent to the object's child specified by the resource_name parameter. The param<n> arguments define additional parameters of the message depending on the message type.

GlgObject GetNamedPlot( char * resource_name. char * plot_name )

Finds a chart's plot by name and returns it's object ID. If the resource_name parameter is NULL, a named plot of this chart is returned. Otherwise, the resource_name parameter points to a child chart of this object. The method returns NULL if a plot with the specified name has not been found.

GlgObject AddPlot( char * resource_name, GlgObject& plot )

Adds a plot to a chart object. If the resource_name parameter is NULL, the plot is added to this chart. Otherwise, the plot is added to a child chart of this object pointed to by the resource_name parameter. The plot parameter specifies the plot object to add; NULL can be used to create a new plot. The method returns the added plot object on success, or NULL on failure.

GlgBoolean DeletePlot( char * resource_name, GlgObject& plot )

Deletes a plot from a chart object. If the resource_name parameter is NULL, the plot is deleted from this chart. Otherwise, the plot is deleted from a child chart of this object pointed to by the resource_name parameter. The plot parameter specifies the plot object to delete. The method returns True if the plot was successfully deleted.

GlgBoolean GetDataExtent( char * resource_name, GlgMinMax * min_max, GlgBoolean x_extent )

Queries the minimum and maximum extent of the data accumulated in a chart or in one of its plots. If the resource_name parameter is NULL, the data extent of this chart or plot object is returned. Otherwise, the resource_name parameter points to a child chart or a child plot of this object. If x_extent is True, the X extent of the data is returned in min_max, otherwise the method returns the Y extent of the data. GlgMinMax is defined in the GlgApi.h file:

typedef struct _GlgMinMax	
{
	double min, max;
} GlgMinMax;

For a chart object, the method returns the data extent of all plots in the chart. For a plot, the data extent of that plot is returned. The object hierarchy must be set up for this function to succeed. The method returns True on success.

Additional Standard API Methods

The GetElement and GetSize methods described in the Intermediate and Extended API Methods section are also available in the Standard API.

Extended and Intermediate API

There are two flavors of the Extended API: GLG Intermediate API and GLG Extended API. The Intermediate API provides all Extended API methods except for the methods for creating and deleting objects at run time. The list below describes methods of both APIs, with an availability comment for methods that are available only with the Extended API.

Intermediate and Extended API Methods
GlgObject GetResourceObject( char * resource_name );

Explicit GetResourceObject(). The return value may be assigned to a GlgObjectC class.

GlgBoolean SetResourceObject( char * resource_name, GlgObjectC& o_value );

Sets the new value of the object's attribute specified by the resource_name (Extended API only). It is used for attaching Custom Property objects and aliases.

GlgObject GetTagObject( char * search_string, GlgBoolean by_name, GlgBoolean unique_tags,   GlgBoolean single_tag )

Finds a single tag with a given tag name or tag source, or creates a list of tags matching the wildcard. The search_string specifies either the exact tag name or tag source to search for, or a search pattern which may contain the ? and * wildcards. The by_name parameter defines the search mode: by a tag name or tag source. In the single tag mode, the first tag matching the search criteria is returned. The unique_tags controls if only one tag is included in case there are multiple tags with the same tag name or tag source. The unique_tags flag is ignored in the single tag mode.

In the single tag mode, the method returns the first attribute that has a tag matching the search criteria. In the multiple tag mode, a list containing all attributes with matching tags will be returned. The return value may be assigned to a GlgObjectC class.

In the multiple tag mode, the method creates a new list object and its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

GlgObject QueryTags( GlgTagType tag_type_mask )

Returns a list of all tags of the specified tag type. Since the method creates a new list object, its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

GlgObject GetAlarmObject( char * search_string, GlgBoolean single_alarm )

Finds a single alarm with a given alarm label, or creates a list of alarms with alarm labels matching the specified wildcard. The search_string specifies either the exact alarm label or a search pattern which may contain the ? and * wildcards.

In the single alarm mode, the method returns the first alarm object with an alarm label matching the search criteria. In the multiple alarm mode, a list containing all alarms with matching alarm labels will be returned.

In the multiple alarm mode, the method creates a new list object and its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

GlgBoolean SetXform( GlgObjectC& xform );

Adds a transformation to the object (Extended API only).

GlgObject GetParent( GlgLong * num_parents );

Gets a parent object or array of parents if num_parents > 1.

GlgCube * GetBoxPtr( void );

Returns 3D bounding box of an object.

GlgObject GetDrawingMatrix( void );

Returns a drawing matrix object used to render the object.

void SuspendObject( void );
void ReleaseObject( void );

Suspends or releases the object.

GlgObject CreateResourceList( GlgBoolean list_named, GlgBoolean list_default,
GlgBoolean list_aliases );

Returns a list of resources of the object.

Since the method creates a new object, its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

GlgObject CreatePointArray( GlgControlPointType type );

Creates and returns an array containing all of an object's control points. The type parameter specifies the type of points to be returned.

Since the method creates a new object, its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

GlgBoolean MoveObject( GlgCoordType coord_type, GlgPoint * start_point, GlgPoint * end_point );

Moves an object by the specified vector.

GlgBoolean MoveObjectBy( GlgCoordType coord_type, double x, double y, double z );

Moves an object by the specified X, Y and Z distances.

GlgBoolean ScaleObject( GlgCoordType coord_type, GlgPoint * center, double x, double y, double z );

Scales an object relative to the center by the specified X, Y and Z scale factors.

GlgBoolean RotateObject( GlgCoordType coord_type, GlgPoint * center, double x, double y, double z );

Rotates an object around the specified center by the specified X, Y and Z angles.

GlgBoolean PositionObject( GlgCoordType coord_type, GlgLong anchoring,
double x, double y, double z );

Positions an object at the specified location using the specified anchoring.

GlgBoolean FitObject( GlgCoordType coord_type, GlgCube * box, GlgBoolean keep_ratio );

Fits the object to the specified area.

GlgBoolean LayoutObjects( GlgObject sel_elem, GlgLayoutType type, double distance,
GlgBoolean use_box, GlgBoolean process_subobjects )

Performs a requested layout operation. Refer to GLG Intermediate and Extended API on page 121 for more details.

GlgBoolean ScreenToWorld( GlgBoolean inside_vp, GlgPoint * in_point, GlgPoint * out_point );

Converts a point coordinates from the screen to the GLG world coordinate system. The inside_vp flag must be set to GlgTrue for viewport objects to convert to the world coordinate system inside the viewport. When converting the cursor position to world coordinates, add GLG_COORD_MAPPING_ADJ to the cursor's x and y screen coordinates for precise mapping.

GlgBoolean WorldToScreen( GlgBoolean inside_vp, GlgPoint * in_point, GlgPoint * out_point );

Converts a point coordinates from the GLG world to the screen coordinate system. The inside_vp flag must be set to GlgTrue for viewport objects to convert from the world coordinate system inside the viewport.

GlgBoolean PositionToValue( char * resource_name, double x, double y,
GlgBoolean outside_x, GlgBoolean outside_y, double * value )

Returns a value corresponding to the specified x, y position on top of a chart or an axis object. If the resource_name parameter is null, the value corresponding to this object is returned. Otherwise, the resource_name parameter points to a child chart, a child plot or a child axis of this object.

If outside_x or outside_y are set to True, the method returns NULL if the specified position is outside of the chart or the axis in the corresponding direction.

For a plot, the method converts the specified position to a Y value in the Low/High range of the plot and returns it via the value pointer.

For an axis, the function converts the specified position to the axis value and returns the value.

For a chart, the function converts the specified position to the X or time value of the chart's X axis and returns the value.

When using the cursor position, add GLG_COORD_MAPPING_ADJ to the cursor's x and y coordinates for precise mapping.

GlgObject CreateChartSelection( GlgObjectC plot, double x, double y, GlgBoolean screen_coord,
GlgBoolean include_invalid, GlgBoolean x_priority )

Selects a chart's data sample closest to the specified x, y position and returns a message object containing the selected sample's information. If plot contains a null GLG object, the method queries samples in all plots of the chart and selects the sample closest to the specified position. If plot contains a non-null GLG object, the method queries only the samples in that plot.

If the screen_coord parameter is set to True, the position is defined in the screen coordinates of the chart's parent viewport. If screen_coord is set to False, the x position is defined as an X or time value, and the y position is defined in relative coordinates in the range [0; 1] to allow the chart to process selection for plots with different ranges (0 corresponds to the Low range of each plot, and 1 to the High range). When the mouse position is used, add GLG_COORD_MAPPING_ADJ to the x and y screen coordinates of the mouse for precise mapping.

The dx and dy parameters specify an extent around the point defined by the x and y parameters. The extent is defined in the same coordinates as x and y, depending on the value of the screen_coord parameter. A data sample in a chart is selected only if its x and y coordinates differ from the specified position by amounts less or equal to the values of the corresponding dx or dy parameters.

If include_invalid if set to True, invalid data samples are considered for selection, otherwise they are never included. If x_priority is set to True, the method selects the data sample closest to the specified position in the horizontal direction, with no regards to its distance from the specified position in the vertical direction. If x_priority is set to False, a data sample with the closest distance from the specified position is selected.

The information about the selected data sample is returned in the form of a message object described in the Chart Selection Message Object section on page 458. The method returns NULL if no data sample matching the selection criteria was found.

Since the method creates a new object, its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

char * CreateTooltipString( double x, double y, double dx, double dy, char * format )

Creates and returns a chart or axis tooltip string corresponding to the specified x, y position in screen coordinates. The string can be used to provide cursor feedback and display information about the data sample under the current mouse position, as shown in the Real-Time Strip-Chart demo.

The format parameter provides a custom format for creating a tooltip string and uses the same syntax as the TooltipFormat attributes of the chart and axis objects. If it is set to NULL or an empty string, the format provided by the TooltipFormat attribute of this chart or axis object will be used. A special "<single_line>" tag may be prepended to the format string to force the method to remove all line breaks from the returned tooltip string.

If this object is a chart and the selected position is within the chart's data area, the method selects a data sample closest to the specified position and returns a tooltip string containing information about the sample. The dx and dy parameters define the maximum extent in pixels around the specified position for selecting a data sample, and the TooltipMode attribute of the chart defines the data sample selection mode: X or XY. The method returns NULL if no samples matching the selected criteria were found.

If this object is an axis, or if this object is a chart and the selected position is on top of one of the chart's axes, the function returns a tooltip string that displays the axis value corresponding to the specified position.

When using the cursor position, add GLG_COORD_MAPPING_ADJ to the cursor's x and y screen coordinates for precise mapping.

The returned string must be freed using the GlgFree function.

Attribute Objects
GlgBoolean ConstrainObject( GlgObjectC& to_attribute );
GlgBoolean UnconstrainObject( void );

Constrains or unconstrains the attribute object.

Matrix Objects
GlgObject InverseMatrix( void );

Creates and returns a new matrix. Since the method creates a new matrix object, its returned value must be explicitly dereferenced. This can be done by invoking the Drop method on the GlgObjectC object the return value is assigned to.

void TransformPoint( GlgPoint * in_point, GlgPoint * out_point );

Transforms point using the GLG matrix object associated with this class instance.

void GetMatrixData( GlgMatrixData * matrix_data );

Queries matrix coefficients.

void SetMatrixData( GlgMatrixData * matrix_data );

Sets matrix coefficients.

Container Functionality
GlgBoolean IsContainer( void );

Returns TRUE if the associated GLG object is a GLG container (viewport,

void SetStart( void );

Initializes container for traversing.

GlgObject Iterate( void );

Returns the next subobject of the associated container object.

GlgLong GetSize( void );

Returns the size of the associated container object.

GlgBoolean AddToTop( GlgObjectC& object );
GlgBoolean AddToBottom( GlgObjectC& object );
GlgBoolean AddAt( GlgObjectC& object, GlgLong index );

Add object to container (Extended API only).

GlgBoolean DeleteTopObject( void );
GlgBoolean DeleteBottomObject( void );
GlgBoolean DeleteObjectAt( GlgLong index );
GlgBoolean DeleteObject( GlgObjectC& object );

Delete this object from container (Extended API only).

GlgObject ReorderElement( GlgLong old_index, GlgLong new_index );

Reorder elements of the container.

GlgBoolean ContainsObject( GlgObjectC& object );
GlgObject GetElement( GlgLong index );
GlgObject GetNamedObject( char * name );
GlgLong GetIndex( GlgObjectC& object );
GlgLong GetStringIndex( char * string );

Search functions for finding elements of a container.

void Inverse();

Inverses the order of container's elements.

GlgLinkC

GlgLinkC is subclassed from GlgObjectC to inherit SetResource() and GetResource() and other methods. Provides methods for establishing links between GLG processes by using GLG ICC. Some inherited methods of extended API are not implemented yet for links. Note also that there is a type converter to GlgObject that is inherited from GlgObjectC.

Methods:
GlgLinkC( void );

Default constructor: creates a null link object.

GlgLinkC( char * display_name, char * server_name );

Constructor: creates a link object and connects it to a named GLG ICC Server.

GlgLinkC( GlgObjectC& object );

Constructor: creates a link from a GlgObjectC class:
GlgObjectC some_object;
GlgLinkC link = some_object;

GlgLinkC( GlgObject object );

Constructor: creates a link from a GlgObject.

GlgLinkC( GlgLinkC& object );

Copy constructor. The server connection is not copied.

virtual ~GlgLinkC( void );

Destructor, calls GlgDestroyLink().

Connect( char * display_name, char * server_name );

Establish a connection to a named GLG ICC Server.

Disconnect( void );

Explicit link closing, calls GlgDestroyLink().

GlgLinkC& operator= ( const GlgLinkC& object );

Assignment operator, the server connection is not copied.

GlgBoolean IsActive();

Interface to GlgLinkActive: returns TRUE is the link is active.

GlgControlC (Microsoft Windows Only)

MFC CWnd derived class providing a window for displaying a GLG drawing.

Data Members:
GlgObjectC viewport;

An object ID of the associated GLG viewport object with the drawing.

Methods:
GlgControlC( void );

Default constructor: creates an empty control.

virtual ~GlgControlC( void );

Destructor. Destroys the window and dereferences the viewport object.

void Create( char * drawing_file, CWnd * parent,
char * control_name = "GlgControl", CRect * in_rect = NULL, int IDC_id = 0 );

Creates a control's window and loads drawing from a file into it.

void Create( void * drawing_image, long image_size, CWnd * parent,
char * control_name = "GlgControl", CRect * in_rect = NULL, int IDC_id = 0 );

Creates a control's window and loads drawing from a generated memory image.

void Create( GlgObjectC& object, CWnd * parent,
char * control_name = "GlgControl", CRect * in_rect = NULL, int IDC_id = 0 );

Creates a control's window and uses the "$Widget" viewport of another GLG object as a drawing.

void InitialDraw();

Draws the graphics the first time.

GlgBoolean Update( void );

Updates the displayed graphics.

void SetDrawing( char * filename );

Changes the drawing, load a new drawing from a file.

void SetDrawing( void * drawing_image, long drawing_image_size );

Changes the drawing, load a new drawing from a generated memory image.

void SetDrawing( GlgObjectC& object );

Changes the drawing, use the "$Widget" viewport of another object as a new drawing.

virtual void EnableCallback( GlgCallbackType callback_type,
GlgObject callback_viewport = NULL );

Enables selection and input callbacks of the control. If callback_viewport is not NULL, adds GLG callbacks to it, otherwise adds it to the control's viewport.

virtual void Input( GlgObjectC& callback_viewport, GlgObjectC& message );
virtual void Select( GlgObjectC& callback_viewport, char ** name_array );
virtual void Trace( GlgObjectC& callback_viewport, GlgTraceCBStruct * trace_info );
virtual void Trace2( GlgObjectC& callback_viewport, GlgTraceCBStruct * trace_info );
virtual void Hierarchy( GlgObjectC& callback_viewport, GlgHierarchyCBStruct * hierarchy_info );

Virtual callback functions to be overridden by a derived class.

void Print( CDC * pDC, DWORD dwFlags );

Native Windows print method.

GlgObject GetViewport( void );

Returns an object ID of the control's viewport.

GlgWrapperC (X Windows Only)

C++ wrapper around the GlgWrapper widget. It is a subclass of a GlgObjectC and inherits GLG API and GLG Extended API from it. Note that the GetViewport() method has to be called explicitly after the widget has been realized and before any API functions are used. The GlgGetViewport() method associates a viewport object with the instance of a class. While the widget is being realized, the widget creates a viewport. The viewport is set to NULL initially and its object ID has to be obtained from the widget after the widget has been realized. Since the widget may be realized by its parent, it is difficult to encapsulate GetViewport() functionality into the GlgWrapperC class so that it is transparent to the user. Trying to do so causes a lot of code duplication and will lead to problems in the future, so invoking this call is left as the responsibility of the user.

Data Members:
Widget widget;
Methods:
GlgWrapperC( void );

Default constructor: creates an empty wrapper widget with no drawing.

virtual ~GlgWrapperC( void );

Destructor. Destroys the wrapper widget. Be careful to set the widget to NULL if it is destroyed by destroying its parent to avoid XtDestroyWidget() being called with an invalid widget ID.

void Create( char * filename, Widget parent, char * widget_name = "GlgWrapper",
long width = 400, long height = 300 );

Creates the widget and loads drawing from a file into it.

void Create( void * image_data, long image_data_size, Widget parent,
char * widget_name = "GlgWrapper", long width = 400, long height = 300 );

Creates a widget and loads drawing from a generated memory image.

void Create( GlgObjectC& object, Widget parent, char * widget_name = "GlgWrapper",
long width = 400, long height = 300 );

Creates a widget and uses the "$Widget" viewport of another GLG object as a drawing.

The following collection of SetDrawing() methods change the drawing using a particular wrapper widget resource. The actual drawing displayed is still subject to the priority of a particular wrapper widget drawing resource. Setting the drawing by using one of the SetDrawing() functions may interfere with others.

void SetDrawing( char * filename );

Loads a new drawing from a file (uses XtNglgDrawingFile resource).

void SetDrawing( void * image_data, long image_data_size );

Loads a new drawing from a generated memory image ( uses XtNglgDrawingImage resource).

void SetDrawing( GlgObjectC& object );

Uses the "$Widget" viewport of another object as a new drawing (uses XtNglgDrawingObject resource).

Widget GetWidget( void );

Returns a widget id.

GlgObject GetViewport();

Associates a viewport object of the wrapper widget with the instance of the class after the widget has been realized.

void EnableCallback( GlgCallbackType callback_type, GlgObject callback_viewport = NULL );

Enables selection and input callbacks of the control. If callback_viewport is not NULL, adds GLG callbacks to it, otherwise adds it to the widget's viewport.

virtual void Input( GlgObjectC& callback_viewport, GlgObjectC& message );
virtual void Select( GlgObjectC& callback_viewport, char ** name_array );
virtual void Trace( GlgObjectC& callback_viewport, GlgTraceCBStruct * trace_info );
virtual void Trace2( GlgObjectC& callback_viewport, GlgTraceCBStruct * trace_info );
virtual void Hierarchy( GlgObjectC& callback_viewport, GlgHierarchyCBStruct * hierarchy_info );

Virtual callback functions to be overridden by a derived class.

void SetXtResource( String xt_ resource_name, char * res_value );
void GetXtResource( String xt_ resource_name, char ** res_value_ptr );

Sets and gets Xt resources of string type (is primarily used with XtNglgHResource* and XtNglgVResource* resources).


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