PREV NEXT

Generic Logic, Inc. www.genlogic.com


5 Input Objects

Widgets such as Sliders, Dials, 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 that handles input events. 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:

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 without a need to write any supporting code.

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

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.

Input Handlers

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 used by the dial widgets 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 widget resources are changed in the Builder, the widget's drawing has to be reset using the File, Reset menu option 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 passed by the handler to an input callback function. The message object also contains resources that indentify the input handler that triggered the input callback. These resources are described in the Callback Events section on page 105 of the GLG Programming Reference Manual. Refer to Appendix B: Message Object Resources on page 365 of the GLG Programming Reference Manual for a complete list of all message object types and their resources.

The handlers available are as follows:

GlgSlider
Interprets linear mouse movement. Used for scrollbars, switches and sliders.
GlgNSlider
A native slider handler that takes advantage of local window system graphical representations.
GlgKnob
Interprets angular mouse movement. Used to implement dials, meters, knobs and switches.
GlgButton
Accepts mouse clicks for toggle and push buttons.
GlgNButton
A native button handler that works with native buttons, toggles and check box controls.
GlgNText
A native text handler that takes advantage of native text input widget. Works with both single and multi-line text edit controls.
GlgNList
A native list handler that handles native list widget in a cross-platform way. Works with both single and multiple selection list controls.
GlgNOption
A native option menu handler that works with the native option menu and combo box controls.
GlgMenu
Assembles buttons into a menu or a radio box.
GlgBrowser
A specialized browser for selecting object resources, tags and alarms.
GlgFontBrowser
A specialized browser, optimized for browsing X Windows fonts.
GlgClock
Displays the time. Can also be used as a stopwatch to record elapsed time.
GlgTimer
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.
GlgPalette
A specialized menu allowing a user to select arbitrary objects.

Attaching an Input Handler

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 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. Depending on the handler type, an input handler recognizes a certain set of resources that control the handler's behavior.

An input handler is attached to a viewport with the viewport's Handler attribute. This attribute is a character string identifying which of the available handlers is to be used. To use the handler, you must also set the viewport's DisableInput attribute to NO (default).

To use a handler, you must equip the viewport with the resources the handler 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 define optional resources that provide additional information to the handler, such as Increment or Granularity. These resources may be added to the widget's viewport as custom properties, using the Object, Custom Properties, 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.

The sections below describe each of the available handlers, and list the resources they control.

Examples of Creating Custom Input Widgets

While the GLG Control Widget Set provides a variety of ready to use input widgets, the following examples illustrate input handlers' use by creating basic toggle and slider widgets from scratch. Refer to the following section for detailed description of the resources used in the examples.

Here are the steps to create a simple toggle button:

1. Create a drawing with a viewport and an object in the viewport, such as a small rectangle, that will be the indicator of the toggle state. You can also place a text label next to the rectangle.
2. Bring the rectangle's properties dialog, click on the ellipsis button next to the Visibility attribute and name the attribute "OnState".
3. Set the viewport Handler attribute to "GlgButton". Make sure that the DisableInput attribute is set to NO.
4. Prototype this drawing using the Start toolbar button and select Skip Command in the Animation Command dialog. The GlgButton handler will toggle the rectangle's Visibility (the OnState resource) every time the button is pressed. Use the Stop toolbar button to exit the Run mode.

Here are the steps to follow to create a simple horizontal slider:

1. 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.
2. 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.
3. Set the viewport Handler attribute to "GlgSlider". Make sure that the DisableInput attribute is set to NO.

When you run this drawing, 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 Object, Custom Properties, Add Custom Property 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 the marker's 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.

For more information on the internal design of the input widgets, see page 231.

Common Input Handler Resources

All input handlers support the ActiveState resource:

ActiveState
The value of this resource is set to 0 when the input handler is disabled by setting the viewport's DisableInput attribute to YES. The ActiveState attribute may be attached to some resource in the drawing to alter widget's appearance in the inactive state.
Resources with the Param suffix
The output resources of input handlers, such as Value, ValueX, ValueY, OnState and others, have a corresponding resource whose name is formed by adding the "Param" suffix: ValueParam, ValueXParam, OnStateParam and so on. These resources are used only in the internal design of the input widgets and can be ignored in the application code.

For information on the internal design of the input widgets, see 1

GlgSlider

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.

When a slider is moved or dragged with the mouse, it captures the mouse input until the mouse button is released and changes the cursor for the duration of the capture. The GlgChangeCursorOnGrab global configuration resource or the GLG_CHANGE_CURSOR_ON_GRAB environment variable can be used to disable cursor change.

All the slider resources are optional. However at least one of the ValueX or ValueY resources must be present.

ValueX
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.
ValueY
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.
ActiveArea
The screen cursor must be within this polygon for the slider to react to user input.
Start
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.
XEnd
This resource identifies a marker object that is placed at the upper limit of the slider X value.
YEnd
This resource identifies a marker object that is placed at the upper limit of the slider Y value.
Granularity
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.
DisableMotion
If this resource is present and non-zero, the control is disabled.
IncrementOnClick
If this resource is not present or is set to zero, the slider moves to the location of the mouse click. If the resource is present and non-zero, the alternate behavior is used for mouse clicks outside of the slider's ActiveElement. Each click moves the slider by its PageIncrement in the direction of the mouse. If the mouse button is held down, the slider keeps moving until the button is released or the slider reaches the mouse position.
RepeatTimeout
Defines a timeout in seconds after which the slider with IncrementOnClick starts moving when the mouse button is held down. If the resource is not defined, the default value of 250 ms is used.
RepeatInterval
Defines how fast a slider with IncrementOnClick repeats the slider movement when the mouse button is held down. If the resource is not defined, the default value of 100 ms is used.
Stateless
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.
Plane
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
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 two hundredth of the slider range.
PageIncrement
Page increment for changing the knob's value by using the page 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.
Left, Right, Up, Down
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.
Increase, Decrease
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.
IncreaseKeys, DecreaseKeys
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the slider's value.
PageIncrease, PageDecrease
If buttons with these names are embedded into a one-dimensional slider, each press of a button moves the slider in the direction corresponding to the button's name and by the amount specified by the slider's PageIncrement.
PageIncreaseKeys, PageDecreaseKeys
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the slider's value by PageIncrement.
Wrap
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.
SliderSize, StartPosition, EndPosition
These resources are defined in most of the slider and scrollbar objects to control the size of the slider's ActiveElement and the extent of its movement. These resources are used only to define the slider's geometry and are not used by the GlgSlider interaction handler. These resources are not present in the slider's message object and may be accessed only as resources of the slider's viewport.
Messages

The GlgSlider interaction handler supports the following messages that can be sent using the GlgSendMessage method:

Increase
Increases the slider's value by its Increment. The message has no parameters.
Decrease
Decreases the slider's value by its Increment. The message has no parameters.
PageIncrease
Increases the slider's value by its PageIncrement. The message has no parameters.
PageDecrease
Decreases the slider's value by its PageIncrement. The message has no parameters.
Up
Increases the slider's Y value by its Increment. The message has no parameters.
Down
Decreases the slider's Y value by its Increment. The message has no parameters.
Right
Increases the slider's X value by its Increment. The message has no parameters.
Left
Decreases the slider's X value by its Increment. The message has no parameters.
UpLeft, UpRight, DownLeft, DownRight
Composite messages that perform the actions of the two messages indicated by their names. The messages have no parameters.

GlgNSlider

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 the GlgSlider section, but it also has the following resources:

Increment
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.
PageIncrement
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). It can also be set to -1, in which case the slider size will be used as a page increment. If the page increment is missing, a default page increment is used.

In the C# environment, .NET scrollbar controls do not allow setting the page increment and slider size independently. If PageIncrement is set to a positive value, it will define both the page increment and the slider size, otherwise SliderSize will be used to define both parameters.
SliderSize
Specifies the size of the moving part of a scrollbar. The slider size is expressed as a fraction of the total range of the slider (ranging from 0 to 1). If slider size is missing, the default size is used. This resource is applied only to the native scrollbar widget.
Granularity
Specifies a number of possible positions the slider can take. If the resource is absent, the slider may take any value between the lower and upper limits.
DrawTicks (Java only)
Activates display of the JSlider's major ticks if set to an integer value greater than 0. If the Granularity resource is not defined, the number of ticks is defined by the value of the DrawTicks resource. If Granularity is defined, its value is used as the number of ticks.
Messages

The GlgNSlider interaction handler supports the following messages that can be sent using the GlgSendMessage method:

Increase
Increases the slider's value by its Increment. The message has no parameters.
Decrease
Decreases the slider's value by its Increment. The message has no parameters.
PageIncrease
Increases the slider's value by its PageIncrement. The message has no parameters.
PageDecrease
Decreases the slider's value by its PageIncrement. The message has no parameters.

GlgKnob

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

When a knob is moved or dragged with the mouse, it captures the mouse input until the mouse button is released and changes the cursor for the duration of the capture. The GlgChangeCursorOnGrab global configuration resource or the GLG_CHANGE_CURSOR_ON_GRAB environment variable can be used to disable cursor change.

All the knob resources are optional, except for Value.

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.
Center
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.
StartAngle
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.
EndAngle
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.
RotateAngle
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.
Granularity
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.
DisableMotion
If this resource is present and non-zero, the control is disabled.
IncrementOnClick
If this resource is not present or is set to zero, the knob moves to the location of the mouse click. If the resource is present and non-zero, the alternate behavior is used for mouse clicks outside of the knob's ActiveElement. Each click moves the knob by its PageIncrement in the direction of the mouse. If the mouse button is held down, the knob keeps moving until the button is released or the knob reaches the mouse position.
RepeatTimeout
Defines a timeout in seconds after which the knob with IncrementOnClick starts moving when the mouse button is held down. If the resource is not defined, the default value of 250 ms is used.
RepeatInterval
Defines how fast a knob with IncrementOnClick repeats the movement when the mouse button is held down. If the resource is not defined, the default value of 100 ms is used.
Stateless
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.
Plane
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
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.
Increase, Decrease
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.
IncreaseKeys, DecreaseKeys
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the knob's value.
PageIncrease, PageDecrease
If buttons with these names are embedded into a knob, each press of a button moves the knob in the direction corresponding to the button's name and by the amount specified by the knob's PageIncrement.
PageIncreaseKeys, PageDecreaseKeys
These S resources define a list of characters that will be used as keyboard accelerators for incrementing or decrementing the knob's value by PageIncrement.
Wrap
If this resource is present and non-zero, the knob will wrap around when the value is incremented or decremented past its low or high values.
Messages

The GlgKnob interaction handler supports the following messages that can be sent using the GlgSendMessage method:

Increase
Increases the knob's value by its Increment. The message has no parameters.
Decrease
Decreases the knob's value by its Increment. The message has no parameters.
PageIncrease
Increases the knob's value by its PageIncrement. The message has no parameters.
PageDecrease
Decreases the knob's value by its PageIncrement. The message has no parameters.

GlgButton

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. GlgButton supports only binary toggle buttons. A slider or knob with a non-zero Granularity resource can be used to create multi-position switches.

PressedState
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.
OnState
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.
InState
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.
Label
This resource indicates a text object displaying a label for the button.
LabelString
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.
TooltipString
When the cursor enters the button viewport, and is still briefly, a small label appears displaying the string indicated by this resource. The ButtonTooltip event is generated when a button tooltip is activated or erased. Refer to 1, 2
RepeatTimeout
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. Repeated action is enabled only for push buttons with ActOnPress activation.
RepeatInterval
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.
ActOnPress
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.
ArmedState
If this resource is present and has a value different from -1, the button is enabled (armed) only when the Control key is pressed. Without the Control key, the button is locked. This type of buttons is used in a process control applications where it is important to prevent the user from triggering an action by accidentally pressing a button. When the Control key is pressed, the resource changes to 1, returning to 0 when the Control key is released.
If the resource is set to -1, the ArmedState functionality is disabled and the button does not pay attention to the Control key. This makes it possible to use a single button widget template and enable or disable the ArmedState functionality for individual button instances.
TokenValue
The button's "value" is an arbitrary scalar value assigned to the button. This resource is used when the button is part of a menu widget.
Messages

The GlgButton interaction handler supports the following messages that can be sent using the GlgSendMessage method:

Set
Sets the toggle (toggle buttons only). The message has no parameters.
Reset
Resets the toggle (toggle buttons only). The message has no parameters.
Activate
Generates an Activate event (push buttons only). The message has no parameters.

GlgNButton

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, 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 OnState resource is supported not only for the TOGGLE_BUTTON, but also for other button types. If the LabelString resource of a push button has the list transformation attached, the OnState resource may be used to control the list transformation to toggle the button's label on a mouse click. Such button will behave as a toggle button, but without rendering the toggle button's state indicator. The button will still generate the push button's Activate action.

Messages

The GlgNButton interaction handler supports the same messages as the GlgButton handler listed above.

GlgNText

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.

On Windows, the text box uses a native text control and supports standard keyboard shortcuts for copying, pasting or deleting selected text (Ctrl-C, Ctrl-V, Ctrl-X, etc.). In the X Windows environment on Unix/Linux, a Motif text widget used for a text box supports these shortcuts as well. However, the copy and paste operations use the clipboard, which is different from the primary selection (the text highlighted with the mouse). The highlighted text can be pasted by using the middle mouse button. The Motif text widget also supports Ctrl-A shortcut for selecting all text and Ctrl-Z for deselecting. On both platforms, the highlighted text selection can be unselected by either a mouse click or moving the cursor using directional arrows. All text in a text box can be selected when the text box receives the keyboard focus. This behavior is controlled by the SelectAllOnFocus resources described below.

The Pan attribute of the widget's viewport can be used to enable or disable scrollbars. If the horizontal scrollbar is not displayed for the TEXT_EDIT widget, the widget will wrap long lines that extend past the width of the text box.

TextString
This resource indicates the string attribute of the text object.
MaxLength
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.
SelectAllOnFocus
This optional resource may be set to a non-zero value to highlight all text in the text box when the focus moves into the box. This behavior can be overridden by the settings of the GlgSelectAllOnFocus global configuration resource, which can be used to enable or disable this behavior for all text boxes regardless of the setting of their SelectAllOnFocus resources.
InputFormat
This S-type resource indicates an optional format and may have the following values:
If the resource is not specified, the "string" default value is assumed.
MinValue, MaxValue
Specify optional minimum and maximum values of the numerical input.
EnforceRange
For the numerical input, this optional resource defines how the values outside of the
[MinValue, MaxValue] range are handled. If it is defined and set to 0, the input values will not be adjusted and may exceed the range. If it is set to 1 or not defined, the input values outside of the range will be adjusted to fit inside the range.
InputInvalid
This resource contains the input status for numerical inputs, and may be set to the following values when the input is completed:
Value
This resource contains the entered value of the numerical input object.
ValueFormat
This resource specifies an optional C-style format that controls how the entered value is displayed in the numerical input object.

GlgText

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

TextObject
This resource indicates the scrolled text object where the text is to be typed.
TextString
This optional resource indicates the string attribute of the text object.
Focus
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.

GlgSpinner

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.

Value
The spinner's value.
MinValue, MaxValue
The spinner's minimum and maximum values (optional).
Wrap
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.
Increment
Increment for changing the value by using Increase and Decrease buttons.
PageIncrement
Increment for changing the value by using PageIncrease and PageDecrease buttons.
Increase, Decrease
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.
PageIncrease, PageDecrease
If buttons with these names are embedded into a spinner viewport, each press of a button changes the spinner's value in the direction corresponding to the button's name and by the amount defined by its PageIcrement.
IncreaseKeys, DecreaseKeys
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.
PageIncreaseKeys, PageDecreaseKeys
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.
TextInput
An optional text entry widget that may be used to display spinner's value.
Slider
An optional slider widget that may be used in a sliding spinner.
Done
An optional Done button for generating Activate message.
Messages

The GlgSpinner interaction handler supports the following messages that can be sent using the GlgSendMessage method:

Increase
Increases the spinner's value by its Increment. The message has no parameters.
Decrease
Decreases the spinner's value by its Increment. The message has no parameters.
PageIncrease
Increases the spinner's value by its PageIncrement. The message has no parameters.
PageDecrease
Decreases the spinner's value by its PageIncrement. The message has no parameters.

GlgNList

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. The Pan attribute of the widget's viewport can be used to enable or disable scrollbars.

InitItemList
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.
ItemList
A group object created by the list handler which contains the current list of strings displayed in the list widget.
SelectedIndex
In the single selection mode, the value of this resource is set to the 0-based index of the selected list item.
SelectedItem
In the single selection mode, the value of this resource is set to the string of the selected list item.
ItemStateList
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.
Messages

The GlgNList interaction handler supports the following messages that can be sent using the GlgSendMessage method:

SetInitItemList
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.
SetItemList
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.
GetItemList
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.
AddItem
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.
DeleteItem
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.
UpdateItemList
Updates the list's display after changing its ItemList. The message has no parameters.
GetItemCount
Returns a number of items in the list. This message has no parameters.
SetItemState
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.
GetItemState
Returns the state of the item specified by the zero-based index passed as the first parameter of the message.
SetItemStateList
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.
GetItemStateList
Returns a list of item states of a multiple-selection list widget. The list of states is returned as a group object containing integer values. This message has no parameters.
ResetAllItemsState
Deselects all selected items. This message has no parameters.
GetSelectedItemList
Returns a list of selected items. This message has no parameters and returns a group object containing integer values.

GlgNOption

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.

InitItemList
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.
ItemList
A group object created by the option menu handler which contains the current list of option strings displayed in the widget.
InitSelectedIndex
This optional resource (D type) provides a zero-based index of an item to be selected on the initial appearance of the option menu.
SelectedIndex
The value of this resource is set to the 0-based index of the selected option item when the selection is made. Setting this resource from a program changes the displayed selection.
SelectedItem
The value of this resource is set to the string of the selected option item.
Messages

The GlgNOption interaction handler supports the following messages that can be sent using the GlgSendMessage method:

SetInitItemList
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.
SetItemList
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.
GetItemList
Returns a current list of option menu items. This message has no parameters and returns a group object containing a list of strings.
AddItem
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.
DeleteItem
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.
UpdateItemList
Updates the widget's display after changing its ItemList. The message has no parameters.
GetItemCount
Returns a number of option menu items. This message has no parameters.

GlgMenu

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. Alternatively, a series object may be used to create a required number of buttons from the series' template, as shown in the menu widgets provided in the Special Widgets set. With either method, a menu widget manages the geometry of the buttons, resizing them proportionally when the menu is resized. If the number of buttons in the menu is changed after the drawing hierarchy has been set up, the menu has to be reset via the Builder's File, Reset Drawing menu option, or with the GlgSuspendObject and GlgReleaseObject API methods.

If a menu contains toggle buttons (buttons with OnState resource) and one of the SelectedIndex, SelectedString or SelectedValue menu resources are defined, the menu will behave as a radio menu, allowing the user to select only one toggle button. In this case, the SelectedIndex resource may be set to a value of a zero-based button index to select the corresponding button. If none of the selection state resources are defined, the menu will behave as a multiple-selection menu.

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 labels taken from the list by setting each button's LabelString resource, if it exists. 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 may be scrolled (an explicitly defined scrollbar named ScrollObject must be provided to facilitate scrolling).

Button<n>
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.
LabelList
An optional group object containing a list of the button labels (S data objects) to be displayed. If no such resource exists, the button's name or LabelString resource is used. To redraw button labels after changing strings in the list, reset the menu.
TooltipList
An optional group object containing a list of the tooltip strings (S data objects) used to initialize the buttons on hierarchy setup.
InitStateList
An optional group object containing a list of initial state values (D data objects) used to set the initial state of toggle buttons of a multiple-selection menu.
InitSelectedIndex
This optional resource (D type) provides a zero-based index of a toggle button to be selected on the initial appearance of a radio menu.
ScrollObject
If the list is too long for the menu window, a scroll object may be included. This is a vertical slider widget.
SelectedIndex, SelectedString, SelectedValue
These resources may be present in the menu viewport. They contain the index, label string, and token value of the last button pressed. They are more often used as resources of the message object returned when a menu button is pressed. However, the SelectedIndex resource may be used for selecting an item of a radio menu at run time by setting the resource to a zero-based button index.
Messages

The GlgMenu interaction handler supports the following message that can be sent using the GlgSendMessage method:

GetItemCount
Returns the number of buttons in the menu. The message has no parameters.

GlgBrowser and GlgFontBrowser

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

Menu
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).
Filter
This text widget displays the filter string used to display the entries in the menu. Only entries that match the filter are displayed.
Selection
This text widget displays the selection that will be made. To save typing, the browser usually echoes the filter string into this widget.
FontName (Font Browser only)
This is a string resource containing the name of the font chosen.
FontSampleName (Font Browser only)
This text object is used to display a sample of the chosen font. Its String resource is usually some sample sentence.
FieldMenu (Font Browser only)
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.
TypeObject
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.

Done
Pushing this button indicates that the selection has been made.
Cancel
Pushing this button sends a Cancel message, which may be used to erase the browser, without making a selection.
Reset
This button resets the filter to its default value.

GlgPalette

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.

PaletteObject
A container object presenting a variety of objects to be chosen by a user.

GlgClock

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. Alternatively, a Time Format and Time Display transformations can be used to display 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.

Hour, Min, Sec
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.
ValueHour, ValueMin, ValueSec
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.
TimeString
This string resource contains a character string indicating the time.
TimerState
If this resource is present, the widget functions as a stopwatch. If the clock is running, the TimerState is 1, otherwise it equals 0.
Start, Stop, Reset
These three resources each indicate a button widget. When the Start button is pushed, the stopwatch begins timing. The Stop button stops the clock, and the Reset button resets the time to zero.
Messages

The GlgClock interaction handler with the TimerState resource 9stopwatch) supports the following messages that can be sent using the GlgSendMessage method:

Start
Starts the stopwatch. The message has no parameters.
Stop
Stops the stopwatch. The message has no parameters.
Reset
Resets the stopwatch. The message has no parameters.

Native Widgets

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 Screen Attributes 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, 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, text field, list and option menu widgets.

For complete control over a native widget's resources, in both C/C++ , Java and C#/.NET, 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; GetResource method returning Object is the Java and C#/.NET equivalent). 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.

The widget types are listed in the table below, with their X Windows/Motif, Windows, Java and .NET equivalents. To learn how to control these widgets, refer to the documentation for the appropriate windowing environment.

Widget Types and Their Equivalences
GLG WidgetType
X Windows/Motif Widget Type
Windows
Window Class
Java Component Class
.NET Component Class
Drawing Area
XmDrawingArea
WINDOW
AWT: Panel
Swing: JPanel
UserControl
Push Button
XmPushButton
Push style BUTTON
AWT: Button
Swing: JButton
Button
Toggle Button
XmToggleButton
Toggle Style BUTTON
AWT: Checkbox
Swing: JCheckBox
CheckBox
Custom Button
XmDrawnButton
WINDOW
AWT: Panel
Swing: JPanel
UserControl
Arrows
(Left, Right, Up, and Down)
XmArrowButton
Push style BUTTON with Left, Right, Up or Down label.
AWT:
Button with a label
Swing:
JButton with a label
Button with a label
Scale
(Horizontal, Vertical)
XmScale
SCROLLBAR
AWT: Scrollbar
Swing: JSlider
HScrollbar
or
VScrollbar
Scrollbar
(Horizontal, Vertical)
XmScrollBar
SCROLLBAR
AWT: Scrollbar
Swing: JScrollBar
HScrollbar
or
VScrollbar
Text
XmTextField
EDIT (single line)
AWT: TextField
Swing: JTextField
TextBox
Text Edit
XmText
EDIT (multi-line)
AWT: TextArea
Swing: JTextArea
TextBox
Label
XmLabel
Text style STATIC
AWT: Label
Swing: JLabel
Label
Option Menu
XmOptionMenu
Drop-down List style COMBOBOX
AWT: Choice
Swing: JComboBox
ComboBox
Separator
XmSeparator
WINDOW
AWT: Panel
Swing: JPanel
UserControl
List
XmList
LISTBOX
AWT: List
Swing: JList
ListBox
Bulletin
XmBulletinBoard
WINDOW
AWT: Panel
Swing: JPanel
UserControl
Form
XmForm
WINDOW
AWT: Panel
Swing: JPanel
UserControl
Dialog Area
XmDrawingArea
WINDOW
AWT: Panel
Swing: JPanel
UserControl

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.

Input Objects Design and the ValueParam resource

Starting with the release 3.4, the output resources of input handlers, such as Value, ValueX, ValueY, OnState and others, have a corresponding resource whose name is formed by adding the "Param" suffix: ValueParam, ValueXParam, OnStateParam and so on. These resources are used only in the internal design of the input widgets and can be ignored in the application code.

The following section provides detailed information on the internal design of input widgets; it is intended for system integrators who want to create custom input widgets from scratch. This information is not required for using the Control Widgets provided with the Toolkit and can be safely skipped.

Advanced: Internals of the Input Objects

Widgets that use GlgSlider and GlgKnob input handlers use Move and Rotate transformations to move the widgets' active elements. A Range Conversion transformation is attached to the Factor attribute of the Move and Rotates transformations; the Input Value parameter of the range conversion transformation controls the slider's or knob's active element and is named Value, ValueX or ValueY depending on the widget type.

The Range Conversion transformation converts a user-defined range of the slider or knob to the [0;1] range of the Factor attribute that drives the widget's active element. When a range transformation is attached, an interaction handler needs to know the object IDs of both the Factor and Input Value parameters in order to properly animate the widget. To accomplish that, the Factor attribute is named by adding the "Param" suffix to the name of the corresponding controlling variable: ValueParam, ValueXParam or ValueYParam.

To allow the input object's output resources to be constrained to other resources in the drawing without the loss of the input widget functionality, the Value, ValueY or ValueY resources are defined as aliases using default attribute names relative to the corresponding resource with the Param suffix. For example, in a horizontal slider, the ValueX resource is defined as an alias to "ValueYParam/Xform/XformAttr6", which is relative to the ValueYParam resource. Since the default attribute names are not affected when the ValueY resource is constrained to a resource in the drawing with a different name, such constraining operation will not interfere with the functioning of the input handler. Previously, the resources in the drawing could be constrained to the input objects's output resources, but not visa versa.

To avoid resource name conflicts when Value, ValueX and ValueY resources are present in the drawing as both named resources and aliases, set HasResources of the active element or of the range transformation to make sure these resources are not visible at the top level directly, but only through the aliases.

For input widgets that do not have ranges, such as toggle buttons, the Identity transformation is used to enable the use of aliases in a similar way.

The new input objects were redesigned to support the functionality described above. The old widget design is still supported for backward compatibility.


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