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 Widget C++ class for Motif 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 Unix or Windows environment, you may use GLG Object C++ class, which uses the generic window-platform independent API of the Toolkit. The InitialDraw() method of the class provides a platform-independent API for creating a window with a GLG drawing displayed inside it.
No matter which C++ API you use in your application, platform-specific or generic, you are always dealing with 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 ); }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.
There are also explicit Reference() and Dereference() methods as well as overloaded increment and decrement operators providing the same functionality. Note that these methods should not be normally used and are provided only for some special complex programming cases.
Also note that calling the Deference() method explicitly without referencing the object before that may cause destruction of the object and the invalid GLG object ID.
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.
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.
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.
The tree demo and network demos in the DEMOS directory come with complete source code and may be used as examples of using the C++ API. There are also some other C++ examples in the examples directory.
If you don't have the Extended API library, you have to define the GLG_DISABLE_CPLUS_EXTENDED_API symbol before including the GlgClass.h file. Passing this defined symbol to a compiler using -D option provides the most convenient way of doing it. In the Visual C++ environment, define this symbol in the project settings.
This is the main class of the GLG C++ bindings. It has the functionality of the regular and Extended API.
Constructor: creates a new object of the type using default attributes.
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.
Constructor: associates with a named resource object inside another and references it.
Constructor: creates a C++ class from GlgObject to allow assigning GlgObject to a GlgObjectC object class:
GlgObjectC object = GetResourceObject( ... );Constructor: creates a C++ class from a GlgObjectC pointer. This constructor is needed by some C++ compilers for proper handling of temporary objects.
Assignment operator: associates the GLG object and references it.
Overloaded ++; --, both infix and postfix. Overloaded to reference/dereference.
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.
Associates with an object inside another object and references it. If object_name is NULL , uses the parameter object itself.
Set S resource or tag from a double value according to the specified format.
Low-level object manipulation function: sets the associated GLG object.
Returns TRUE if the object refers to the same object ID as the parameter object.
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 callback functions to be overridden by a derived class.
Performs a zoom or pan operation specified by the type parameter. If the res_name parameter is null, the viewport itself is zoomed. Otherwise, the zoom operation will be performed on its child viewport specified by the res_name parameter. The value parameter defines the zoom factor or pan distance. Refer to GlgSetZoom on page 71 for a complete list of all zoom and pan types.
Sets or resets a viewport's GIS Zoom Mode. If the GIS zoom mode is set, any zooming and panning operations invoked 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. If the res_name parameter is null, the GIS zoom mode of the viewport itself will be set. Otherwise, the GIS zoom mode will be set for its child viewport specified by the res_name parameter. If the gis_name parameter is not null, it specifies the resource path of the GIS object relative to the gis_object parameter, or relative to the viewport if the gis_object parameter is null. The method may be invoked with gis_object=null and gis_name=null to reset the GIS zoom mode.
Method for saving an image of the visible area of the drawing's viewport.
MICROSOFT WINDOWS ONLY: Native windows printing, GLG controlled page layout.
MICROSOFT WINDOWS ONLY: Native window printing, windows-controlled page layout.
MICROSOFT WINDOWS ONLY: Native window printing with clipping disabled.
Sends a message specified by the message parameter. If the res_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 res_name parameter. The param<n> arguments define additional parameters of the message depending on the message type.
Explicit GetResourceObject() . The return value may be assigned to a GlgObjectC class.
Sets the new value of the object's attribute specified by the res_name . It is used for attaching Custom Property objects and aliases .
Finds a single tag or creates a list of tags matching the wildcard. In a single tag mode, returns the first found tag with the tag name. The unique_tags controls if only one tag is included in case there are multiple tags with the same name. It is ignored in the single tag mode. The return value may be assigned to a GlgObjectC class.
Gets a parent object or array of parents if num_parents > 1.
Scales an object relative to the center by the specified X, Y and Z scale factors.
Rotates an object around the specified center by the specified X, Y and Z angles.
Positions an object at the specified location using the specified anchoring.
Perform requested layout operation. Refer to The GLG Extended API on page 97 for more details.
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.
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.
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.
Constructor: creates a link object and connects it to a named GLG ICC Server.
Constructor: creates a link from a GlgObjectC class:
GlgObjectC some_object;
GlgLinkC link = some_object;
MFC CWnd derived class providing a window for displaying a GLG drawing.
Create control's window, load drawing from a generated memory image.
Create control's window, use the "$Widget" viewport of another object as a drawing.
Change the drawing, load a new drawing from a generated memory image.
Change the drawing, use the "$Widget" viewport of another object as a new drawing.
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.
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.
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.
Create the widget, load drawing from a generated memory image.
Create the widget, use the "$Widget" viewport of another 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.
Load a new drawing from a file (uses XtNglgDrawingFile resource).
Load a new drawing from a generated memory image ( uses XtNglgDrawingImage resource).
Use the "$Widget" viewport of another object as a new drawing (uses XtNglgDrawingObject resource).
Associates a viewport object of the wrapper widget with the instance of the class after the widget has been realized.
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.