Preface

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.

Index

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.

 

GLG Programming Reference Manual

 

Chapter 1 Using the C/C++ version of the Toolkit 17

1.1 Displaying a GLG Drawing 17

X Windows and Wrapper Widget 17

Creating the Wrapper Widget 18

Wrapper Widget Resources 19

Obtaining a Viewport Handle 23

Closing the Wrapper Widget 24

Microsoft Windows and GLG Custom Control 24

Creating the GLG Custom Control 25

Setting Initial Resources 25

Obtaining a Viewport Handle 26

Closing the Custom Control 27

Messages 27

The GLG Generic API 28

Function Summary 28

Generic Program Entry Point 29

Loading and Displaying a Glg Drawing using Generic API 29

GLG Generic API Function Descriptions 30

GlgAddCallback 30

GlgAddTimeOut 31

GlgAddWorkProc 32

GlgBell 32

GlgInit 33

GlgInitLocale 34

GlgInitialDraw 34

GlgLoadWidgetFromFile 35

GlgLoadWidgetFromImage 35

GlgLoadWidgetFromObject 36

GlgMainLoop 36

GlgRand 36

GlgRemoveTimeOut 37

GlgRemoveWorkProc 37

GlgResetHierarchy 37

GlgSetDefaultViewport 38

GlgSetupHierarchy 38

GlgSleep 38

GlgTerminate 39

Coding Examples 39

1.2 Details of using GLG Standard API for C and C++ 41

Creating a Widget 41

Widget Input 42

Displaying a Widget 42

Controlling a Widget 43

H and V Resources 43

Utilities 44

Linking with the GLG Libraries 45

OpenGL libraries 45

X Windows / UNIX 45

Microsoft Windows 46

Error Processing 47

1.3 Animating a GLG Drawing Using the Standard API 49

Overview 49

Function Descriptions 50

GlgConcatResNames 51

GlgConcatStrings 52

GlgCreateIndexedName 52

GlgCreateTagList 53

GlgError 54

GlgExportStrings 55

GlgExportTags 55

GlgFree 56

GlgGetDResource 56

GlgGetGResource 57

GlgGetMajorVersion 57

GlgGetSelectionButton 58

GlgGetSResource 58

GlgGISConvert 59

GlgHasResourceObject 59

GlgImportStrings 60

GlgImportTags 60

GlgOnDrawMetafile 61

GlgOnPrint 61

GlgPrint 62

GlgReset 63

GlgSaveImage 63

GlgSendMessage 64

GlgSetBrowserObject 65

GlgSetDResource 65

GlgSetErrorHandler 66

GlgSetGResource 67

GlgSetReadOnlyStrings 68

GlgSetResourceFromObject 68

GlgSetSResource 69

GlgSetSResourceFromD 70

GlgSetZoom 71

GlgSetGISZoom 72

GlgStrClone 73

GlgUpdate 73

GlgWinPrint 74

GlmConvert 75

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

GlgCreateLink 78

GlgDestroyLink 79

GlgLinkActive 79

GlgSync 79

Programming Examples of Inter-Client Communication 80

Writing a Custom Data Generator for Prototyping 83

1.4 Handling Input Events 85

Callback Events 85

Attaching Callbacks to a Viewport Object 85

Adding Callbacks to a GLG Wrapper Widget 86

Selection Callback 87

Input Callback 89

Trace Callbacks 90

Message Object 91

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

Trace Callback examples 95

1.5 The GLG Extended API 97

Overview 97

Handling GLG Objects 99

The Reference Count 99

Function Descriptions 99

GlgCreateObject 100

Using GlgCreateObject 101

GlgAddObjectToTop 113

GlgAddObject 113

GlgConstrainObject 115

GlgContainsObject 116

GlgCopyObject 117

GlgCloneObject 117

GlgCreateInversedMatrix 118

GlgCreatePointArray 118

GlgCreateResourceList 119

GlgCreateSelectionNames 120

GlgCreateSelection 121

GlgDeleteTopObject 122

GlgDeleteObject 122

GlgDeleteThisObject 124

GlgDropObject 124

GlgFindObject 125

GlgFitObject 125

GlgGetBoxPtr 126

GlgGetDrawingMatrix 127

GlgGetElement 127

GlgGetIndex 128

GlgGetMatrixData 128

GlgGetNamedObject 128

GlgGetParent 129

GlgGetResourceObject 130

GlgGetSize 130

GlgGetStringIndex 130

GlgGetTagObject 131

GlgIterate 131

GlgLayoutObjects 132

GlgLoadObject 134

GlgLoadObjectFromImage 135

GlgMoveObject 135

GlgMoveObjectBy 136

GlgPositionObject 137

GlgReferenceObject 137

GlgReleaseObject 139

GlgReorderElement 139

GlgRotateObject 140

GlgSaveObject 141

GlgScaleObject 141

GlgScreenToWorld 142

GlgSetElement 142

GlgSetMatrixData 143

GlgSetResourceObject 143

GlgSetStart 144

GlgSetXform 144

GlgSuspendObject 145

GlgTransformObject 146

GlgTransformObject 146

GlgTransformPoint 147

GlgUnconstrainObject 147

GlgWorldToScreen 148

Get and Set Resource Function Extension 149

Enabling Strong Typing 149

1.6 GLG C++ Bindings 151

Using GLG Objects 151

Automatic Referencing and Dereferencing 152

Comparison Operators 152

Using Input and Selection Callbacks 153

Miscellaneous Utility Classes 153

Programming Examples 153

C++ API Files and Libraries 154

GlgClass.h 154

GlgClass.cpp 154

stdafx.h 154

Standard and Extended API 154

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

GlgSessionC 154

GlgObjectC 155

GlgLinkC 164

GlgControlC (Microsoft Windows Only) 165

GlgWrapperC (X Windows Only) 167

Chapter 2 Using the ActiveX Control 169

Overview 169

GLG ActiveX Control Properties 170

General Page 170

HProperties Page 171

VProperties Page 172

DLinks Page 172

SLinks Page 172

GLinks Page 173

Dynamic Resource String Syntax 173

Persistency Support 174

GLG ActiveX Control Events 174

ActiveX Control Methods 175

ActiveX Control Extended API Methods 181

GLG ActiveX Control Security 188

GLG ActiveX Control Environment Variables 188

Chapter 3 Using the Java version of the GLG Toolkit 189

Introduction 189

Using the Documentation 191

Jar Files 191

Interfaces 191

GlgInputListener 191

GlgSelectListener 192

GlgTraceListener 192

GlgHListener 192

GlgVListener 192

GlgReadyListener 193

GlgErrorHandler 193

GlgBean class 193

GlgJBean class 193

GlgJLWBean class 193

Properties 194

Constructors 196

Methods 196

Extended API methods 202

GlgObject class 207

Variables 207

Methods 214

Extended API methods 220

GLG utility classes 226

GlgPoint class 227

GlgCube class 227

GlgMatrixData class 228

GlgTraceData class 228

GLG objects classes 229

Overview 229

GlgArc class 229

GlgBoxAttr class 229

GlgDynArray class 230

GlgFont class 230

GlgFontTable class 230

GlgFrame class 231

GlgFunction class 231

GlgHistory class 231

GlgImage class 231

GlgList class 232

GlgLight class 232

GlgMarker class 232

GlgParallelogram class 232

GlgPolySurface class 233

GlgPolygon class 233

GlgPolyline class 233

GlgReference class 234

GlgRenderingAttr class 234

GlgResourceReference class 234

GlgScreen 234

GlgSeries class 234

GlgSpline class 235

GlgSquareSeries class 235

GlgText class 235

GlgViewport class 235

GlgXform class 236

Attribute classes 236

GlgDataPoint class 236

GlgDDataPoint class 236

GlgGDataPoint class 236

GlgSDataPoint class 237

Data Value classes 237

GlgDataValue class 237

GlgDDataValue class 237

GlgGDataValue class 237

GlgSDataValue class 238

GlgMatrix class 238

Graph Layout Classes 238

Overview 238

GlgGraphNode class 239

GlgGraphEdge class 239

GlgGraphLayout class 240

Chapter 4 GLG Programming Tools and Utilities 247

4.1 The Data Generation Utility 248

Using datagen to Prototype Drawings in the Builder 248

Using datagen in Stand-Alone mode 248

Command Line Arguments and Options 249

Data Set Specification 250

Data Set Options 251

Data File Format 252

4.2 GLG Script 253

Overview 253

Standard Command Set 253

set_value 253

set_tag 254

update 254

sync 254

print 254

Database Record Support Commands 255

create_record 255

add_field 255

delete_record 255

read_records 255

end_read 256

read_one_record 256

Database Record Support Example 256

Extended Command Set 257

get_value 257

get_tag 257

select_object 257

select_container 258

reference 258

drop 258

create 258

add_new 260

add_copy 260

delete 261

4.3 Code Generation Utility 262
4.4 Drawing File Conversion Utility 263

4.5 C/C++ Graph Layout Component 265

Overview 265

Data Access Macros 265

Function Descriptions 267

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

Slider Message Object 283

Knob Message Object 284

Button Message Object 284

Text Message Object 286

Spinner Message Object 287

List Message Object 287

Option Message Object 288

Menu Message Object 288

Clock and Stopwatch Message Object 289

Timer Message Object 289

Palette Message Object 290

Font Browser Message Object 290

Browser Message Object 291

Zoom Message Object 291

Custom Event Message Object 293

Object Selection Message Object 295

Window Message Object 296

Appendix C: GLG Object's Attribute Table 297

Generic Attributes 297

Generic Attributes of Drawable objects 297

Polygon Attributes 297

Rendering Object Attributes 298

Marker Attributes 298

Text Object Attributes 298

Box Attributes Object Attributes 298

Arc Attributes 299

Parallelogram Attributes 299

Spline Object Attributes 299

Image Object attributes 300

GIS Object attributes 300

Group and List Objects' Attributes 300

Connector Object Attributes 300

Reference Object Attributes 300

Series Object Attributes 301

Square Series Object Attributes 301

Polyline Attributes 301

Polysurface Attributes 302

Frame Object Attributes 302

Viewport Attributes 302

Light Object Attributes 303

Screen Object Attributes 303

Colortable Object Attributes 304

Font Table Object Attributes 304

Font Object Attributes 305

Transformation Object Attributes 305

Alias Object Attributes 305

History Object Attributes 305

Data Object Attributes 305

Attribute Object Attributes 306

Function Object Attributes 306

Using the C/C++ version of the Toolkit

Using the ActiveX Control

Using the Java version of the GLG Toolkit

GLG Programming Tools and Utilities

Appendix A: Global Configuration Resources

Appendix B: Message Object Resources

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.

Generic Resources of the Message Object

All message objects have the following named attributes:

 

Resource Name

Data Type

Description

Format

String

Defines the format of the message object and the resources present in it. It is defined by the event type and, for input messages, the type of the input handler which detected the input activity and sent the message. It may have values such as Button , Slider , Knob , ObjectSelection and CustomEvent .

Origin

String

Contains one of the following values:

The name of the viewport with an input handler that generated the input message

The name of the object that generated the custom event message

The name of the viewport that generated the window message

An empty string for object selection and other message types.

FullOrigin

String

Contains the full path name of the viewport that initiated an input or window message, or the full path name of the object that initiated a custom event message. This resource will be set to an empty string for other types of messages.

Action

String

Describes the input action occurred. It may have values of ValueChanged , Activated , CustomEvent, MouseClick and so (see below). All input handlers send Abort2 when they receive a middle mouse button click, and Abort3 when they receive a right mouse button click.

SubAction

String

Describes the action in more details. For example, for the ValueChanged action it describes what caused the value change and may have values such as Pick , Motion , Increase , and so on.

Object

GlgObject

The viewport object that triggered the input callback, or the object that triggered custom event. This resource is present in all messages except the ObjectSelection message.

Specific Resources of the Message Object

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.

Slider Message Object

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.

 
Slider Message Object Resources

Resource

Value

Format

Slider

Action

ValueChanged indicates when a value change has resulted from a mouse click

GrabPointer is issued when the mouse button is pressed over the slider active area, causing the mouse to assume control of the slider position. The SubAction is NULL.

UngrabPointer is issued when the mouse button is released, ending mouse control of the slider position. The SubAction is NULL.

Object

The slider's viewport.

The ValueX, ValueY, Granularity, Increment and DisableMotion resources are also present in the message object.

Knob Message Object

This message object is generated by the GlgKnob input handler whenever a user acts to change the position of the knob.

 
Knob Message Object Resources

Resource

Value

Format

Knob

Action

ValueChanged indicates when a value change has resulted from a mouse click

GrabPointer is issued when the mouse button is pressed over the slider active area, causing the mouse to assume control of the slider position. The SubAction is NULL.

UngrabPointer is issued when the mouse button is released, ending mouse control of the slider position. The SubAction is NULL.

SubAction

Click when a value change has resulted from a mouse click

Motion when a value change has resulted from a mouse motion while the left mouse button is held down

Increase or Decrease when a value change has resulted from activating the corresponding button.

Object

The knob's viewport.

The Value, Granularity, Increment and DisableMotion resources are also present in the message object.

Button 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.

 
Button Message Object Resources

Resource

Value

Format

Button

Action

Activate (push buttons without OnState resource)

ValueChanged (toggle buttons with OnState resource)

Update

SubAction

MouseMove for Update actions when mouse moves inside or outside the button

NULL otherwise

Object

The button's viewport.

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.

Text Message Object

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.

 
Text Widget Message Object Resources

Resource

Value

Format

Text

Action

Activate if the key pressed was <Return>
NOTE: The <Return> key doesn't produce the Activate action when the text handler is deployed in the ActiveX control or MFC application on Windows, where the default <Return> key action is to close the active dialog.

Update for any other key.

Focus if the text input gained the input focus ( GlgNText handler only).

LosingFocus if the text input lost the input focus ( GlgNText handler only).

SubAction

none

Object

The text widget's viewport.

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.

Spinner Message Object

This message object is generated by the GlgSpinner input handlers whenever a user changes the spinner's value.

 
Spinner Widget Message Object Resources

Resource

Value

Format

Spinner

Action

ValueChanged if the spinner's value has changed

Update for any other user interaction.

Activate if the spinner's Done button was pressed. The Activate action of the spinner's text input object is also propagated to the spinner.

SubAction

none

Object

The spinner widget's viewport.

All resources of the spinner, such as Value, MinValue, MaxValue, Increment, etc. are also present in the message object.

List 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.

 
List Widget Message Object Resources

Resource

Value

Format

List

Action

Select if an item was selected or deselected.

Update for any other key.

SubAction

DoubleClick if the item was selected using a double-click, otherwise NULL .

Object

The list's viewport.

The GlgSendMessage method may be used to get extended selection information for a multiple selection list widget.

Option Message Object

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.

 
List Widget Message Object Resources

Resource

Value

Format

Option

Action

Select if a new option was selected.

Update for any other key.

SubAction

none

Object

The option widget's viewport.

Menu Message Object

This message object is generated by the GlgMenu input handler whenever a user presses a button in the menu.

 
Menu Message Object Resources

Resource

Value

Format

Menu

Action

Activate

SubAction

none

Object

The menu's viewport.

The SelectedIndex, SelectedValue and SelectedString resources are present in the message object even if they do not exist in the menu viewport, allowing the menu to pass information about the selection with the message.

Clock and Stopwatch Message Object

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.

Clock Widget Message Object Resources

Resource

Value

Format

Clock

Action

Update

SubAction

none

Object

The widget's viewport.

Stopwatch Widget Message Object Resources

Resource

Value

Format

Clock

Action

Start , Stop , or Reset depending on the corresponding stopwatch button.

SubAction

none

Object

The widget's viewport.

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.

Timer Message Object

This message object is generated automatically by the GlgTimer input handler upon every update of the timer output Value.

 
Timer Widget Message Object Resources

Resource

Value

Format

Timer

Action

Update

SubAction

none

Object

The timer's viewport.

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.

Palette Message Object

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.

 
Palette Message Object Resources

Resource

Value

Format

Palette

Action

Activate

SubAction

none

Object

The widget's viewport.

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.

Font Browser Message Object

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.

 
Font Browser Message Object Resources

Resource

Value

Format

FontBrowser

Action

Activate when the Done button of the Font Browser is activated

Cancel when the Cancel button is pressed.

Update on any other activity in the Font Browser.

SubAction

none

Object

The widget's viewport.

All the resources of the font browser widget are also present in the message object, allowing the font selection to be passed in the message.

Browser Message Object

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.

 
Browser Message Object Resources

Resource

Value

Format

Browser

Action

Activate when the Done button of the Browser is pressed.

Cancel when the Cancel button is pressed.

Select when the user clicks on a list entry.

Update on any other activity in the Browser.

SubAction

For the Update action, the SubAction may be DoubleClick when the user double-clicks to open another hierarchy level. Otherwise, this resource is not used.

Object

The browser's viewport.

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.

Zoom Message Object

This message object is generated when a zoom or pan operation is performed, activated either by user interaction or programmatically.

 
Browser Message Object Resources

Resource

Value

Format

Zoom

Action

Zoom or Pan

SubAction

Left, Right, Up or Down for the Pan action.

ZoomIn, ZoomOut, Start, End, Set or Reset for the Zoom action.

Object

The viewport that triggered the message.

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 .

Custom Event Message Object

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.

 
Custom Event Message Object Resources

Resource

Value

Format

CustomEvent

Action

MouseOver when user moves the mouse over an object with the GlgMouseOverEvent property or moves away from it.

MouseClick when user clicks on an object with the GlgMouseClickEvent property.

MouseRelease when user releases the mouse button after the custom mouse click event.

ObjectTooltip when an object tooltip is activated or erased.

ButtonTooltip when a button tooltip is activated or erased.

SubAction

none

EventLabel

The string value of the GlgMouseOverEvent or GlgMouseClickEvent properties attached to the object that generated the mouse click or mouse over events.

The tooltip string for the tooltip events (the string value of the TooltipString property attached to an object), or an empty string if the tooltip event is generated when the mouse moves away from the object and the tooltip is erased.

ButtonIndex

For events generated by a mouse click, the index of the button that generated the custom event. A value of 0 for other custom events.

Object

The top-level object that generated the custom event. For example, if a group object has the custom events defined, the group will be used as the Object resource when any object in the group is selected with the mouse. NULL when the message is invoked on mouse release, the mouse being moved away from the object or a tooltip being erased.

OrigObject

The low-level object that originated the custom event. If a group object has the custom events defined, the Object resource is the group and OrigObject is the object inside the group that was actually selected with the mouse. NULL when the message is invoked on mouse release, the mouse being moved away from the object or a tooltip being erased.

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. );

Object Selection Message Object

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.

 
Object Selection Message Object Resources

Resource

Value

Format

ObjectSelection

Action

MouseMove when user moves the mouse over objects in the drawing.

MouseClick when the user clicks on the objects in the drawing.

SubAction

none

ButtonIndex

The index of the button that generated the selection event, or 0 for selections generated by mouse over events.

Selection-Array

A group object containing object IDs of all objects on the lowest level of the hierarchy selected by the mouse event.

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.

Window Message Object

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.

 
Window Message Object Resources

Resource

Value

Format

Window

Action

DeleteWindow when user closes the viewport's window.

FirstExposure when the viewport's window is becoming visible for the first time.

SubAction

none

Object

The viewport that triggered the message.

 

Appendix C: GLG Object's Attribute Table

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.

Generic Attributes

Type

Object type.

Name

HasResources

Global

MoveByXform

Xform

An optional transformation object attached to the object.

Generic Attributes of Drawable objects

Visibility

History

A group containing all history objects attached to the object, if any.

CustomData

A group containing all custom properties attached to the object, if any.

NoCustomDataSetup

A flag to disable setup of custom properties when complex objects are attached as properties.

Aliases

A group containing all aliases attached to the object, if any.

RenderingAttr

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.

Polygon Attributes

EdgeColor

FillColor

LineWidth

LineType

FillType

OpenType

NoShade

Disables 3D shading.

Array

A group object containing polygon points.

Rendering Object Attributes

GradientResolution

GradientType

GradientColor

GradientCenter

GradientLength

GradientAngle

ArrowType

ShadowOffset

ShadowColor

FillDirection

FillAmount

If an object has a rendering object attached, the object inherits all of the rendering object's attributes, so that they can be queried directly from the object.

Marker Attributes

MarkerType

MarkerSize

Point

Control point

EdgeColor