Widgets such as Sliders, Knobs, Buttons and others that are capable of reacting to input events are called input widgets. These can allow a user to control a GLG drawing, either directly, through constrained drawing attributes, or indirectly, through a user application. The ability to build custom input widgets is a necessary attribute for creating an open interactive graphical environment.
The GLG Toolkit offers two options for creating input widgets:
You can use GLG graphical objects to render the widget.
You can use the WidgetType attribute of a viewport's screen object to select one of the available native widget types (button, slider, etc.) to render the widget. "Native" refers to the windowing environment in which GLG is running: Windows, X Windows/Motif, or Java. For example, a native button will appear as a Windows button if the drawing is displayed in C/C++ or ActiveX on Windows, as a Motif button if the drawing is displayed in C/C++ in X/Motif environment, or as a AWT or Swing button if the drawing is displayed in Java.
In both cases, the Handler attribute of a viewport object has to be used to specify a GLG input handler , which accepts user input, changing the widget's resources and visual appearance accordingly. For example, a slider widget reacts to mouse events by moving the graphical element that indicates its current position and updating the slider's Value resource. The handler also generates messages passed to the application's input callback, allowing the program to react to the input events.
Some input widgets, such as a toggle or slider, keep value or state information and change corresponding resources of the widget's drawing, making it possible to constrain other elements of the drawing to the resources of the input widget. For example, the Visibility attribute of an object in the drawing may be constrained to the OnState resource of the toggle button. The toggle's handler will change the value of the toggle's OnState resource each time it is clicked on with the mouse, changing the visibility of the constrained object in the drawing.
Each time the toggle changes its state, the toggle widget's handler also generates a ValueChanged message. At run time, the application's input callback is invoked to receive the message and provide additional application-specific handling of the vent.
Other input widgets, such as a push button, don't keep any state information or resources that may be used to control other objects in the drawing. These widgets rely on the input callback to handle user interaction with the widget.
A variety of input handlers are available. The handlers are attached to a viewport, where they look for a specific set of resources to control. For example, the GlgKnob handler controls a resource called Value (among others). When the handler is attached, the handler looks for a resource with that name. When the drawing is run, mouse movements in the viewport will be interpreted by the knob handler and translated into values of the Value resource.
The behavior of an input handler may be modified by defining certain resource names it recognizes. For example, the GlgButton handler searches for the resource named OnState. If it finds this resource, the handler implements a toggle, otherwise it implements a push button.
The resources controlled by an input handler must be visible at the top level of the widget viewport. Alias objects may be used to make resources defined inside the hierarchy to be visible at the top level. If handler resources were changed in the Builder, the widget's drawing has to be reset to allow the handler to update resource information.
The handler's resources appear not only in the widget viewport, but also in the message object returned by the handler to an input callback function. In addition, several of the input handlers define special resources that only appear in the message object. These resources are described with the description of each message object in Callback Events of the GLG Programming Manual.
The handlers available are as follows:
A native slider handler that takes advantage of local window system graphical representations.
A native text handler that takes advantage of native text input widget. Works with both single and multi-line text edit controls.
A native list handler that handles native list widget in a cross-platform way. Works with both single and multiple selection list controls.
A native option menu handler that works with the native option menu and combo box controls.
Triggers periodic updates with a specified rate. May be used to attach various blinking action to objects. It is superseded by more flexible Timer transformation in the release 2.8 of GLG.
To make the widget sensitive to the input events, an input handler is attached to the widget internally. The input handler is a block of code that has input resources and output resources generated from those inputs. The handler reacts to the incoming events, changes the widget's appearance and calls the input callback when some event is translated into a change in the widget's state. For example, a slider widget reacts to mouse events by moving the graphical element that indicates its current position and changing the slider's Value resource.
An input handler is attached to a viewport with the viewport's Handler attribute. This attribute is a character string identifying which of the handlers is to be used. To use the handler, you must also set the viewport's HandlerDisabled attribute to NO.
To use a handler, you must not only set the appropriate attributes, you must equip the viewport with the resources it needs to operate. A knob widget, for example, must have a Value resource controlling some aspect of the drawing in such a way that changing the resource value in the range from 0 to 1 rotates the knob from the preferred minimum to maximum angle. You may also create any other optional resources the handler needs, such as Stateless or Granularity . These resources may be added to the widget's viewport as custom properties, using the Object, Add Custom Property menu in the Enterprise Edition of the Builder. In the Basic and Professional Editions, named resources in the drawing may be used.
An example will illustrate a handler's use. Here are the steps to follow to create a one-dimensional slider:
Create a drawing with a viewport, and an object in the viewport that is to be the indicator of the slider motion. This can be any shape or group of shapes. We will call this object the active element.
Assign a move transformation to the active element. Name the Factor attribute of the transformation "ValueX" and make sure that this attribute is visible at the top level of the viewport. (Set the viewport HasResources flag to YES and the active element's HasResources flag to NO. Alternatively, an alias object named "ValueX" may be added to the viewport to specify the full path to the ValueX resource.) Edit the move distance and the initial position of the active element to make sure that the values of Factor in the range from 0 to 1 correspond to the active element moving from the left side of the viewport to the right.
Set the viewport Handler attribute to " GlgSlider ". Make sure that the HandlerDisabled attribute is set to NO.
When you run this drawing (use an empty run command), the GlgSlider handler will read input from the cursor position when you click in the viewport, and use that position to set the value of the viewport's ValueX resource. Of course, the ValueX resource need not control the position of an object. A move transformation attached to the active element is what we expect to see, but the resource could be attached to anything. For example, you could rotate a joystick in three-dimensions based on the linear position of the mouse.
To make the slider granular, create a scalar data resource named " Granularity " at the top level of the slider viewport's resource hierarchy. The value of the object indicates the number of positions the slider may take.
In the Enterprise Edition of the Builder, you can use the Custom Properties button in the Object Menu to add a D property named " Granularity " to the slider's viewport. In the Basic and Professional Editions, create a dummy marker object to hold the resource, name its MarkerSize attribute " Granularity " and set its HasResources flag to NO to make the Granularity resource visible at the viewport's top level. When editing is finished, reset the drawing using the Reset toolbar button and run the drawing to check the slider's new behavior.
The sections below describe each of the available handlers, and list the resources they control.
A slider is used to convert a linear mouse position into a numeric value. Sliders can be one- or two-dimensional, returning one or two coordinates. One-dimensional sliders can be horizontal or vertical. A scroll bar is a form of slider. Adjusting the granularity can turn a slider into a multi-position switch.
All the slider resources are optional. However at least one of the ValueX or ValueY resources must be present.
The slider's X value. This is a value between 0 and 1. When the cursor is at the left edge of the viewport, ValueX is 0. When it is at the right edge, it equals 1.
The slider's Y value. This is a value between 0 and 1. When the cursor is at the bottom edge of the viewport, ValueY is 0. When it is at the top edge, it equals 1.
This resource identifies a marker object that is placed at the lower limit of the X and Y values. For example, in a horizontal slider, the start marker is at the left edge of the range, while in a two-dimensional slider, it is placed at the lower left corner.
This resource identifies a marker object that is placed at the upper limit of the slider X value.
This resource identifies a marker object that is placed at the upper limit of the slider Y value.
A control's granularity is the number of possible positions that control can take. This resource is an integer indicating that value. As an example, a granularity of 2 for a vertical slider creates a 2-position linear switch. If the resource is absent, the slider may take any value between the lower and upper limits.
If this resource is present and non-zero, the slider has no state. That is, each time a move operation is completed, the slider values moves back to the center of their range, and delivers the final move coordinates to the application program via the message object. The view sliders in the GLG Graphics Builder are stateless. This allows the sliders to control an unlimited range.
The slider element appears to slide on the plane defined by this polygon. The points of the polygon must be co-planar. When you click on the slider widget, the cursor position is projected onto this plane. The resulting coordinates are used to set the slider position.
Increment for changing the knob's value by using the directional buttons listed below. The increment is expressed as a fraction of the total range of the slider (ranging from 0 to 1). If this resource is missing, the default increment is one tenth of the slider range.
If buttons with these names are embedded into a two-dimensional slider, each press of a button moves the slider in the direction indicated by the button's name and by the amount specified by the slider's Increment .
If buttons with these names are embedded into a one-dimensional slider, each press of a button moves the slider in the direction indicated by the button's name and by the amount specified by the slider's Increment .
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the slider's value.
If this resource is present and non-zero, the slider will wrap around when the value is incremented or decremented past its low or high values.
The GLG Toolkit includes a native slider input handler that uses features of the native windowing environment and may be attached to a viewport object with WidgetType of VERTICAL_SCROLLBAR, HORIZONTAL_SCROLLBAR, VERTICAL_SCALE and HORIZONTAL_SCALE. The native slider handler encapsulates the native slider and scrollbar widget's interfaces and allows to handle them in a cross-platform way. The native slider is more limited than the GLG version, and only handles one-dimensional input. Its Value and Stateless resources are described in GlgSlider, but it also has the following resources:
Specifies the amount the value changes when the users moves the slider by one increment. The increment is expressed as a fraction of the total range of the slider (ranging from 0 to 1). If this resource is missing, the default increment of the native slider widget is used.
Specifies the amount the value changes when the user moves the slider by one page increment. The page increment is expressed as a fraction of the total range of the slider (ranging from 0 to 1). If it is missing, the default page increment is used.
A knob input widget is used to translate the angular position of the mouse into a value between 0 and 1. Adjusting the granularity can turn a knob into a multi-position switch. All knob angles, like all angles in a GLG drawing, are measured in degrees from the X axis (the 3 o'clock position).
All the knob resources are optional, except for Value .
The knob's value. This is a number between 0 and 1. The knob is at 0 when the cursor is at the StartAngle position relative to the Center , and 1 when the cursor is at the EndAngle position. None of these resources need be present, in which case, the start angle is 0, the end angle is 360, and the center is the origin of the viewport.
The angular position of the cursor is measured relative to this point. This resource is actually a marker object, which may or may not be visible, but in either case is used to define a position in the viewport space. If the resource is not present, the viewport's origin is used as the center.
This is the angle, measured counter-clock wise in degrees from the 3 o'clock position, at which the knob value is 0. If absent, the default value of 0 is used.
This is the angle, measured counter-clock wise in degrees from the 3 o'clock position, at which the knob value is 1. If absent, the RotateAngle value is used. The default value of 360 is used if the RotateAngle is absent.
An alternative rotation angle measured counter-clock wise in degrees from the 3 o'clock position and relative to the StartAngle . If the EndAngle is absent, and the RotateAngle is defined, its value is used to define the end angle of rotation as StartAngle + RotateAngle .
A control's granularity is the number of possible positions that control can take. This resource is an integer indicating that value. As an example, a granularity of 3 for a knob creates a 3-position rotary switch. If the resource is absent, the knob may take any value between the lower and upper limits.
If this resource is present and non-zero, the knob has no state. That is, each time a move operation is completed, the knob Value moves back to the center of the knob range, and delivers the final move coordinates to the application program via the message object.
The knob element appears to rotate on the plane defined by this polygon. The points of the polygon must be co-planar. When you click on the knob widget, the cursor position is projected onto this plane. The resulting coordinates are used to set the knob position.
Increment for changing the knob's value by using Increase and Decrease buttons. The increment is expressed as a fraction of the total range of the knob (ranging from 0 to 1). If this resource is missing, the default increment is one tenth of the knob range.
If buttons with these names are embedded into a knob viewport, each press of a button changes the knob's value in the direction indicated by the button's name and by the amount defined by its Increment.
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the slider's value.
A button widget reacts to left mouse button clicks while the mouse cursor is within the widget viewport. There are two kinds of buttons: toggle buttons and push buttons. A toggle button has an internal state that changes with each press of the button, while a push button has no internal state, and only reacts to the external event (the mouse click). A toggle button's state may or may not be displayed. The GLG Toolkit supports only binary toggle buttons. (You can use a slider or knob with non-zero granularity to create multi-position switches, however.)
This resource is usually 0, but when the mouse button is pressed, the resource momentarily changes to 1. When the button is released, the resource goes back to 0.
If this resource is present, the button is a toggle button, and successive clicks on the button change this resource value from 0 to 1 and back again. The value is set to 0 at startup and after a drawing reset.
This resource is usually 0, but when the mouse cursor enters the button widget viewport, it changes to 1. When the cursor exits the viewport, the value goes back to 0.
This resource generally indicates the string displayed by the Label resource text object. It is used when the button is displayed as part of a menu widget.
When the cursor enters the button viewport, and is still briefly, a small label appears displaying the string indicated by this resource. The ButtonTooltip custom event is generated when a button tooltip is activated or erased. Refer to Appendix B: Message Object Resources of the GLG Programming Reference Manual for more details.
Defines an interval in seconds after which the button starts generating repeated Activate messages if the button is held down. If it is set to a value less or equal to 0 (default value), the button repeat is disabled.
Defines an interval in seconds between repeated Activate messages generated when the button is held down. The default value is 1/10 of a second.
If this resource is present and has a non-zero value, the button's action happens on the down-click of the mouse button. Otherwise, the action is taken on the release of the button. If this resource is not present, and if the mouse cursor is moved out of the button viewport before the mouse button is released, that no action is taken.
The GLG Toolkit provides a native button input handler which may be attached to a viewport object with WidgetType of PUSH_BUTTON, CUSTOM_BUTTON and TOGGLE_BUTTON. The native button handler encapsulates the native push button, toggle and checkbox widget's interface and allows to handle native buttons in a cross-platform way.
Its only resources are PressedState , OnState (toggle only) , LabelString , TooltipString , RepeatInterval and RepeatTimeout, with the same meaning as for the GlgButton handler. Note that, whereas the GLG button widget's label is supplied by a text object, the native widget uses a simple string value, and draws the label itself.
The text widget is used for entering single lines of typed text. It also contains a resource that provides initial text to display, and another to control the widget's appearance when it receives the input focus. This handler is superseded with the GlgNText and is maintained for compatibility with the older code.
This resource changes when the widget is available for input. It is normally 0, but changes to 1 when you click on the text widget with the mouse. It is used to control the look of the widget when it is ready to accept typed input. For example, you could use a linear transformation to make a border around the widget appear when the widget is selected.
This is a native text widget handler which may be used with both single and multi-line text widgets. It may be attached to a viewport object with WidgetType of TEXT and TEXT_EDIT. The native text handler encapsulates the native text box widget's interface and allows to handle it in a cross-platform way.
This optional resource indicates the maximum length of a text string that user can enter from the keyboard. This resource does not affect strings that are entered programmatically by setting the TextString resource.
This S-type resource indicates an optional format and may have the following values:
"string" - for entering any alpha-numerical characters
"integer" - for entering integer values
"double" - for entering floating-point values
If the resource is not specified, the "string" default value is assumed.
A spinner displays a numerical value and contains two or more buttons to increase or decrease it. A text edit box widget may be used to display and edit the value, or the value may be presented as a display-only text object which could only be altered by a predefined increment using the increase and decrease buttons. Some of the spinner's resources may be inherited from the GlgText handler of the embedded text edit box used to display the spinner's value. In this case, aliases are used to "redirect" the resource by pointing to the corresponding resource of the embedded text widget. An optional slider widget may be used to implement a "sliding" spinner which allows the user to change its value using either a text edit box, a slider, or increase and decrease buttons.
If this resource is present and non-zero, the spinner will wrap around when the value is incremented or decremented past its low or high values.
If buttons with these names are embedded into a spinner, each press of a button changes the spinner's value in the direction indicated by the button's name and by the amount defined by its Increment.
If buttons with these names are embedded into a spinner viewport, each press of a button changes the spinner's value in the direction indicated by the button's name and by the amount defined by its PageIcrement.
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the slider's value by its Increment.
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the slider's value by its PageIncrement.
The native list handler encapsulates the behavior of a native list widget, allowing to use it in a cross-platform way. It may be attached to a viewport object with the WidgetType of LIST, MULT_LIST and EXT_LIST, and handles both the single and multiple selection, depending on the native list type. In the single selection mode, the list's selection may be changed by setting the value of the SelectedIndex resource. In the multiple selection mode, the GlgSendMessage method may be used to change list's selection as well as to add, delete or query list entries.
This resource is a list of strings to be displayed in the list widget on initial appearance. It may be edited in the Graphics Builder.
A group object created by the list handler which contains the current list of strings displayed in the list widget.
In the single selection mode, the value of this resource is set to the 0-based index of the selected list item.
In the single selection mode, the value of this resource is set to the string of the selected list item.
In the multiple selection mode, the list creates this resource to hold the selection state of its items. The resource is a group object containing integer values.
The GlgNList interaction handler supports the following messages that can be sent using the GlgSendMessage method:
Updates the list widget with the new items from the viewport's InitItemList after changing items of the InitItemList resource. The message has no parameters.
Updates the list widget with the items from the item list passed as the first parameter of the message. The passed item list must be a group object containing item strings. The message does not alter InitItemList .
Returns a current list of items displayed in the list widget. This message has no parameters and returns a group object containing a list of strings.
Adds a new item to the list. The new list item is passed as the first message parameter, and the second parameter may contain GLG_TOP or GLG_BOTTOM to specify the place to add the item to. If the second parameter is NULL, the default GLG_BOTTOM value is used. The UpdateItemList message must be used to display the new items when finished. The SetItemList message provides a way to replace the whole item list.
Deletes a list item. The first message parameter may contain GLG_TOP or GLG_BOTTOM to specify the item to be deleted. If the parameter is NULL, the default GLG_BOTTOM value is used. The UpdateItemList message must be used to update display when finished. The SetItemList message provides a way to replace the whole item list.
Updates the list's display after changing its ItemList . The message has no parameters.
Sets the item specified by the zero-based index passed as the first parameter of the message to the state ( True or False ) specified by the second message parameter.
Returns the state of the item specified by the zero-based index passed as the first parameter of the message.
Sets the state of all items of a multiple-selection list. The list of new item states is supplied as the first parameter of the message and must be a group object containing integer values. The number of items in the list must match the number of displayed items in the list widget.
The native option menu handler encapsulates the behavior of native option menu (X Windows) and combo box (Windows) widgets, allowing to use them in a cross-platform way. It may be attached to a viewport object with the OPTION_MENU WidgetType . The option menu's selection may be changed by setting the value of the SelectedIndex resource. The GlgSendMessage method may be used to add, delete or query option menu's entries.
This resource is a list of strings to be displayed in the option menu or combo box widget on initial appearance. It may be edited in the Graphics Builder.
A group object created by the option menu handler which contains the current list of option strings displayed in the widget.
The GlgNOption interaction handler supports the following messages that can be sent using the GlgSendMessage method:
Updates the option menu widget with the new option items from the viewport's InitItemList after changing items of the InitItemList resource. The message has no parameters.
Updates the option menu widget with the option items from the item list passed as the first parameter of the message. The passed item list must be a group object containing item strings. The message does not alter InitItemList .
Returns a current list of option menu items. This message has no parameters and returns a group object containing a list of strings.
Adds a new option menu item to the widget. The new item is passed as the first message parameter. The second parameter may contain GLG_TOP or GLG_BOTTOM to specify the place in the list of options where the new item will be added. If the second parameter is NULL, the default GLG_BOTTOM value is used. The UpdateItemList message must be used to display the new option items when finished. The SetItemList message provides a way to replace the whole option list.
Deletes an option item. The first message parameter may contain GLG_TOP or GLG_BOTTOM to specify the option item to be deleted. If the parameter is NULL, the default GLG_BOTTOM value is used. The UpdateItemList message must be used to update display when finished. The SetItemList message provides a way to replace the whole item list.
A menu widget is a container used to manage a set of buttons. When a button within a menu is pressed, it issues an Activate message object. The menu converts this Activate message of the button into an Activate message for the menu, supplying the logical button number in the message. This allows an application program to ignore the presence or absence of specific buttons in the menu and to deal only with a menu as a whole. The menu widget also supplies information about the selected button's label and assigned value by placing this information into the menu's message object. The buttons placed in the menu are recognized by their names. The name of the first button must be Button0 , the name of the second Button1 , and so on.
Buttons may be pasted into the menu and positioned inside it using the GLG Graphics Builder. This may be done in two ways. First, you may simply paste or copy them into a menu one by one, name them sequentially and position as desired. You can also use a series or square series object to create instances of the buttons and to position them. In this case, a button named Button should be used as a template for the series object. The series object takes care of creating the specified number of buttons, naming them sequentially and placing them. The labels should be individually applied with the GLG API. The control points of the series object and the dimensions of the template button control the layout. With either method, a menu widget manages the geometry of the buttons, resizing them proportionally when the menu is resized.
In addition to buttons, the menu may also contain a slider called ScrollObject . This slider is used for scrolling when the menu is a part of some kind of browser, like a Font or File Browser Widget.
Menu button labels may be assigned dynamically by changing the String attribute of a button's label. Button labels may also be applied with the LabelList resource. If present, this resource identifies a list of data properties of S type specifying labels to use (usually attached to the menu's viewport as a Custom Property list). The buttons in the menu will be assigned the labels taken from these objects. If there are more buttons then the labels in the LabelList, the LabelString of the button itself is used. If there are more labels in the group than there are buttons in the menu, the menu is scrolled (an explicitly defined scrollbar named ScrollObject must be provided to facilitate scrolling).
These resources name the menu buttons. The first button is called Button0 , and must be present for any menu widget. The other buttons in the menu must follow this first button in sequence. The numeric suffix is the index of the button, and is returned with the SelectedIndex resource of the message object.
This resource indicates an optional group object containing a list of the button labels to be displayed. If no such resource exists, the button's name or LabelString resource is used.
This is a group object containing a list of all the buttons whose labels are to be highlighted. This only affects buttons using the GlgButton handler.
This text object has the colors to be used to highlight labels in the list. The list entries of the objects in the HighlightList list will bear labels constrained to look like this object. This only affects buttons using the GlgButton handler.
The browsers are an arrangement of menus, buttons and lists designed to facilitate the selection of some item. Typical arrangements include a filter , or string containing wildcard characters, a list of objects that match that string, and a text widget into which a user can type the selection. Often, the filter string will be reproduced in the selection text widget to save typing by the user.
Different browsers include optimizations designed for the objects being browsed. A font browser, designed for making selections from fonts that use the X font naming conventions, has a menu of buttons designed to make the construction of a filter string easy. The font browser is only supported on X Windows.
The browser handler is designed to be used for browsing resources of GLG drawings and objects, a example of which can be seen as the resource browser in the GLG Graphics Builder. The browser handler may also be used to browse tags (tag browser) and custom data sources (custom data browser).
The menu from which selections may be made. For a resource browser, the menu presents the resources on the chosen level of the hierarchy. For a tag browser, the menu displays a list of tags of the selected object. For a custom data browser, the menu displays a list of data sources. For a font browser, it displays either fonts matching the filter string or a list of available entries for a specified filter field. The menu object uses a native list widget (a viewport with WidgetType=LIST).
This text widget displays the filter string used to display the entries in the menu. Only entries that match the filter are displayed.
This text widget displays the selection that will be made. To save typing, the browser usually echoes the filter string into this widget.
This text object is used to display a sample of the chosen font. Its String resource is usually some sample sentence.
This resource indicates a menu used to specify the field of the font filter string a user wishes to edit. That is, if you want to change the font family, you push the Family button in this menu. The browser then presents you with the available options. When you choose one of them, the filter is modified accordingly.
This resource is a string value defining the type of the browser for the GlgBrowser input handler, not used by the GlgFontBrowser. The value of the string must be "Resource" for the resource browser, " Tag " for the tag browser and " Data " for the custom data browser.
The browser has three buttons, to signal the action to take. For details of the messages these buttons send, see the description of the GlgButton and GlgNButton handlers. The button messages are processed by the browser handler and do not require any additional handling.
The palette widget is used to present a user with the opportunity to select one from a variety of objects. This widget is designed to be used within a program using the GLG API.
A palette widget has only one resource, an object named PaletteObject . This is a container object with several members, each corresponding to a different possible choice. The user selects one of the presented objects with the left mouse button, and the chosen object is returned to the calling program in the callback message object. The returned object is indicated with the SelectedObject resource of the message object.
For more information about callbacks and message objects, see Input Objects
The clock input handler is used for two different timekeeping tasks: measuring elapsed time, and displaying the absolute time. Unlike the other input handlers, the clock widget is not primarily used for user input. Rather, it is used for updating a drawing with the current time.
If the TimerState resource is present, the widget becomes a stopwatch, measuring elapsed time instead of absolute time. Used as a stopwatch, the handler recognizes user input when the control buttons are operated. All the resources are optional.
These resources indicate the time in its traditional format. All scalar data types, the hour ranges from 0 to 11, and the minute and second resources range from 0 to 59.
These resources are also used to indicate the time. However, instead of measuring hours, minutes, and seconds, they indicate the proportion of the clock's circumference used to indicate the desired quantity. For example, six hours is indicated by the value 0.5, and 15 seconds by the value 0.25. These resources are generally used to drive the arms of a clock drawing.
The timer input handler is used for changing object attributes at periodic intervals. Same as the Clock handler, the timer is not used for user input. Rather, it is used for adding various blinking behaviors to objects in the drawing. The timer recognizes several resources that control the rate, type and amplitude of periodic attribute changes. The timer handler is superseded by more flexible Timer transformation in the release 2.8 of GLG.
To add blinking behavior to an object's attribute, constrain either the attribute or some parameter of the attribute's transformation to the timer's output Value resource. In the simplest case, object's Visibility may be constrained to the timer's Value to blink the object. To blink the object's color between two color values, a factor of the object's color transformation may be constrained to the timer's Value . The timer will toggle the factor's value between 0 and 1, causing the object to change it's color. The TimerEnabled resource may be used to enable or disable the timer. All the resources are optional.
Several objects may be connected to the same timer to blink the objects with the same rate. To control blinking of the objects individually, Transfer transformations may be used to connect the blinking attribute of each object to the timer. To control blinking of an object, attach the controlling transformation to the Buffer attribute of the Transfer transformation.
Several timers may be used in a drawing to provide blinking with different rates. The timer's viewports may be made invisible by setting its Visibility attribute to OFF .
In the editor, the blinking is visible in the run mode. In a program, you'll have to add an Input callback and handle the timer's update messages by calling GlgUpdate() function. The GLG ActiveX control and Java Bean handle the timer update messages automatically.
This resource defines the update frequency in seconds. If the resource is not present, the default value of 1. will be used. To update several times per second, set this resource to fractional values. For example, set it to 0.25 to blink four times per second. To update as fast as possible with no timeouts use the value of zero.
This is the output resource of the timer. The timer will change this resource periodically between the High and Low values according to the setting of other resources. If an object's attribute is constrained to this resource, the timer will change that attribute periodically.
These resources define the maximum and minimum values used to alternate the output Value of the timer. If these resources are not present, 0. and 1. will be used as defaults.
This resource defines the number of intervals it takes to swing the output Value from the minimum to maximum value and back. If this resource is not present, 2 will be used as the default value. The default value causes the output to alternate between High and Low .
This is a string resource that defines the type of the output value changes. It may have the following values:
Sine - a sinusoidal signal is used to update the output value. The Period resource defines the sine wave's period.
Increment - when this update type is used, the value is incremented from Low to High in a number of steps defined by the Period and then jumps back to Low in one step.
Increment2 - the value is incremented from Low to High and back to Low in a number of steps defined by the Period .
Circular - similar to Increment , but skipping the last step (where value equals High ). It is used to animate rotational animation where the value of 0 and the value of 360 correspond to the same position.
In addition to making drawings using GLG widgets, you can use the GLG Toolkit to create an arrangement of widgets native to the windowing environment. The type of native widget used to render a viewport is defined by the WidgetType viewport attribute. This attribute is inherited from the screen object associated with each viewport, and available for editing in the Builder by clicking on the More button in the list of viewport properties.
The default DRAWING_AREA widget type is used to render viewports that are used as drawing surfaces for displaying graphical objects. By placing viewport objects with widget type different from the default into the GLG drawing, you can embed native widgets into the drawing. The look and feel of the native widgets will change to match the environment in which the drawing is displayed. For example, a native button will be displayed as a Windows, Motif, AWT or Swing button when it is displayed in the respective environments.
Native widgets come with some limitations. For example, you cannot use the drawing resources to control the behavior of these widgets, although you can control graphical features such as color, layout and, via input handler's resources, labels. The input handlers are provided only for some of the native widgets: buttons, toggles, sliders, scrollbars and text widgets.
For complete control over a native widget's resources, in both C/C++ and Java, use the windowing environment's native API. The Builder's graphical interface is still quite useful for application design tasks such as arranging windows and graphical controls.
The Widget ID of the native widget used for rendering the viewport may be obtained by querying the Widget resource of the viewport using the GlgGetLResource method of the GLG API (similar to the GlgGetDResource method, but uses long return value type). The Widget ID must be queried after setting up the drawing hierarchy (at which time the native widget is created) and may be used in any further native API calls. For example, a widget ID of a list widget may be used to fill the list with string items in both C/C++ environment in Windows or X/Motif, and Java.
The widget types are listed in the table below, with their X Windows/Motif, Windows and Java equivalents. To learn how to control these widgets, refer to the documentation for the appropriate windowing environment.
If you are using the Xt Wrapper Widget instead of the Motif-based Wrapper Widget, the Drawing Area widget is of the Composite class, and the other Motif native types are not available.
The user interface controls widgets, such as PUSH_BUTTON, SCROLLBAR, TEXT, LIST and others, are used in conjunction with the corresponding interaction handler (described earlier in this chapter) which handles user interaction with the native widget. On Windows, the color of these widgets is defined by the system's color settings, and the FillColor of the viewport is ignored. In Java, the color of these widgets is defined by the chosen Look and Fill scheme, and the viewport's FillColor is ignored as well. In UNIX / X Windows environment, the background color of the widgets is defined by the viewport's FillColor, and the widgets' forecolor is taken from the system's settings. The CUSTOM_BUTTOM widget is an exception, it uses viewport's FillColor as a background color in X Windows and Java environments, and system color on Windows.
The DIALOG_AREA widget may be used to provide a matching dialog background color for other native control widgets. On Windows, the color of the dialog widget is defined by the system color. In X Windows and Java environments, the color is defined either by the viewport's FillColor, or by the GlgDefaultDialogColor global configuration resource, which, if set, overrides the viewport's FillColor. This provides a global way to define the background of all dialogs in the X Windows and Java environments in a way similar to that on Windows. The default unset value of the GlgDefaultDialogColor global configuration resource is (-1, -1, -1).
When the DRAWING_AREA, CUSTOM_BUTTOM, BULLETIN, FORM and DIALOG_AREA widget types are used, the 3D bevels are drawn if the value of the ShadowWidth parameter is not equal 0.