This book provides information about programming with GLG and using different GLG Run-Time environments, including C/C++, Java and ActiveX control.
The first section of this manual describes the C API, while the rest of the book describes the C++, Java and ActiveX control versions.
Although various programming environments such as C, C++, Java, ActiveX, use different syntax to invoke the GLG API, the semantics of the API methods is the same in either environment. The C programming section provides the most detailed description of each method in terms of its effect on the underlying GLG objects. It also provides more examples and may be used as a reference for C, C++, Java and ActiveX programmers.
The book contains the following chapters:
GLG Programming Reference Manual
Using the C/C++ version of the Toolkit
How to render a GLG drawing from an application program.
Details of using GLG Standard API for C and C++
A general overview of the process of programming with the GLG Toolkit.
Animating a GLG Drawing Using the Standard API
Now that the drawing has been rendered, a description of how to animate the drawing with the function library supplied with the GLG Toolkit.
Handling Input Events
A description of the ways in which a GLG drawing can be used to get input from an application program user.
The GLG Extended API
How to modify a drawing from an application program.
C/C++ Graph Layout Component
How to modify a drawing from an application program.
GLG C++ Bindings
A description of GLG C++ Bindings and GLG MFC class.
GLG Programming Tools and Utilities
Descriptions of the utility tools that come with the GLG Toolkit.
Using the ActiveX Control
A description of the Glg ActiveX control that allows GLG drawings to be used with OLE-compliant Microsoft Windows applications or in IE.
Using the Java version of the GLG Toolkit
A description of the Java version of the Glg Run-Time environment.
Appendix A: Global Configuration Resources
A list of global configuration resources
Appendix C: GLG Object's Attribute TableAppendix B: Message Object Resources
A table of the GLG event types and their message object resources.
Appendix C: GLG Object's Attribute Table
A list of the default attribute names for all object types.
This guide assumes that you are conversant with the basic concepts of computer graphics programming. For a comprehensive discussion of three dimensional computer graphics, we recommend Computer Graphics: Principles and Practice , Foley, Van Dam, Feiner, and Hughes. Second edition, 1990; Addison-Wesley, Reading MA.
Please note that although the illustrations in this document represent the UNIX version of the GLG Graphics Builder, the information it contains is equally relevant to MS Windows users. The two versions present the same functionality in equivalent user interfaces, with minimal, cosmetic differences caused by the different platforms.
X Windows and Wrapper Widget 17
Creating the Wrapper Widget 18
Obtaining a Viewport Handle 23
Microsoft Windows and GLG Custom Control 24
Creating the GLG Custom Control 25
Obtaining a Viewport Handle 26
Generic Program Entry Point 29
Loading and Displaying a Glg Drawing using Generic API 29
GLG Generic API Function Descriptions 30
1.2 Details of using GLG Standard API for C and C++ 41
Utilities 44
Linking with the GLG Libraries 45
1.3 Animating a GLG Drawing Using the Standard API 49
Overview 49
Communicating from a Client Process 76
Using Inter-Process Communication with the Standard API 77
Connecting to the GLG Graphics Builder 78
Communication Function Descriptions 78
Programming Examples of Inter-Client Communication 80
Writing a Custom Data Generator for Prototyping 83
Attaching Callbacks to a Viewport Object 85
Adding Callbacks to a GLG Wrapper Widget 86
Examples 92
Printing Selected Object Names using Selection Callback 92
Printing Selected Object Names using Input Callback 92
Processing Input Object Messages 94
Refining Input Object Selection 95
Overview 97
Get and Set Resource Function Extension 149
Automatic Referencing and Dereferencing 152
Using Input and Selection Callbacks 153
Miscellaneous Utility Classes 153
C++ API Files and Libraries 154
List of Classes and Methods in the GLG C++ Bindings 154
Overview 169
GLG ActiveX Control Properties 170
Dynamic Resource String Syntax 173
GLG ActiveX Control Events 174
ActiveX Control Extended API Methods 181
Introduction 189
Interfaces 191
GlgBean class 193
GlgJBean class 193
GlgJLWBean class 193
GlgObject class 207
Using datagen to Prototype Drawings in the Builder 248
Using datagen in Stand-Alone mode 248
Overview 253
Database Record Support Commands 255
4.5 C/C++ Graph Layout Component 265
Overview 265
Appendix A: Global Configuration Resources 277
Appendix B: Message Object Resources 281
Generic Resources of the Message Object 281
Specific Resources of the Message Object 282
Clock and Stopwatch Message Object 289
Font Browser Message Object 290
Custom Event Message Object 293
Object Selection Message Object 295
Appendix C: GLG Object's Attribute Table 297
Generic Attributes of Drawable objects 297
Rendering Object Attributes 298
Box Attributes Object Attributes 298
Group and List Objects' Attributes 300
Connector Object Attributes 300
Reference Object Attributes 300
Square Series Object Attributes 301
Colortable Object Attributes 304
Font Table Object Attributes 304
Transformation Object Attributes 305
A message object is a GLG object used by the Toolkit to pass information about GLG input, object selection and other events to the Input callback. It is a group object containing data in the form of named resources. The Input callback code can query resources of the message object using the GLG GetResource methods. Refer to Handling Input Events of Using the C/C++ version of the Toolkit for more information on handling input events.
All message objects have the following named attributes:
A message object can have other resources as well, depending on the type of the input handler (for input events) or the type of the message (for object selection and custom events).
In the case of an input event, the message object includes all handler resources of the widget. For example, the message object coming from a GLG slider object may also contain such resources as ValueX, ValueY, Granularity, Increment, DisableMotion and others. These resources may be queried from either the message object or the viewport object that generated the message.
Handler resources not present in the viewport are not present in the message object. For example, a one-dimensional slider uses only one of its ValueX and ValueY resources, and the second resource will be absent from the message object. Several handlers define resources that appear only in the message object. For example, the GlgMenu input handler defines SelectedIndex and other resources used by the handler during its operation. All such resources are defined in the sections below.
The following sections describe the format of message objects generated by various input handlers as well as object selection and custom events. Refer to Input Handlers of the GLG User's Guide for a complete list of resources of various GLG input handlers.
This message object is generated by the GlgSlider or GlgNSlider input handlers whenever a user acts to change the position of the slider or scrollbar controlled by these input handlers.
The ValueX, ValueY, Granularity, Increment and DisableMotion resources are also present in the message object.
This message object is generated by the GlgKnob input handler whenever a user acts to change the position of the knob.
The Value, Granularity, Increment and DisableMotion resources are also present in the message object.
This message object is generated by the GlgButton or GlgNButton input handlers whenever a user presses the button or toggle controlled by these handlers.
|
Activate (push buttons without OnState resource) |
|
|
MouseMove for Update actions when mouse moves inside or outside the button |
|
As with all the message objects, the button message object also includes the handler resources that are used in the widget, such as PressedState , OnState and others. Refer to Input Handlers of the GLG User's Guide for a complete list of resources of the GlgButton and GlgNButton input handlers.
This message object is generated by the GlgText or GlgNText input handlers whenever a user enters text into the text input widget controlled by these input handlers.
The TextString resource and, for numerical inputs, Value resource are present in the message object even if they do not exist in the Text Widget's viewport, allowing the current values to be passed in the message. The MaxLength and, for numerical inputs, the MinValue, MaxValue, InputInvalid and ValueFormat resources are also present in the message object.
This message object is generated by the GlgSpinner input handlers whenever a user changes the spinner's value.
All resources of the spinner, such as Value, MinValue, MaxValue, Increment, etc. are also present in the message object.
This message object is generated by the GlgNList input handlers when a user selects items in a list widget controlled by this input handler.
This message object is generated by the GlgNOption input handlers when a user changes an option selection in an option menu or combox box widget controlled by this input handler.
This message object is generated by the GlgMenu input handler whenever a user presses a button in the menu.
The first message is generated by the clock and stopwatch widgets (GlgClock input handler) when they update the graphical representation of the clock. This is invoked automatically every second. If seconds are not displayed, the callback is invoked once per minute, instead.
The second message is only called from a stopwatch widget, whenever a user presses one of the control buttons.
|
Start , Stop , or Reset depending on the corresponding stopwatch button. |
|
Either message object will also contain resources of GlgClock input handler such as Sec , ValueSec , and so on. For the Stopwatch Widget, the Sec resource is present in the message object even if it does not exist in the stopwatch's viewport.
This message object is generated automatically by the GlgTimer input handler upon every update of the timer output Value.
The program should call the GlgUpdate() function to make the changes caused by the timer visible. The remaining resources of the message object ( Interval , Period , ActiveState , and so on) can be used to change the timer's state and parameters. The timer handler has been superseded by the timer transformation in the release 2.8 of GLG.
This message object is generated by the GlgPalette input handler whenever a user selects one of the objects in the palette with the left mouse button.
The palette's message object also has a resource named SelectedObject. This resource refers to the object selected and is used to get values of the that object's attributes. For example, for a color palette, the SelectedObject/FillColor resource of the message object yields the chosen color.
This message object is generated by the GlgBrowser input handler whenever any input activity is detected in the font browser controlled by the input handler.
This message object is generated by the GlgBrowser input handler whenever any input activity is detected in the resource, tag or custom data browser controlled by the input handler.
The Input callback is called with Activate as the value of the Action resource when the Done button of the file browser is activated or when the <Return> key is pressed with the keyboard focus in the Path text widget and the string is the name of some file.
This message object is generated when a zoom or pan operation is performed, activated either by user interaction or programmatically.
|
Left, Right, Up or Down for the Pan action. ZoomIn, ZoomOut, Start, End, Set or Reset for the Zoom action. |
|
The Start and End subactions are generated when the ZoomTo or custom zoom operation is started or finished. The Reset subaction is generated when the zooming state is reset using the `n' or `N' zoom action. The Set subaction is generated when the drawing is zoomed, paned or rotated using any zoom actions other than ZoomTo, custom zoom or Reset .
This message object is generated by a GLG drawing when a mouse moves over an object with the GlgMouseOverEvent property attached or when an object with the GlgMouseClickEvent property is clicked on with the mouse button. It is also generated when the tooltip (attached to an object or a button using the TooltipString property) is activated or erased. The viewport's ProcessMotion attribute has to be set to Move and Click or Click to enable custom event processing (except for the button tooltip events). The input callback can use the message object's resources to process the custom event. This message is invoked for any viewport object and does not require an input handler.
The GetResourceObject method may be used to get the object ID of the object and origin object from the message using the "Object" and "OrigObject" resource names:
GlgObject object = GlgGetResourceObject( message_object, "Object" );The resources of the object and origin object may be accessed through the message object using the Standard API. For example, the "Object/FillColor" resource name may be used to access the FillColor attribute of the object as a resource of the message object:
GlgSetGResource( message_object, "Object/FillColor", 1., 0., 0. );This message object is generated by a GLG drawing when objects in the drawing are selected via the mouse over or mouse click events. The viewport's ProcessMotion attribute has to be set to Move and Click or Click to enable object selection processing. The input callback can use the message object's resources to process the object selection. This message is invoked for any viewport object and does not require an input handler.
The objects selected by the mouse event may be queried from the SelectionArray using the GetElement method of the Extended API:
GlgObject selection_array = GlgGetResourceObject( message_object, "SelectionArray" ); for( i=0; i<GlgGetSize( selection_array ); ++i ) GlgObject selected_object = GlgGetElement( selection_array, i );The array contains the selected objects on the lowest level of the hierarchy. For example, if the object is part of a group, it will contain the object itself and not the group. The parents of the selected objects may be queried by using the selected object's GetParent method.
This message object is generated by a viewport object when it becomes visible for the first time or receives a message to delete or close its window. The delete window request is received when the user activates the window's controls to close the window. The input callback gives the program a chance to react to the user's request. This message is invoked for any viewport object and does not require an input handler.
The following lists the Default Attribute Names that may be used by a program to access attributes of various objects. The generic attributes are common attributes that may be used for objects of any type. The rest of the attributes exist only in certain types of objects and are listed under their corresponding object types.
Most of the attribute names are either self-explanatory or are described in the corresponding section GLG Objects of the GLG User's Guide. There are some attributes that are not described in the User's Guide and may be used only by a program to access some objects' internal structures. Such attributes may have an explanation next to the attribute name.
A group containing all history objects attached to the object, if any.
A group containing all custom properties attached to the object, if any.
A flag to disable setup of custom properties when complex objects are attached as properties.
A group containing all aliases attached to the object, if any.
The rendering object attached to the object, if any. Objects that have a rendering object attached, inherit the rendering object's attributes. In this case, rendering attributes may be queried directly from the object the rendering object is attached to.