PREV NEXT

Generic Logic, Inc. www.genlogic.com


3 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 GLG ActiveX Control is implemented as a dynamic link library with the .OCX extension. When registered and loaded, this single .ocx file may be used to display an extensive set of GLG widgets and custom drawings that can be accessed by users and applications. There are several versions of the GLG ActiveX control in the commercial version of the Toolkit:

glg_std.ocx - includes GLG Standard API
glg_int.ocx - includes GLG Intermediate API
glg_ext.ocx - includes GLG Extended API

The demo and Community Edition of the GLG Toolkit contains a single glg.ocx that combines all three GLG APIs.

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 generates custom Input, Select, Alarm and other events. These events provide user feedback, allowing an application to react to user input or determine which graphical objects were selected with the mouse.

The ActiveX Control's API methods mimic the methods of the GLG API. This chapter describes specific details of using the GLG ActiveX Control and provides only a brief description of each API method; refer to Animating a GLG Drawing with Data Using the Standard API on page 63 for a detailed description of each method's functionality. Refer to Handling User Input and Other Events on page 103 for details of the Input callback. Refer to GLG Intermediate and Extended API on page 121 for details of the Extended API methods.

The examples_csharp and examples_vbnet directories contain source code examples of using the GLG ActiveX Control in the respective programming environments.

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 The Data Generation Utility section 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 The Data Generation Utility section 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.

AlarmsEnabled

Controls whether alarm events are generated (default: FALSE). Alarm events are generated by alarm objects attached to dynamic attributes to monitor their values when the values go out of range.

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.

UseOpenGL

Controls the use of the OpenGL driver (default: FALSE). When set to TRUE, the OpenGL driver is enabled for the viewports that have the OpenGLHint=ON. When set to FALSE, the OpenGL driver is disabled and the GDI driver is used for all viewports.

UseMapURL

Controls the usage mode of the map server (default: FALSE). When set to FALSE, the maps are rendered using local datasets defined by the GISDataFile property of the GIS Object. When set to TRUE, a web-based map server defined by the GISMapServerURL property of the GIS Object is used to render maps from a centralized web server, without installing map datasets on each client computer.

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 the H and V Resources section in Integrating GLG Drawings into a Program. The syntax for the character strings is described in the Dynamic Resource String Syntax section 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 the H and V Resources section in Integrating GLG Drawings into a Program. The syntax for the character strings is described in the Dynamic Resource String Syntax section 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:

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. Refer to Appendix B: Message Object Resources on page 439 for more information.

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.

The Input2 event provides a more elaborate alternative for handling object selection using either object IDs or custom events and command actions attached to objects in the Graphics Builder.

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. By default, trace events are activated for the top level viewport of the ActiveX control. The SetTraceViewport method may be used to activate trace events only for a child viewport of the control.

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

Alarm( long object, long alarm, String alarm_label, String action, String subaction, long reserved )

Generated by alarm objects based on the specified alarm condition. The object parameter is the resource whose value has changed. The alarm 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 the 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 of the GLG User's Guide and Builder Reference Manual for more information.

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 GLG ActiveX Control provides the following methods:

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

Return 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_source, double dvalue, BOOL if_changed )

Set 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_source )

Return 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 )

Set 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 resource_name, String format, double dvalue )

Set 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.
void GetGResource( String resource_name, double * x, double * y, double * z )
void GetGTag( String tag_source, double * x, double * y, double * z )

Query the value of the drawing's geometrical resource or tag and return it via the x, y and z parameters.

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

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_source, double dvalue1, double dvalue2, double dvalue3,
BOOL if_changed )

Set the value of the drawing's geometric resource or tag. For tags, all tags with the specified tag_source will be set to the supplied values. 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 )

Returns TRUE if a named resource object exists, returns FALSE otherwise.

BOOL HasTagName( long object, String tag_name )
BOOL HasTagSource( long object, String tag_source )

Return TRUE if a tag with a specified tag name or tag source 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 UpdateGlg()

Forces GLG ActiveX Control to update the displayed drawing to reflect the new data. 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 setting some resources may interfere with setting other resources, and that it may be necessary to invoke either the UpdateGlg or SetupHierarchy methods 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 UpdateGlg method, and then query the series members.

void Update()           (deprecated)
Same as the UpdateGlg method, deprecated due to a conflict with the .NET environment, where the Update method of the GLG ActiveX Control is shadowed by the object's Update method of the .NET framework. Use the UpdateGlg method instead.
BOOL SetAutoUpdateOnInput( BOOL 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. 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 UpdateGlg() for timer events (Format="Timer") to update objects in the drawing with the timer transformation attached.

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

Performs a zoom or pan operation specified by the type parameter. If the resource_name parameter is null, the viewport or the light viewport specified by the viewport parameter will be zoomed. Otherwise, the zoom operation will be performed on its child viewport specified by the resource_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 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.

BOOL SetZoomMode( long viewport, String resource_name, long 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 Drawing Zoom Mode (default), 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.

BOOL GISGetElevation( long object, String resource_name, String layer_name,
double lon, double lat, double * elevation )

Returns elevation of a lat/lon point on a map. If the resource_name parameter is null, the object parameter specifies the GIS object, otherwise it specifies the GIS object's parent and resource_name specifies the resource path of the GIS Object relative to the parent. The layer_name specifies the name of the elevation layer to query. The elevation value is returned via the elevation parameter. The method returns TRUE if the query was successful.

long GISCreateSelection( long object, String resource_name, String layers, double x, double y,
int select_labels )

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 object parameter specifies the GIS object, otherwise object specifies the GIS object's parent and resource_name specifies the resource path of the GIS Object relative to the parent. 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 function 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 demonstrates how to handle it.

long GISGetDataset( long object, String resource_name )

Returns a dataset object associated with the GIS object. If the resource_name parameter is null, the object parameter specifies the GIS object, otherwise it specifies the GIS object's parent and resource_name specifies the resource path of the GIS Object relative to the parent. The method may be invoked after the GIS object has been setup to retrieve its dataset. The dataset may be used to dynamically change attributes of individual layers displayed in the GIS object. The program can use SetResource methods for changing layer attributes. Refer to the GLG Map Server Reference Manual for information on layer attributes.

BOOL GISConvert( long object, String resource_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 resource_name parameter is null, object specifies the GIS Object whose coordinate system to use for conversion. If the resource_name parameter is not null, object specifies a parent of the GIS Object. The resource_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 GLG_GIS_OUTSIDE_VALUE value for points on the invisible part of the globe.

long SendMessage( String resource_name, String message, long param1, long param2, long param3,
long 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.

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.

long SendMessageStr( String resource_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 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.

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

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

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

long ImportTags( long object, String filename )

Replaces tag names and tag sources of tags in the drawing defined by the object parameter with information loaded from a tag translation file. 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 function returns the number of imported tags 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 resource_name, String filename, long format )

Saves a JPEG or PNG 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. Both the JPEG (format=2) and PNG (format=4) image formats are supported. 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.

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

Saves a JPEG or PNG 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. Both the JPEG (format=2) and PNG (format=4) image formats are supported. 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 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.

long GenerateImage( long object, String resource_name, long bitmap )

Same as the SaveImage method, but returns the image as a bitmap. If the bitmap parameter is not NULL, fills and returns the bitmap provided by the parameter instead of creating and returning a new bitmap.

long GenerateImageCustom( long object, String resource_name, long bitmap, long format, long x, long y, long width, long height, long gap )

Same as the SaveImageCustom method, but returns the image as a bitmap. If the bitmap parameter is not NULL, fills and returns the bitmap provided by the parameter instead of creating and returning a new bitmap.

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.

BOOL GetModifierState( int modifier )

Returns the state of the modifier requested by the modifier parameter. Use 1 to query the state of the Shift key, 2 for the Control key and 3 for a double click: these values correspond to the elements of the GlgModifierType enum defined in the GlgApi.h file.

long CreateSelectionNamesExt( long top_vp, long selected_vp,
double x1, double y1, double x2, double y2 )

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 in the Trace event handler 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.

long CreateSelectionMessage( long top_vp, long selected_vp,
double x1, double y1, double x2, double y2, long selection_type, long button )

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: GLG_MOVE_SELECTION, GLG_CLICK_SELECTION or GLG_TOOLTIP_SELECTION defined in the GlgAPI.h file.

void ChangeObject( long object, String resource_name )

Sends a change message 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 argument. Otherwise, the message will be sent to its child object specified by the resource_name parameter.

void SetBrowserObject( long browser, long object )

Sets the object for browsing with the GLG resource, tag or alarm browser widgets.

void SetBrowserSelection( long 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. Setting a new selection will display a new list of matching entries.

If the resource_name parameter is null, a new selection will be set for the browser supplied by the object argument. Otherwise, it will be set for its child object specified by the resource_name parameter.

BOOL SetEditMode( long viewport, String resource_name, BOOL edit_mode )

Sets the viewport's edit mode which disables input objects in the viewport while the drawing is being 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. If the viewport parameter is null, the viewport of the ActiveX control's drawing is used. 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 the edit mode of the previous viewport. The viewport's edit mode is inherited by its all child viewports. Returns TRUE on success.

void SetTraceViewport( long viewport, String resource_name )

Specifies the viewport for which the trace events will be activated. If the resource_name parameter is null, the trace events will be activated for the viewport itself. Otherwise, trace events will be activated for the child viewport specified by the resource_name parameter. If the viewport parameter is null, the viewport of the ActiveX control's drawing is used. The trace events will be generated only if the control's TraceEnabled property is set.

void SetFocus( long object, String resource_name )

Sets keyboard focus to the parent viewport of an object, or to the object itself if it is a viewport. If resource_name is null, the object is specified by the object parameter. If resource_name is not null, it specifies the child object of the object that will be used for setting focus.

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 .NET environment.

void FreeStringID( long string_id )

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

BOOL SetCursor( long viewport, long cursor_type )

Sets the Windows cursor type to be used by the viewport. If the viewport parameter is null, the cursor of the main viewport of the ActiveX Control is used. The cursor_type parameter specifies one of the predefined Windows cursor types. Returns TRUE on success.

void GlgGetMajorVersion()
void GlgGetMinorVersion()

Return major and minor version numbers of the GLG Toolkit.

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

long GetNamedPlot( long object, String resource_name. String plot_name )

Finds a chart's plot by name and returns its object ID. If the resource_name parameter is null, a named plot of the chart specified by the object parameter is returned. Otherwise, the resource_name parameter points to a child chart of the object. The method returns 0 if a plot with the specified name has not been found.

long AddPlot( long object, String resource_name, long plot )

Adds a plot to a chart object. If the resource_name parameter is null, the plot is added to the chart specified by the object parameter. Otherwise, the plot is added to a child chart of the object pointed to by the resource_name parameter. The plot parameter specifies the object ID of the plot object to add; 0 can be used to create a new plot. The method returns the object ID of the added plot on success, or 0 on failure.

BOOL DeletePlot( long object, String resource_name, long plot )

Deletes a plot from a chart object. If the resource_name parameter is null, the plot is deleted from the chart specified by the object parameter. Otherwise, the plot is deleted from a child chart of the 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.

long AddTimeLine( long object, String resource_name, long time_line, double time_stamp )

Adds a time line to a chart object. If the resource_name parameter is null, the time line is added to the chart specified by the object parameter. Otherwise, the time line is added to a child chart of the object pointed to by the resource_name parameter. The time line parameter specifies the level line object to be used as a time line; 0 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 0 on failure. The returned time line is referenced only by the chart's time line array it has been added to and may be destroyed when the chart scrolls. The program should increase the time line's reference count if it needs to keep a persistent reference to the time line. The NumTimeLines attribute of the chart should be set to -1 in order to use this function.

BOOL DeleteTimeLine( long object, String resource_name, long 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 the chart specified by the object parameter. Otherwise, the time line is deleted from a child chart of the 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 0, the time line with the time stamp specified by the time_stamp attribute will be deleted. If time_line is not 0, 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 function.

long AddAnnotation( long object, String resource_name, long annotation, double position_x,
double position_y, BOOL add_box )

Adds an annotation to a chart object. If the resource_name parameter is null, the annotation is added to the chart specified by the object parameter. Otherwise, the annotation is added to a child chart of the object pointed to by the resource_name parameter. The annotation parameter specifies the annotation object to be added; 0 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 0 on failure. The NumAnnotations attribute of the chart should be set to -1 in order to use this function.

BOOL DeleteAnnotation( long object, String resource_name, long 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 the chart specified by the object parameter. Otherwise, the annotation is deleted from a child chart of the object pointed to by the resource_name parameter. The annotation parameter specifies the annotation object to delete. If annotation is set to 0, the annotation at the position specified by the position_x and position_y attributes will be deleted. If annotation is not 0, 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 function.

BOOL ClearDataBuffer( long object, String resource_name )

Clears accumulated data samples of a real-time chart or one of its plots. If resource_name is null, the object parameter supplies an object ID of the chart or plot object. If resource_name is not null, it supplies a resource name of a child chart or plot object inside the parent object specified by the object parameter. 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.

BOOL GetChartDataExtent( long object, String resource_name, double * min, double * max,
BOOL 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 method returns the data extent of the chart or the plot specified by the object parameter. Otherwise, the resource_name parameter points to a child chart or a child plot of the object. If x_extent is TRUE, the X extent of the data is returned in min and max parameters, 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 function to succeed. The method returns TRUE on success.

BOOL SetLinkedAxis( long object, String resource_name, long 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 the object, otherwise associates a child plot or a child level line of the 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.

long GetNativeComponent( long object, String resource_name, short type )

Returns an ID of a native windowing system component used to render the viewport. If resource_name is null, a native component of the viewport specified by the object parameter is returned, otherwise a native component of a child viewport of the object pointed by the resource_name parameter is returned. The type parameter defines the type of the native component to query, as described on page 76. The value of zero may be used to retrieve the handle of a viewport's window.

String GetObjectName( long object )
String GetObjectType( long object )
String GetDataType( long object )

Convenience functions for querying Name and Type properties of an object, as well as a DataType property of data and attribute objects.

Additional Standard API Methods

The GetElementExt and GetSizeExt methods described in the Intermediate and Extended API Methods section are also available in the Standard API.

Intermediate and Extended API Methods

The GLG Extended API provides methods that allows an application program to add objects on the fly or edit the drawing at run time, as well as query objects and resources contained in the drawing. This may be used to create sophisticated applications using C# or VB.NET.

The ActiveX Control provides two flavors of the Extended API: Intermediate API and Extended API. The Intermediate API provides all Extended API methods except methods for creating and deleting objects at run time.

The ActiveX Control's Extended API methods mimic the methods of the GLG Extended API. This chapter provides only a brief description of each method; refer to GLG Intermediate and Extended API on page 121 for a detailed description of each method's functionality.

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 null 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:

long AddAttachmentPointExt( long 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.

BOOL AddObjectToTopExt( long container, long object )

Adds the object to the beginning of the container (Extended API only). Returns true if the object was successfully added.

BOOL AddObjectToBottomExt( long container, long object )

Adds the object to the end of container (Extended API only). Returns true if the object was successfully added.

BOOL AddObjectAtExt( long container, long index )

Adds the object to the container at the index position (Extended API only). 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) (Extended API only). 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 (Extended API only).

BOOL ConstrainObjectExt( long from_object, long to_object )

Constrains an attribute object.

long ConvertViewportType( long 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.

long CopyObjectExt( long object )

Creates and returns a copy of the object (Extended API only).

long CreateChartSelectionExt( long chart, long plot, double x, double y, BOOL screen_coord,
            BOOL include_invalid, BOOL x_priority )

ADVANCED: 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 GLG_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. The returned message object must be dereferenced using the DropObject method when finished.

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 (Extended API only). The object has to be explicitly added to the drawing in order to be displayed.

long CreatePointArrayExt( long object, long type )
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).
long CreateSelectionExt( long top_vp, long selected_vp, double x1, double y1, double x2, double y2 )

ADVANCED: Given the top viewport of the drawing and a screen coordinates rectangle in a selected viewport, returns an array of all objects within the rectangle. This method may be used in the Trace event handler 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.

String CreateTooltipStringExt( long object, double x, double y, double dx, double dy,
                      String format )

ADVANCED: 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 the 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 selected criteria were found.

If the object is an axis, or if the object is a chart and the selected position is on top of one of the chart's axes, the function returns a tooltip string that displays the axis value corresponding to the specified position.

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

The returned string must be freed using the FreeStringID function.

BOOL DeleteObjectAtExt( long container, long index )

Deletes the object of the container at the index position (Extended API only). Returns false if index is invalid.

BOOL DeleteBottomObjectExt( long container )

Deletes the first object of this container (Extended API only). Returns true if the object was successfully deleted.

BOOL DeleteTopObjectExt( long container )

Deletes the first object of this container (Extended API only). Returns true if the object was successfully deleted.

BOOL DeleteThisObjectExt( long container, long object )

Deletes an object from container (Extended API only). 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 (Extended API only).

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 FindMatchingObjectsExt( long object, long match_type, BOOL find_parents,
            BOOL find_first_match, BOOL search_inside,
            BOOL search_drawable_only, long object_type,
            LPCTSTR object_name, LPCTSTR resource_name, long object_id )

Finds either one or all parents or children of the specified object that match the supplied criteria (Extended API only).

The match_type parameter specifies a bitwise mask of the object matching criteria using the following constants defined in the GlgApi.h file:

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

If find_parents 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. If find_first_match 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.

If search_inside is set to false, the object's children or parents are not searched if the object itself matches. If search_drawable_only is set to true when searching descendents, 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 IsDrawableExt method on page 270 for more information.

If find_first_match is set to true, the method returns the first found matching object. If find_first_match is set to false, a group containing all matching objects is returned. If no matching objects were found, 0 is returned.

double GetDResourceExt( long object, String resource_name )
double GetDTagExt( long object, String tag_source )

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

String GetSResourceExt( long object, String resource_name )
String GetSTagExt( long object, String tag_source )

Return the value of a string resource or tag.

double GetGResourceExt( long object, String resource_name, double * x, double * y, double * z )
double GetGTagExt( long object, String tag_source, double * x, double * y, double * z )

Query the value of the drawing's geometrical resource or tag and return it via the x, y and z parameters.

double GetXResourceExt( long object, String resource_name )
double GetXTagExt( long object, String tag_source )
double GetYResourceExt( long object, String resource_name )
double GetYTagExt( long object, String tag_source )
double GetZResourceExt( long object, String resource_name )
double GetZTagExt( long object, String tag_source )

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

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 GetLegendSelectionExt( 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.

long GetNamedObjectExt( long container, String name )

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

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 GetParentViewportExt( long object, BOOL heavy_weight )

Returns the parent viewport of a drawable GLG object specified by the object parameter. 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.

long GetResourceObjectExt( long object, String resource_name )

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

long GetTagObjectExt( long object, String search_string, BOOL by_name, BOOL unique_tags,
BOOL 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 function returns an object ID of the first attribute that has a tag matching the search criteria. In the multiple tag mode, it returns an object ID of a group containing all attributes with matching tags. The returned list must be dereferenced using DropObject when it is no longer needed.

long GetAlarmObjectExt( long object, String search_string, BOOL single_alarm, long reserved )

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. The reserved parameter is reserved for future use and must be set to 0.

In a single alarm mode, the function returns an object ID of the first alarm that has an alarm label matching the search criteria. In the multiple alarm mode, it returns an object ID of a group containing all alarms with matching alarm labels. The returned list must be dereferenced using DropObject when it is no longer needed.

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")

BOOL IsDemoExt( void )

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

BOOL IsDrawableExt( long object )

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.

void InverseExt( long container )

Inverses the order of components inside the container.

BOOL IsAtExt( long container, long position)

Checks the position of the iteration pointer (the current element of the container).

long IterateExt( long container )
long IterateBackExt( long container )

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

The SetStartExt method must be used to initialize the container for iterating before IterateExt is invoked the first time, and SetEndExt must be used to initialize the container for backward iteration with IterateBackExt. 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 CloneObjectExt 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, GetElementExt can be used to traverse elements of the container using an element index, which is not affected by the search operations on 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, BOOL keep_ratio )

Fits the object to the specified area.

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

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

BOOL ScreenToWorldExt( long object, 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 world coordinate system of the object.

If 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 (object) viewport. If inside_vp=FALSE, the method will use the world coordinate system used to draw this object 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 GLG_COORD_MAPPING_ADJ to the cursor's x and y screen coordinates for precise mapping.

BOOL WorldToScreenExt( long object, 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 object's world coordinate system to the screen coordinate system.

If 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 (object) viewport. If inside_vp=FALSE, the method will use the world coordinate system used to draw this object viewport inside its parent viewport. The value of this parameter is ignored for objects other than a viewport or light viewport.

void TranslatePointOriginExt( long from_viewport, long to_viewport,
double * x, double * y, double * z )

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 x, y and z parameters specify the input values and return the output value.

BOOL RootToScreenCoordExt( long viewport, double * x, double * y )

converts screen coordinates relative to the root window to the screen coordinates in the specified viewport. The x and y parameters specify the input values and return the output value.

BOOL PositionToValueExt( long object, String resource_name, double x, double y,
         BOOL outside_x, BOOL outside_y, double * value )

Returns a value corresponding to the specified x, y position on top of a chart or an axis object. 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 FALSE if the specified position is outside of the chart or the axis in the corresponding direction.

For a plot, the function converts the specified position to a Y value in the Low/High range of the plot and returns the value through the value pointer.

For an axis, the function converts the specified position to the axis value and returns the value.

For a chart, the function 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 GLG_COORD_MAPPING_ADJ to the cursor's x and y coordinates for precise mapping.

The function returns TRUE on success.

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. If object is a light viewport, the output will be generated for its parent viewport.

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_source, double dvalue, BOOL if_changed)

Set a new value of a 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.

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

Replaces the element of the container indicated by the index with new_object (Extended API only).

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_source, double dvalue1, dvalue2, dvalue3,
BOOL if_changed )

Set 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 (Extended API only). 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_source, String svalue, BOOL if_changed )

Set a new value of a string 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.

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_source, String format, double dvalue,
BOOL if_changed )

Set 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 )
void SetEndExt( long container )

Initializes the container for the forward or backward traversing, should be called before using IterateExt and IterateBackExt methods.

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 (Extended API only). If the xform parameter is null, removes any object transformations. The CloneObjectExt 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 without repainting 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. If object is a light viewport, update of its parent viewport will be performed.

BOOL TraceObjectExt( long object, BOOL state, BOOL is_widget, long top_parent )

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 or top_parent) 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-zero, the parent objects that are direct children of top_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 function 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.

BOOL SetAttachmentMoveModeExt( BOOL 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.
BOOL EnableAttachmentPointsExt( BOOL 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.

BOOL DeleteTags( long object, long tag_type_mask )

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 (GLG_DATA_TAG), public properties (GLG_EXPORT_TAG) or both.

GLG ActiveX Control Security

By default, the GLG ActiveX Control is allowed to save files on a local file system. The GLG_ACTIVEX_SECURE_MODE environment variable may be set to True to activate a Secure mode, which prevents the control from saving files.

In the secure mode, a user can enable saving files to a file system using predefined filenames by setting the GLG_ACTIVEX_SAVE_FILE, GLG_ACTIVEX_IMAGE_FILE and GLG_ACTIVEX_PRINT_FILE environment variables described later in this document. This variable define filenames used for saving drawings, images and the PostScript files.

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.

The environment variables may be set using the system's Control Panel.

GLG_ACTIVEX_SECURE_MODE

Turns on the Secure mode, which prohibits the ActiveX control from saving arbitrary files in the file system.

GLG_ACTIVEX_SAVE_FILE

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

GLG_ACTIVEX_IMAGE_FILE

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

GLG_ACTIVEX_PRINT_FILE

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


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