Any viewport object provides an automatic zooming and panning feature controlled by the viewport's Pan attribute. If panning is enabled, the viewport creates and displays automatically generated scrollbars that allow the drawing to be scrolled when it extends beyond the boundaries of the viewport's visible area. The Pan attribute allows the user to enable X and Y scrollbars independently, to scroll the drawing area in only one direction or in both directions.
If the viewport's ZoomEnabled attribute is set to YES, the viewport object also handles zoom and pan accelerators, such as the ZoomTo key or scrolling the drawing by dragging it with the mouse. Refer to Viewport on page 58 for the complete list of zoom and pan accelerators. If ZoomEnabled is set to NO, the accelerators are disabled, but the integrated zooming and panning is still available for programmatic use. Performing zoom and pan operations on a viewport generates Zoom and Pan events. Refer to Appendix B: Message Object Resources of the GLG Programming Reference Manual for more details.
A special GIS Zoom Mode is supported for zooming and panning a map displayed in the GIS Object instead of zooming and panning the viewport's drawing. In the GIS Zoom Mode, the zoom and pan operations zoom and pan the map displayed in the viewport's GIS object, and integrated scrollbars scroll the map vertically or horizontally. The map can also be dragged with the mouse, which works best with either fast CPUs or not very complex maps. In the Builder, the GIS Zoom Mode may be set by using the Set as parent viewport's GIS Object option in the Arrange menu while the GIS Object is selected. The GIS Zoom Mode is persistent and is saved with the drawing.
When integrated scrollbars are activated, they can be accessed as viewport resources using resource names GlgPanX and GlgPanY. There is also an object named GlgPanSpacer used in the lower right corner of the viewport when both scrollbars are enabled. By default, the colors of the scrollbars are constrained to the color of the viewport. To change them to be different from the viewport's color, unconstrain the FillColor attribute of the viewport, then set the scrollbar's FillColor to a different color value.
By default, the integrated scrollbars use native scrollbars that differ in appearance on different platforms. GLG scrollbars may be used to provide the same look and fill regardless of the platform by setting the GlgNativeScrollbars global configuration resource to 0. The GlgNativeScrollbars global configuration resource is automatically set to 0 for Qt and GTK integrations.
When GlgNativeScrollbars is set to 0, the application may also provide its own custom scrollbars to use as the integrated scrollbars. This is done by setting the GlgVScrollbarRef and GlgHScrollbarRef global configuration resources to the filenames (or URL when used on the web) of the drawings that contain the widgets to be used as the vertical and horizontal scrollbars.
The GIS maps can be embedded into the GLG drawing via an integrated GIS Object. The GIS Object displays a map image in a selected GIS projection and transparently handles all aspects of interaction with the GLG Map Server, automatically issuing map requests every time the map is resized, panned or zoomed.
Starting with the release 3.0, the GIS Object can be used as a container that holds dynamic icons, polylines and other graphical objects that need to be drawn on top of the map. The objects are drawn on the map in the GIS Rendering Mode, in which the coordinates of the objects' control points are interpreted as lat/lon coordinates. This allows positioning of icons and lines on the map by defining their lat/lon coordinates directly, without any coordinate conversions. When the map is zoomed or panned, the objects on the map will be automatically adjusted to stay with the map, with no application support required in the previous releases of the Toolkit.
The Graphics Builder supports the GIS Editing Mode for creating and editing objects to be drawn on top of the map. In this mode, dynamic icons, polylines and other objects can be drawn and positioned on the map with the mouse in the lat/lon coordinates. The Builder automatically converts the mouse position to lat/lon coordinates, which are stored in the object's control points. The Builder transparently handles GIS projections, which allows the user to draw polylines on top of the globe displayed in the ORTHOGRAPHIC projection.
To start the GIS Editing Mode, select the GIS Object, then press the Hierarchy Down button to go down into it. In the GIS Editing Mode, you can draw and position objects on top of the map with the mouse, as well edit attributes of the previously created objects. All objects added to the GIS Object for the GIS rendering will be contained in its GISArray and will be saved with the GIS Object. Dynamic icons and other graphical objects may also be added to the GIS Object programmatically at run time using the GlgAddObject methods. The GLG GIS Demo and GLG AirTraffic Control Demo may be used as source code examples of adding dynamic icons at run-time.
The map displayed in the GIS Object may be zoomed and panned using the integrated zooming and panning features, including integrated scrollbars. The map may also be dragged with the mouse as described in Integrated Zooming and Panning above.
Refer to the GIS Object on page 55 for more information.
The GLG drawing supports integrated object tooltips. If an object or any of its parents have the TooltipString resource defined, the value of this resource is used to display a tooltip when the mouse is moved over the object. The first found TooltipString resource of the object or its nearest parent is used to display the tooltip. For example, if the object is a group, the tooltip will be displayed every time the mouse moves over any object in that group. If the object inside the group has its own tooltip resource, that object's resource value will be used to display the tooltip instead of the group's tooltip resource.
The TooltipString resource is usually attached as a custom property, and the Enterprise edition of the Builder has menu options for adding it. The object's HasResources flag has to be set to YES in order for the TooltipString resource to be visible at the object level.
The viewport's ProcessMouse attribute has to be set to Move & Click to enable tooltip handling. If the viewport's ProcessMouse attribute is set to Move & Click (Named), the object name is used to display the tooltip instead of the value of the object's TooltipString resource. The Run mode may be used to prototype the tooltips in the Builder. The object tooltips will be handled automatically at run time, with no actions required in the program.
The ObjectTooltip custom event is generated every time an object tooltip is activated or erased. Refer to Appendix B: Message Object Resources of the GLG Programming Reference Manual for more details.
The GLG drawing supports object highlighting when the mouse is moved over the object. The object highlight on mouse over may be used to create a "hot spot". Moving the mouse over such hot spots highlights the objects associated with them and, using the custom events described below, sends the message to the program to perform application-defined actions.
To enable MouseOver highlight processing, the viewport's ProcessMouse attribute must be set to Move and Click. If the object or any of its parents have the MouseOverState resource of D type, they are highlighted when the mouse moves over them by setting the resource value to 1. The resource value will be reset to 0 when the mouse moves away from the object. Only the first found MouseOverState resource of the object or its nearest parent is highlighted.
The MouseOverState resource may be connected to any attribute of the object or any of the transformations attached to it. For example, if an object is a polygon and its LineWidth attribute is named MouseOverState, the line width of the polygon will be set to 1 when the mouse moves over it, displaying the polygon's edge. When the mouse moves away from the polygon, the polygon's line width will be reset to 0 and the polygon's edge will disappear.
Consider another example with a list transformation attached to the polygon's LineWidth attribute. If the list contains two elements with values 1 and 3, and the controlling ValueIndex parameter of the list transformation is named MouseOverState, then the polygon's line width changes from 1 to 3 when the mouse moves over the polygon and changes back to 1 when the mouse moves away. Visually, this will create a form of highlighting effect. Various other types of highlighting may be used. For example, the object's color may changed by attaching a color list transformation to the object's color attribute. If more then two attributes needs to be highlighted, they may be constrained to change together.
The MouseOverState resource must be visible at the proper place in the object hierarchy. If the polygon in the previous example has HasResources set to YES, the MouseOverState resource will appear as a resource of the polygon, and the polygon will be highlighted when the mouse moves over it. If the polygon is part of a group and the group's HasResources is set to YES, but the polygon's HasResources is set to NO, the MouseOverState resource will appear as a resource of the group and the polygon will be highlighted every time the mouse moves over any object in the group.
The Run mode may be used to prototype the MouseOver highlight in the Builder. At run time, it will be handled automatically, with no actions required in the program.
An object in the drawing may be setup to provide visual feedback when it is pressed with the mouse button, for example to "depress" an object when the mouse clicks on it. This may be used to imitate custom button behavior or implement custom visual effects. The drawing also supports MouseClick toggle functionality, altering the object's visual appearance every time it is pressed with the mouse button. This may be used to implement a custom toggle.
Object feedback and toggle on mouse click may be used to implement lightweight viewport-less buttons and toggles, which provide a visual feedback and, using custom events feature described in the next section, send a message to the program when the button is pressed. The integrated drawing features allow the custom button and toggle functionality to be implemented without using a viewport-based button objects with an input handler attached to the viewport to handle the visual feedback.
To enable MouseClick feedback processing, the viewport's ProcessMouse attribute must be set to either Click or Move and Click. If the object or any of its parents have a MouseClickState resource of D type, they are highlighted when the mouse is clicked on them by setting the resource value to 1. The resource value will be reset to 0 when the mouse button is released. In the case of MouseClickToggle, the value of the resource is alternated between 0 and 1 every time the mouse clicks on the object. Only the first found MouseClickState or MouseClickToggle resource of the object or its nearest parent is processed.
The MouseClickState resource may be connected to any attribute of the object or any of the transformations attached to it. For example, an object may have a move transformation attached to it with its Factor attribute named MouseClickState. When the object is clicked with the mouse button the value of the transformation's Factor will be set to 1 and the object will move, showing a visual feedback. When the mouse button is released, the Factor will be reset to 0 and the object will move back.
If the Factor attribute of the transformation in the previous example is named MouseClickToggle, the object's position will alternate every time it is clicked with the mouse. You can also name the object's Visibility attribute MouseClickToggle, in which case the object's visibility will alternate every time it is pressed with the mouse. It is easy to imagine many various ways to implement a custom toggle object using this functionality.
The MouseClickState and MouseClickToggle resources must be visible at the proper place in the object hierarchy. If the object in the previous examples has HasResources set to YES, the MouseOverState resource will appear as a resource of the object, and the object will move every time its is clicked on with the mouse. If the object is part of a group and the group's HasResources is set to YES, but the object's HasResources is set to NO, the MouseClickState resource will appear as a resource of the group and the object will move every time the mouse clicks on any object in the group.
The Run mode may be used to prototype the MouseClick feedback and toggle behavior in the Builder. At run time, they will be handled automatically, with no actions required in the program.
The GLG drawing allows custom events, such as MouseClick and MouseOver, to be attached to objects. If the object has any custom events attached, the program's Input callback will receive a message with a custom label defined by the event and other information the program can use to process it.
Custom events are usually attached as a custom properties, and the Enterprise edition of the Builder has menu options for adding them. To attach a mouse click custom event to an object, a custom property of S type named MouseClickEvent is added to the object. To add a custom event on mouse over, an S property named MouseOverEvent is attached. The object's HasResources flag has to be set to YES in order for the MouseOverEvent and MouseClickEvents resources to be visible at the object level.
To enable processing of custom mouse click events, the viewport's ProcessMouse attribute must be set to either Click or Move & Click. The value of Move and Click must be used to enable custom mouse over events.
When a mouse moves over an object at run time, the GLG engine searches the object and all its parents for the MouseOverEvent resource of S type. If the resource is found, the program's Input callback will be invoked with a message containing the custom event label defined by the value of the MouseOverEvent resource. The message will also contain the MouseOver event action, the source object that generated the event and other information that may be used by the program to handle the event.
Only the first found MouseOverEvent resource of the object or its nearest parent is processed. When the mouse is moved away from one object with a custom MouseOver event to another, a custom mouse over event for the second object will be generated. If the mouse moves away from one object with the custom mouse over event but does not move over another object, the Input callback will be invoked with the same message, but its custom event label will be set to an empty string and the source object will be set to NULL.
The MouseClickEvent resource is used in a similar way to process custom mouse click events when an object is clicked on with a mouse button. The message's action will be MouseClick. When the button is released, the program will receive a message with the MouseRelease action, an empty custom event label and a NULL source object.
Refer to the GLG Programming Manual for details on the usage of the Input callback and custom event handling. Refer to Appendix B: Message Object Resources of the GLG Programming Reference Manual for the message object details.
There are several features of the GLG Toolkit that support deploying the drawings in different language locales. The GLG font objects defined in the viewport's font table support various character sets, both single and multi-byte. The font table to be used at run-time may be defined using the FonttableFile attribute described on page 65.
The Unicode is also supported via the UTF-8 version, which, due to its ASCII compatibility, is the version used the most across different platforms and on the web. The unicode support provides a locale-independent way to render text, and also allows to mix characters from different language locales in one text string. To enable this feature in the X Windows environment, the font objects and the text rendering drivers support the use of both the individual fonts as well as the font sets. On Windows, the text strings rendered using unicode are automatically converted to the wide character representation and rendered using the wide characters version of the text rendering functions.
The String Export and Import features provide a way to translate all text strings defined in the drawing into a different language, either at a design time using the Builder or at run-time, using the GLG API functions to import the string translation file.
The String Export feature is used to export all strings defined in the drawing into an ASCII string translation file. The string translation file contains an entry for each exported string and may be edited using a text editor. Each string entry contains the name of a string resource which helps identify how the string is used, and two copies of the string. Each item in the string entry is separated by two separator characters. The name of the string resource and the first copy of the string are used to identify the string and should not be changed.
When the file is translated, the second copy of the string may be replaced with a new string representing the text in the local language and local character set. The String Import feature is then used to load the translated file and replace strings in the drawing with the new translated strings from the string import file.
The strings in the exported translation file are separated with a two-character separator. Two double quotation characters are used as the default separators, but that can be changed by defining the GLG_STRING_SEPARATOR environment variable to supply a two character string to be used as a separator. In the GLG API, separator characters are supplied as function parameters.
The following is an example of the string conversion file using the default "" separator characters:
""GlgStringConverter""2"" # Comment: Translated Strings ""Resource1""String1""Stroka1"" ""Resource2""Label2""Metka2"" ""Resource3""Multi-line Text""Tekst b dve stroki""The first line of the file contains version information and should not be modified. Any characters between the string's terminating separator and the separator at the beginning of the next string are ignored, allowing for comments and blank lines to annotate the string file. A string may extend to several lines, as shown in the last conversion file entry.
If some strings should be not translated, their entries may be left unchanged, or even better, removed from the file. Only the strings defined in the translation file will be replaced.
The File menu of the Graphics Builder contains Export Strings and Import Strings options to export or import strings of the drawing loaded in the Builder. When editing focus is in a viewport, only that viewport's strings are exported or imported, providing a way to export or import strings for only a part of the loaded drawing. After the exported string file has been translated, it can be imported back and the new localized drawing may be saved. This allows the translator to edit the strings in a text file instead of finding all text strings in the drawing.
The drawing conversion utility supports
"-export_strings <filename>"
and
"-import_strings <filename>"
options for exporting and importing the strings in a batch mode.
The GlgExportStrings and GlgImportStrings methods are provided in both C/C++, ActiveX and Java versions of the Toolkit's API. The application may utilize a single drawing and provide translation files for multiple locales to localize the application at run time. The run-time localization is performed by loading an appropriate translation file depending on the system's locale into the drawing using the GlgImportStrings method.
The Java version of GLG API supports Unicode and uses InputStreamReader to read native characters from the strings translation file, decoding the characters using character set defined by the current locale. The ImportStrings method of the GLG Java API has an encode parameter, allowing an application to load string translation files with encoding different from the current locale setting.
It is common in Java environment to use ASCII encoding with \u Unicode escape character for representing non-ASCII characters. Such encoding, however, does not correspond to any system locale, is not supported by InputStreamReader and must be converted to some supported encoding before processing. For example, in Java source code and resource bundles, such conversion is done at the compilation time by the Java compiler, which converts the \u -encoded ASCII to UTF-16 characters in the generated Java byte-code.
For string translation files, an equivalent conversion has to be performed. Java provides a native2ascii utility that can be used to convert from Unicode to ASCII encoding with \u Unicode escape, or vise versa. The following command line shows how to run the utility to convert the ASCII strings.txt file to UTF-8 unicode, which can be used with any UTF-8 locale:
native2ascii -reverse -encoding UTF8 strings.txt strings2.txtThe converted strings2.txt file may then be used with the Java program. To convert from Unicode back to ASCII with \u encoding, run the native2ascii utility without the - reverse option.
All objects and object attributes are inherently dynamic and may be accessed and changed at run-time by using the API's SetResource methods. Not only the properties such as colors or line width, but also resources that define rotation angles, move distances, scale factors, thresholds and many others may be set from a program via programming API by specifying the resource name and a new value, as shown in the following example:
GlgSetDResource( drawing, "Meter1/Value", 25. ); GlgSetSResource( drawing, "Meter1/Label", "MPH" ); GlgSetDResource( drawing, "Group1/Polygon1/LineWidth", 3. ); GlgSetDResource( drawing, "Group1/Polygon2/RotateAngle", 30. ); GlgUpdate( drawing );The GlgUpdate method is invoked at the end to update and render the drawing with the new resource values.
The Toolkit's resource-based access to data provides a unified and compact programming API which is ideally suited for applications that need an access to all objects defined in the drawing and complete control over the objects' attributes.
Tags provide an alternative way to access dynamic attributes defined in the drawing. A tag may be attached to an attribute object to define data connectivity or store user-defined information associated with the attribute. The tag's TagSource attribute provides a way to map resources of the drawing to database fields, which is commonly used for data connectivity in process control applications.
While the resources are hierarchical and require the application to know the exact resource path of each resource, the tags are global and are accessed in an application as a flat list. This enables the application to query and use the tags defined in the drawing without the need to know the exact structure of the drawing.
The tags may be assigned to attribute objects in the Builder. The Builder also provides a Tag Browser for browsing and editing tags defined in the drawing. With the Tag Browser, a user can edit each tag by assigning a database field to its TagSource. A custom Data Browser may be integrated with the Builder to allow the user to browse and select a TagSource from a list of available database tags. The TagName and TagComment attributes of the tag object help the user identify the tag in the Tag Browser or attach custom information to the attributes.
At run-time, an application may use tags as global resources. Attaching tags to important resources of the drawing allows the user to easily browse them in the Builder. By assigning meaningful names to the TagSource attributes, the application can access the resources by their associated TagSource as shown in the following example:
GlgSetDTag( drawing, "PressureMeterValue", 25. ); GlgSetDTag( drawing, "PressureAlarmState", 0 );Here the tags are used in virtually the same way as resources, with the TagSource being handled as a global resource name. Unlike resources, TagSources do not have to be unique. If several tags in the drawing have the same TagSource, invoking GlgSetTag with this TagSource will set values of all the tags. This may be interpreted as a programmatic way of handling constrained values without actually constraining objects in the drawing. The application may also easily query all tags defined in the drawing using the GlgCreateTagList method.
Tags may also be used in a more sophisticated way to store database connectivity information in the drawing by attaching a tag to each resource in the drawing that needs to be updated from a database. The tag's TagName attribute is set to a logical name that helps to identify the tag while browsing, and the TagSource is set to the name of the database field that will provide the data for the resource the tag is attached to. A user can browse all tags defined in the drawing and edit their database data sources by changing the tags` TagSource attributes. The Tag Export and Tag Import features described in the next section may also be used for editing or remapping all tags in the drawing, either at design time in the Builder or at run-time in an application.
At run-time, a process-control application may load the drawing, query the list of tags defined in the drawing with the GlgCreateTagList method and subscribe for updates for the process database fields defined by the tags' TagSource attributes. When data changes, the application may set the new data values by invoking the GlgSetTag method, passing the TagSource and the new data value for each tag as shown in the source code of Tags Example, which is provided for both C/C++. Java and C# versions of the Toolkit.
All tags defined in the drawing may be exported into an ASCII tag file for editing them via a batch script or a text editor. The modified tag file may then be imported back into the drawing, importing the modified TagName and TagSource attributes.
The tag export and import features provide a way to modify the tags defined in the drawing to map them to the database fields of a specific process database. It may be done either at design time using the Builder, or at run-time using the GLG API functions to import the tag file.
The tag export feature exports all tags defined in the drawing into a tag file. Each tag entry contains two copies of the tag's TagName and TagSource attributes separated by two separator characters. The first copy of the TagName and TagSource attributes is used to identify the tag and should not be changed. The second copy of the attributes may be changed to modify the tag. The new value of the TagSource attribute supplies the database field associated with the tag. The TagName attribute may be changed to modify the tag name in the drawing.
The import feature is then used to load the translated file and replace tags in the drawing with the new tags from the tag import file.
The strings in the exported tag file are separated with a two-character separator. Two double quotation characters are used as the default separators, but that can be changed by defining the GLG_STRING_SEPARATOR environment variable to supply a two character string to be used as a separator. In the GLG API, separator characters are supplied as function parameters.
The following is an example of the tag conversion file using the default "" separator characters:
""GlgTagConverter""2"" # Comment: Converted Tags ""AlarmState""undefined""""AlarmState""Plant3:Tank2:Alarm"" ""Pressure""undefined""""Pressure""Plant3:Tank2:Pressure""The first line of the file contains version information and should not be modified. Any characters between the string's terminating separator and the separator at the beginning of the next string are ignored, allowing for comments and blank lines to annotate the tag file. The example assigns new values to the TagSource attributes of two tags with the AlarmState and Pressure tag names, changing their tag sources from the "undefined" string to "Plant3:Tank2:Alarm" and "Plant3:Tank2:Pressure" respectively. The tags' TagName attributes remain unchanged.
If some tags should be not translated, their entries may be left unchanged, or even better, removed from the file. Only the tags defined in the translation file will be replaced.
The File menu of the Graphics Builder contains Export Tags and Import Tags options to export or import all tags defined in the drawing. When editing focus is inside a viewport, only that viewport's tags are exported or imported, providing a way to export or import tags for only a part of the loaded drawing. After the file has been modified, it can be imported back and the new drawing may be saved.
The drawing conversion utility gconvert supports
"-export_tags <filename>"
and
"-import_tags <filename>"
options for exporting and importing the tags in batch mode.
The GlgExportTags and GlgImportTags methods are provided in both C/C++, ActiveX and Java versions of the Toolkit's API. The GlgImportTags method may be used to load database connectivity information from an external tag file at run-time. An application may utilize the same drawing with different databases, using the tag file to map the tags in the drawing to the database fields.
The GlgCreateTagList API method may be used in an application to query all tags defined in the drawing and obtain database mapping from the tag's TagSource attribute, as shown in the Tags Example source code.
Custom Properties may be attached to any graphical object to store application-specific data related to the object. The custom properties are attached using the Add Custom Property button of the Object Menu and are saved with the drawing. The object's custom properties can be retrieved in a program as object's resources, using their resource names.