Any viewport object provides an automatic zooming and panning feature controlled by the viewport's Pan attribute. If Pan is set to YES, 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.
If the viewport's ZoomEnabled attribute is set to YES, the viewport object also handles zoom and pan accelerators. Refer to Viewport on page 56 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.
When automatic scrollbars are active, they can be accessed as resources of the viewport named GlgPanX and GlgPanY. There also is an additional object named GlgPanSpacer used in the lower right corner of the viewport. By default, the colors of the scrollbars are constrained to the color of viewport. To change them to be different from the viewport's color, unconstrain the FillColor attribute of each scrollbar and set it to a different color value.
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.
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 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 the string translation file, containing an entry for each exported string. Each entry contains two copies of the string separated by two separator characters. When the file is translated, the second copy of the string is replaced with a new string representing the text in the local language and local character set. The import feature is then used to load the translated file and replace strings in the drawing with the new translated version from the 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""1 "" // Comment: Translated Strings ""String1""Stroka1"" ""Label2""Metka2"" ""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 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 multiple translation files to localize the application at run time 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.