Using the ActiveX Control

Overview

The GLG ActiveX Control provides GLG Toolkit functionality and a complete GLG Programming API in the form of the Windows' ActiveX control. The ActiveX may be used in Visual Studio.NET with C++, C# and Visual Basic. It may also be used with other products that support embedded ActiveX controls. The ActiveX control may be deployed on the Web inside the Internet Explorer Web browser.

The GLG ActiveX Control is implemented as a dynamic link library with the .OCX extension. When registered and loaded, this single glg.ocx file may be used to display an extensive set of GLG widgets and custom drawings that can be accessed by users and applications.

The flexibility of the GLG drawing architecture translates into flexibility for the GLG ActiveX Control. Any GLG drawing may be used as a custom control by loading it into the ActiveX control. For example, loading a custom process control drawing into the GLG ActiveX control makes it a custom control with the functionality of the loaded drawing. The GLG ActiveX Control includes properties and methods to dynamically change the resources of a GLG drawing as your application's data change, allowing you to bind your real-time data to the attributes of the drawing displayed by the control.

For example, in a business application you may bind real-time data like a current stock price, as well as the high and low values, to a graph to display a history of changes. In a chemical process monitoring application, you may bind the temperature and level of fluid in a tank to the color and height of the tank's filling in the drawing, to display these parameters graphically.

The GLG ActiveX Control also defines custom Input and Select events. These events provide user feedback, allowing an application to react to user input or determine which graphical objects were selected with the mouse.

This chapter describes specific details of using the GLG ActiveX Control. Refer to Using the C/C++ version of the Toolkit for a detailed description of the Standard and Extended API methods, as well as details of the Input callback (described in Handling Input Events). 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.

GLG ActiveX Control Properties

GLG ActiveX Control has the following properties:

General Page

DrawingFile

Specifies a GLG drawing to display in a control. The drawing file must exist at the time the control is created. This property has priority over the DrawingImageFile property described below.The drawing must contain a viewport object named $Widget with HasResources flag set to YES.

DrawingImageFile

Specifies a drawing to be used and stored in a control. The drawing file must exist at the time this property is set. and a copy of it is stored in the control. Saving the control with this property set saves a copy of the drawing with the control, allowing loading and using the control later with no separate drawing file. The DrawingFile property has higher priority: if both DrawingFile and DrawingImageFile properties are set, the control will use the drawing defined by the DrawingFile property, and only if loading that drawing fails, DrawingImageFile property is used. To discard the stored drawing, set this property to an empty string.

NOTE: the DrawingImageFile property doesn't support compressed drawings. Save drawings with the drawing compression option disabled for use them with this property.

DrawingURL

Specifies a URL address to load a drawing from a Web. The drawing is cached. If other drawing properties are used to define the drawing, they have higher priority. DrawingURL property has the lowest priority and is used when other drawing properties are not specified or can't be used. Local drawings may be loaded using this property by specifying " file:// " at the beginning of the complete path name.

SetupDataURL

Specifies the URL used for the setup data script. The script has the standard GLG script format , described in The Data Generation Utility of GLG Programming Tools and Utilities. The script is invoked after the hierarchy has been setup and may access any resources of the drawing. The H properties of the control may be used to change resources before the hierarchy has been setup. The script is invoked only once when the drawing is loaded and initializes it with data. The script is not cached and is loaded asynchronously.

DataURL

Specifies the URL of the script to supply data. The script has the standard GLG script format , described in The Data Generation Utility of GLG Programming Tools and Utilities. The script is first invoked after the SetupData script and fills the control with data. If the UpdatePeriod property is set, the script at the DataURL location is invoked repeatedly with the interval defined by the UpdatePeriod property. This enables the ActiveX control to periodically reload data to update display with the latest data.

UpdatePeriod

Defines a periodic interval in seconds for running the DataURL script.

PrintFile

Specifies a filename for printing the current content of a drawing in the encapsulated PostScript format, which may later imported into most word processors. Setting this property saves a PostScript output into the specified file using a default page layout. The control's Print method described later may be used to control page layout.

InputEnabled

Controls whether input events are sent (default: TRUE). Input events are generated when a user activates sliders, dials, buttons or other input controls inside the GLG ActiveX Control. Generating input events is disabled if this property is set to FALSE.

SelectEnabled

Controls whether selection events are sent (default: TRUE). Selection events are generated when a user selects a graphical object inside the GLG ActiveX Control with the mouse. Generating selection events is disabled if this property is set to FALSE. Set this property to FALSE to increase performance for GLG ActiveX Controls which do not need selection feedback.

TraceEnabled

Controls whether trace events are sent (default: FALSE). Trace events are low level Windows events which may be used to trace the mouse position inside the ActiveX control, handle mouse and keyboard events, etc. Set this property to FALSE to increase performance for GLG ActiveX Controls which do not need trace events.

SupressErrors

When set to TRUE (default value), suppresses the error message dialogs and recording errors in a " glg_err.log " log file. Set the property to FALSE to enable debugging GLG ActiveX Control problems.

HProperties Page

HProperty0 - HProperty4

These are character strings that specify five pre-creation properties. These properties serve as entry points to the GLG drawing resource hierarchy and may be used for setting resources before the drawing's object hierarchy is created. They should be used for setting a drawing's H resources, which control the structure of a GLG drawing's hierarchy. For information about H resources, refer to H and V Resources in Details of using GLG Standard API for C and C++. The syntax for the character strings is described in Dynamic Resource String Syntax of this chapter. These properties are persistent and may be used for customizing a drawing's appearance before saving the control.

 

The GLG ActiveX Control does not need five different dynamic properties of this type. In one sense, it would be adequate to have just one, and use it repeatedly. However, it is often useful to be able to set the initial values of several drawing resources, so multiple dynamic properties like these are provided. The same is true of the V properties described in the following section.

In the event that there are not enough GLG ActiveX Control dynamic properties for your purpose, you can use the GLG ActiveX Control 's Ready event and call the GLG ActiveX Control's methods to set the initial resources. The GLG ActiveX Control's custom events and methods are described later in this chapter.

VProperties Page

VProperty0 - VProperty4

These are five character strings that specify five post-creation properties. These properties serve as entry points to the GLG drawing resource hierarchy and may be used for setting resources after the drawing's object hierarchy is created. They should be used for setting a drawing's V resources, which only control the values of attributes within the structure of a GLG drawing's hierarchy. For information about V resources, refer to H and V Resources in Details of using GLG Standard API for C and C++. The syntax for the character strings is described in Dynamic Resource String Syntax of this chapter. These properties are persistent and may be used for customizing a drawing's appearance before saving the control.

DLinks Page

DLinkName0 - DLinkName4

Specify resource names to be used for accessing scalar (D) resources of a drawing.

DLinkValue0 - DLinkValue4

Specify double-precision values to be set for scalar resources whose names are defined by the corresponding DLinkName properties. Use these properties to access frequently used double resources, an entry point of a graph's data samples, for example. These properties are bindable and not persistent.

SLinks Page

SLinkName0 - SLinkName4

Specify resource names to be used for accessing string (S) resources of a drawing.

SLinkValue0 - SLinkValue4

Specify values to be set for string resources whose names are defined by the corresponding SLinkName properties. Use these properties to access frequently used string resources, an entry point of a graph's labels, for example. These properties are bindable and not persistent.

GLinks Page

GLinkName

Specify resource names to be used for accessing geometric (G) resources of a drawing (colors and control points defined by triplets of double values).

GLinkValueX, GLinkValueY, GLinkValueZ

Specify values to be set for a geometric resource whose name is defined by GLinkName property. These properties are bindable and not persistent.

Dynamic Resource String Syntax

The H and V Properties are dynamic properties of the GLG ActiveX Control. These properties contain character strings which in turn contain the names and values of GLG drawing resources. The strings have the following syntax:

<resource_name> <resource_type> <values>
<resource_name>

The name of the GLG drawing resource, including the complete path (omitting the "$Widget" ). For example, "XLabelGroup/XLabel4/String" accesses the text string of the fifth label on the X axis in a graph widget.

<resource_type>

The type of the resource and can be one of the following:

d Indicates the resource value is represented by a single floating point number (a scalar), like a line width, a font number or a value of a data sample

s The resource value is a string, like a text string of a label text object

g The resource value is a set of three floating point numbers, like a geometrical point with X, Y and Z coordinates or a color, in which case the three components represent the color's Red, Green, and Blue values.

<values>

A value or a set of values for the resource. The values given depend on the resource type.

The following strings are examples of specifying resources:

"DataGroup/DataSample3/Value d 2.5"
"DataGroup/DataSample5/Value d 4"
"XLabelGroup/XLabel4/String s April"
"DataGroup/DataSample6/FillColor g 0.5 0 0.9"

Persistency Support

The following properties are persistent and keep their values when the control is saved and loaded:

DrawingFile (saves the file name only)

DrawingImageFile (saves a copy of the drawing)

PrintFile (saves the file name only)

InputEnabled

SelectEnabled

HProperty0-HProperty4 (the last property resource setting is stored )

VProperty0-VProperty4 (the last property resource setting is stored)

The remaining properties are not persistent and are initialized to their default values when loaded.

GLG ActiveX Control Events

GLG ActiveX Control has the following custom events:

Input( String Format, String Origin, String FullOrigin, String Action, String SubAction )

Input event is fired on user input, for example when a slider in the ActiveX control drawing is moved. It's parameters are identical to the resources of message object in the GLG API's Input callback . The last input message objects is stored by the ActiveX control, and its resources may also be accessed as resources by prepending " $message/ " to the resource name. For example, " $message/ValueX " may be used to query the value of a slider using methods of the Standard API.

Input2( long message_obj )

Input2 is an alternative form of the Input event which provides a message object parameter containing all resources of the input event. The message object may be passed to the Extended API methods to query its resources. The Input event may be used with the Standard API methods.

Select( String selected_name, short button )

Selection event is fired when objects in the ActiveX control drawing are selected with a mouse click (button press). The parameters define the complete resource name of the selected object and the mouse button which was used for selection. If several closely positioned objects are selected with a mouse click, the callback is called repeatedly with a name of each selected object. The first and last call have " @@SelectionStart@@ " and " @@SelectionEnd@@ " as values of the selected_name parameter, allowing to detect the start and the end of a single mouse selection sequence of events. The name of the selected object and the mouse button used to select it may also be queried using the GetSelectedName and GetSelectionButton methods of the ActiveX control.

Select2( long selection_array, short button )

Same as the Select event, but invoked just once with an array of resource names of all selected objects. The GetElementExt method of the Extended API may be used to retrieve resource names of selected objects.

Trace( long top_viewport, long viewport, long message, long wParam, long lParam )
Trace2( long top_viewport, long viewport, long message, long wParam, long lParam )

Generated for all low-level windowing events such as mouse move, mouse click, button press, etc. May be used to trace the position of the mouse inside the drawing or handle native low-level events. The top_viewport parameter is the top-level viewport of the drawing. The viewport parameter is the viewport where the event occurred. The message parameter is the Windows' message number. The wParam and lParam are message-dependent data parameters.

The Trace event is generated before the event has been dispatched for processing. The Trace2 event is generated after the event has been processed.

HCallback()

Generated after loading the control's drawing but before its hierarchy was set up. It may be used to initialize values of H resources, such as a number of instances in a series object or a number of datasamples in a graph.

VCallback()

Generated after the hierarchy setup, but before the drawing is displayed for the first time. It may be used for initializing V resources, such as filling the graph with data for the initial appearance.

Ready()

Generated when the control finished loading the drawing and was painted for the first time.

ActiveX Control Methods

The methods of the ActiveX control's API allow you to animate control's drawing with application data from a VC++ or VB application. The methods can also be used to animate the drawing with data when the ActiveX control is deployed on a Web, in which case Java or Visual Basic Script is used to invoke the methods.

The GLG ActiveX Control provides the following methods:

double GetDResource( String resource_name )

double GetDTag( String tag_name )

Returns the value of the drawing's scalar resource or tag. Returns zero if the resource or tag was not found.

BOOL SetDResource( String resource_name, double dvalue )

BOOL SetDTag( String tag_name, double dvalue, BOOL if_changed )

Sets the value of the drawing's scalar resource or tag. Returns TRUE if the resource or tag exists and the setting was successful, FALSE otherwise.

NOTE: Use SetDResourceIfExt with null object parameter for SetDResourceIf functionality.

String GetSResource( String resource_name )

String GetSTag( String tag_name )

Returns the value of the drawing's string resource or tag. Returns the empty string ("") if the resource or tag was not found.

BOOL SetSResource( String resource_name, String svalue )

BOOL SetSTag( String resource_name, String svalue, BOOL if_changed )

Sets the value of the drawings's string resource or tag. Returns TRUE if the resource or tag exists and the setting was successful; otherwise returns FALSE.

NOTE: Use SetSResourceIfExt with null object parameter for SetSResourceIf functionality.

BOOL SetSResourceFromD( String res_name, String format, double dvalue )

Sets the value of the drawing's string resource to a string obtained by converting the supplied double value according to the format . The format parameter is a C format string. Returns TRUE if the resource exists and the setting was successful; otherwise returns FALSE.

NOTE: Use SetSResourceFromDIfExt with null object parameter for SetSResourceFromDIf functionality.

double GetXResource( String resource_name )

double GetXTag( String tag_name )

double GetYResource( String resource_name )

double GetYTag( String tag_name )

double GetZResource( String resource_name )

double GetZTag( String tag_name )

Return the X , Y , or Z value of the drawing's geometric resource or tag. Returns zero if the resource was not found.

BOOL SetGResource( String resource_name, double dvalue1, double dvalue2, double dvalue3 )

BOOL SetGTag( String tag_name, double dvalue1, double dvalue2, double dvalue3,
BOOL if_changed )

Sets the value of the drawing's geometric resource or tag. Returns TRUE if the resource or tag exists and the setting was successful.

NOTE: Use SetGResourceIfExt with null object parameter for SetGResourceIf functionality.

BOOL HasResourceObject( long object, String resource_name )

BOOL HasTagObject( long object, String tag_name )

Returns TRUE is a named resource object or tag exists, returns FALSE otherwise.

long CreateTagList( long object, BOOL unique_tags )

Creates and returns a list of object's tags, or NULL if no tags were found. If unique_tags parameter is set to TRUE, the list will include only one tag instance in case there are multiple tags sharing the same name. The list must be destroyed using DropObject when it is no longer needed.

void Update()

Forces GLG ActiveX Control to update the displayed drawing to reflect the current object hierarchy. Several resource changes may be effected at once by invoking several resource setting methods and then invoking the update method once to display all changes at once. This also increases performance. Note, however, that some setting some H resources may interfere with setting other V resources, and that it may be necessary to invoke the Update method in between setting these two kinds of resources. For example, before you know that a series has eight members, it makes no sense to query the eighth member. You must set the series Factor resource, execute the Update method, and then query the series members.

NOTE: In the .NET environment, the Update method of the GLG ActiveX Control is shadowed by the object's Update method of the .NET framework. As the result, the GLG Update method is never invoked. To invoke the GLG Update method of the GLG ActiveX Control, use the UpdateExt method of the Extended API, invoking it with null object parameter:

glg_control.UpdateExt( 0 );

While UpdateExt is the Extended API method, it is available to the Standard API when the method is invoked with null object parameter. With null object, the method is applied to the ActiveX control's drawing viewport, which is equivalent to the control's Update method.

BOOL SetZoom( long viewport, String res_name, short type, double value )

Performs a zoom or pan operation specified by the type parameter. If the res_name parameter is NULL, the viewport itself is zoomed. Otherwise, the zoom operation will be performed on its child viewport specified by the res_name parameter. If the viewport parameter is null , the viewport of the ActiveX control's drawing is used. The value parameter defines the zoom factor or pan distance. Refer to GlgSetZoom on page 71 for a complete list of all zoom and pan types.

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.

BOOL SetGISZoom( String res_name, long gis_object, String gis_name)

Sets or resets a viewport's GIS Zoom Mode. If the GIS zoom mode is set, any zooming and panning operations invoked by the GlgSetZoom method will zoom and pan the map displayed in the viewport's GIS object instead of being applied to the viewport's drawing. If the res_name parameter is null, the GIS zoom mode of the viewport itself will be set. Otherwise, the GIS zoom mode will be set for its child viewport specified by the res_name parameter. If the gis_name parameter is not null, it specifies the resource path of the GIS object relative to the gis_object parameter, or relative to the viewport if the gis_object parameter is null. The method may be invoked with gis_object=null and gis_name=null to reset the GIS zoom mode.

BOOL GISConvert( long object, String res_name, long coord_type, BOOL coord_to_lat_lon, double x1, double y1, double z1, double * x2, double * y2, double * z2 )

Converts coordinates between the GIS coordinate system of the GIS Object and GLG coordinate system of the drawing. If the res_name parameter is NULL, object specifies the GIS object whose coordinate system to use for conversion. If the res_name parameter is not NULL, object specifies a parent of the GIS object. The res_name parameter specifies the resource name of the GIS object inside the parent object specified by the object parameter. The coord_type parameter specifies the type of the GLG coordinate system type to convert to or from: GLG_SCREEN_COORD for screen coordinates or GLG_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. The x1, y1 and z1 parameters specify coordinates to be converted. The x2, y2 and z2 parameters point to the variables that will receive converted coordinate values. The function returns TRUE if conversion succeeds. When converting from GLG to GIS coordinates, the Z coordinate is set to a negative value for points on the invisible part of the globe.

long SendMessage( String res_name, String message, long param1, long param2, long param3,
long param4 )

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

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

long SendMessageStr( String res_name, String message, String param1, long param2, long param3,
long param4 )

Same as SendMessage , but sends the first parameter as a string. It is intended for use in VB.net environment that does not provide type casts.

long ExportStrings( long object, String filename, long separator1, long separator2 )

Writes all text strings defined in the drawing specified by the object parameter into a string translation file using requested separator characters. Refer to Localization Support on page 101 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.

long ImportStrings( long object, String filename )

Replaces text strings in the drawing defined by the object parameter with the strings loaded from a string translation file. Refer to Localization Support on page 101 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.

long ExportTags( long object, String filename, long separator1, long separator2 )

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

long ImportTags( long object, String filename )

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

void Print( String filename, double x, double y, double width, double height,
BOOL portrait, BOOL stretch )

Saves encapsulated PostScript output with the current state of the drawing into the specified file. The x , y , width , and height parameters define the PostScript page layout. The origin is defined to be in the middle of the page, the left edge of the page is at -1000, and the right edge is at 1000. The top and bottom of the page are similarly defined to be at 1000 and -1000, respectively. The x and y parameters define the lower left corner of the drawing, while width , and height give the dimensions of the drawing area. As an example, the default page layout you get when you print a drawing by setting the PrintFile property puts the lower left corner of the drawing area at ( -900 -900 ), while the dimensions are 1800 by 1800 . This makes the drawing about as large as it can be while still keeping a small border all the way around the page. The portrait parameter specifies portrait (TRUE) or landscape (FALSE) mode. If the stretch parameter is set to FALSE, the X/Y ratio of the drawing is preserved.

BOOL SaveImage( long object, String res_name, String filename, long format )

Saves a JPEG image of the visible area of the viewport's drawing into a file. Returns TRUE if the image was successfully saved. This method is disabled in Secure mode if GLG_ACTIVEX_SAVE_FILE environment variable is not set. In the current release of GLG, only JPEG image format (format=2) is supported. The res_name parameter specifies the resource name of a child viewport whose image to generate, or null to generate the image of the viewport itself.

BOOL SaveImageCustom( long object, String res_name, String filename, long format, long x, long y, long width, long height, long gap )

Saves a JPEG image of the specified area of the drawing into a file. Returns TRUE if the image was successfully saved. This method is disabled in Secure mode if GLG_ACTIVEX_SAVE_FILE environment variable is not set. In the current release of GLG, only JPEG image format (format=2) is supported. The res_name parameter specifies the resource name of a child viewport whose image to generate, or null to generate the image of the viewport itself. The x, y, width and height parameters specify the area of the drawing in screen pixels for generating the image. If both the width and height parameters are set to 0, 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 width and height equal 0. The viewport's zoom factor defines the scaling factor for objects in the drawing when the image is saved.

void AboutBox()

Displays version number and other GLG ActiveX Control information in a box on the screen.

String GetSelectedName()

Returns the name of the last selected object reported by the Select event. It may be used to access the Select event information by using the control's methods in cases when there is no access to the events' parameters (scripting usage).

short GetSelectionButton()

Returns the mouse button which was pressed to generate the last Select event. Similar to GetSelectedName , it may be used to access the Select event information by using the control's methods.

void DropObject( long object )

Dereferences an object.

long GetStringID( String string )

Converts the string to a persistent GLG string and returns its handle. The handle has to be freed with FreeStringID method when done. This function provides conversion between the String and GLG string types for the VB.net environment.

void FreeStringID( long string_id )

Frees the GLG string identified by its string_id handle in the VB.net environment.

void GetMajorVersion()
void GetMinorVersion()

Return major and minor version numbers.

ActiveX Control Extended API Methods

The methods of extended API may be used to add objects, dynamics and constraints to the ActiveX control drawing on the fly. This may be used to create sophisticated VC++ or Visual Basic applications. On the Web, Java or Visual Basic Script may be used to access the Extended API methods, enabling web designers to create complex interactive web applications.

The ActiveX control's Extended API methods mimic the methods of GLG Extended API. Refer to The GLG Extended API for more details on GLG Extended API methods.

The methods of the ActiveX control Extended API listed below have parameters identical to the corresponding methods of the C API, unless mentioned otherwise. A long value is used to represent an object id. This object id has meaning only inside a particular ActiveX control and can't be used interchangeably between several ActiveX controls. Refer to the GlgApi.h file for the values of the enumerated parameters of the methods. In most of the cases a null value may be used as a reasonable default.

There are several methods of Extended API which are identical to the corresponding methods of the regular API with the only difference of having an additional object parameter. For example,

SetDResource( resource_name, resource_value )

and

SetDResourceExt( object, resource_name, resource_value )

The Extended API method above allows setting resources of the specific object while the regular API method sets the resource of the main viewport of the drawing (viewport named "$Widget" ).

If the null value is used as an object parameter of such Extended API methods, the object defaults to the main viewport of the drawing and the result will be identical to the corresponding regular API method invocation. This is also true even for the Extended API method which do not have corresponding regular API methods. For example, to add objects to the main viewport of the drawing using AddObjectExt method, you can use the value of zero as the first parameter, which results in using the main viewport of the drawing as a container. For the Get/SetResource methods of the Extended API passing NULL value for the object parameter allows using the methods even if the Extended API is disabled.

All Extended API methods have the Ext suffix, allowing to differentiate them from methods of the regular API.

The GLG ActiveX Control provides the following Extended API methods:

BOOL AddObjectToTopExt( long container, long object )

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

BOOL AddObjectToBottomExt( long container, long object )

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

BOOL AddObjectAtExt( long container, long index )

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

BOOL AddObjectExt( long container, long object, long access_type, long position_modifier )

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.

BOOL ContainsObjectExt( long container, long object )

Returns true if the object is contained in container .

long CloneObjectExt( long object, long clone_type )

Creates and returns a copy of an object according the clone_type.

BOOL ConstrainObjectExt( long from_object, long to_object )

Constrains an attribute object.

long CopyObjectExt( long object )

Creates and returns a copy of the object.

long CreateObjectExt( long object_type, String object_name,
long data1, long data2, long data3, long data4 )

Creates and returns an object of a specified type. The object has to be explicitly added to the drawing in order to be displayed.

BOOL DeleteObjectAtExt( long container, long index )

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

BOOL DeleteBottomObjectExt( long container )

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

BOOL DeleteTopObjectExt( long container )

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

BOOL DeleteThisObjectExt( long container, long object )

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

BOOL DeleteObjectExt( long container, long reserved, long access_type, long position_modifier )

Deletes an object from a container.

long FindObjectExt( long container, long object, long search_type, long reserved )

Finds an object in the container according to the search type and returns it.

long GetElementExt( long container, long index )

Returns the element of the container indicated by the index .

BSTR GetElementAsString( long container, long index )

Returns a string of the string list ( container) indicated by the index . This method is intended for VB.net environment which does not provide type casts.

long GetIndexExt( long container, long 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.

long GetStringIndexExt( long container, 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.

long GetNamedObjectExt( long container, String name )

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

double GetDResourceExt( long object, String resource_name )

double GetDTagExt( long object, String tag_name )

Returns a value of an object's resource or tag.

long GetNumParents( long object )

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

long GetParentExt( long object )

Returns the objects' parent if 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.

long GetResourceObjectExt( long object, String tag_name )

Finds and returns an object ID of the object's attribute or named resource.

long GetTagObjectExt( long object, String resource_name, BOOL unique_tags, BOOL single_tag)

In a single tag mode, finds and returns an object ID of the first named tag with the specified name or matching a tag name pattern. In the multiple tags mode, returns a list of tags matching the tag name pattern (the list must be dereferenced using DropObject when no longer needed). The unique_tags controls if only one tag is included in case there are multiple tags with the same name. It is ignored in the single tag mode.

String GetSResourceExt( long object, String resource_name )

String GetSTagExt( long object, String tag_name )

Returns the value of a string resource or tag.

long GetSizeExt( long container )

Returns the size of a container object.

long GetViewportExt( void )

Returns the object ID of the main viewport of the drawing (the viewport named "$Widget" )

double GetXResourceExt( long object, String resource_name )

double GetXTagExt( long object, String tag_name )

double GetYResourceExt( long object, String resource_name )

double GetYTagExt( long object, String tag_name )

double GetZResourceExt( long object, String resource_name )

double GetZTagExt( long object, String tag_name )

Returns the value of the X, Y or Z coordinates of a G-type resource or tag.

BOOL IsDemoExt( void )

Returns TRUE if the a Free Non-Commercial version of the ActiveX Extended API is used.

void InverseExt( long container )

Inverses the order of components inside the container.

long IterateExt( long container )

Returns the object ID of the next subobject in the container.

long LoadObjectExt( String filename )

Loads an object from a file and returns its object ID. The object has to be added to the drawing to be displayed.

long LoadWidgetFromFileExt( String filename )

Loads a viewport named "$Widget" from a file and returns its object ID. The viewport has to be added to the drawing to be displayed.

long LoadWidgetFromObjectExt( long object )

Finds a viewport named "$Widget" inside the object returns its object ID.

BOOL MoveObjectExt( long object, long coord_type, double start_x, double start_y, double start_z,
double end_x, double end_y, double end_z )

Moves an object by the specified vector.

BOOL MoveObjectByExt( long object, long coord_type, double x, double y, double z )

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

BOOL ScaleObjectExt( long object, long coord_type,
double center_x, double center_y, double center_z, BOOL around_center,
double scale_x, double scale_y, double scale_z )

If around_center equals TRUE, scales an object relative to the center by the specified X, Y and Z scale factors, otherwise scales the object relative to the center of the object's bounding box.

BOOL RotateObjectExt( long object, long coord_type,
double center_x, double center_y, double center_z, BOOL around_center,
double x_angle, double y_angle, double z_angle )

If around_center equals TRUE, rotates an object around the specified center by the specified X, Y and Z angles, otherwise rotates the object relatively to the center of the object's bounding box.

BOOL PositionObjectExt( long object, long coord_type, long anchoring, double x, double y, double z )

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

BOOL FitObjectExt( long object, long coord_type, double x1, double y1, double z1,
double x2, double y2, double z2 )

Fits the object to the specified area.

BOOL LayoutObjectsExt( long object, long sel_elem, int type, double distance, BOOL use_box )

Perform requested layout operation. Refer to The GLG Extended API on page 97 for more details.

BOOL ScreenToWorldExt( BOOL inside_vp, double screen_x, double screen_y, double screen_z,
double * world_x, double * world_y, double * world_z )

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

BOOL WorldToScreenExt( BOOL inside_vp, double world_x, double world_y, double world_z,
double * screen_x, double * screen_y, double * screen_z )

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

BOOL PrintExt( long object, String filename, double x, double y,
double width, double height, BOOL portrait, BOOL stretch )

Saves a PostScript image of the specified viewport object into a file. This method is disabled in Secure mode if GLG_ACTIVEX_PRINT_FILE environment variable is not set.

long ReferenceObjectExt( long object )

References the object and returns its object ID.

void ReleaseObjectExt( long object, long suspend_info )

Releases a previously suspended for editing object. The suspend_info parameter is a returned value of a previous call to SuspendObjectExt .

BOOL ReorderElementExt( long container, long old_index, long new_index )

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

void ResetHierarchyExt( long object )

Resets the hierarchy of the object.

BOOL SaveObjectExt( long object, String filename )

Saves object into a file. Returns TRUE if the object was successfully saved. This method is disabled in Secure mode if GLG_ACTIVEX_SAVE_FILE environment variable is not set.

BOOL SetDResourceExt( long object, String resource_name, double dvalue )

BOOL SetDResourceIfExt( long object, String resource_name, double dvalue, BOOL if_changed)

BOOL SetDTagExt( long object, String tag_name, double dvalue, BOOL if_changed)

Sets a new value of a scalar resource or tag. Returns TRUE if the value of the resource or tag was successfully changed.

BOOL SetElementExt( long container, long index, long new_object )

Replaces the element of the container indicated by the index with new_object .

BOOL SetGResourceExt( long object, String resource_name, double dvalue1, dvalue2, dvalue3 )

BOOL SetGResourceIfExt( long object, String resource_name, double dvalue1, dvalue2, dvalue3, BOOL if_changed )

BOOL SetGTagExt( long object, String tag_name, double dvalue1, dvalue2, dvalue3,
BOOL if_changed )

Sets a new value of the G-type resource or tag. Returns TRUE if the value of the resource or tag was successfully changed.

BOOL SetResourceFromObjectExt( long object, String resource_name, long ovalue )

Sets a value of the data or matrix resource object defined by the resource_name to the value of the ovalue object. The resource types should match. Returns TRUE if the value of the resource was successfully changed.

BOOL SetResourceObjectExt( long object, String resource_name, long ovalue )

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

BOOL SetSResourceExt( long object, String resource_name, String svalue )

BOOL SetSResourceIfExt( long object, String resource_name, String svalue, BOOL if_changed )

BOOL SetSTagExt( long object, String tag_name, String svalue, BOOL if_changed )

Sets a new value of a string resource or tag. Returns TRUE if the value of the resource or tag was successfully changed.

BOOL SetSResourceFromDExt( long object, String resource_name, String format, double dvalue )

BOOL SetSResourceFromDIfExt( long object, String resource_name, String format, double dvalue, BOOL if_changed )

BOOL SetSTagFromDExt( long object, String tag_name, String format, double dvalue,
BOOL if_changed )

Sets a new value of a string resource or tag to a string obtained by converting the supplied double value according to the format. The format parameter is a C format string. Returns TRUE if the value of the resource or tag was successfully changed.

void SetStartExt( long container )

Initializes the container for traversing, should be called before using IterateExt method.

BOOL SetViewportExt( long viewport )

Sets the new drawing of the ActiveX control. The setting the drawing by using SetViewportExt method has the highest priority and overrides all other drawing properties.

BOOL SetXformExt( long object, long xform )

Sets the object transformation to a constrained copy of the xform parameter. If the xform parameter is NULL, removes any object transformations. The CloneExt method may be used in conjunction with SetXformExt to add unconstrained copies of a transformation to several objects. Returns True if a transformation was successfully added.

void SetupHierarchyExt( long object )

Sets up the object hierarchy of the object.

long SuspendObjectExt( long object )

Suspends 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 an object ID of the suspend_info object, which is used in a consequent call to the ReleaseObjectExt method.

BOOL UnconstrainObjectExt( long object )

Unconstrains the attribute object. Returns TRUE if the object was successfully unconstrained.

void UpdateExt( long object )

Updates the viewport object to display the latest resource settings.

GLG ActiveX Control Security

The GLG ActiveX Control is normally operates in a Secure mode, which does not allow saving any files on a local file system.

You can allow saving and generating PostScript files by setting GLG_ACTIVEX_SAVE_FILE and GLG_ACTIVEX_PRINT_FILE environment variables described later in this document. This variable define filenames for use to save PostScript output of the ActiveX control's Print method and the output of the Save method.

There also is a NonSecure mode, which may be turned on by setting GLG_ACTIVEX_NON_SECURE_MODE environment variable described below. In NonSecure mode, the ActiveX control is allowed to save and print using arbitrary file names defined by the web-page designer, which makes it possible to overwrite files on a local file system.

GLG ActiveX Control Environment Variables

Several environment variables may be used to modify GLG ActiveX Control's behavior. This is optional and not required for a typical GLG ActiveX Control usage. It is usually used for debugging when new web pages using the GLG ActiveX Control are developed.

On Windows NT, the environment variables may be set in the Systems Control Panel. On Windows 95 the autoexec.bat file may be used to set the variables.

GLG_ACTIVEX_NON_SECURE_MODE

Turns on the NonSecure mode. In NonSecure mode, the file names for printing and saving files are accepted, which may cause overwriting files on a local disk.

GLG_ACTIVEX_SAVE_FILE

Provides a name of a file to be used for the ActiveX Control's Save method. In Secure mode , saving is allowed only if this environment variable is set, in which case the file name parameter of the Save method is ignored and the name defined by GLG_ACTIVEX_SAVE_FILE will be used.

GLG_ACTIVEX_PRINT_FILE

Provides a name of a file to be used for the ActiveX Control's Print methods. In Secure mode, Print methods are enabled only if this variable is set, in which case it provides a name for a PostScript file to be generated.