PREV NEXT

Generic Logic, Inc. www.genlogic.com


4 Using the Java and C# Versions of the Toolkit

Introduction

The Java and C# versions of the GLG Toolkit provide Java and C# class libraries for native Java and C# applications. The class libraries are very similar, with majority of the methods, fields and interfaces being the same for both Java and C#. This chapter describes both class libraries in one document, listing environment-specific differences as applicable.

C# Note: Documentation for the C# methods uses the boolean alias for boolean values for brevity and uniformity with the corresponding Java methods. In the actual C# code, the bool type is used. All other differences between the Java and C# versions are explicitly noted.

Using the Documentation

This chapter describes the language-specific details of using the Java and C# versions of the Toolkit. It does not go into details of the GLG objects behavior when the class library methods are listed.

Refer to Using the C/C++ version of the Toolkit on page 31 for a detailed description of semantics of the API methods, as well as details of handling user input (described in the Handling User Input and Other Events section on page 103). The semantics of all API methods is the same in all versions of the Toolkit, and the C/C++ section provides examples and details of using them.

Refer to the GLG Programming Tutorial for Java for detailed examples and a walk-through tutorial.

An on-line documentation for the Java and C# class library (in the JavaDoc and XMLDoc formats, respectively) is also provided. The online documentation is intended as a quick reference for the Java and C# classes and methods, but not as a definitive guide to using the Toolkit. This chapter provides more detailed information specific to the use of the GLG Java and C# class libraries. Refer to Using the C/C++ version of the Toolkit for more information about the semantics of the GLG objects usage that is common across all supported platforms.

Numerous demos and examples for both Java and C# are also provided (in the DEMOS_JAVA and examples_java directories for Java, and DEMOS_CSHARP, examples_csharp.NET and examples_csharp_ocx for C#).

Overview

The Java and C# versions of the GLG Toolkit provide Java and C# class libraries that load and display GLG drawings in Java and C# applications. Both class libraries support all GLG Toolkit features and are available in all forms of the GLG API: Standard, Intermediate and Extended.

The Java and C# versions of the Toolkit use GLG drawings saved with the GLG Graphics Builder. The drawings imported from the Builder must be saved in ASCII format, either compressed or uncompressed. The same drawing may be used in both Java, C# and C/C++ versions of the Toolkit. The drawing can also be generated on the fly using the Extended API, which provides methods to create and copy objects at run-time.

Class Hierarchy

GlgObject is the main class of the Java version of the GLG Toolkit. The GlgObject class contains all the functionality available to GLG objects. Since all objects implement the Get and SetResource functions central to the GLG architecture, it's only natural that the GlgObject superclass is heavily used, making it a Superclass in a more general sense. Using one main superclass also makes it easier to deal with GLG objects by limiting the number of classes and methods one has to learn.

The GLG Toolkit also contains classes for different GLG objects: polygons, arcs, etc. However, only the constructors of these classes are used. Once the object is created, all further object manipulation is done by using the GlgObject methods.

The GLG Toolkit also provides classes such as GlgPoint, GlgCube and some other utility classes, mainly used to exchange information between different object methods.

Integrated Components for Java and .NET

The Java class library provides the GlgBean, a Java bean component that seamlessly integrates GLG Toolkit into a Java environment, embedding Java-based GLG components into Java application frameworks and Java IDEs. Several types of the GLG Bean are provided for AWT and Swing.

The C# class library provides the GlgControl component which integrates GLG Toolkit in the .NET and Visual Studio environment, providing properties and events that can be used in the Visual Studio Design Mode.

The GLG component (GlgBean in Java or GlgControl in C#) encapsulates a GLG viewport object that loads, displays and animates a GLG drawing. The component provides several properties that facilitate loading the drawing: DrawingFile, DrawingURL, DrawingName and DrawingObject.

Two Ways to use the GLG API

There are two alternatives for most of the GLG API methods: the methods of the GlgObject class, and the methods of the GlgBean or GlgControl integrated component.

While the GlgObject methods have to be invoked for individual objects, the component provides a central place for invoking methods on any object or any resource inside the component's drawing. The methods exposed by the GLG component are similar to the methods of the GlgObject class, and decision which methods to use depends on the complexity of the application's interaction with the drawing displayed in the component:

In the rest of this chapter, the GlgBean and GlgControl integrated components may be referred generically using the term component.

Events and Input Handling

GLG integrated components (GlgBean in Java and GlgControl in C#) provide two mechanisms for handing user input: listeners or callbacks. In the C# environment, the GlgControl component also supports C# events.

Listeners can be added to a GLG component to handle events of different types, such as input or object selection. A listener must implement an interface to handle events of the corresponding type. For example, GlgInputListener must implement the InputCallback method.

The following listeners are supported for GlgBean and GlgControl components:

By default, the GLG Component (GlgBean or GlgControl) is used as a default listener for all event types and implements callback methods required by the listener interfaces: InputCallback, ReadyCallback and so on. This makes it more convenient to create custom components by subclassing GlgBean or GlgControl and overriding some or all of its listener interfaces. An application can also add listeners to the component (via the AddListener method) to handle events without subclassing the component.

In addition to the GlgBean or GlgControl listeners, event listeners may also be added to individual child viewports displayed in the component's drawing using methods of the GlgObject class. This allows an application to provide a custom input handler for each child viewport displayed in the drawing if needed. Input, Select, Trace and Hierarchy listeners may be added to individual GLG objects, while H, V and Ready listeners are supported only for the GLG component, as they are not needed at the GlgObject level.

In the C#/.NET environment, GlgControl events are also implemented for the convenience of using the control in the VisualStudio's design mode. The supported .NET event types match the types of the event listeners: GlgInput, GlgSelect, GlgH, GlgV, GlgHierarchy, GlgReady, GlgTrace and GlgTrace2.

Installable Interface Handlers API

GLG Installable Interface Handler Utilities assist an application developer with implementing functionality of complex user interactions usually encountered in editor-style applications. The utilities include a collection of methods as part of the GLG Intermediate API library. The GLG Diagram demo provides an example of a custom diagraming editor application implemented using the GLG Installable Interface Handlers functionality.

Refer to the GLG Installable Interface Handlers on page 208 for an overview of the Installable Interface Handlers functionality. Refer to the GLG Java, C# or JavaScript online documentation for descriptions of the interface handler methods for the respective APIs.

Using Threads in Java and C#/.NET

Threads are commonly used in Java and C# applications for getting data from various sources over a network. Using threads for querying data allows an application to continuously stream incoming data independently from the user interface.

GLG Toolkit uses Swing in Java and .NET graphics framework in C#. These graphical frameworks are single-threaded and do not allow asynchronous access to graphics. All access to graphics should be done only from the event dispatching thread in Java and the UI thread in C#. Since GLG uses native interface components and graphics for displaying GLG drawings, all calls to the GLG API methods must be performed from the event dispatching thread as well.

This applies to all GLG calls, including GetResource and SetResource methods. These methods are not simple getters and setters, but rather complex methods that traverse the GLG object hierarchy to perform the requested operation. This traversal operation is not thread-safe.

If an application uses a thread-safe timer to obtain new data, it can update GLG drawings by invoking GLG SetResource and Update methods directly from the timer callback.

If an application uses data threads for querying new data, the thread code can not invoke SetResource and Update methods directly, and instead should pass the accumulated data to the event thread where the data will be used to update the graphics. In Java, this can be accomplished by using the SwingUtilities.InvokeLater method. In C#/.NET, the data thread can use the GlgControl's Invoke method or the InvokeRequired property to execute SetResource and Update calls on the UI thread.

An alternative way to implement multi-threaded design would be have a data thread continuously accumulating data, and use a thread-safe timer to periodically (several times per second) check if new data from the data thread are available. If the new data came in, the timer code can issue SetResource calls for all new data values and then invoke the Update method to redraw the drawing just once for optimum performance.

With either design, it is the application's responsibility to properly synchronize access to all data structures if data threads are used.

Types of GLG Bean (Java Only)

Several GLG Bean classes are provided:

AWT-based Java bean.
Heavyweight Swing-based Java bean.
Lightweight Swing-based Java bean for use with JDesktopPane and JInternalFrame.

All GLG Bean classes have the same GLG-inherited interface and differ only in the methods inherited from respective AWT or Swing superclasses. The AWT and Swing-based GLG beans should not be intermixed in one application. The light-weight version of the GLG bean (GlgJLWBean) uses Swing's light-weight model which imposes a performance penalty related to the absence of a native window and a necessity to handle clipping in software. Although it is OK to use the light-weight component for small to medium drawings, a heavy-weight component is recommended for large graphically-intensive drawings.

The type of the top level bean may be different from the type of the components used to render GLG viewport objects displayed inside the GlgBean and GlgJBean. By default, the GlgBean uses AWT components, while the GlgJBean and GlgJLWBean use Swing-based components.

GLG Graphics Server
GLG Graphics Server for JSP / Java

A separate GLG class library for the JSP environment is provided in the GlgServer.jar file. This class library provides the GLG Extended API, and also supports headless operation as well as a multi-threaded access by the servlet threads. When used in a servlet, the GlgObject classes should be used instead of the GLG Bean. The examples_jsp directory contains elaborate examples of the GLG servlets with the source code.

GLG Graphics Server for ASP.NET / C#

The Glg.NETServer.dll file provides the GLG DLL for the ASP.NET environment. In addition to providing the GLG Extended API, this DLL provides the GlgHttpRequestProcessor class used to implement custom HTTP handlers in the ASP.NET environment. The DLL also supports headless operation and multi-threaded ASP.NET handlers. The examples_ASP.NET directory contains elaborate source code examples of custom GLG-based ASP.NET HTTP handlers.

Error Handling and Miscellaneous Features
Error Handling

The Toolkit provides the GlgErrorHandler interface for custom error handling. A custom error handler can be installed using the SetErrorHandler method. The Error method of the error handler will be invoked with the error message string as a parameter when a GLG error is detected, such as trying to access a null or non-existing resource.

The default error handler emits an audio beep and displays the error message in the Java console or in a message dialog for C#/.NET. The error message includes a stack trace showing the location where the error occurred.

In the C#/.NET version of the class library, the default error handler also logs the error message in the glg_error.log log file. The location of the log file is determined by the GLG_LOG_DIR and GLG_DIR environment variables as described in the Error Processing and Debugging section on page 49. An application can use the GlgObject.Error method to signal errors or log messages into the glg_error.log log file.

Anti-aliasing and Point Coordinates Precision

In the Java version of the GLG class library, a global GlgAntiAliasing configuration resource, described on page 429 of Appendices, controls default anti-aliasing setting for all drawings in an application. The anti-aliasing behavior of individual viewports can be controlled at run time by the viewport's AntiAliasing attribute. The AntiAliasing attribute of individual polygons is ignored.

In the Java environment, point coordinates are passed as integer values, and the only available settings of the GlgAntiAliasing global configuration resource are ANTI_ALIASING_OFF and ANTI_ALIASING_INT.

In the C# version, the anti-aliasing behavior of polygons is controlled on per-object basis depending on the setting of the object's AntiAliasing attribute.

In the .NET environment, point coordinates are passed as double values and the ANTI_ALIASING_DBL setting of the attribute is supported in addition to ANTI_ALIASING_OFF and ANTI_ALIASING_INT. If an object's AntiAliasing attribute is set to ANTI_ALIASING_UNSET (default, displayed as INHERIT in the Builder), the anti-aliasing setting is inherited from the viewport the object is displayed in, or from the global GlgAntiAliasing configuration resource.

Generic API

While the most common way to display a GLG drawing in a Java or .NET application is using integrated GlgBean and GlgControl components described above, an application can also display a GLG drawing using only the methods of the GlgObject class:

Java:
GlgObject drawing = GlgObject.LoadWidget( "my_drawing.g", GlgObject.FILE );
drawing.AddListener( GlgObject.INPUT_CB, my_input_handler );
drawing.InitialDraw();

C#:
GlgObject drawing = GlgObject.LoadWidget( "my_drawing.g", GlgMediumType.FILE );
drawing.AddListener( GlgCallbackType.INPUT_CB, my_input_handler );
drawing.InitialDraw();

The InitialDraw method in the above code creates a window for the top-level viewport of the drawing and displays the drawing in it.

Class Library Files for Java and C#/.NET

Java Jar Files

The following JAR files are available for the Java version of the Toolkit:

GlgCE.jar - a free Evaluation and Community Edition version, which includes all GLG APIs: Standard, Intermediate and Extended.
Glg2.jar - a commercial version of the Standard API. It is used to display the drawing, update it with dynamic data and handle user input.
GlgInt2.jar - a commercial version of the Intermediate API. It includes the Standard API and extends it with methods to manipulate objects in the drawing at run time and implement elaborate logic for handling user input.
GlgExt2.jar - a commercial version of the Extended API, includes all methods of the Standard and Intermediate APIs and adds methods for creating and adding objects to the drawing at run time.

GlgGraphLayout.jar provides the graph layout functionality.

GlgDemo.jar contains the class files of the GLG demos.

The following GLG Graphics Server JAR files are provided:

GlgServerCE.jar - a free Evaluation and Community Edition version
GlgServer.jar - a commercial version of the GLG Graphics Server for JSP.

Both Graphic Server JARs include all GLG APIs: Standard, Intermediate and Extended.

C#/.NET DLLs

The following DLLs are available for the C#/.NET version of the Toolkit:

Glg.NetCE.dll - a free Evaluation and Community Edition version, includes all GLG APIs: Standard, Intermediate and Extended.
Glg.Net.dll - a commercial version with the Standard API. It is used to display the drawing, update it with dynamic data and handle user input.
Glg.NetInt.dll - a commercial version with the Intermediate API. It includes the Standard API and extends it with methods to manipulate objects in the drawing at run time and implement elaborate logic for handling user input.
Glg.NetExt.dll - a commercial version with the Extended API, includes all methods of the Standard and Intermediate API and adds methods for creating and adding objects to the drawing at run time.

Glg.Net.GraphLayout.dll provides the commercial version of the graph layout library, while Glg.Net.GraphLayoutCE.dll can be used with the free Community Edition.

The following GLG Graphics Server DLLs provide all GLG APIs (Standard, Intermediate and Extended):

Glg.NetServerCE.dll - a free Evaluation and Community Edition version
Glg.NetServer.dll - a commercial version of the GLG Graphics Server for ASP.NET.

JurassicGLG.dll provides the JavaScript interpreter used by the above DLLs.

Interfaces

Interfaces are used for event listeners, custom error and alarm handlers, label and tooltip formatters, as well as utility functions.

Event listeners note: Only a single event listener for each event type is enabled per an instance of a GLG object or a GLG component. The GLG component is a default listener for all events, and adding a listener to a component disables the component's callback for the corresponding event. Multiple listeners can be added to different child viewports inside the component's drawing, so that each viewport can have it sown event listener if required.

GlgInputListener

public interface GlgInputListener

The main listener interface for handling user interaction and object selection.

Methods
public void InputCallback( GlgObject object, GlgObject message_object )

This callback method is invoked every time a user interacts with input objects in the drawing or selects objects in the drawing with the mouse. More information about the type of the input activity may be extracted from the message object passed by the message_object parameter. The object parameter is the viewport the listener is attached to (or the top viewport of the drawing if the listener was added to GlgBean or GlgControl). Refer to the Input Callback section of Handling User Input and Other Events on page 107 for more details.

GlgSelectListener

public interface GlgSelectListener

Listener interface used to handle an object selection with the mouse, provides a simplified name-based interface for object selection handling.

GlgInputListener provides a more elaborate alternative for handling selection events using either object IDs, or custom event and command actions which can be attached to objects in the Graphics Builder.

Methods
public void SelectCallback( GlgObject object, Object[ ] name_array, int button )

This callback is invoked every time the user selects one or more objects with the mouse. The name_array parameter is a null-terminated array containing names of the selected objects. Each name includes a complete GLG resource path that ends with the object's name. The button parameter is the mouse button used for selection (1, 2 or 3). The object parameter is the viewport the listener is attached to (or the top viewport of the drawing if the listener was added to GlgBean or GlgControl). Refer to the Selection Callback section of Handling User Input and Other Events on page 105 for more details.

GlgTraceListener

public interface GlgTraceListener

Listener interface used to handle low-level native events.

Methods
public void TraceCallback( GlgObject object, GlgTraceData trace_info )

This callback is invoked for every event occurring in any of the drawing's viewports and may be used to implement custom selection or hot-spots logic and to handle low-level native events. The object parameter is the viewport the listener is attached to (or the top viewport of the drawing if the listener was added to GlgBean or GlgControl). Refer to the Trace Callbacks section of Handling User Input and Other Events on page 108 for more details.

GlgHierarchyListener

public interface GlgHierarchyListener

Listener interface used for initialization of drawings displayed in SubWindows or instances of the SubDrawings.

Methods
public void HierarchyCallback( GlgObject object, GlgHierarchyData hierarchy_info )

This callback is invoked every time a SubWindow object loads a new drawing to be displayed, or a SubDrawing object loads its template. The callback may be used to attach different Input listeners for each drawing displayed in the subwindow to handle user interaction in each drawing. It may also be used to initialize the subwindow's drawing or subdrawing's template before it is drawn.

The object parameter is the viewport the listener is attached to (or the top viewport of the drawing if the listener was added to GlgBean or GlgControl). Refer to the Hierarchy Callback section of Handling User Input and Other Events on page 109 for more details.

GlgHListener

public interface GlgHListener

Interface for setting the initial values of resources of the drawing displayed in the GlgBean or GlgControl.

Methods
public void HCallback( GlgObject viewport )

This callback is invoked after the component's drawing is loaded, but before the drawing hierarchy is set up. It may be used to set the initial resources of the drawing, such as the number of samples in a GLG graph object. The viewport parameter is the top viewport of the drawing displayed in the GlgBean or GlgControl.

GlgVListener

public interface GlgVListener

Interface for setting the initial values of resources of the drawing displayed in the GlgBean or GlgControl.

Methods
public void VCallback( GlgObject viewport )

This callback is invoked after the component's drawing is loaded and set up, but before it is displayed for the first time. It may be used to set the initial resources of the drawing. For example, it may be used to supply data for the initial appearance of a GLG graph object. The viewport parameter is the top viewport of the drawing displayed in the GlgBean or GlgControl.

GlgReadyListener

public interface GlgReadyListener

Interface for detecting the Ready event.

Methods
public void ReadyCallback( GlgObject viewport )

This callback is invoked after the component's drawing is loaded, setup and displayed for the first time. It may be used to detect when the GlgBean or GlgControl is ready and begin updating the drawing with data. The viewport parameter is the top viewport of the drawing displayed in the GlgBean or GlgControl.

GlgErrorHandler

public interface GlgErrorHandler

Error handling interface.

Methods
public void Error( String message, int eror_type, Exception exception )                          (Java)
public void Error( String message, GlgErrorType error_type, Exception exception )       (C#)

Displays the error message. The message parameter is the text of the error message; exception is an optional parameter that, if not null, supplies exception information and the exact location of the error shown in the stack trace. The error_type parameter specifies the type of the error message and may have the following values:

INTERNAL_ERROR
USER_ERROR
USER_ERROR_NO_STACK
WARNING
INFO              (Java)
LOGGING     (C#)

Refer to the description of the Error method on page 320 for more information on the error types.

GlgAlarmHandler

public interface GlgAlarmHandler

Alarm handling interface.

Methods
public void Alarm( GlgObject data_object, GlgObject alarm_object, String alarm_label, String action, String subaction, Object reserved )

Processes the alarm message. The data_object parameter is the resource whose value has changed. The alarm_object parameter is the alarm attached to the data_object to monitor its value; it is the alarm that generated the alarm message. The alarm_label parameter supplies the AlarmLabel used to identify alarm_object. The action and subaction parameters provide details about the condition that caused the alarm; refer to the Alarm Messages section on page 197 for more information.

GlgLabelFormatter

public interface GlgLabelFormatter

An interface for supplying custom axis labels.

Methods
public void GetString( GlgObject axis, int label_type, int value_type,
double value, long sec, double fractional_sec, Object reserved )         (Java)
public void GetString( GlgObject axis, GlgLabelType label_type, GlgValueType value_type,
double value, long sec, double fractional_sec, Object reserved )         (C#)

The method is invoked every time a new label string needs to be generated. It can create and return a label string, or return null to use a default label string.

The axis parameter is the axis the formatter is attached to.
The label_type parameter specifies the type of the label to be generated: TICK_LABEL_TYPE, SELECTION_LABEL_TYPE or TOOLTIP_LABEL_TYPE.
The value_type parameter is the type of the axis value: NUMERICAL_VALUE or TIME_VALUE.
The value parameter provides the X value corresponding to the label position.
The sec parameter supplies an integer number of seconds since the Epoch corresponding to the label position.
The fractional_sec parameter supplies the fractional number of seconds.
The reserved parameter must be null.

GlgChartFilter

public interface GlgChartFilter

An interface for a custom chart filter. All chart filter methods receive input filter data via the filter_data parameter. The client_data parameter contains data passed to the filter by the application when the filter was attached to a plot.

Refer to the CustomChartFilter.java file (CustomChartFilter.cs file for C#) in the src directory of the GLG installation for an extensive self-documented coding example of implementing several types of custom filters.

Methods
int Start( GlgChartFilterData filter_data, Object client_data );

Invoked before drawing plot's data, must return CHART_FILTER_VERSION constant.

void AddSample( GlgChartFilterData filter_data, Object client_data );

Invoked by the plot to supply a next data sample to filter.

int Flush( GlgChartFilterData filter_data, Object client_data );                                    (Java)
GlgChartFilterRval Flush( GlgChartFilterData filter_data, Object client_data );        (C#)

Invoked before starting a new filter interval (defined by the filter precision) to flush accumulated aggregate data for the previous interval. Must returns one of the following values:

void Finish( GlgChartFilterData filter_data, Object client_data );

Invoked after drawing plot's data.

GlgTooltipFormatter

public interface GlgTooltipFormatter

An interface for supplying custom tooltip labels.

Methods
public void GetString( GlgObject viewport, GlgObject object, GlgObject tooltip_obj,
int root_x, int root_y )

The method is invoked every time a new tooltip string needs to be generated. It can create and return a tooltip string, or return null to use a default tooltip string.

The viewport parameter is the parent viewport of the object.
The object parameter is the object with the tooltip action.
The tooltip_obj is a data object of S (string) type that contains the tooltip string.
The root_x parameter is the X coordinate of the cursor relative to the root window.
The root_y parameter is the Y coordinate of the cursor relative to the root window.

GlgObjectActionInterface

public interface GlgObjectActionInterface

An interface used for performing special queries, such as FindMatchingObjects.

Methods
public boolean Action( GlgObject object )

The method is invoked for every object that is tested and should return true if the object matches a desired custom search criterion.

The object parameter is the object being tested.

GlgGISRequestObserver

public interface GlgGISRequestObserver

A GIS request observer interface used to notify the program about the status of the asynchronous GIS map requests.

Methods
public void RequestUpdate( GlgObject gis_object, GlgGISRequestStatus status)

This method is invoked with the status of the GIS request when the GIS request becomes ready or is aborted. The gis_object parameter is set to the request's GIS object. The status parameter specifies the reason this method is invoked and may be one of the following constants (defined in the GlgObject class for Java or the GlgGISRequestStatus enum for C#):

public boolean RequestAdjustment()

This method is invoked before proceeding with the request to specify if any adjustments need to be done. If the method returns true, the AdjustRequest method will be invoked to adjust request parameters before proceeding with the request. For example, a map projection or displayed GIS layers may need to be changed depending on the map zoom factor.

public boolean AdjustRequest( GlgGISRequestData request_data )

If RequestAdjustment returns true, this method is invoked before proceeding with the request to perform any desired adjustments to the request parameters. This may be used to adjust parameters of the request created by the RequestGISZoom method before the request is used to generate a new map image. The method must return true if any request parameters were modified.

The request_data object supplies GIS parameters of the request, which can be modified in place to adjust them. See the GlgGISRequestData class section on page 352 for more information.

Enums

Enums are used in the C# version of the class library. The enums are defined at the top level of the GenLogic package namespace. Refer to the online documentation in the XMLDoc format for a list of all enums of the GenLogic namespace.

In the Java version, integer constants named the same way as enum elements are used. The constants are defined at the GlgObject class level. Refer to the online documentation in the JavaDoc format for a list of all enums of the GenLogic namespace.

GLG Integrated Component Classes

The GlgBean and GlgControl integrated components are provided for Java and C#/.NET deployment. While the classes have different constructors, the API methods described below are common for both Java and C# components.

GlgBean Java class

GlgJBean Java class

GlgJLWBean Java class

public class GlgBean extends Applet implements GlgInputListener, GlgSelectListener, GlgTraceListener, GlgHierarchyListener, GlgHListener, GlgVListener, GlgReadyListener, GlgErrorHandler

AWT-based Java bean.

public class GlgJBean extends JApplet implements GlgInputListener, GlgSelectListener, GlgTraceListener, GlgHierarchyListener, GlgHListener, GlgVListener, GlgReadyListener, GlgErrorHandler

Heavyweight Swing-based Java bean.

public class GlgJLWBean extends JPanel implements GlgInputListener, GlgSelectListener, GlgTraceListener, GlgHierarchyListener, GlgHListener, GlgVListener, GlgReadyListener, GlgErrorHandler

Lightweight Swing-based Java bean for use with JDesktopPane and JInternalFrame.

Description

GLG Beans are Java bean components that integrate GLG objects into the Java environment. The GLG Bean is a Java Bean encapsulation of a GLG viewport object that loads, displays and animates a GLG drawing. All GLG Bean classes have the same GLG-inherited interface and differ only in the methods inherited from their respective AWT or Swing superclasses. The AWT and Swing-based GLG beans should not be intermixed in one application.

The GLG Bean provides methods similar to those of GlgObject. Methods of the GLG Bean and the bean's viewport GlgObject may be used interchangeably.

The GLG Bean implements all GLG listener interfaces and is used as a default listener for all GLG events. The bean's listener interface methods may be overridden by the bean's subclasses.

When the GLG Bean is used as an applet, it provides functionality for following HTML links on mouse clicks. If an object contains an S resource named "$href", the value of the resource is interpreted as a URL which defines an HTML link. If the user selects an object in the drawing which has an HTML link, the link's URL will be automatically loaded. Custom Properties may be used to attach the "$href" property to objects in the Builder. The HRefTarget property of the bean may be used to define an html target name to open the link in a different browser window.

The functionality for following HTML links is activated by setting the TraceHRef bean property to true. The property is set to false by default. The value of the ProcessMouse attribute of the viewport containing the drawing displayed in the bean also has to include the Click mask to activate processing of the mouse selection events. If the mask include the Move mask, the bean will also trace the link's hot spot, changing the cursor shape when cursor hovers over an object that represents a link and displaying the link's URL in the status bar.

GlgControl C# class

public class GlgControl : System.Windows.Controls.Control, GlgInputListener, GlgSelectListener, GlgTraceListener, GlgHierarchyListener, GlgHListener, GlgVListener, GlgReadyListener, GlgErrorHandler

GLG .NET control.

Description

GglControl is a .NET-based custom control component that integrates GLG drawings into the .NET and Visual Studio environment. The GlgControl is a .NET encapsulation of a GLG viewport object that loads, displays and animates a GLG drawing.

GlgControl provides methods similar to those of GlgObject. Methods of GlgControl and the control's viewport GlgObject may be used interchangeably.

GlgControl implements all GLG listener interfaces and is used as a default listener for all GLG events. The control's listener interface methods may be overridden by the control's subclasses.

Fields

public boolean SelectEnabled

Enables or disables the Select callback, listener and event; is set to true by default.

To increase performance when the Select callback is not used, set SelectEnabled to false before loading the component's drawing.

public boolean HierarchyEnabled

Enables or disables the Hierarchy callback, listener and event; is set to true by default.

To increase performance when the Hierarchy callback is not used, set HierarchyEnabled to false before loading the component's drawing.

public boolean TraceEnabled
public boolean Trace2Enabled

Enables or disables the Trace and Trace2 callbacks, listeners and events. The Trace callback is invoked before the native event is processed by the Input and Select callbacks, and Trace2 is invoked after the native event is processed. The properties are set to false by default. To enable the callbacks, set the corresponding property to true before loading the component's drawing.

The GlgTraceData class contains information about the native event and is passed to trace callbacks and events as the trace_info parameter. A single method can handle both Trace and Trace2 events, using the trace_info.trace2 field to differentiate between them. The field is set to false for the Trace events and to true for Trace2.

C# Properties

DrawingFile

The filename of the drawing to be loaded into the control.

public String DrawingFile { get; set; }

DrawingURL

The URL of the drawing to be loaded into the GlgBean or GlgControl.

public String DrawingName { get; set; }

Using Properties in the Visual Studio Design Mode

An application can add C# event handlers and set the DrawingFile or DrawingURL properties of GlgControl using the Visual Studio Design Mode.

Java Bean Properties

DrawingFile

The filename of the drawing to be loaded into the bean.

DrawingURL

The URL of the drawing to be loaded into the GlgBean or GlgControl.

If a relative filename, such as "drawing.g", is specified when the bean is used as an applet, it will be interpreted relatively to the applet's DocumentBase.

DrawingName

A relative drawing name. This can be used to transparently specify the drawing location for both the applet and stand-alone Java application. For an applet, it is relative to it's DocumentBase. For a stand-alone application, it is relative to the current directory.

DrawingResource

The name of the drawing file in a jar file.

CharsetName

The name of a Java charset to be used for decoding strings in the drawing when it is loaded. It should match the locale in which the drawing was created in the GLG Graphics Builder. If it is set to null, the default charset will be used.

SetupDataURL

The URL of the setup script in the GLG Script Format to use for initializing drawing's resources.

DataURL

The URL of the data script in the GLG Script Format to use for periodic updates of the drawing's resources.

UpdatePeriod

Double value that defines an update interval for reading DataURL, in seconds.

HResource0
HResource1
HResource2
HResource3
HResource4

String properties used to initialize drawing's resources before hierarchy setup. For information about the format of the strings see Dynamic Resource String Syntax on page 249.

VResource0
VResource1
VResource2
VResource3
VResource4

String properties used to initialize drawing's resources after hierarchy setup. For information about the format of the strings see Dynamic Resource String Syntax on page 249.

TraceHRef

If set to true, the bean will trace the hot spots for http links which are defined in the drawing. To make a graphical object a hot spot, it needs to have a custom property of an S type named "$href". The value of the custom property defines link's URL. When the mouse moves over an object with a link, the cursor will change and, if the bean is used inside the browser, the links' URLs will be displayed in the browser's status area. The default value of the property is false.

HRefTarget

Specifies a name of the browser frame to use when opening http links defined in the drawing. The default value is null, causing link's URL to replace the bean.

JavaLog

Enables Java Console logging of bean events for debugging bean problems.

ResourceLog

Enables Java Console logging of resource settings from the SetupDataURL and DataURL to debug data scripts.

APILog

Enables Java Console logging of the bean's GLG API methods.

Constructors

Java Constructors
public GlgBean()
public GlgJBean()
public GlgJLWBean()

Create a GLG bean.

C# Constructors
public GlgControl()

Creates a GLG control.

Standard API Methods of GlgBean and GlgControl Containers

public void SetDrawingFile( String drawing_file )

Sets a new value of the DrawingFile property, loads the drawing from the file and displays it in the component.

public String GetDrawingFile()

Returns the current value of the DrawingFile property.

public void SetDrawingURL( String drawing_url )

Sets a new value of the DrawingURL property, loads the drawing from the URL and displays it in the component.

public String GetDrawingURL()

Returns the current value of the DrawingURL property.

public GlgObject GetDrawingObject()

Returns the viewport object of the component's drawing.

public boolean SetDrawingObject( GlgObject viewport )

Sets a new viewport object as a component's drawing and displays the new drawing.

public String GetCharsetName()            (Java)
public Encoding GetCharsetName()      (C#)

Returns the name of a Java charset or a C# encoding used to decode strings in the drawing when it is loaded.

public boolean SetCharsetName( String charset )             (Java)
public boolean SetCharsetName( Encoding charset )       (C#)

Sets the name of a Java charset or a C# encoding used to decode strings in the drawing when it is loaded.

public double GetDResource( String resource_name )
public double GetDTag( String tag_source )

Return the value of the D-type resource or tag of the component's drawing.

public String GetSResource( String resource_name )
public String GetSTag( String tag_source )

Return the value of the S-type resource or tag of the component's drawing.

public double GetXResource( String resource_name )
public double GetYResource( String resource_name )
public double GetZResource( String resource_name )
public double GetXTag( String tag_source )
public double GetYTag( String tag_source )
public double GetZTag( String tag_source )

Return the X, Y or Z values of the G-type resource or tag of the component's drawing.

public boolean HasResourceObject( String resource_name )

Returns true if the component's drawing contains a resource with the specified name.

public boolean HasTagName( String tag_name )
public boolean HasTagSource( String tag_source )

Return true if the component's drawing contains a tag with a specified tag name or tag source.

public boolean SetDResource( String resource_name, double dvalue )
public boolean SetDResource( String resource_name, double dvalue, boolean if_changed )
public boolean SetDTag( String tag_source, double dvalue, boolean if_changed )

Set the value of the D-type resource or tag of the component's drawing. Returns true if the value of the resource or tag was successfully changed.

public boolean SetSResource( String resource_name, String svalue )
public boolean SetSResource( String resource_name, String svalue, boolean if_changed )
public boolean SetSTag( String tag_source, String svalue, boolean if_changed )

Set the value of the S-type resource or tag of the component's drawing. For tags, all tags with the specified tag_source will be set to the supplied value. Returns true if the value of the resource or tag was successfully changed.

public boolean SetGResource( String resource_name,
          double dvalue1, double dvalue2, double dvalue3 )
public boolean SetGResource( String resource_name, double dvalue1, double dvalue2, double dvalue3,          boolean if_changed )
public boolean SetGTag( String tag_source, double dvalue1, double dvalue2, double dvalue3,
boolean if_changed )

Set the values of the G-type resource or tag of the component's drawing (x, y and z values of a point or R, G and B values or a color). Returns true if the value of the resource or tag was successfully changed.

public boolean SetSResourceFromD( String resource_name, String format, double dvalue )

Sets the value of the S-type resource of the component's drawing to a string obtained by converting the supplied double value (dvalue) according to the given format. The format parameter is a C-like format string. Returns true if the value of the resource was successfully changed.

public void Update()                       (Java)
public void UpdateGlg()                 (C#)

Updates the component's drawing to display the latest resource settings.

In C#, the method is named UpdateGlg to avoid a conflict with the Update method of the component's base class.

public void Reset()

Resets the object hierarchy of the component's drawing.

public GlgObject LoadWidget( String filename, int meduim_type )
public GlgObject LoadWidget( String filename, int meduim_type, String charset )            (Java)
public GlgObject LoadWidget( String filename, int meduim_type, Encoding charset )       (C#)

Loads a viewport named "$Widget" from a file or URL, and returns the viewport object. The meduim_type parameter defines the loading type (URL or FILE). Returns null if the drawing can't be loaded or if it the "$Widget" viewport can't be found.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for decoding strings in the loaded drawing. It should match either the locale in which the drawing was created using the GLG Graphics Builder, or the charset used when saving the drawing from a Java or .C# application. If the charset name is not specified or null, the default charset is used.

public GlgObject LoadWidget( GlgObject object )

Finds a viewport named "$Widget" inside the object and returns the viewport. Returns null if the "$Widget" viewport can't be found.

public static GlgObject LoadObject( String filename, int meduim_type )
public static GlgObject LoadObject( String filename, int meduim_type, String charset )         (Java)
public static GlgObject LoadObject( String filename, int meduim_type, Encoding charset )   (C#)

Loads an object from a file or URL, and returns the loaded object. The meduim_type parameter defines the loading type (URL or FILE). Returns null if the object can't be loaded.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for decoding strings in the loaded drawing. It should match either the locale in which the drawing was created using the GLG Graphics Builder, or the charset used when saving the drawing from a Java or C# application. If the charset name is not specified or null, the default charset is used.

public void InitialDraw( GlgObject object )

Sets up the hierarchy and draws the component's drawing.

If the object parameter is not null, the viewport object supplied by the parameter is set up and drawn instead of the top viewport of the component's drawing. If the viewport object does not have a parent, it will appear as a separate top level window.

public void SetupHierarchy( GlgObject object )

Sets up the hierarchy of the component's drawing.

If the object parameter is not null, the viewport object supplied by the parameter is set up instead of the top viewport of the component's drawing. Refer to the GlgObject.SetupHierrachy method on page 312 for more information.

public void ResetHierarchy( GlgObject object )

Resets the component's drawing.

If the object parameter is not null, the viewport object supplied by the parameter is reset instead of the top viewport of the component's drawing.

public void Bell()

Emits an audio beep.

public boolean Print( String filename, double x, double y, double width, double height, boolean portrait, boolean stretch )

Prints the component's drawing and saves it in a PostScript file. Returns true if the drawing was successfully printed.

The NativePrint method of the drawing's viewport may be used for native Java and .NET printing.

public String CreateIndexedName( String template_name, int resource_index )

Creates and returns a resource name string by inserting a number (resource_index) to the template string (template_name). The number is inserted at the position indicated by the "%" character, or at the end of the template name if it does not contain the "%" character.

public boolean IsDemo()

Returns true if the Evaluation Version or the Community Edition of the class library is used.

public boolean SetAutoUpdateOnInput( boolean update )

Enables or disables automatic updates on input events. Returns the previous setting of the parameter.

Automatic updates on input events are enabled by default, but may be disabled to prevent slowing down scrolling and other operations of the real-time charts. If automatic updates are turned off, input objects redraw themselves on user input event, but an explicit Update() call has to be used to redraw any objects constrained to input objects and located outside them.

If automatic updates are turned off, input objects redraw themselves on user input event. However, an explicit Update() call has to be used to redraw any objects constrained to input objects and located outside of them.

When automatic updates are turned off, the application code also has to explicitly invoke Update() for timer events (Format="Timer") to update objects in the drawing with the timer transformation attached.

public void AddListener( int callback_type, Object listener)                             (Java)
public void AddListener( GlgCallbackType callback_type, Object listener)     (C#)

Adds a GLG event listener to the component. The callback_type parameter may have one of the following values: SELECT_CB, INPUT_CB, TRACE_CB, TRACE2_CB, HIERARCHY_CB, H_CB, V_CB or READY_CB. The type of the listener provided by the second parameter must match the type parameter and may have one of the following values: GlgSelectListener, GlgInputListener, GlgTraceListener, GlgHierarchyListener, GlgHListener, GlgVListener or GlgReadyListener, respectively. Only one listener of each type may be added. Use with null as the listener parameter to remove the listener specified by the callback_type parameter.

If no listener was added for some event types, the component is used as a default listener, invoking the component's callback methods: InputCallback, SelectCallback, etc. The component's callback methods can be overridden by the component's subclasses to implement custom event handling.

The Trace and Trace2 listeners use the same GlgTraceListener interface. If the same object (for example, a GLG Bean) is added as both the Trace and Trace2 listener, the same TraceCallback method of the object will be invoked for either event, with the trace2 field of the trace_data parameter set to false for Trace event and to true for Trace2 event. However, if Trace and Trace2 events are activated by the bean's SetTraceEnabled and SetTrace2Enabled methods, the bean's TraceCallback will be invoked for the Trace events and the Trace2Callback will be invoked for the Trace2 events.

The AddListener method of the GlgObject class may be used to add different event listeners to individual child viewports inside the component's drawing.

public void HCallback( GlgObject viewport )

The default HCallback invoked after the component's drawing is loaded, but before its object hierarchy is set up. The component's AddListener method may be used to change the default callback. The viewport parameter is the top level viewport of the component's drawing.

public void VCallback( GlgObject viewport )

The default VCallback invoked after the component's drawing is loaded and set up, but before it is displayed for the first time. The component's AddListener method may be used to change the default callback. The viewport parameter is the top level viewport of the component's drawing.

synchronized public void ReadyCallback( GlgObject viewport )

The default ReadyCallback invoked after the component has finished loading the drawing and reading its data. The component's AddListener method may be used to change the default callback. The viewport parameter is the top level viewport of the component's drawing.

public void InputCallback( GlgObject top_viewport, GlgObject message_object )

The default InputCallback invoked every time the user interacts with input objects in the drawing. More information about the type of the input activity may be extracted from the message_object parameter. Refer to the Input Callback section on page 107 for more details. The component's AddListener method may be used to change the default callback. The top_viewport parameter is the top level viewport of the component's drawing.

public void SelectCallback( GlgObject top_viewport, Object[] name_array, int button )

The default SelectCallback invoked every time the user selects one or more objects in the drawing with the mouse. The name_array parameter is a null-terminated array of names of selected objects. The button parameter is the mouse button used for selection (1, 2 or 3). Refer to the Selection Callback section on page 105 for more details. The component's AddListener method may be used to change the default callback. The top_viewport parameter is the top level viewport of the component's drawing.

public void TraceCallback( GlgObject top_viewport, GlgTraceData trace_info )
public void Trace2Callback( GlgObject top_viewport, GlgTraceData trace_info )

The TraceCallback and Trace2Callback are invoked for every event occurring in any of the drawing's viewports. They may be used as an escape mechanism to handle low-level Java or C# events. The TraceCallback is invoked before dispatching the event for processing, while the Trace2Callback is invoked after the event has been processed. The top_viewport parameter is the top level viewport of the component's drawing.

public void HierarchyCallback( GlgObject top_viewport, GlgHierarchyData hierarchy_info )

The HierarchyCallback is invoked every time SubWindow or SubDrawing objects in the component's drawing load their templates. The hierarchy_info parameter provides information about the SubWindow or SubDrawing object that triggered the callback and about the copy of template to be displayed. Refer the Hierarchy Callback section on page 109 for more details. The top_viewport parameter is the top level viewport of the component's drawing.

public boolean IsReady()

Returns the Ready status of the component. The component is ready when it finished loading the drawing (and finished reading setup data and data URLs for a Java bean).

public String GetFullPath( String filename )

Given a relative filename, returns a full path relative to the path of the loaded drawing. If the filename is not a relative path, it is returned unchanged.

In Java, if a bean is used as an applet or a part of another applet (the SetParentApplet method was used), the returned path is relative to the applet's document base.

Additional Standard API Methods

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

Java-only Methods
public void PrintToJavaConsole( String message )

Prints the message to the Java Console.

public void SetDrawingName( String drawing_resource )

Sets a new value of the DrawingName property, loads the drawing and displays it in the bean. If the bean is used as an applet or part of another applet (bean's SetParentApplet method was used), the DrawingName is interpreted as a URL relative to the applet's document base directory. Otherwise, the DrawingName is interpreted as a file relative to the current directory.

public String GetDrawingName()

Returns the current value of the DrawingName property.

public void SetDataURL( String data_url )

Sets a new value of the DataURL property, reads and executes the new DataURL script. If the UpdatePeriod property is greater than 0, the DataURL will be read periodically with the period defined by the UpdatePeriod. The data script will be read once each time the drawing is reloaded using the SetDrawing methods, and then periodically if the UpdatePeriod property is set.

public String GetDataURL()

Returns the current value of the DataURL property.

public void SetSetupDataURL( String setup_data_url )

Sets a new value of the SetupDataURL property. The SetupDataURL script is read and executed once after a new drawing is loaded into a bean and every time the drawing is reloaded by using the SetDrawing methods.

public String GetSetupDataURL()

Returns the current value of the SetupDataURL property.

public void SetUpdatePeriod( double update_period )

Sets a new value of the UpdatePeriod property and starts or stops periodic reading of DataURL if necessary. The DataURL is read periodically if the UpdatePeriod is greater than 0.

public double GetUpdatePeriod()

Returns the current value of the UpdatePeriod property.

public void SetJavaLog( boolean active )

Activates logging debugging messages to stdout or the Java Console.

public boolean GetJavaLog()

Returns the current value of the JavaLog property.

public void SetResourceLog( boolean active )

Activates logging messages for setting resources from data scripts.

public boolean GetResourceLog()

Returns the current value of the ResourceLog property.

public void SetAPILog( boolean active )

Activates logging API calls, which is convenient for debugging Java Scripts in a web browser.

public boolean GetAPILog()

Returns the current value of the APILog property.

public void SetHResource0( String value )
public void SetHResource1( String value )
public void SetHResource2( String value )
public void SetHResource3( String value )
public void SetHResource4( String value )

Set the value of the H properties. These properties are used to set resources of the bean's drawing before the drawing's object hierarchy is created.

The syntax of these properties is described in the Dynamic Resource String Syntax section of page 249. Refer to the H and V Resources section on page 27 for more details on H and V resources.

public String GetHResource0()
public String GetHResource1()
public String GetHResource2()
public String GetHResource3()
public String GetHResource4()

Return the current value of H properties.

public void SetVResource0( String value )
public void SetVResource1( String value )
public void SetVResource2( String value )
public void SetVResource3( String value )
public void SetVResource4( String value )

Set the value of the V properties. These properties are used to set resources of the bean's drawing after the drawing's object hierarchy is created.

The syntax of these properties is described in the Dynamic Resource String Syntax section of page 249. Refer to the Dynamic Resource String Syntax section on page 249 for more details on H and V resources.

public String GetVResource0()
public String GetVResource1()
public String GetVResource2()
public String GetVResource3()
public String GetVResource4()

Return the current value of V properties.

public void SetTraceHRef( boolean trace )

Sets the value of the TraceHRef property. If the property is set to true, the bean traces the mouse movements and changes the cursor shape when cursor moves over objects in the drawing which have HTML links. If an object contains an S resource named "$href", the value of the resource is interpreted as a URL which defines an HTML link.

public boolean GetTraceHRef()

Returns the current value of the TraceHRef property.

public void SetHRefTarget( String target )

Sets the value of the TraceHRef property which defines the target name for showing html links. If set to null, clicking on the hot spot defined by the "$href" property with the left mouse button opens the link in the same browser window, or in a separate window with the "_blank" target name if other mouse buttons are used. If HRefTarget property is not null, the link is always opened in a separate window with the target name defined by the HRefTarget property.

public String GetHTarget()

Returns the current value of the HRefTarget property.

public void SetIgnoreErrors( boolean ignore )

Sets the value of the IgnoreErrors properties. If set to true, suppresses GLG error messages.

This is useful in the bean box test program, which tries to set the value of a string property on every starting change before the entry is finished, which results in errors for the string properties that define URLs.

public boolean GetIgnoreErrors()

Returns the current value of the IgnoreErrors property.

public Applet SetParentApplet( Applet parent_applet )

Sets the parent applet used to determine the document base when the bean is used as part of another applet.Use null for the parent_applet parameter to unset the parent applet.

public void UpdateCallback()

This callback is invoked after the bean finished reading data on periodic updates. The ReadyCallback is invoked the first time, and the UpdateCallback is invoked on any subsequent data updates.

Intermediate and Extended API Methods of GlgBean and GlgControl Containers

Overview

While the Standard API methods of the Java GlgBean and the C# GlgControl operate on the component's drawing as a whole, the methods of the Intermediate and Extended API take an object ID and can be applied to individual objects inside the drawing.

The first argument of the Intermediate and Extended API methods of the GlgBean and GlgControl specifies the object to apply the method to. If null is passed as the argument value, the method is applied to the top viewport of the component's drawing.

The corresponding methods of the GlgObject class can also be used for even greater flexibility.

Intermediate API Methods
public boolean SaveObject( GlgObject object, String filename )
public boolean SaveObject( GlgObject object, String filename, String charset )           (Java)
public boolean SaveObject( GlgObject object, String filename, Encoding charset )      (C#)

Saves the object into a file with the given filename. Returns true if the object was successfully saved.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for encoding strings in the saved drawing. If charset is not specified or null, the default charset is used.

For applications that load a drawing, modify it and save if back into a file, the drawing should be loaded using the LoadObject method instead of LoadWidget. LoadWidget extracts the $Widget viewport from the loaded drawing, discarding the rest of the drawing, while LoadObject returns an object that represents the whole drawing. Using SaveObject to save a viewport loaded with LoadWidget will result in a loss of information contained in the discarded part of the drawing, such as the type of the coordinate system used to display the viewport, which will make it difficult to load and edit the drawing in the Builder. The following example demonstrates the proper technique:

GlgObject drawing = LoadObject( "drawing.g" );
GlgObject viewport = LoadWidgetFromObject( drawing ); /* Extracts $Widget viewport */
... /* Code that modifies the drawing. */
SaveObject( drawing, "new_drawing.g" );
public boolean ContainsObject( GlgObject container, Object object )

Returns true if the object is contained in container.

public Object GetElement( GlgObject container, int index )

Returns the element of the container indicated by the index.

public int GetIndex( Object object )

Returns the index of the first occurrence of the object in the container or -1 if the object wasn't found in the container.

public GlgObject GetNamedObject( GlgObject container, String name )

Returns the named element of the container defined by the name parameter.

public boolean ReorderElement( GlgObject container, int old_index, int new_index )

Moves the container's element from the old_index to the new_index position. The method returns false if indexes are out of range.

public void SetStart( GlgObject container )

Sets the current position pointer before the first element of the container, preparing the container object for forward traversing with Iterate.

public void SetEnd( GlgObject container )

Sets the current position pointer past the last element of the container, preparing it for backward traversing with IterateBack.

public Object Iterate( GlgObject container )
public Object IterateBack( GlgObject container )

For forward traversing, Iterate advances the iteration pointer and returns the next element of container. For backward traversing, IterateBack decrements the iteration pointer and returns the previous element.

The SetStart method must be used to initialize the container for iterating before Iterate is invoked the first time, and SetEnd must be used to initialize the container for backward iteration with IterateBack. See page 144 for an example. The add, delete and search operations affect the iteration state and should not be performed on the container while it is being iterated.

To perform a safe iteration that is not affected by the add and delete operations, a copy of the container can be created using the CloneObject method with the SHALOW_CLONE clone type. The shallow copy will return a container with a list of objects IDs, and it can be safely iterated while objects are added or deleted from the original container.

Alternatively, GetElement can be used to traverse elements of the container using an element index, which is not affected by the search operations on the container.

public int GetSize( GlgObject container )

Returns the size of container.

public GlgObject GetResourceObject( GlgObject object, String resource_name )

Finds and returns a named resource or an attribute of the object. The resource or attribute must be of the GlgObject type, and is specified with the resource_name parameter.

public Object GetResource( GlgObject object, String resource_name )

Finds and returns a named resource or an attribute of the object. The resource or attribute may be of the Object type or any subclass of the Object.

public boolean ConstrainObject( GlgObject from_object, GlgObject to_object )

Constrains an attribute object (from_object) to the object defined by the to_object attribute parameter. The attribute object being constrained must be obtained by using either a default attribute name at the end of the resource path name, or using the container access methods. If the object has already been drawn, a SuspendObject method should be invoked on either the attribute object or its parent before constraining.

public boolean UnconstrainObject( GlgObject object )

Unconstrains the input attribute object. The input object is obtained by using either a default attribute name at the end of the resource path name, or using container access methods. If the object has already been drawn, a SuspendObject method should be invoked on either the attribute object or its parent before constraining.

public GlgObject SuspendObject( GlgObject object )

Suspends the object for editing. This method must be called before adding a transformation or constraining attributes of the object whose object hierarchy has been setup (the object has been drawn). The method returns a GlgObject, which can be used as the suspend_info parameter to a subsequent call to the ReleaseObject method.

public void ReleaseObject( GlgObject object, GlgObject suspend_info )

Releases the object after suspending for editing. The suspend_info parameter is a returned value of a previous call to SuspendObject.

public int GetNumParents( GlgObject object )

Returns the number of parents of the object. Used to determine a type of the return value of the GetParent method.

public GlgObject GetParent( GlgObject object )

Returns the objects' parent if the object has one parent. If object has more than one parent, returns an array of parents. The type of the return value may be determined by using GetNumParents method.

public double GetDResource( GlgObject object, String resource_name )

Returns the value of an object's D-type resource specified by resource_name.

public String GetSResource( GlgObject object, String resource_name )

Returns the value of an object's S-type resource specified by resource_name.

public double GetXResource( GlgObject object, String resource_name )
public double GetYResource( GlgObject object, String resource_name )
public double GetZResource( GlgObject object, String resource_name )

Return the X, Y or Z values of an object's G-type resource specified by resource_name.

public boolean SetDResource( GlgObject object, String resource_name, double dvalue )

Sets the value of the D-type resource (specified by resource_name) of object to dvalue. Returns true if the value of the resource was successfully changed.

public boolean SetSResource( GlgObject object, String resource_name, String svalue )

Sets the value of the S-type resource (specified by resource_name) of the object. Returns true if the value of the resource was successfully changed.

public boolean SetGResource( GlgObject object, String resource_name,
          double dvalue1, double dvalue2, double dvalue3 )

Sets the new values of the G-type resource (specified by resource_name) of the object. Returns true if the value of the resource was successfully changed.

public void Update( GlgObject viewport )                     (Java)
public void UpdateGlg( GlgObject viewport )             (C#)

Updates the viewport to display the latest resource settings.

public boolean Print( GlgObject object, String filename, double x, double y, double width,
double height, boolean portrait, boolean stretch )

Prints a drawing of the viewport to a PostScript file. If object is a light viewport, the output will be generated for its parent viewport. The x, y, width and height parameters define the page layout of the print output in the GLG coordinate system (use x=-1000, y=-1000, width=2000, height = 2000 to use the whole page). The portrait parameter defines the portrait or landscape orientation. If the stretch parameter is false, the aspect ratio of the drawing is preserved. The method returns true if the drawing was successfully printed.

The NativePrint method of the drawing's viewport may be used for native Java and .NET printing.

public boolean SetResourceFromObject( GlgObject object, String resource_name, GlgObject o_value )

Sets the value of the data or matrix resource (specified by resource_name) to the value of the o_value object. The resource types should match, otherwise false is returned. Returns true if the value of the resource was successfully changed.

public boolean SetSResourceFromD( GlgObject object, String resource_name, String format,
double dvalue )

Sets the value of the input object's S-type resource (specified by resource_name) to a string obtained by converting the supplied double value (dvalue) according to the format. The format parameter is a C-like format string. Returns true if the value of the resource was successfully changed.

Extended API Methods
public GlgObject CopyObject( GlgObject object )

Creates and returns a copy of the object.

public GlgObject CloneObject( GlgObject object, int clone_type )                         (Java)
public GlgObject CloneObject( GlgObject object, GlgCloneType clone_type )      (C#)

Creates and returns an full or constrained copy of an object according the clone_type (WEAK_CLONE, STRONG_CLONE, FULL_CLONE or CONSTRAINED_CLONE).

public boolean AddObjectToTop( GlgObject container, Object object )

Adds the object to the beginning of the container. Returns true if the object was successfully added.

public boolean AddObjectToBottom( GlgObject container, Object object )

Adds the object to the end of container. Returns true if the object was successfully added.

public boolean AddObjectAt( GlgObject container, int index )

Adds the object to the container at the index position. Returns false if index is invalid.

public boolean AddObject( GlgObject container, Object object,
int access_type, int position_modifier )                                                    (Java)
public boolean AddObject( GlgObject container, Object object,
GlgAccessType access_type, GlgPositionModifier position_modifier )  (C#)

Adds an object to the container at the position indicated by the access_type (BOTTOM, TOP or CURRENT). If the access type is CURRENT, the object is added before or after the element indicated by the container's current position, as indicated by the position_modifier parameter (BEFORE or AFTER). Sets the container's current position to point to the added object. Returns true if the object was successfully added.

public boolean DeleteTopObject( GlgObject container )

Deletes the first object of this container. Returns true if the object was successfully deleted.

public boolean DeleteBottomObject( GlgObject container )

Deletes the first object of this container. Returns true if the object was successfully deleted.

public boolean DeleteObjectAt( GlgObject container, int index )

Deletes the object of the container at the index position. Returns false if index is invalid.

public boolean DeleteObject( GlgObject container, Object object )

Deletes an object from container. Returns true if the object was successfully deleted.

public boolean SetXform( GlgObject object, GlgObject xform )

Sets the object's transformation to a constrained copy of the xform parameter. If the object has already been drawn, it has to be suspended with the SuspendObject method before setting its transformation. If the xform parameter is null, the method removes any object transformations. The CopyObject and CloneObject methods may be used in conjunction with the SetXform to add unconstrained copies of the same transformation to several objects.

public boolean SetResourceObject( String resource_name, GlgObject value )

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

GlgObject class

abstract public class GlgObject

The base class for all GLG objects.

Description

GlgObject is the main class of the Java and .NET implementations of the GLG Toolkit. It provides functionality available to all GLG objects. The instances of this class are never created directly. Instead, GLG objects are either loaded from a GLG drawing created using the GLG Graphics Builder, or, for advanced users, created using one of the constructors for the GLG graphical objects (see the the GLG objects classes section later in this chapter) and then accessed using the GlgObject superclass.

Constants

Enums are used in the C# version of the class library. The enums are defined at the top level of the GenLogic namespace. Refer to the online documentation in the XMLDoc format for a list of all enums of the GenLogic namespace.

In the Java version, integer constant fields named the same way as enum elements are used. The constants are defined at the GlgObject class level. Refer to the online documentation in the JavaDoc format for a list of all fields of the GenLogic package.

Standard API Methods

The GlgObject class provides the following public methods.
public void SetupHierarchy()

When invoked on a drawing which has been loaded but not yet displayed, the method sets up the drawing's object hierarchy to prepare the drawing for rendering. The drawing should contain either a top-level viewport object, or a group containing several top-level viewports.

After the initial draw (when the object hierarchy has already been set up), the method can be used to set up any type of object after its resources were changed. Unlike the Update method, SetupHierarchy sets up the object without repainting it.

public void ResetHierarchy()

Resets the object hierarchy of a top-level viewport or drawing displayed using the Generic API. This method should not be used for viewports displayed in the GlgBean and GlgControl containers.

public void InitialDraw()

Draws a viewport object for the first time. If the viewport object does not have a parent, it will appear as a separate top level window. Sets up the hierarchy if it hasn't been set up yet.

public boolean SetZoom( String resource_name, char 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 method may be invoked on either a viewport or a light viewport.

The value parameter defines the zoom factor or pan distance. The type parameter specifies the type of the zoom or pan action. Refer to the GlgSetZoom section on page 96 for a complete list of all zoom and pan types.

In the Drawing Zoom Mode, if the method attempts to set a very large zoom factor which would result in the overflow of the integer coordinate values used by the native windowing system, the zoom operation is not performed and the method returns false.

public boolean SetZoomMode( String resource_name,
        GlgObject zoom_object, String zoom_object_name )

Sets or resets a viewport's Zoom Mode by supplying a GIS or Chart object to be zoomed. In the default Drawing Zoom Mode, 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 SetZoom 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.

public static GlgObject LoadObject( String filename, int meduim_type )                                 (Java)
public static GlgObject LoadObject( String filename, int meduim_type, String charset )        (Java)
public static GlgObject LoadObject( String filename, GlgMediumType meduim_type )           (C#)
public static GlgObject LoadObject( String filename, GlgMediumType meduim_type,
                    Encoding charset )                                                           (C#)

Loads an object from a file or URL (given by filename) and returns it. The meduim_type parameter defines the loading type (URL or FILE). Returns null if the object can't be loaded.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for decoding strings in the loaded drawing. It should match either the locale in which the drawing was created using the GLG Graphics Builder, or the charset used when saving the drawing from a Java or .NET application. If the charset name is not specified or null, the default charset is used.

public static GlgObject LoadObject( Object stream, int meduim_type )                                 (Java)
public static GlgObject LoadObject( Object stream, int meduim_type, String charset)         (Java)
public static GlgObject LoadObject( Object stream, GlgMediumType meduim_type )           (C#)
public static GlgObject LoadObject( Object stream, GlgMediumType meduim_type,
                    Encoding charset)                                                         (C#)

Loads an object from a stream (given by filename) and returns it. The meduim_type parameter defines the loading type (STREAM). Returns null if the object can't be loaded.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for decoding strings in the loaded drawing. It should match either the locale in which the drawing was created using the GLG Graphics Builder, or the charset used when saving the drawing from a Java or .NET application. If the charset name is not specified or null, the default charset is used.

public static GlgObject LoadWidget( String filename, int meduim_type )                                 (Java)
public static GlgObject LoadWidget( String filename, int meduim_type, String charset )        (Java)
public static GlgObject LoadWidget( String filename, GlgMediumType meduim_type )           (C#)
public static GlgObject LoadWidget( String filename, GlgMediumType meduim_type,
                     Encoding charset )                                                          (C#)

Loads a viewport named "$Widget" from a file or URL, and returns it. The meduim_type parameter defines the loading type (URL or FILE). Returns null if the drawing can't be loaded or if it the "$Widget" viewport can't be found.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for decoding strings in the loaded drawing. It should match either the locale in which the drawing was created using the GLG Graphics Builder, or the charset used when saving the drawing from a Java or .NET application. If the charset name is not specified or null, the default charset is used.

public static GlgObject LoadWidget( GlgObject object )

Finds a viewport named "$Widget" inside the object and returns it. Returns null if the "$Widget" viewport can't be found.

public boolean Update()                 (Java)
public boolean UpdateGlg()           (C#)

Updates the viewport to display the latest resource settings. If this object is a light viewport, update of its parent viewport will be performed.

In C#, the method is named UpdateGlg for consistency with the UpdateGlg method of the GLG C# Control, which avoids a conflict with the Update method of the control's base class.

public boolean UpdateImmediately()

Updates the viewport immediately without waiting for the next paint event. Does not repaint children viewports. If this object is a light viewport, update of its parent viewport will be performed.

public boolean Reset()

Resets the viewport.

public Object SendMessage( String resource_name, char * message, Object param1,
Object param2, Object param3, Object 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. The Integer object must be used to pass integer values to the message. Integer values returned by the query messages are returned as Integer objects.

Refer to Input Objects on page 237 of the GLG User's Guide and Builder Reference Manual for a list of messages supported by each type of the available input handlers.

public static GlgAlarmHandler SetAlarmHandler( GlgAlarmHandler alarm_handler )

Specifies a global alarm handler that will process all alarms generated by an application's drawings.

int ExportStrings( GlgObject object, String filename, char separator1, char separator2,
String charset )                                                                                     (Java)
int ExportStrings( GlgObject object, String filename, char separator1, char separator2,
Encoding charset )                                                                                (C#)

Writes all text strings defined in the drawing specified by the object parameter into a string translation file using requested separator characters and an encoding charset. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the string translation file format. The method returns the number of exported strings or -1 in case of an error.

int ImportStrings( GlgObject object, String filename, String charset )                  (Java)
int ImportStrings( GlgObject object, String filename, Encoding charset )            (C#)

Replaces text strings in the drawing defined by the object parameter with the strings loaded from a string translation file using the specified charset for string decoding. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the string translation file format.The method returns the number of imported strings or -1 in case of an error.

int ExportTags( GlgObject object, String filename, char separator1, char separator2,
String charset )                                                                                     (Java)
int ExportTags( GlgObject object, String filename, char separator1, char separator2,
Encoding charset )                                                                                (C#)

Writes tag names and tag sources of all tags defined in the drawing specified by the object parameter into a file using requested separator characters and an encoding charset. The method uses the same file format as the ExportStrings method. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the file format. The method returns the number of exported tags or -1 in case of an error.

int ImportTags( GlgObject object, String filename, String charset )                 (Java)
int ImportTags( GlgObject object, String filename, Encoding charset )            (C#)

Replaces tag names and tag sources of tags in the drawing defined by the object parameter with information loaded from a tag translation file using the specified charset for string decoding. The method uses the same file format as the ImportStrings method. Refer to Localization Support on page 230 of the GLG User's Guide and Builder Reference Manual for information about the tag translation file format.The method returns the number of imported tags or -1 in case of an error.

public boolean Print( String file, double x, double y, double width, double height, boolean portrait, boolean stretch )

Prints the viewport object's drawing and saves it as a PostScript file. If this object is a light viewport, the output will be generated for its parent viewport.

The x, y, width and height parameters define the page layout of the print output in the GLG coordinate system (use x=-1000, y=-1000, width=2000, height = 2000 to use the whole page). The portrait parameter defines the portrait or landscape orientation. If the stretch parameter is false, the aspect ratio of the drawing is preserved. The method returns true if the drawing was successfully printed.

The NativePrint method may be used for native Java and .NET printing.

public boolean NativePrint( Graphics graphics )

Prints the viewport object's drawing into a provided graphics object. If this object is a light viewport, the output will be generated for its parent viewport. The origin of graphics is assumed to be (0,0) and clipping is assumed to be set the viewport's window width and height. Returns true if the drawing was successfully printed.

public BufferedImage CreateImage( String resource_name )             (Java)
public Bitmap CreateImage( String resource_name )                         (C#)

Generates an image of the visible area of the viewport's drawing and returns it in a form of the Image object for Java or a C# Bitmap for .NET. The resource_name parameter specifies the resource name of a child viewport whose image to generate, or null to generate the image of the viewport itself. For a light viewport, the output will be generated for its parent viewport. The method returns null if image creation fails.

public Image CreateImageCustom( String resource_name, Rectangle image_area, int gap )      (Java)
public Bitmap CreateImageCustom( String resource_name, Rectangle image_area, int gap )    (C#)

Generates an image of the area of the drawing defined by the image_area (in the screen pixels), and returns it in a form of the Image object for Java or a C# Bitmap for .NET. If image_area is null, the image of the whole drawing is generated, which may be bigger than the visible area of the viewport if the drawing is zoomed in. The gap parameter specifies the padding space between the extent of the drawing and the edge of the image when the image_area is null. The viewport's zoom factor defines the scaling factor for objects in the drawing when the image is saved.

The resource_name parameter specifies the resource name of a child viewport whose image to generate, or null to generate the image of the viewport itself. For a light viewport, the output will be generated for its parent viewport. The method returns null if image creation fails.

public static String CreateIndexedName( String template_name, int resource_index )

Creates and returns a resource name string by inserting the given number (resource_index) to the template_name string. The index is inserted at the position indicated by the "%" character, or at the end of the template name if it does not contain the "%" character.

public static String ConcatResNames( String resource_name1, String resource_name2 )

Creates a "/"- separated resource name by appending the second resource name to the first one, and inserting the "/" separator is necessary.

public String GetObjectName( GlgObject )

Returns an object's name.

public int GetObjectType( GlgObject )                            (Java)
public GlgObjectType GetObjectType( GlgObject )        (C#)

Returns an object's type.

public int GetDataType( GlgObject )                            (Java)
public GlgDataType GetDataType( GlgObject )           (C#)

Returns a data type (D, S or G) of a data or attribute object.

public Double GetDResource( String resource_name )              (Java)
public Double GetDTag( String tag_source )                              (Java)
public GlgDouble GetDResource( String resource_name )         (C#)
public GlgDouble GetDTag( String tag_source )                         (C#)

Return the value of a scalar resource or tag.

public GlgDouble GetDResourceObj( String resource_name )              (Java)
public GlgDouble GetDTagObj( String tag_source )                              (Java)

More efficient versions of the corresponding methods, return a cached GlgDouble object. For efficiency, if the returned object is not null, it can be returned to the cache using its ReleaseToCache method.

public GlgPoint GetGResource( String resource_name )
public GlgPoint GetGTag( String tag_source )

Return the value of a G-type resource or tag.

public String GetSResource( String resource_name )
public String GetSTag( String tag_source )

Return the value of a string resource or tag.

public boolean SetDResource( String resource_name, double d_value )
public boolean SetDResource( String resource_name, double d_value, boolean if_changed )
public boolean SetDTag( String tag_source, double d_value, boolean if_changed )
public boolean SetDResource( String resource_name, Double d_value )                                        (Java)
public boolean SetDResource( String resource_name, Double d_value, boolean if_changed )      (Java)
public boolean SetDTag( String tag_source, Double d_value, boolean if_changed )                      (Java)
public boolean SetDResource( String resource_name, GlgDouble d_value )
public boolean SetDResource( String resource_name, GlgDouble d_value, boolean if_changed )
public boolean SetDTag( String tag_source, GlgDouble d_value, boolean if_changed )

Set the value of scalar resource or tag. For tags, all tags with the specified tag_source will be set to the supplied value. Returns true if the value of the resource or tag was successfully changed.

public boolean SetGResource( String resource_name, double g_value1, double g_value2,
double g_value3 )
public boolean SetGResource( String resource_name, GlgPoint g_value )
public boolean SetGResource( String resource_name, double g_value1, double g_value2,
double g_value3, boolean if_changed )
public boolean SetGResource( String resource_name, GlgPoint g_value, boolean if_changed )
public boolean SetGTag( String tag_source, double g_value1, double g_value2, double g_value3, boolean if_changed )
public boolean SetGTag( String tag_source, GlgPoint g_value, boolean if_changed )

Set the value of a G-type resource or tag. For tags, all tags with the specified tag_source will be set to the supplied values. Returns true if the value of the resource or tag was successfully changed.

public boolean SetSResource( String resource_name, String s_value )
public boolean SetSResource( String resource_name, String s_value, boolean if_changed )
public boolean SetSTag( String tag_source, String s_value, boolean if_changed )

Set the value of a string resource or tag. Returns true if the value of the resource or tag was successfully changed.

public boolean SetSResourceFromD( String resource_name, String format, double d_value )
public boolean SetSResourceFromD( String resource_name, String format, double d_value,
boolean if_changed )
public boolean SetSTagFromD( String tag_source, String format, double d_value,
            boolean if_changed )
public boolean SetSResourceFromD( String resource_name, String format, Double d_value )      (Java)
public boolean SetSResourceFromD( String resource_name, String format, Double d_value,
                     boolean if_changed )                                                           (Java)
public boolean SetSTagFromD( String tag_source, String format, Double d_value,
            boolean if_changed )                                                                    (Java)
public boolean SetSResourceFromD( String resource_name, String format, GlgDouble d_value )    (C#)
public boolean SetSResourceFromD( String resource_name, String format, GlgDouble d_value,
                    boolean if_changed )                                                               (C#)
public boolean SetSTagFromD( String tag_source, String format, GlgDouble d_value,
boolean if_changed )                                                                                   (C#)

Set the value of a string resource or tag to a string obtained by converting the supplied double value according to the specified format. The format parameter is a C-like format string. Returns true if the value of the resource or tag was successfully changed.

public boolean SetResourceFromObject( String resource_name, GlgObject o_value )

Sets the new value of the resource object defined by the resource name to the value of the o_value object. The resource types should match. Returns true if the value of the resource was successfully changed.

public GlgObject CreateTagList( boolean unique_tags )

Returns a list of all object's tags.

public boolean HasResourceObject( String resource_name )

Returns true if a named resource exists.

public boolean HasTagName( String tag_name )
public boolean HasTagSource( String tag_source )

Return true if a tag with a specified tag name or tag source exists.

public static void Init()

Initializes the GLG Toolkit. If an integrated GlgBean or GlgControl component is not used, this method must be invoked before using any other GLG methods. If the component is used, it will invoke this method automatically in its constructor.

public static void Terminate()

May be used to free internal structures allocated by the Toolkit if the Toolkit will not be used any more by the program.

public static boolean Sync()

Synchronizes the Toolkit's graphical state by flushing any buffered graphics events.

public void AddListener( int type, Object callback )                                (Java)
public void AddListener( GlgCallbackType type, Object callback )        (C#)

Adds an input, selection or event listener to a viewport object depending on the type parameter (INPUT_CB, SELECT_CB, TRACE_CB, TRACE2_CB or HIERARCHY_CB). The INPUT_CB listener may also be attached to a light viewport. The listener should implement the GlgInputListener, GlgSelectListener, GlgTraceListener or GlgHierarchyListener interface, depending on the specified type. Only one listener of a particular type may be added to one viewport. The listeners must be added before setting the drawing hierarchy or displaying the drawing for the first time. The method can be used to add one event listener to the top-level viewport, and different listeners to its children viewports.

public static void Lock()                         (Java JSP Servlet only)
public static void Unlock()                     (Java JSP Servlet only)

Locks and unlocks the object for synchronization of object access in the JSP Servlets. These methods may be used to lock an object to avoid an access to object's components while it is being manipulated. The locking may also be used to prevent a thread being killed in the middle of the object manipulation, which would result in an unpredictable object state.

The calls to the Lock and Unlock methods must be balanced. If a thread was locked with a several calls to the Lock method, an equal number of calls to the Unlock method must be used to unlock the thread.

In Swing applications, asynchronous access is not allowed and these methods should not be used.

public static void UnlockThread()                     (Java JSP Servlet only)

Unconditionally unlocks the current tread regardless of the number of the Lock calls made to lock the thread. It may be used at the end of the JSP Servlet's doGet method to unlock the thread after an exception that interrupts the normal flow of control, or to ensure that the thread is unlocked even if there was an unbalanced number of the Lock nd Unlock calls due to a programming error.

public static GlgErrorHandler SetErrorHandler( GlgErrorHandler new_handler )

Replaces a default GLG error handler with a custom one. If the new_handler parameter is null, the method restores the default error handler.

The default error handler emits an audio beep and displays the error message on a Java console or in a message dialog for C#/.NET. The error message includes a stack trace showing where the error occurred.

In the C#/.NET version of the class library, the default error handler also logs error messages into the glg_error.log file. The location of the log file is determined by the GLG_LOG_DIR and GLG_DIR environment variables as described in the Error Processing and Debugging section on page 49. An application can use the GlgObject.Error method to display error messages or log messages into the glg_error.log log file using the current error handler.

public static void Error( String message, int error_type, Exception exception)                       (Java)
public static void Error( String message, GlgErrorType error_type, Exception exception )    (C#)

Invokes a currently installed error handler to display an error message or to log a message to the glg_error.log file. The message parameter specifies the error message. exception is an optional parameter that, if not null, supplies exception information and the exact location of the error shown in the stack trace. The error_type parameter specifies the type of action to perform and may be one of the following:

INTERNAL_ERROR
Reserved for the Toolkit's internal use.
In Java, prints the error message and the stack trace on the Java console and emits an audio beep.
In C#, displays an error dialog with the stack trace, emits an audio beep and logs the error message and the stack trace into the glg_error.log file.
USER_ERROR
In Java, prints the error message and the stack trace on the Java console and emits an audio beep.
In C#, displays an error dialog with the stack trace, emits an audio beep and logs the message and the stack trace into the glg_error.log file.
USER_ERROR_NO_STACK
In Java, prints the error message on the Java console and emits an audio beep.
In C#, displays an error dialog, emits an audio beep and logs the message into the glg_error.log file.
WARNING
In Java, prints the warning message on the Java console and emits an audio beep.
In C#, displays a warning dialog, emits an audio beep and logs the message into the glg_error.log file.
INFO             (Java only)
Prints the message on the Java console.
LOGGING     (C# only)
Logs the message into the glg_error.log file.

The location of the glg_error.log file is determined by the GLG_LOG_DIR and GLG_DIR environment variables as described in the Error Processing and Debugging section on page 49.

public static void CatchGlobalErrors( boolean catch_all, boolean exit )              (C# only)

May be invoked on application start-up to log exceptions and display stack trace for application errors via the GLG error handler.

If the catch_all parameter is set to true, catches all exceptions, otherwise catches only thread exceptions. If the exit parameter is set to true, the application exits after displaying an error message.

public static String GetStackTraceAsString()

Returns the current stack trace as a string which may be used for logging.

public static String GetStackTraceAsString( Exception e )

Returns the stack trace of the specified exception as a string.

public static boolean GetModifierState( int modifier )                            (Java)
public static boolean GetModifierState( GlgModifierType modifier )      (C#)

Returns the state of the modifier specified by the modifier parameter: SHIFT_MOD, CONTROL_MOD or DOUBLE_CLICK_MOD.

public static void Bell()

Emits an audio beep.

public static boolean Sleep( long milisec )

Sleeps for the specified number of milliseconds. In Java, returns false if the sleep was interrupted. In C#, always returns true.

public static double Rand( double low, double high )

Returns a random number in the defined range.

void ChangeObject( GlgObject object, String resource_name )

Sends a change method to the object without actually changing the object's attributes, may be used to redraw the object.

If the resource_name parameter is null, the change message will be sent to the object specified by the object parameter. Otherwise, the message will be sent to its child object specified by the resource_name parameter.

public static void SetBrowserObject( GlgObject browser, GlgObject object )

Sets an object to be browsed by the GLG resource, tag or alarm browser widgets.

public static void SetBrowserSelection( GlgObject object, String resource_name, String selection, String filter )

Sets a new value of a browser's selection and filter text boxes for resource, tag, alarm and data browsers after the browser object has been set up. Setting a new selection will display a new list of matching entries. If the resource_name parameter is null, selection of the object itself is set. Otherwise, selection of its child viewport specified by the resource_name parameter will be set.

public static boolean SetEditMode( GlgObject viewport, String resource_name, boolean edit_mode )

Sets the viewport's edit mode which disables input objects in the viewport while the drawing is edited; returns true on success. The viewport could be either a viewport or a light viewport. If the resource_name parameter is null, the edit mode of the viewport itself is set. Otherwise, the edit mode of its child viewport specified by the resource_name parameter will be set. The edit mode is global and may be set only for one viewport used as a drawing area. Setting the edit mode of a new viewport resets editing mode of the previous viewport. The viewport's edit mode is inherited by its all child viewports.

public void SetFocus( String resource_name )

If resource_name is null, sets the keyboard focus to the parent viewport of this object, or to this object if it is a viewport. If resource_name is not null, it specifies the resource name of a child object to use for setting focus.

public void SetImageSize( int width, int height )                     (Graphics Server only, JSP and ASP.NET)

Sets the size of the image to be generated for the drawing represented by a viewport object.

public static GlgTooltipFormatter SetTooltipFormatter( GlgTooltipFormatter formatter )

Supplies a custom tooltip formatter, returns the previously set formatter, if any.

public char[] GetWidgetPassword( String resource_name )         (Java only)

Returns the password string entered into the password text widget. A separate method for querying entered password is required to comply with the Java security model. If the resource_name parameter is null, the password of this text input object is returned . Otherwise, the resource_name parameter points to a child text input object of this object.

public Object GetNativeComponent( String resource_name, int type )     (Java)
public Object GetNativeComponent( String resource_name, GlgComponentQueryType type )     (C#)

Returns a native component used to render the viewport according to the query type specified by the type parameter. It returns the component itself for the WIDGET_QUERY query type, or the ID of the top-level form (in case if the form was created by the GLG class library) for the SHELL_QUERY query type. In Java, the CHILD_WIDGET_QUERY query type can be used to query a child component of the text edit and list widgets that use a scroll pane; for these widgets the WIDGET_QUERY query type returns the scroll pane.

Additional Standard API Methods

The GetElement and GetSize methods described in the Intermediate API Methods section are also available in the Standard API. The SetResourceObject method of the Extended API may be used for setting global configuration resources with the Standard and Intermediate APIs.

Intermediate API Methods

public boolean SaveObject( String filename )
public boolean SaveObject( String filename, String charset )                (Java)
public boolean SaveObject( String filename, Encoding charset )           (C#)

Saves the object into a file. Returns true if the object was successfully saved.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for encoding strings in the saved drawing. If the charset name is not specified or null, the default charset is used.

public boolean SaveObject( Object stream, int medium_type )                                                        (Java)
public boolean SaveObject( Object stream, int medium_type, String charset )                               (Java)
public boolean SaveObject( Object stream, GlgMediumType medium_type )                                  (C#)
public boolean SaveObject( Object stream, GlgMediumType medium_type, Encoding charset )    (C#)

Serializes the object by saving it into a stream specified by the stream parameter. The medium_type parameter specifies medium type (STREAM). Returns true if the object was successfully saved. The LoadObject method may be used to restore the object from a stream.

The charset parameter specifies the name of a Java charset or a C# encoding to be used for encoding strings in the saved drawing. If the charset name is not specified or null, the default charset is used.

public boolean ContainsObject( Object object )

Returns true if the object is contained in this container.

public Object GetElement( int index )

Returns the element of this container indicated by index or null if index is invalid.

public int GetIndex( Object object )

Returns the index of the first occurrence of the object in the container or -1 if the object wasn't found in the container.

public int GetStringIndex( String string )

Returns the index of the first occurrence of the string in the container or -1 if the string wasn't found in the container.

public GlgObject GetNamedObject( String name )

Returns the named element of this container defined by the name parameter.

public boolean ReorderElement( int old_index, int new_index )

Moves an element of this container from the position specified by old_index to the position defined by new_index. Returns false if indexes are out of range.

public void Inverse( GlgObject container )

Reverses the order of objects in the container.

public void SetStart()

Sets the current position pointer before the first element of the container, preparing the container object for forward traversing with Iterate.

public void SetEnd()

Sets the current position pointer past the last element of the container, preparing it for backward traversing with IterateBack.

public boolean IsAt( int position )                             (Java)
public boolean IsAt( GlgPositionType position )      (C#)

Checks the position of the iteration pointer (the current element of the container). The following lists the return values for different values of the position argument:

public Object Iterate()
public Object IterateBack()

For forward traversing, Iterate advances the iteration pointer and returns the next element of a container. For backward traversing, IterateBack decrements the iteration pointer and returns the previous element.

The SetStart method must be used to initialize the container for iterating before Iterate is invoked the first time, and SetEnd must be used to initialize the container for backward iteration with IterateBack. See page 144 for an example. Refer to the Iterate method of the GlgObject class on page 307 for more information on safe traversing.

public int GetSize()

Returns the size of this container.

public void Flush( int size )

Sets a new container size. If the new size is less than the current container size, extra elements are removed. If the new size is greater than the current size, the method adds elements by making a copy of the last element in the container.

The container may be a group, a viewport, a polygon (as a container of points), a spline or a connector. The method can only be invoked if the container is not set up. If the container is set up (drawn), the method must be surrounded by the SuspendObject and ReleaseObject calls.

public void Inverse()

Reverses the order of the objects in this container.

public boolean SetResource( String resource_name, int type, Object value,
        boolean if_changed_only, boolean is_attribute )                    (Java)
public boolean SetResource( String resource_name, GlgDataType type, Object value,
        boolean if_changed_only, boolean is_attribute )                     (C#)

ADVANCED: Sets the value of a generic resource of a type defined by the type parameter (D, S, G or O). For D resources, the type of the value parameter must be Double type in Java and GlgDouble in C#. For the rest of the resource types, the type of the value parameter must be String for S resources, GlgPoint for G resources, and Object for O (object) resources. If the if_changed_only parameter is true, the value change event will be generated only if value of the resource was different. The is_attribute parameter may be set to true to speed up setting default attributes of an object. The method returns null if the resource can't be set.

public GlgObject GetResourceObject( String resource_name )

Finds and returns a named resource or an attribute of this object. The resource or attribute must be of the GlgObject type.

public Object GetResource( String resource_name )

Finds and returns a named resource or an attribute of this object. The resource or attribute must be of the Object type.

public Object GetResource( String resource_name, int type, boolean mandatory,
      boolean is_attribute, boolean dont_cache )                                       (Java)
public Object GetResource( String resource_name, GlgDataType type, boolean mandatory,
      boolean is_attribute, boolean dont_cache )                                       (C#)

ADVANCED: Gets the value of a generic resource of a type defined by the type parameter. (D, S, G or O). For resources of the D type, the type of the returned value is Double in Java and GlgDouble in C#. For the rest of the resource types, the type of the returned value is String for S resources, GlgPoint for G resources and Object for all other resources that are objects. The method returns null if the resource can't be found.

For resources that are infrequently accessed, passing dont_cache=true suppresses adding the resource to the resource cache to conserve memory.

public GlgObject GetTagObject( String search_string, boolean by_name, boolean unique_tags, boolean 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 a 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.

public GlgObject GetAlarmObject( String search_string, boolean single_alarm )

Finds a single alarm with a given alarm label, or creates a list of alarms matching the specified wildcard. The search_string specifies either the exact alarm label to search for, or a search pattern which may contain the ? and * wildcards. In a single tag mode, the method returns the first alarm that has an alarm label matching the search criteria. In the multiple alarm mode, a list containing all alarms with matching alarm labels is returned.

public boolean ConstrainObject( GlgObject to_attribute )

Constrains this attribute object to the object defined by the to_attribute parameter. The attribute object being costrained must be obtained by using either a default attribute name at the end of the resource path name, or using the container access methods. If the object has already been drawn, a SuspendObject method should be invoked on either the attribute object or its parent before constraining.

public boolean UnconstrainObject()

Unconstrain this attribute object. The attribute object being unconstrained must be obtained by using either a default attribute name at the end of the resource path name, or using container access methods. If the object has already been drawn, the SuspendObject method should be invoked on either the attribute object or its parent before constraining.

public boolean UnconstrainObject( int clone_type )                              (Java)
public boolean UnconstrainObject( GlgCloneType clone_type )            (C#)

ADVANCED: Unconstrain this attribute object using clone_type parameter (WEAK_CLONE, STRONG_CLONE, FULL_CLONE or CONSTRAINED_CLONE) to unconstrain the transformation attached to the object, if any. The attribute object being unconstrained must be obtained by using either a default attribute name at the end of the resource path name, or using container access methods. If the object has already been drawn, a SuspendObject method should be invoked on either the attribute object or its parent before constraining.

public GlgObject SuspendObject()

Suspends this object for editing. It must be called before adding a transformation or constraining attributes of the object whose object hierarchy has been setup (the object has been drawn). The method returns a GlgObject, which can be used as the suspend_info argument to the ReleaseObject method.

public void ReleaseObject( GlgObject suspend_info )

Releases this object after suspending for editing. The suspend_info parameter is a returned value of a previous call to SuspendObject.

public int GetNumParents()

ADVANCED: Returns the number of parents of this object. Used to determine the type of the return value of the GetParent method.

public GlgObject GetParent()

ADVANCED: Returns the objects' parent if this object has one parent. If object has more than one parent, returns an array of parents. The type of the return value may be determined with the GetNumParents method.

public GlgCube GetBox()

ADVANCED: Returns a 3D bounding box of the object that can be used for collision detection. The coordinates of the bounding box are valid only after the object has been drawn.

public GlgObject GetDrawingMatrix()

ADVANCED: Returns a matrix object of the transformation used to draw the object on the screen.

public GlgObject CreateInversedMatrix()

ADVANCED: Creates and returns an matrix inversed relative to this one.

public void GetMatrixData( GlgMatrixData matrix_data );

ADVANCED: Queries matrix coefficients.

public void SetMatrixData( GlgMatrixData matrix_data );

ADVANCED: Sets matrix coefficients.

public void TransformPoint( GlgPoint in_point, GlgPoint out_point )

ADVANCED: Transforms the in_point with this matrix and places the result into the out_point.

public boolean MoveObject( int coord_type, GlgPoint start_point, GlgPoint end_point );       (Java)
public boolean MoveObject( GlgCoordType coord_type,
        GlgPoint start_point, GlgPoint end_point );                                (C#)

Moves an object by the specified vector in the specified coordinate system (SCREEN_COORD or WORLD_COORD). If start_point is null, (0,0,0) is used as the start point of the move vector.

public boolean MoveObjectBy( int coord_type, double x, double y, double z );                            (Java)
public boolean MoveObjectBy( GlgCoordType coord_type, double x, double y, double z );         (C#)

Moves an object by the specified X, Y and Z distances in the specified coordinate system (SCREEN_COORD or WORLD_COORD).

public boolean ScaleObject( int coord_type, GlgPoint * center, double x, double y, double z );      (Java)
public boolean ScaleObject( GlgCoordType coord_type,
        GlgPoint * center, double x, double y, double z );                              (C#)

Scales an object relative to the specified center in the specified coordinate system (SCREEN_COORD or WORLD_COORD) by the specified X, Y and Z scale factors.

public boolean RotateObject( int coord_type, GlgPoint * center, double x, double y, double z );    (Java)
public boolean RotateObject( GlgCoordType coord_type,
         GlgPoint * center, double x, double y, double z );                             (C#)

Rotates an object around the specified center in the specified coordinate system (SCREEN_COORD or WORLD_COORD) by the specified X, Y and Z angles.

public boolean PositionObject( int coord_type, int anchoring, double x, double y, double z );       (Java)
public boolean PositionObject( GlgCoordType coord_type, GlgAnchoringType anchoring,
            double x, double y, double z );                                                         (C#)

Positions an object at the specified location in the specified coordinate system (SCREEN_COORD or WORLD_COORD) using the specified anchoring. The value of anchoring is formed as a bitwise "or" of the horizontal anchoring constant (HLEFT, HCENTER or HRIGHT) with the vertical anchoring constants (VTOP, VCENTER or VBOTTOM). The object's bounding box is used to anchor an object's edges.

public boolean FitObject( int coord_type, GlgCube box, boolean keep_ratio );                            (Java)
public boolean FitObject( GlgCoordType coord_type, GlgCube box, boolean keep_ratio );         (C#)

Fits the object to the specified area in the specified coordinate system (SCREEN_COORD or WORLD_COORD).

public boolean LayoutObjects( GlgObject sel_elem, int type, double distance,
 boolean use_box, boolean process_subobjects )                           (Java)
public boolean LayoutObjects( GlgObject sel_elem, GlgLayoutType type, double distance,
            boolean use_box, boolean process_subobjects )                            (C#)

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

public void TransformObject( GlgObject xform, int coord_type, GlgObject parent )                      (Java)
public void TransformObject( GlgObject xform, GlgCoordType coord_type, GlgObject parent )   (C#)

ADVANCED: Transforms all control points of an object with the transformation, calculating new control points values.The coord_type specifies the coordinate system to interpret the transformation in. If SCREEN_COORD is used, the parameters of the transformation are considered to be in screen pixels. For example, this may be used to move the object by the number of screen pixels as defined by the mouse move. If OBJECT_COORD is used, the transformation parameters are interpreted as GLG world coordinates. The parent parameter specifies the object's parent in the OBJECT_COORD mode, null may be used in the SCREEN_COORD mode. The object's hierarchy must be set to use this method.

public boolean ScreenToWorld( boolean inside_vp, GlgPoint in_point, GlgPoint out_point );

Converts a point coordinates from the screen coordinate system to the world coordinate system of the object.

If this object is a viewport or a light viewport, inside_vp specifies which world coordinate system to use. If inside_vp=true, the method will use the world coordinate system used to draw objects inside this viewport. If inside_vp=false, the method will use the world coordinate system used to draw this viewport inside its parent viewport. The value of this parameter is ignored for objects other than a viewport or light viewport.

When converting the cursor position to world coordinates, add GlgObject.COORD_MAPPING_ADJ to the cursor's x and y screen coordinates for precise mapping.

public boolean WorldToScreen( boolean inside_vp, GlgPoint in_point, GlgPoint out_point );

Converts a point coordinates from the object's world coordinate system to the screen coordinate system.

If this object is a viewport or a light viewport, inside_vp specifies which world coordinate system to use. If inside_vp=true, the method will use the world coordinate system used to draw objects inside this viewport. If inside_vp=false, the method will use the world coordinate system used to draw this viewport inside its parent viewport. The value of this parameter is ignored for objects other than a viewport or light viewport.

public static void TranslatePointOrigin( GlgObject from_viewport, GlgObject to_viewport,
                       GlgPoint point )

Converts screen coordinates of a point in the viewport specified by the from_viewport parameter to the screen coordinates of the viewport specified by to_viewport. The point parameter supplies the input coordinates and is used to return the converted coordinates.

public static boolean RootToScreenCoord( GlgObject viewport, GlgPoint point )

Converts screen coordinates relative to the root window to the screen coordinates of the specified viewport. The point parameter supplies the input coordinates and is used to return the converted coordinates.

public GlgObject GetParentViewport( boolean heavy_weight )

Returns the parent viewport of a drawable GLG object. The heavy_weight parameter controls the type of a parent viewport to be returned. If set to False, the method returns the closest parent viewport regardless of its type: either a heavyweight or light viewport. If set to True, it returns the closest heavyweight parent viewport. For example, if the object is inside a light viewport, it will return the heavyweight viewport which is a parent of the light viewport.

public static GlgObject CreateSelectionNames( GlgObject top_vp, GlgCube rectangle,
                                       GlgObject selected_vp )

ADVANCED: Given the top viewport of the drawing, and a screen coordinates rectangle in a selected viewport, returns an array of names of all objects within the rectangle. This method may be used inside the TraceListener to implement custom selection logic based on the mouse events. Either a viewport or a light viewport can be used for the top_vp and selected_vp parameters.

public static GlgObject CreateSelectionNames( MouseEvent event, int delta, GlgObject top_vp,                                      GlgObject selected_vp )

ADVANCED: Given the top viewport of the drawing, a mouse event, a viewport in which the mouse event occurred and the selection distance (delta), returns an array of names of all objects selected by the mouse event. This method may be used inside the TraceListener to implement custom selection logic based on the mouse events. Either a viewport or a light viewport can be used for the top_vp and selected_vp parameters.

public static GlgObject CreateSelectionMessage( GlgObject top_vp, GlgCube rectangle,
                                         GlgObject selected_vp, int selection_type,
                                          int button )                                                       (Java)
public static GlgObject CreateSelectionMessage( GlgObject top_vp, GlgCube rectangle,
                                         GlgObject selected_vp,
                                         GlgSelectionEventType selection_type,
                                          int button )                                                        (C#)

ADVANCED: Given the top viewport of the drawing and a screen coordinates rectangle in a selected viewport, the method searches all objects inside the rectangle for the action with the specified selection trigger type attached to an object. Either a viewport or a light viewport can be used for the top_vp and selected_vp parameters.

The method returns a selection message for the first matching action it finds, and may be used in the Trace event handler to retrieve an action which would be triggered by a specified mouse event in the rectangular area. The selection message is a message equivalent to the message received in the input callback. The selection_type parameter may specify one of the following predefined selection types: MOVE_SELECTION, CLICK_SELECTION or TOOLTIP_SELECTION.

public static GlgObject CreateSelection( GlgObject top_vp, GlgCube rectangle,
                           GlgObject selected_vp )

ADVANCED: This is the same as the corresponding CreateSelectionNames, but returns an array of selected objects on the bottom of the hierarchy instead of an array of names. Either a viewport or a light viewport can be used for the top_vp and selected_vp parameters.

public static GlgObject CreateSelection( MouseEvent event, int delta, GlgObject top_vp,
                           GlgObject selected_vp )

ADVANCED: Same as the corresponding CreateSelectionNames, but returns an array of selected objects on the bottom of the hierarchy instead of an array of names. Either a viewport or a light viewport can be used for the top_vp and selected_vp parameters.

public GlgObject CreateResourceList( boolean list_named_res, boolean list_def_attr,
                        boolean list_aliases )

ADVANCED: Creates an array of all resource names of this object on one level of hierarchy. If list_def_attr is true, the default attributes are included. The list_aliases parameter is reserved for the future use and must be false.

public GlgObject CreatePointArray( int type )                                           (Java)
public GlgObject CreatePointArray( GlgControlPointType type )             (C#)
ADVANCED: Creates and returns an array containing all of an object's control points. The type parameter specifies the type of points to be returned: control points (CONTROL_POINTS), or control and attachment points (CONTROL_AND_ATTACHMENT_POINTS).
public boolean IsDrawable()

Returns true if the object is drawable. Drawable objects can be placed directly in a drawing area, have control points and a bounding box, have the visibility attribute and can contain custom properties, actions and aliases. For a chart object, the chart itself is drawable, but its plots are not.

public boolean FindMatchingObjects( GlgFindMatchingObjectsData data )

Finds either one or all parents or children of the specified object that match the supplied criteria. The data parameter contains parameters of the search and is also used to return found objects, see the GlgFindMatchingObjectsData class section on page 350 for more information. The method returns true if at least one matching objects was found.

public GlgObject ConvertViewportType( GlgObject object )

ADVANCED: Converts a viewport to a light viewport, or a light viewport to a viewport, returning a newly created object on success or null on error. The object parameter supplies the object to be converted. If a converted object is added to the drawing, the original object must be deleted, since both objects reuse the graphical objects inside the viewport and cannot be both displayed at the same time.

public static void TraceObject( GlgObject object, boolean state, boolean is_widget,
            GlgObject top_parent, GlgObjectActionInterface action )

Searches all parents of the traced object and highlights or unhighlights them based on the specified conditions. The parent search is performed until any of the specified conditions (is_widget, top_parent or a custom criteria evaluated by the supplied action interface) is satisfied. The objects will be highlighted if the state parameter is true and unhighlighted otherwise.

If is_widget=true, the parent objects that have resource named IsWidget will be highlighted or unhighlighted depending on the state parameter. If top_parent is non-null, the parent objects that are direct children of top_parent will be highlighted or unhighlighted. If the action parameter is non-null, its Action method will be invoked for each parent of a traced object to check if a custom condition is satisfied. If the method returns true, the parent will be highlighted or unhighlighted.

If no conditions are specified, all immediate drawable parents of the traced object will be highlighted or unhighlighted.

The method returns true if any parents were highlighted.

The dependent parent objects are highlighted with an outline. The attributes of the outline are defined by the GlgHighlightPolygon global configuration resource.

public static boolean EnableAttachmentPoints( boolean state )

Specifies if attachment points should be used in addition to the control points to determine object extents when the objects are aligned. Returns the previous setting.

public boolean DeleteTags( GlgObject object, int tag_type_mask )                    (Java)
public boolean DeleteTags( GlgObject object, GlgTagType tag_type_mask )      (C#)

Deletes all object's data tags or all object's public properties. Returns true on success. type_type_mask specifies a bitwise mask that defines the type of tags to be deleted: data tags (DATA_TAG), public properties (EXPORT_TAG) or both.

Extended API

public GlgObject CopyObject()

Creates and returns a copy of the object.

public GlgObject CloneObject( int clone_type )                                 (Java)
public GlgObject CloneObject( GlgCloneType clone_type )              (C#)

Creates and returns a full or constrained copy of an object according to the clone_type (WEAK_CLONE, STRONG_CLONE, FULL_CLONE or CONSTRAINED_CLONE).

public GlgObject AddAttachmentPoint( GlgObject reference, double dx, double dy, double dz )

Adds an attachment point to a reference object and returns the added point. The world coordinate offsets for initial position of the attachment point relatively to the reference object's single control point are provided by the dx, dy and dz parameters. When the reference object is resized, the offsets will be automatically adjusted to maintain the point's position relatively to the object.

public boolean AddObjectToTop( Object object )

Adds the object to the beginning of this container. Returns true if the object was successfully added.

public boolean AddObjectToBottom( Object object )

Adds the object to the end of this container. Returns true if the object was successfully added.

public boolean AddObjectAt( Object object, int index )

Adds the object to the container at the position specified by index. Returns true if the object was successfully added.

public boolean AddObject( Object object, int access_type, int position_modifier )             (Java)
public boolean AddObject( Object object, GlgAccessType access_type,
     GlgPositionModifier position_modifier )                                 (C#)

Adds the object to this container at the position indicated by the access type (BOTTOM, TOP or CURRENT). If access_type is CURRENT, adds before or after the element indicated by the container's current position, as indicated by the position_modifier parameter (BEFORE or AFTER). Sets the container's current position to point to the added object. Returns true if the object was successfully added.

public boolean DeleteTopObject()

Deletes the first object of this container. Returns true if the object was successfully deleted.

public boolean DeleteBottomObject()

Deletes the last object of this container. Returns true if the object was successfully deleted.

public boolean DeleteObjectAt( int index )

Deletes an object at the specified position in this container.

public boolean DeleteObject( Object object )

Deletes the given object from this container. Returns true if the object was successfully deleted.

public boolean DeleteObject( int access_type, int pos_modifier )                                                    (Java)
public boolean DeleteObject( GlgAccessType access_type, GlgPositionModifier pos_modifier )   (C#)

Deletes an object from this container and adjusts the current position according to the pos_modifier (BEFORE or AFTER). The object is deleted from the position indicated by the access_type (BOTTOM, TOP or CURRENT). Returns true if the object was successfully deleted.

public static boolean SetAttachmentMoveMode( boolean state )
Changes the attachment point move mode and returns the previous mode state. By default, the attachment point move mode is off, and moving the attachment point will move the reference object it is attached to. If the mode is on, moving the attachment point will change its position relatively to the reference object.
public boolean SetElement( int index, GlgObject new_object )

Replaces the element of this container indicated by index. Returns false if index is invalid.

public boolean SetXform( GlgObject xform )

Sets this object's transformation to a constrained copy of the xform parameter. If the object has already been drawn, it has to be suspended with the SuspendObject method before setting its transformation. If the xform parameter is null, this method removes any object transformations. The CopyObject and CloneObject methods may be used in conjunction with the SetXform to add unconstrained copies of the same transformation to several objects.

public boolean SetResourceObject( String resource_name, GlgObject value )

Sets the new value of the object's attribute specified by the resource_name. It is used for attaching Custom Property objects and aliases. This method may also be used with the Standard and Intermediate APIs for setting global configuration resources.

Chart-Related Methods of GlgObject

The following methods provide an API for handling specific aspects of the GLG Real-Time Chart object.

Standard API
public GlgObject GetSelectedPlot( )

Returns the plot object corresponding to the last legend item selected with the mouse, if any, or null if no plots were previously selected.

public GlgObject GetNamedPlot( String resource_name. String plot_name )

Finds a chart's plot by name and returns the plot object. If the resource_name parameter is null, a named plot of this chart object 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.

public GlgObject AddPlot( String 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 object. 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.

public boolean DeletePlot( String 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.

public GlgObject AddTimeLine( String resource_name, GlgObject time_line, double time_stamp )

Adds a vertical time line to a chart object. If the resource_name parameter is null, the time line is added to this chart object. Otherwise, the time line is added to a child chart of this object pointed to by the resource_name parameter. The time line parameter specifies the level line object to be used as a time line; null can be used to create a new time line. The time_stamp parameter specifies the time stamp to position the time line at and is assigned to the time line's Level attribute. The method returns the added time line object on success, or null on failure. The NumTimeLines attribute of the chart should be set to -1 in order to use this method.

public boolean DeleteTimeLine( String resource_name, GlgObject time_line, double time_stamp )

Deletes a time line from a chart object. If the resource_name parameter is null, the time line is deleted from this chart. Otherwise, the time line is deleted from a child chart of this object pointed to by the resource_name parameter. The time_line parameter specifies the time line object to delete. If time_line is set to null, the time line with the time stamp specified by the time_stamp attribute will be deleted. If time_line is not null, the time_stamp parameter is ignored. The method returns true if the time line was successfully deleted. The NumTimeLines attribute of the chart should be set to -1 in order to use this method.

public GlgObject AddAnnotation( String resource_name, GlgObject annotation, double position_x,                double position_y, boolean add_box )

Adds an annotation to a chart object. If the resource_name parameter is null, the annotation is added to this chart object. Otherwise, the annotation is added to a child chart of this object pointed to by the resource_name parameter. The annotation parameter specifies the annotation object to be added; null can be used to create a new annotation. The position_x and position_y parameters specify the annotation's position. If add_box is set to true, a text box will be added to the annotation's text object. The method returns the added annotation object on success, or null on failure. The NumAnnotations attribute of the chart should be set to -1 in order to use this method.

public boolean DeleteAnnotation( String resource_name, GlgObject time_line, double position_x,                double position_y )

Deletes an annotation from a chart object. If the resource_name parameter is null, the annotation is deleted from this chart. Otherwise, the annotation is deleted from a child chart of this object pointed to by the resource_name parameter. The annotation parameter specifies the annotation object to delete. If annotation is set to null, the annotation at the position specified by the position_x and position_y attributes will be deleted. If annotation is not null, position parameters are ignored. The method returns true if the annotation was successfully deleted. The NumAnnotations attribute of the chart should be set to -1 in order to use this method.

public boolean ClearDataBuffer( String resource_name )

Clears accumulated data samples of a real-time chart or one of its plots. If resource_name is not null, it supplies a resource name of a child chart or plot object. For a chart, ClearDataBuffer discards data samples in all plots of the chart. For a plot, it discards only the data samples of that plot. The method returns true on success.

public boolean GetChartDataExtent( String resource_name, GlgMinMax min_max, boolean 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 in min_max. 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.

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 method to succeed. The method returns true on success.

public boolean SetLinkedAxis( String resource_name, GlgObject axis_object,
          String axis_resource_name )

Associates a chart's plot or a level line with an Y axis for automatic rescaling, returns true on success. If resource_name is null, associates this object, otherwise associates a child plot or a child level line of this object pointed to by the resource_name parameter. If axis_resource_name is null, associates with axis_object, otherwise associates with the child axis of axis_object pointed to by the axis_resource_name parameter.

public boolean SetLabelFormatter( String resource_name, GlgLabelFormatter formatter )

Attaches a custom label formatter to a stand-alone axis object or an axis of a chart if resource_name is null, otherwise attaches the formatter to a child axis or a child chart of this object pointed to by the resource_name parameter. The method returns true on success.

public boolean SetChartFilter( String resource_name, GlgChartFilter filter, Object client_data )

Attaches a custom data filter to a chart's plot if resource_name is null, otherwise attaches the formatter to a child plot of this object pointed to by the resource_name parameter. The method returns true on success. Refer to the CustomChartFilter.java file (CustomChartFilter.cs file for C#) for an extensive self-documented coding example of implementing MIN_MAX, AVERAGE and DISCARD custom filter types.

Intermediate API
public void AddDataSampleNode( GlgDataSampleNode datasample_node, boolean quick_mode )

Adds a data sample node to this chart plot, is used to enhance performance when prefilling the chart with a large number of samples. For periodic updates, new data may be pushed into the plot's entry points using SetDResource. The CreateDataSampleNode method should be used to obtain a new data sample to be added. The quick mode may be activated to increase prefill speed by bypassing the chart scrolling and auto-scaling when adding data samples. When the last data sample is added, the chart can be scrolled by setting the EndValue of the chart's Time axis to the data sample's time stamp. To auto-scale the chart when prefilling is finished, set the chart's AutoScale attribute to a desired value.

The RealTime Chart Demo provides an coding example of prefilling a chart.

public static GlgDataSampleNode CreateDataSampleNode( GlgObject plot, boolean extended )

Is used to create a data sample node to be added to a chart via the AddDataSampleNode method. An optional plot parameter specifies the plot the data sample node will be added to. If plot is not null, a new data sample node will be taken from the plot's cache, if possible. If the extended parameter is set to true, a data sample node containing an extended data sample (GlgDataSampleExt) is returned, otherwise the node will contain the GlgDataSample object.

The node's GlgGetNodeDataSample method described in the GlgDataSampleNode Interface section on page 350 can be used to get access to the node's data sample. The fields of the data sample must be filled before adding it to the plot.

public static void FreeDataSampleNode( GlgObject plot, GlgDataSampleNode node )

Returns a data sample node to the plot cache or the global node cache for reuse. If plot is not null, the data sample node will be returned to the plot's cache. Otherwise, the node will be returned to the global cache. A node may be freed only if it was not used by adding it to a chart. When a chart scrolls, it will automatically free data sample nodes that are pushed out from the chart.

public GlgObject GetLegendSelection( long object, double x, double y )

Returns the plot object corresponding to the legend item at the specified position, if any. If no legend item is found at the specified position, null is returned. The object parameter specifies the legend object, and the x and y parameters specify position in screen coordinates of the viewport that contains the legend.

public GlgObject CreateChartSelection( GlgObject plot, double x, double y, boolean screen_coord,
                          boolean include_invalid, boolean 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 is null, the method queries samples in all plots of the chart and selects the sample closest to the specified position. If plot is not null, 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 GlgObject.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. Only the data samples located within the dx and dy distances from the specified position are considered for the selection.

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

public String CreateTooltipString( double x, double y, double dx, double dy, String 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 the chart or the axis 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 selection 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 method returns a tooltip string that displays the axis value corresponding to the specified position.

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

public Double PositionToValue( String resource_name, double x, double y,
                  boolean outside_x, boolean outside_y )                        (Java)
public GlgDouble PositionToValueObj( String resource_name, double x, double y,
                         boolean outside_x, boolean outside_y )                  (Java)
public GlgDouble PositionToValue( String resource_name, double x, double y,
                    boolean outside_x, boolean outside_y )                       (C#)

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.

If this object is a plot, the method converts the specified position to a Y value in the Low/High range of the plot and returns the value.

If this object is an axis, the method converts the specified position to the axis value and returns the value.

If this object is a chart, the method 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 GlgObject.COORD_MAPPING_ADJ to the cursor's x and y coordinates for precise mapping.

For efficiency, if the returned GlgDouble object is not null, it can be returned to the internal cache using its ReleaseToCache method.

GIS-Related Methods of GlgObject

Standard API
public boolean GISConvert( String resource_name, int coord_type, boolean coord_to_lat_lon,
GlgPoint in_point, GlgPoint out_point )                                            (Java)
public boolean GISConvert( String resource_name, GlgCoordType coord_type,
       boolean coord_to_lat_lon, GlgPoint in_point, GlgPoint out_point )   (C#)

Converts coordinates between the GIS coordinate system of the GIS Object and GLG coordinate system of the drawing. If the resource_name parameter is null, the coordinate system of this object is used for conversion. If the resource_name parameter is not null, it specifies the resource name of the GIS Object that is contained inside this object and whose coordinate system will be used for conversion. The coord_type parameter specifies the type of the GLG coordinate system type to convert to or from: SCREEN_COORD for screen coordinates or OBJECT_COORD for world coordinates. If the coord_to_lat_lon parameter is true, coordinates are converted from GLG to GIS coordinate system. If it is false, the coordinates are converted from GIS to GLG coordinate system. When converting from GLG to GIS coordinates, the Z coordinate is set to a negative GLG_GIS_OUTSIDE_VALUE value for points on the invisible part of the globe.

public static boolean GlmConvert( int projection, boolean stretch, int coord_type, boolean         coord_to_lat_lon, GlgPoint center, GlgPoint extent, double angle,
       double min_x, double max_x, double min_y, double max_y,
      GlgPoint in_point, GlgPoint out_point )                                  (Java)
public static boolean GlmConvert( GlgProjectionType projection, boolean stretch,
                GlgCoordType coord_type, boolean coord_to_lat_lon,
                GlgPoint center, GlgPoint extent, double angle,
                double min_x, double max_x, double min_y, double max_y,
               GlgPoint in_point, GlgPoint out_point )                                  (C#)

Low-level method similar to GISConvert, but without the use of the GIS Object. The projection, stretch, center, extent and angle parameters provide information about the GIS Object's attributes, and min_x, max_x, min_y and max_y parameters provide information about the extent of the GIS Object in the drawing using a coordinate system (screen or object) matching the coord_type parameter. Refer to the GlmConvert method description in the GLG Map Server Reference Manual for details.

public GlgDouble GISGetElevation( String resource_name, String layer_name,
        double lon, double lat )

Returns an elevation of a lat/lon point on a map. If the resource_name parameter is null, the elevation query will be executed on this GIS object. If the resource_name parameter is not null, it specifies the resource name of the GIS Object contained inside this object. The layer_name parameter specifies the name of the layer with elevation data to query.

The method returns null if the point is outside of the map in the ORTHOGRAPHIC projection or if there is no elevation data for the specified location. Otherwise, the method returns the elevation value in the units (such as meters or feet) defined by the elevation data file.

For efficiency, if the returned GlgDouble object is not null, it can be returned to the internal cache using its ReleaseToCache method.

public GlgObject GISCreateSelection( String resource_name, String layers, double x, double y,
                 int select_labels )                                                               (Java)
public GlgObject GISCreateSelection( String resource_name, String layers, double x, double y,
                        GlmLabelSelectionMode select_labels )                             (C#)

Returns a message object containing information about GIS features located at the specified position on the map. If the resource_name parameter is null, the query will be executed on this GIS object. If the resource_name parameter is not null, it specifies the resource name of the GIS Object inside this object. The layers parameter specifies a list of layers to query. The x and y parameters specify location on the map in the screen coordinates of the GIS object's parent viewport. The select_label parameter specifies the label selection policy. It can have the following values:

Refer to page 204 for more information on the label selection.

The method returns a message object containing information about the selected GIS features. Refer to the GlmGetSelection section on page 129 of the GLG Map Server Reference Manual for information on the structure of the returned message object as well as a programming example that shows how to handle it.

Intermediate API
public boolean RequestGISZoom( String res_name, char type, double value,
                 GlgGISRequestObserver request_observer )

Requests a GIS zoom or pan operation to be performed on a viewport with the GIS Zoom mode using an asynchronous GIS request in a way compatible with the SetZoom method. The application will continue to operate with the current map view until the new map is ready. When the new map image is either ready or aborted, the request observer's RequestUpdate method will be invoked with the status information. The observer can install a successfully prepared request via the InstallGISRequest method, or do nothing to cancel the request. See the GlgGISRequestObserver section on page 292 for more information.

If the res_name parameter is not null, it specifies the resource path of a child viewport to be zoomed, otherwise this viewport will be used.

The value parameter defines the zoom factor or pan distance. The type parameter specifies the type of the zoom or pan action. Refer to the GlgSetZoom section on page 96 for a complete list of all zoom and pan types.

public boolean RequestGISMap( String res_name, double extent_x, double extent_y,
              double center_x, double center_y, double angle,
              int projection, String layers, int flags,
               GlgGISRequestObserver request_observer )                            (Java)
public boolean RequestGISMap( String res_name, double extent_x, double extent_y,
              double center_x, double center_y, double angle,
              GlgProjectionType projection, String layers,
              GlgGISRequestFlags flags,
               GlgGISRequestObserver request_observer )                              (C#)

Requests a new GIS map to be prepared for the GIS object using an asynchronous GIS request. The application will continue to operate with the current map view until the new map is ready. When the new map image is either ready or aborted, the request observer's RequestUpdate method will be invoked with the status information. The observer can install a successfully prepared request via the InstallGISRequest method, or do nothing to cancel the request. See the GlgGISRequestObserver section on page 292 for more information.

If the res_name parameter is not null, it specifies the resource path of a child GIS object, otherwise this GIS object will be used.

The extent_x, extent_y, center_x, center_y, angle, projection and layers parameters define the new attribute values for the GIS object.

The flags parameter controls which GIS object's parameters will be updated and may have any OR combination of the following flags (defined in the GlgObject class for Java or GlgGISRequestStatus enum for C#): GIS_REQUEST_EXTENT, GIS_REQUEST_CENTER, GIS_REQUEST_ANGLE, GIS_REQUEST_PROJECTION or GIS_REQUEST_LAYERS.

public boolean InstallGISRequest( String res_name )

Installs the GIS object's GIS request. This method may be invoked only from inside of a request observer's RequestUpdate method invoked with the GIS_REQUEST_READY status.

If the res_name parameter is not null, it specifies the resource path of a child GIS object, otherwise this GIS object will be used.

public void AbortGISRequest( String res_name )

Aborts the GIS request in progress, if any.

If the res_name parameter is not null, it specifies the resource path of a child GIS object, otherwise this GIS object will be used.

public GlgGISRequestObserver GetGISRequestInfo( String res_name )

Obtains information about a GIS object's current GIS request being processed; returns a request observer of a GIS request in progress, or null if the GIS object has no pending GIS requests.

If the res_name parameter is not null, it specifies the resource path of a child GIS object, otherwise this GIS object will be used.

public GlgGISRequestObserver SetScrollbarObserver( String res_name,
                                                  GlgGISRequestObserver request_observer )

Controls the way integrated scrollbars work for the GIS object.

If a non-null request observer is specified, integrated scrollbars will use an asynchronous request to scroll the map. The observer's RequestUpdate method will be invoked with status updates. If null is specified, the new map will be loaded without the use of an asynchronous request.

If the res_name parameter is not null, it specifies the resource path of a child GIS object, otherwise this GIS object will be used.

GLG Utility Classes

These classes are used for incidental tasks associated with the GlgBean, GlgControl and GlgObject classes.

GlgDouble class

public class GlgDouble

A mutable double object.

Variables
public double dvalue;

The object's value.

Constructors
public GlgDouble()

Creates a new point with a default value of 0.

public GlgDouble( double value )
public GlgPoint( GlgDouble value )

Create a new GlgDouble with a defined value.

Methods
public void CopyFrom( GlgDouble value )

Copies a value of the object defined by the value parameter to this object.

public void intValue()        (Java)
public void IntValue()        (C#)

Returns the value of the object as an integer.

public void doubleValue()        (Java)
public void DoubleValue()        (C#)

Returns the value of the object as a double.

public static GlgDouble GetFromCache( double value )

Returns an object from an internal cache and initializes it to the specified value. Creates an object if the cache is empty.

public static void ReleaseToCache( GlgDouble obj )

Releases an object to the internal cache for reuse. Only objects obtained with GetFromCache should be released to the cache. Releasing objects created with new would result in increasing resource consumption due to the growth of the cache size. The object should not be accessed after it has been released to the cache.

GlgPoint class

public class GlgPoint
Variables
public double x, y, z;

X, Y and Z values of the point.

Constructors
public GlgPoint()

Creates a new point with a default (0;0;0) value.

public GlgPoint( double x, double y, double z )
public GlgPoint( GlgPoint point )

Create a new point with a defined value.

Methods
public void CopyFrom( GlgPoint point )

Copies x, y and z values from the point defined by the point parameter to this point.

public static GlgPoint GetFromCache()

Returns an object from an internal cache. Creates an object if the cache is empty.

public static void ReleaseToCache( GlgPoint obj )

Releases an object to the internal cache for reuse. Only objects obtained with GetFromCache should be released to the cache. Releasing objects created with new would result in increasing resource consumption due to the growth of the cache size. The object should not be accessed after it is released to the cache.

GlgCube class

public class GlgCube

Defines a rectangular parallelepiped in 3D space (usually an object's bounding box) by its two diagonal points. The faces of the parallelepiped are parallel to the coordinate planes.

Variables
public GlgPoint p1;

The first corner of the cube. Always has the lowest X, Y and Z.

public GlgPoint p2;

The second corner of the cube. Always has the biggest X, Y and Z.

Constructors
public GlgCube()

Creates a new bounding box with default (0;0;0) values for both corner points.

public GlgCube( GlgCube cube )

Creates a copy of a cube.

public static GlgCube GetFromCache()

Returns an object from an internal cache. Creates an object if the cache is empty.

public static void ReleaseToCache( GlgCube obj )

Releases an object to the internal cache for reuse. Only objects obtained with GetFromCache should be released to the cache. Releasing objects created with new would result in increasing resource consumption due to the growth of the cache size. The object should not be accessed after it is released to the cache.

GlgMatrixData class

public class GlgMatrixData
Variables
public byte type;

Matrix type.

public double matrix[4][4];

Matrix coefficients.

Constructors
public GlgMatrixData()

Creates an empty matrix data object.

public GlgMatrixData( GlgMatrixData matrix_data )

Create a new matrix data fills it with data from another matrix data object.

Methods
public void CopyFrom( GlgMatrixData )

Copies matrix data from another matrix data object.

GlgHierarchyData class

public class GlgHierarchyData

Is used to pass information to GlgHierarchyListener.

Variables
public int condition;                                                   (Java)
public GlgHierarchyCallbackType condition;           (C#)

Indicates when the listener is invoked: before hierarchy setup (BEFORE_SETUP_CB) or after the setup but before the template is drawn (AFTER_SETUP_CB).

public GlgObject object;               (Java)
public GlgObject glg_object;        (C#)

The SubWindow or SubDrawing object that triggered the callback.

public GlgObject subobject;

The instance of the subwindow or subdrawing template that is about to be displayed.

GlgTraceData class

public class GlgTraceData

Is used to pass information for GlgTraceListener.

Variables
public GlgObject viewport;

The viewport object that received the event.

public Object widget;

The window component or control of the viewport (Swing or AWT component in Java, Windows.Forms.Control in C#).

public AWTEvent event;             (Java)
public GlgEvent event;              (C#)

The event that caused GlgTraceListener to be invoked.

public boolean trace2;

Indicates the type of TraceListener, is set to true for Trace2 events and false for Trace.

GlgEvent class (C# only)

public class GlgEvent

Is used to pass event information to GlgTraceListener.

Variables
public GlgEventType type;

The event type:

PAINT
UPDATE
COMPONENT_SHOWN
COMPONENT_HIDDEN
COMPONENT_MOVED
COMPONENT_RESIZED
MOUSE_ENTERED
MOUSE_EXITED
MOUSE_MOVED
MOUSE_WHEEL
MOUSE_PRESSED
MOUSE_RELEASED
KEY_DOWN
KEY_PRESSED
KEY_UP
FOCUS_LOST
FOCUS_GAINED
LV_ENTER_NOTIFY    - GLG event: mouse entered light viewport
LV_LEAVE_NOTIFY    - GLG event: mouse exited light viewport
LV_RESIZE                   - GLG event: light viewport resized
public EventArgs event_args;

Event arguments of the C# event.

GlgEventArgs class (C# only)

public class GlgEventArgs : EventArgs

Generic GLG event arguments object; provides data for GlgH, GlgV and GlgReady events.

Variables
public GlgObject viewport;

The top-level viewport of the GlgControl's drawing.

GlgInputEventArgs class (C# only)

public class GlgInputEventArgs : GlgEventArgs

Provides data for the GlgInput event.

Variables
public GlgObject viewport;

The top-level viewport of the GlgControl's drawing.

public GlgObject message_obj;

The message object containing information about the GLG input event.

GlgSelectEventArgs class (C# only)

public class GlgSelectEventArgs : GlgEventArgs

Provides data for the GlgSelect event.

Variables
public GlgObject viewport;

The top-level viewport of the GlgControl's drawing.

public Object[] name_array;

Null-terminated array containing names of all selected objects, including a complete path name.

public int button;

Specifies which mouse button was pressed to select objects.

GlgHierarchyEventArgs class (C# only)

public class GlgHierarchyEventArgs : GlgEventArgs

Provides data for the GlgHierarchy event.

Variables
public GlgObject viewport;

The top-level viewport of the GlgControl's drawing.

public GlgHierarchyData hierarchy_info;

Contains detailed information about the GlgHierarchy event.

GlgTraceEventArgs class (C# only)

public class GlgTraceEventArgs : GlgEventArgs

Provides data for the GlgTrace event.

Variables
public GlgObject viewport;

The top-level viewport of the GlgControl's drawing.

public GlgTraceData trace_info;

Contains detailed event information.

GlgMinMax class

public class GlgMinMax

Used to return the extent of data in a chart.

Variables
public double min;

The minimum of the data extent.

public double max;

The maximum of the data extent.

Constructors
public GlgMinMax()

Creates a new data extent object and sets all its variables to zero.

public GlgMinMax( double min, double max)

Creates a data extent object with the specified values.

GlgDataSample class

public class GlgDataSample

Used by a chart object to store data for one data sample.

Variables
public double value;

Y value.

public double time;

Time stamp (or X value in an XY Scatter charts).

public boolean valid;

Data sample's Valid flag.

Constructors
public GlgDataSample()

Default constructor.

Methods
public static GlgDataSample GetFromCache()

Returns an object from an internal cache. Creates an object if the cache is empty.

public static void ReleaseToCache( GlgDataSample obj )

Releases an object to the internal cache for reuse. Only objects obtained with GetFromCache should be released to the cache. Releasing objects created with new would result in increasing resource consumption due to the growth of the cache size. The object should not be accessed after it is released to the cache.

GlgDataSampleExt class

public class GlgDataSampleExt extends GlgDataSample

Used by a chart object to store extended data for one data sample, including YLow value for the Hi/Lo Bar Chart, as well as rendering attributes for individual bars and markers that need to be rendered with different colors and marker types.

Variables
public double y_low;

YLow value of a Hi/Lo bar chart.

public int fill_color;

Fill color of a bar or marker in a hex notation (0xRRGGBB)

public int edge_color;

Edge color of a bar or marker in a hex notation (0xRRGGBB)

public int drawn_size;

Bar width or marker size.

public int drawn_type;

Bar fill type or marker type.

public int line_width;

Bar line width.

Constructors
public GlgDataSampleExt()

Default constructor.

Methods
public static GlgDataSampleExt GetFromCache()

Returns an object from an internal cache. Creates an object if the cache is empty.

public static void ReleaseToCache( GlgDataSampleExt obj )

Releases an object to the internal cache for reuse. Only objects obtained with GetFromCache should be released to the cache. Releasing objects created with new would result in increasing resource consumption due to the growth of the cache size. The object should not be accessed after it is released to the cache.

GlgDataSampleNode Interface

public interface GlgDataSampleNode

An object containing a chart data sample and its associated list node.

Methods
GlgDataSample GetNodeDataSample()

Returns the node's data sample, GlgDataSample or GlgDataSampleExt.

GlgFindMatchingObjectsData class

public class GlgFindMatchingObject

A utility class used by the FindMatchingObjects method.

Variables
public int match_type;                                  (Java)
public GlgObjectMatchType match_type;    (C#)

Specifies a bitwise mask of the following object matching criteria:

Multiple criteria can be ORed together. All of the criteria in the mask must be true in order for an object to match.

public boolean find_parents;

Specifies search direction. If it is set to true, ancestors (parents, grandparents and so on) of the object are searched. Otherwise, the object's descendents (children, grandchildren and so on) are searched.

public boolean find_first_match;

Controls whether the search is stopped after finding the first matching object. If is set to true, the search is stopped after the first match and the first matching object is returned, otherwise all matching objects will be returned.

public boolean search_inside;

Controls the search inside the matching objects. If it is set to false, the object's children or parents are not searched if the object itself matches.

public boolean search_drawable_only;

Controls the search inside drawable objects when searching for descendents (find_parents=false). If it is set to true, only drawable objects are searched. For example, when this flag is set, a polygon object's attributes such as FillColor and EdgeColor, will not be searched, which can increase the search speed. Refer to the description of the IsDrawable method on page 330 for more information.

public int object_type;            (Java)
public GlgObjectType type;    (C#)

Object type for the object type search.

public String object_name;

Object name for the object name search.

public String resource_name;

Resource name for the resource search.

public GlgObject object_id;

Object ID for the object id search.

public GlgObjectActionInterface custom_match;

Specifies an instance of the GlgObjectActionInterface interface that provides custom matching logic. The Action method of the interface instance should return true for objects that match the custom matching criterion. See the GlgObjectActionInterface section on page 291 for more information.

public GlgObject found_object;

Contains the result of the search, or null if no matching objects were found. If the result is a single object, the found_multiple variable will be set false. If the result is a group of several matching objects, found_multiple will be set to true.

public boolean found_multiple;

Will be set to true or false to indicate the type of the returned result. If true, the result of the search stored in the found_object variable contains a group of several matching objects. Otherwise (false), the stored result is a single matching object.

Constructors
public GlgFindMatchingObjectsData()

Creates a new instance of the class.

GlgGISRequestData class

public class GlgGISRequestData

Used to pass information to the AdjustRequest method of GlgGISRequestObserver. The object's variables may be changed in place to adjust the request's parameters.

Variables
public GlgPoint extent;

Requested GIS extent.

public GlgPoint center;

Requested GIS center.

public double angle;

Requested GIS angle.

public String layers;

Requested GIS layers.

public int projection;                                 (Java)
public GlgProjectionType projection;    (C#)

Requested GIS projection.

public int flags;                                          (Java)
public GlgGISRequestFlags flags;          (C#)

Indicates which GIS object's parameters were requested to be changed, may have any OR combination of the following flags (defined in the GlgObject class for Java and in the GlgGISRequestStatus enum for C# ):

GIS_REQUEST_EXTENT
GIS_REQUEST_CENTER
GIS_REQUEST_ANGLE
GIS_REQUEST_PROJECTION
GIS_REQUEST_LAYERS

GlgLatLonPoint class

public class GlgLatLonPoint

Used in the UTM coordinate conversion methods.

Variables
public double lat;
public double lon;
Constructors
public GlgLatLonPoint()

Default constructor.

public GlgLatLonPoint( double lat, double lon )

Constructs new GlgLatLonPoint with the specified coordinates.

Methods
public void FromString( String string )

Fills GlgLatLonPoint lat/lon coordinates from a space separated string, for example: "42.5 -75".

public void CopyFrom( GlgLatLonPoint point )

Copies values from another GlgLatLonPoint.

GlgUtmPoint class

public class GlgUtmPoint

Used by the UTM coordinate conversion methods.

Variables
public long northing;
public long easting;
public long zone_number;
public char zone_letter;
Constructors
public GlgUtmPoint()

Default constructor.

public GlgUtmPoint( long northing, long easting, long zone_number, char zone_letter )

Constructs new GlgUTMPoint with the specified coordinates.

Methods
public void FromString ( String string )

Fills GlgUTMPoint values taking UTM coordinates from a space separated string, for example: "19T 251535 4654131".

public void CopyFrom( GlgUtmPoint point )

Copies values from another GlgUtmPoint.

GlgUtmMGRS class

public class GlgUtmMgrs

Utility class that provides UTM coordinate conversion methods.

Accuracy Constants
Java:
static final int GLM_FAILED_ACCURACY;
static final int GLM_10000_METER;
static final int GLM_1000_METER;
static final GLM_100_METER;
static final GLM_10_METER;
static final GLM_1_METER;
C#:
static const GLM_FAILED_ACCURACY;
static const GLM_10000_METER;
static const GLM_1000_METER;
static const GLM_100_METER;
static const GLM_10_METER;
static const GLM_1_METER;
Methods
static void LatLonPointToUtm( GlgLatLonPoint lat_lon_point, GlgUtmPoint utm_point )

Converts lat/lon coordinates to UTM.

static boolean LatLonPointToUtm( GlgLatLonPoint lat_lon_point, GlgUtmPoint utm_point )

Converts UTM coordinates to lat/lon. Returns true if conversion succeeds.

static String UtmToMgrs( GlgUtmPoint utm_point, int accuracy )

Converts UTM coordinates to the MGRS string and returns the string. The accuracy parameter specifies the accuracy of the conversion using one of the values of the accuracy constants.

static int MgrsToUtm( String mgrs_coord, GlgUtmPoint utm_point )

Converts an MGRS string to UTM coordinates; returns accuracy of a successful conversion (one of the accuracy constants), or GLM_FAILED_ACCURACY if conversion fails.

GLG objects classes

Overview

GLG objects classes provide the actual implementation for specific drawing primitives used in the Toolkit. However, these classes are rarely used by the end user, since the GlgObject superclass delivers most of the GLG API. Unless you are dealing with some advanced uses of the Toolkit, you can skip this section of the manual. For details regarding a particular type of a GLG object, refer to GLG Objects.

The GLG objects classes are used only to create objects using their public constructors. After they are created, you use the GlgObject superclass methods for any further processing.

Most of the time the drawing and objects in it will be created interactively using the GLG Graphics Builder. These object classes are provided for the advanced users who may want to build the drawing programmatically for applications that generate objects in the drawing based on some kind of a configuration file or table.

When the constructors are used, the objects are initially created with default attributes (attribute values set to 0). The values may later be set using the GlgObject SetResource methods.

Most of the constructors may be called with null parameters to create an object instance with default attribute values. Where the non-null parameter are required, it will be explicitly mentioned.

All constants used by these classes are defined in the GlgObject superclass.

GlgArc class

public class GlgArc extends GlgObject

An arc object.

Constructor
public GlgArc()

Creates an arc object.

GlgAxis class

public class GlgAxis extends GlgObject

An axis object.

Constructor
public GlgAxis()

Creates an axis object.

GlgBoxAttr class

public class GlgBoxAttr extends GlgObject

A text box attributes object.

Constructor
public GlgBoxAttr()

Creates an text box attributes object.

GlgChart class

public class GlgChart extends GlgObject

A real-time chart object.

Constructor
public GlgChart()

Creates a chart object.

GlgDynArray class

public class GlgDynArray extends GlgObject

A dynamic array. The array automatically increase its size when new elements are added.

Constructor
public GlgDynArray( int type, int n_slots, int increment )                                 (Java)
public GlgDynArray( GlgContainerType type, int n_slots, int increment )        (C#)

Creates a dynamic array.

The type parameter defines the type of objects that will be stored in the array and may be one of GLG_OBJECT, STRING, INT_VALUE or NATIVE_OBJECT. The GLG_OBJECT default value is used if the value of 0 is passed.

The n_slots parameter defines the initial size of the array. A default value is used if the value 0 is passed.

The increment parameter specifies the initial increment to be used when the size of the array has to be increased. A default value is used if the value 0 is passed.

GlgFont class

public class GlgFont extends GlgObject

A GLG font object.

Constructor
public GlgFont( String font_name, String ps_name )

Creates a font object. The font_name parameter defines the name of the font to use, while ps_name defines the name to use for the font when producing a PostScript output. If these parameters are null, default names are used.

GlgFontTable class

public class GlgFontTable extends GlgObject

A font table object.

Constructor
public GlgFontTable( int num_types, int num_sizes, GlgObject font_array )

Creates a font table. The num_types parameter specifies the number of font types in the table, and num_sizes specifies the number of font sizes. The font_array parameter may specify a GLG group object containing an array of strings to be used as font names. If the length of the array is less than the product of the first two parameters, default font names will be used for the remaining fonts. If null values are passed for the number of font types, sizes, or the font_array, the default values will be used.

GlgFrame class

public class GlgFrame extends GlgObject

A GLG frame object.

Constructor
public GlgFrame( int type, int factor, GlgObject reserved )                                  (Java)
public GlgFrame( GlgFrameType type, int factor, GlgObject reserved )              (C#)

Creates a frame object. The type parameter specifies a type of frame to create and must be FRAME_1D, FRAME_2D or FRAME_3D. The factor parameter must specify the number of intervals the frame uses to create frame points. The last parameter is reserved and a null value must be used.

GlgFunction class

public class GlgFunction extends GlgObject

A helper class for implementing GLG interaction handlers.

Constructors:
public GlgFunction( String name, GlgHandler reserved, String arguments )

Creates an interaction handler that can be attached to a viewport object. The name parameter specifies a name of one of GLG's interaction handlers (GlgButton, GlgKnob, etc.). The second and third parameters are reserved and a null value must be used.

GlgHistory class

public class GlgHistory extends GlgObject

A history object that implements a scrolling behavior of the GLG graphs.

Constructor
public GlgHistory( String var_name, GlgObject reserved1, int reserved2 )

Creates a history object. The var_name parameter specifies the name of the resource to scroll. The second and third parameters are reserved and null values (null and 0 ) must be used.

GlgImage class

public class GlgImage extends GlgObject

An image object, integrates GIF, JPEG, PNG and BMP images into a GLG drawing.

Constructors
public GlgImage( int image_type, String filename, String load_path )

Creates a GLG image object. The image_type parameter defines the type of image: FIXED_IMAGE or SCALED_IMAGE. The filename defines the image file to use and may be a local file or a URL. The load_path parameter is reserved for future use and must be null.

GlgLevelLine class

public class GlgLevelLine extends GlgObject

A level line object.

Constructor
public GlgLevelLine()

Creates a level line object.

GlgLineAttr class

public class GlgLineAttr extends GlgObject

A line attributes object.

Constructor
public GlgLineAttr()

Creates a line attributes object.

GlgList class

public class GlgList extends GlgObject

A linked list object.

Constructors
public GlgList( int type )                                 (Java)
public GlgList( GlgContainerType type )        (C#)

Creates a GLG list object. The type parameter defines the type of objects that will be stored in the array and may be one of GLG_OBJECT, STRING, INT_VALUE or NATIVE_OBJECT. The GLG_OBJECT default value is used if the value of 0 is passed.

GlgLight class

public class GlgLight extends GlgObject

A light object.

Constructors
public GlgLight()

Creates a light object.

GlgMarker class

public class GlgMarker extends GlgObject

A GLG marker object.

Constructor
public GlgMarker()

Creates a marker object.

GlgParallelogram class

public class GlgParallelogram extends GlgObject

A parallelogram object.

Constructor
public GlgParallelogram( int subtype )                                (Java)
public GlgParallelogram( GlgParallType subtype )            (C#)

Creates a parallelogram object of the subtype requested by the subtype parameter: a real parallelogram with 3 point (PA_PA), or a rectangular parallelogram with 2 points (RECT_PA).

GlgPlot class

public class GlgPlot extends GlgObject

A plot object.

Constructor
public GlgPlot()

Creates a plot object.

GlgPolySurface class

public class GlgPolySurface extends GlgObject

A polysurface object.

Constructor
public GlgPolySurface( GlgObject marker, GlgObject polygon, GlgObject reserved )

Creates a polysurface object. The first two parameters are optional and null values may be used, the last parameter is reserved and a null value must be used. The marker parameter specifies a template marker object to use, and the polygon parameter specifies a template polygon.

GlgPolygon class

public class GlgPolygon extends GlgObject

A polygon object.

Constructor
public GlgPolygon( int size, GlgObject reserved )

Creates a polygon object. The optional size parameter specifies the number of points in the polygon. If the values of 0 or 1 are used, a default polygon with two points is created. After the polygon is created, more points may be added or existing points may be deleted by using Add and Delete methods of the GlgObject superclass. The value of -1 may be used to create a polygon with no points. The second parameter is reserved and a null value must be used.

GlgPolyline class

public class GlgPolyline extends GlgObject

A polyline object.

Constructor
public GlgPolyline( GlgObject marker, GlgObject polygon, GlgObject reserved )

Creates a polyline object. The first two parameters are optional and null values may be used, the last parameter is reserved and a null value must be used. The marker parameter specifies a template marker object to use, and the polygon parameter specifies a template polygon.

GlgReference class

public class GlgReference extends GlgObject

A reference object.

Constructor
public GlgReference( GlgObject template, GlgObject reserved )

Creates a reference object. A mandatory template parameter specifies the object to be used as the reference's template. The second parameter is reserved and a null value must be used.

GlgRenderingAttr class

public class GlgRenderingAttr extends GlgObject

A rendering attributes object.

Constructor
public GlgRenderingAttr()

Creates a rendering attributes object.

GlgResourceReference class

public class GlgResourceReference extends GlgObject

An alias object.

Constructor
public GlgResourceReference( String from_name, String to_name, GlgObject reserved )

Creates an alias object. The from_name parameter specifies the new logical name for the resource hierarchy pointed to by the alias. The to_name specifies the resource path to the aliased resource. The third parameter is reserved and a null value must be used.

GlgScreen class

abstract class GlgScreen extends GlgObject

This class implements window-related properties of the viewport object. The class is never created directly. Instead, it is created by the viewport object.

GlgSeries class

public class GlgSeries extends GlgObject

A series object.

Constructor
public GlgSeries( GlgObject template, GlgObject reserved )

Creates a series object. A mandatory template parameter specifies the object to be used as the series template. The second parameter is reserved and a null value must be used.

GlgSpline class

public class GlgSpline extends GlgObject

A spline object.

Constructor
public GlgSpline( int size, GlgObject reserved )

Creates a spline object. The size parameter specifies the number of control points. The second parameter is reserved and a null value must be used.

GlgSquareSeries class

public class GlgSquareSeries extends GlgObject

A square series object.

Constructor
public GlgSquareSeries( GlgObject template )

Creates a square series object. A mandatory template parameter specifies the object to be used as the series template.

GlgTag class

public class GlgTag extends GlgObject

A tag object which is attached to object attributes to hold data connectivity information.

Constructor
public GlgTag( String tag_name, String tag_source, String tag_comment )

Creates a tag object. Optional String parameters supply tag name, tag source and tag comment. The default value for these parameters is null.

GlgText class

public class GlgText extends GlgObject

A text object.

Constructor
public GlgText( String string, int type )                           (Java)
public GlgText( String string, GlgTextType type )           (C#)

Creates a text object. An optional string parameter defines the string to display in the text object. If this parameter is null, an empty string is used as a default. The type parameter defines the type of the text object to create and may be FIXED_TEXT, FIT_TO_BOX_TEXT, WRAPPED_TEXT, TRUNCATED_TEXT, WRAPPED_TRUNCATED_TEXT or SPACED_TEXT. If the value of 0 is passed, the FIT_TO_BOX_TEXT type is used as a default.

GlgViewport class

public class GlgViewport extends GlgObject

A viewport object.

Constructor
public GlgViewport( GlgObject reserved )

Creates a viewport object. The constructor's parameter is reserved and a null value must be used.

GlgXform class

public class GlgXform extends GlgObject

A transformation object.

Constructor
public GlgXform( int role, int type, GlgObject reserved1, GlgObject reserved2 )                            (Java)
public GlgXform( GlgRole role, GlgXformType type, GlgObject reserved1, GlgObject reserved2 )  (C#)

Creates a transformation object used to animate objects.

The role parameter specifies the role transformation plays and may have the value of one of the transformation role constants defined in the GlgObject superclass. POINT_XR is the most common value of this parameter that is used to transform geometrical points in 3D space.

The type parameter specifies the type of the transformation to create and may have the value of one of the transformation type constants defined in the GlgObject superclass, for example: TRANSLATE_XF, SCALE_XYZ_XF, ROTATE_Z_XF, and so on.

After the transformation of a desired type is created, its parameters (such as the scale, rotation angle and others) may be set by using SetResource methods of the GlgObject superclass.

The last two parameters are reserved and null values must be used.

Attribute classes

GlgDataPoint class

abstract class GlgDataPoint extends GlgObject

GlgDDataPoint class

class GlgDDataPoint extends GlgDataPoint

GlgGDataPoint class

class GlgSDataPoint extends GlgDataPoint

GlgSDataPoint class

class GlgGDataPoint extends GlgDataPoint

These classes implement object attributes. These classes are not used by the end user and are listed here for the sake of completeness, so that they can be used in the instanceof operator.

Data Value classes

These classes implement an atomic data value holder. The data object may be used in user applications to hold D, S, or G data. One of the GLG containers may be used to hold a collection of data objects. The data may be assigned or queried using the GetResource and SetResource methods using null as a resource name. The type of the Get/Set method to use (D, S or G) is defined by the type of the data value.

GlgDataValue class

abstract class GlgDataValue extends GlgObject

An abstract superclass for all data value classes

GlgDDataValue class

public class GlgDDataValue extends GlgDataValue

Holds one double data value

Constructors
public GlgDDataValue( double value )
public GlgDDataValue( GlgObject ddatavalue )

Creates a D data value from a double or another GlgDDataValue object. If created from a null ddatavalue, the values of 0 is used as a default value.

GlgGDataValue class

public class GlgGDataValue extends GlgDataValue

Hold one triplet of X, Y, Z or R, G and B values.

Constructors
public GlgGDataValue( double x, double y, double z )
public GlgGDataValue( GlgObject gdatavalue)

Creates a G data value from X, Y and Z values or another GlgGDataValue object. If created from null gdatavalue, the values of 0 are used for X, Y and Z.

GlgSDataValue class

public class GlgSDataValue extends GlgDataValue

Holds one string value as a GLG object

Constructors
public GlgSDataValue( GlgObject sdatavalue )
public GlgSDataValue( String value )

Creates an S data value from a sting or another GlgSDataValue object. If created with null parameters, holds an empty string.

GlgMatrix class

abstract class GlgMatrix extends GlgObject

The GlgMatrix class implements a matrix object that is used for 3D transformations. The matrix holds the "value" of the transformation and is considered to be a data object. The matrix is never created directly by a user application. To create a matrix, a GlgXform transformation object of a required type is created with the required transformation parameters, and then either the xform object or its matrix is used.

GLG Graphics Server Support Classes for ASP.NET

The following classes are used with the GLG Graphics Server for ASP.NET.

GlgHttpRequestProcessor class

public class GlgHttpRequestProcessor

The request processor class for implementing custom HTTP handlers for ASP.NET.

GlgHttpRequestProcessor is used in the ASP.NET environment for implementing custom HTTP handlers. The class handles access to the GLG API from asynchronous ASP.NET handlers. All calls to the GLG API should be performed from inside the GlgHttpRequestProcessor class instance, which is accomplished by providing a custom method to the GlgHttpRequestProcessor instance via a delegate. This custom method will be invoked by GlgHttpRequestProcessor to perform any activity that requires GLG API calls.

Constructors
public delegate void GlgProcessRequestDataFunc( GlgHttpRequestData data )
public GlgHttpRequestProcessor( GlgProcessRequestDataFunc func )

Creates an instance of GlgHttpRequestProcessor with a custom request processing method supplied by the func parameter. The GlgProcessRequestDataFunc delegate declares the type of the func parameter.

Methods
public GlgHttpRequestData ProcessRequest( System.Web.HttpContext context )

The main method of the request processor. It will invoke a custom method supplied to the GlgHttpRequestProcessor constructor to perform custom GLG-related actions that will process the HTTP request. The context parameter provides HTTP request data to be processed.

If an application needs to use a custom error handler to log errors, the GlgObject.SetErrorHandler method should be invoked inside the ProcessRequest method to set a custom error handler for the GlgHttpRequestProcessor instance.

Refer to examples in the examples_ASP.NET directory of the GLG installation on Windows for source code examples of using the GlgHttpRequestProcessor class.

GlgHttpRequestData class

public class GlgHttpRequestData extends GlgErrorHandler

This is an auxiliary class used by GlgHttpRequestProcessor to pass the HTML request data to its custom request processing method and to return generated data. It does not have a public constructor and is created by GlgHttpRequestProcessor.

Fields
public HttpContext context;

Supplies an HTTP request to be processed by the custom method.

public Bitmap image;

Contains the generated image (if it was generated).

public String html_response;

Contains non-image html response that may be created when processing a mouse selection request, such as a tooltip.

public Object custom_data;

This field may be used to return any additional custom data generated as a result of the HTML request processing.

public bool got_errors;

An error indicator that may be set to true by the custom processing method to indicate an error, causing GlgHttpRequestProcessor to return null. While the default error handler automatically sets got_errors to true if an error is encountered, the got_errors field may be used by a custom error handler to indicate an error.

Graph Layout Classes

Overview

The GLG Graph Layout package implements the spring embedder graph layout algorithm used for automatic layout of graphs containing nodes connected with edges. The spring embedder algorithm performs a series of iterations optimizing the graph layout and minimizing the number of node intersections. The GLG Graph Layout Demo shows an example of an application that creates and automatically lays out a graph containing connected nodes of a network. The demo's source code may be used as an example of using the Graph Layout module.

As seen in the demo, GLG Graph Layout may be used together with the GLG graphical engine, using GLG to display the graph and its nodes. In this case, the GLG Graphics Builder may be used to define a palette of graphical objects containing icons for the graph's nodes.

The Graph Layout may also be used to lay out non-GLG objects, for example, Swing components or .NET controls representing an application's objects. In this case, the application uses the Graph Layout's relative node position output (in the range from 0 to 1) to position an application's objects on the page.

The Graph Layout Component is provided with the GLG Extended API.

GlgGraphNode class

Fields:
public int type;

Node type (0-based index used to associate the node with the node icon from the palette).

public Object data;

Data object associated with the node.

public GlgPoint display_position;

Node's display position in GLG coordinates.

public GlgPoint position;

Node's position in normalized coordinates (in the range from 0 to 1).

public GlgObject graphics;

GlgObject actually used to display the node.

public GlgObject template;

Custom GlgObject used to display the node. If the template is null, an icon from the palette is used.

public GlgObject link_array;

A group (GlgObject) containing the list of links (of the GlgGraphEdge type) attached to this node.

public boolean anchor;

The node's anchor flag. Setting this flag to true anchors the node: the node does not move, the rest move around this node.

Methods:
public GlgGraphNode();

Default constructor.

GlgGraphEdge class

Fields:
public int type;

Edge type (0-based index used to associate the node with the edge icon from the palette). It is 0 in the current implementation.

public Object data;

Data object associated with the edge.

public GlgObject graphics;

GlgObject actually used to display the edge.

public GlgObject template;

Custom GlgObject used to display the edge. If the template null, an icon from the palette is used.

public GlgGraphNode start_node;

The node the start of the edge is connected to.

public GlgGraphNode end_node;

The node the end of the edge is connected to.

Methods:
public GlgGraphEdge();

Default constructor.

GlgGraphLayout class

C# Enums:

public enum GlgCreateGraphType

{

   RANDOM_GRAPH,

   CIRCULAR_GRAPH,

   STAR_GRAPH

}

Defines types of graphs that can be created via the CreateRandom method.

Java Constants:
public static CIRCULAR_GRAPH;

Graph type constant for creating circular demo graphs.

public static RANDOM_GRAPH;

Graph type constant for creating random demo graphs.

public static STAR_GRAPH;

Graph type constant for creating demo graphs with a star shape.

Fields:
public static GlgObject DefNodeIcon;

A group of node icons to use if no palette is defined.

public static GlgObject DefEdgeIcon;

An edge icon to use if no palette is defined.

public static GlgObject DefViewportIcon;

A default viewport to use to render the graph.

public GlgObject palette;

The graph's palette.

public GlgPoint dimensions;

The extent of the graph's drawing, [-800;800] by default.

public GlgObject node_array;

A group containing all graph nodes (GlgGraphNode).

public GlgObject edge_array;

A group containing all graph edges (GlgGraphEdge).

public double end_temperature;

The final "temperature" of the graph (in the range from 0 to 1) defining the end of the layout process, 0.2 by default. A higher value will result in the process finishing faster but with less precision. A lower value will cause the layout process to last longer, trying to produce a finer layout.

public boolean finished;

Is set to true when the graph layout finishes positioning the nodes.

public boolean iteration;

The current iteration number.

public int update_rate;

The graph's update rate: the graph is redrawn after each update_rate iterations.

Methods:
public GlgGraphLayout();

Constructor.

public void GlgGraphDestroy();

Destroys all internal structures used by the instance of the graph:

public void GlgGraphSetPalette( GlgObject palette_drawing )

Sets the graph's icon palette. The palette drawing must contain node icons named Node0, Node1, Node2, etc. Each node must contain a G-type resource named Position, which is used by the graph layout to position the node. The palette must also contain an edge icon (a polygon named Edge), which is used to define the edges' attributes.

Parameters:
palette_drawing
Specifies the palette to use for the graph.
public void SetDefaultPalette( GlgObject palette_drawing );

Sets the default palette to be used by all graphs:

Parameters:
palette_drawing
Specifies the palette to use as a default palette.
public void UnloadDefaultPalette();

Resets the default palette to null and destroys any stored objects.

public void CreateGraphics( GlgObject viewport );

Loads icons from the palette and creates a GLG drawing to render the graph.

Parameters:
viewport
An optional viewport. If it is not null, it is used as a container for the graph's drawing, rendering the graph in the existing object hierarchy. If it is null, the graph will create a new viewport to render the graph.
public void DestroyGraphics();

Destroys the graph's drawing and all graphical objects used to render nodes and edges.

public GlgObject GetViewport();

Returns the viewport of the graph's drawing.

public void SpringIterate();

Performs one iteration of the spring embedder layout, returns true if the layout process has finished.

public void Update()                       (Java)
public void UpdateGlg()                 (C#)

Updates the display to show the results of the spring layout. There is no need to update the display after every iteration: it may be updated every N iterations, or just once when the layout is finished.

public void AddNode( GlgObject graphics, int node_type, Object data );

Creates a new node and adds it to the graph.

Parameters:
graphics
An optional custom node icon to override the icon from the palette.
node_type
The palette index, specifies what icon to use from the node palette if no custom icons are specified.
data
Custom data to attach to the node.
public void AddEdge( GlgGraphNode start_node, GlgGraphNode end_node, GlgObject graphics,
int edge_type, Object data );

Creates a new edge and adds it to the graph.

Parameters:
graph
Specifies the graph.
graphics
An optional custom edge icon to override the icon from the palette.
edge_type
The palette index, specifies what icon to use from the edge palette if no custom graphics are specified (reserved for future use).
data
Custom data to attach to the edge.
public void DeleteNode();

Deletes node from the graph.

Parameters:
node
Node to delete.
public void DeleteEdge();

Deletes edge from the graph.

Parameters:
edge
Edge to delete.
public GlgPoint GetNodePosition( GlgGraphNode node );

Returns the node position in GLG coordinates (in the range from -1000 to 1000).

Parameters:
node
Node object
public void SetNodePosition() GlgGraphNode node, double x, double y, double z );

Sets the node position in GLG coordinates (in the range from -1000 to 1000).

Parameters:
node
Node object.
x, y, z
New coordinate values.
public GlgGraphNode FindNode( GlgObject node_graphics );

Finds the node object by its graphics and is used to handle mouse selection.

Parameters:
node_graphics
The graphical object used to render the node in the drawing.
public GlgGraphEdge FindEdge( GlgObject edge_graphics );

Finds the edge object by its graphics and is used to handle mouse selection.

Parameters:
edge_graphics
The graphical object used to render the edge in the drawing.
public boolean NodesConnected( GlgGraphNode node1, GlgGraphNode node2 );

Connectivity test, returns true if there is an edge connecting the two nodes.

Parameters:
node1, node2
Node objects.
public void IncreaseTemperature( boolean init );

Forces the graph to continue layout after it is finished by increasing the temperature of the graph by a small increment.

Parameters:
init
Specifies if large increment should be used to re-layout the graph if true.
public boolean GetUntangle();

Returns true if the untangling algorithm is enabled. The untangling algorithm helps the graph layout to avoid local minima in the form of intersecting edges. Using this algorithm roughly doubles the time it takes to finish the layout.

public void SetUntangle( boolean untangle );

Enables or disables the untangling algorithm.

Parameters:
untangle
Specifies whether untangling should be used.
public void Error( String string );

Prints an error message.

Parameters:
string
Error message to print.
public void Scramble();

Randomly scrambles the graph's nodes and is mostly used by demo programs.

public static GlgGraphLayout CreateRandom( int num_nodes, int num_node_types, int graph_type );

The demo constructor, creates and returns a graph layout of a requested type, populating it with nodes and edges.

Parameters:
num_nodes
Number of graph nodes to create.
num_node_types
Number of node types to use for rendering.
type
Graph type constant: RANDOM_GRAPH, CIRCULAR_GRAPH or STAR_GRAPH.


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