Widget Encyclopedia : WkNumericEditor

WkNumericEditor
The WkNumericEditor widget provides a means for editing integer values. Since it is specifically designed for integers, WkNumericEditor ensures that only integers are entered. To further restrict valid values, the range of valid numbers can be bounded by minimum and a maximum values. A user can increment or decrement the values using up/down arrow keys or by selecting the up/down buttons. A user can change the value in an editable spin button by typing in the entry field.
Protocol
alignment: anInteger
Specifies the text alignment used by the widget.
Default: XmALIGNMENTEND (Right)
Valid resource values:
XmALIGNMENTBEGINNING (Left) - Causes the left side of the line of text to be vertically aligned with the left edge of the widget window.
XmALIGNMENTCENTER (Center) - Causes the center of the line of text to be vertically aligned in the center of the widget window.
XmALIGNMENTEND (Right) - Causes the right side of the line of text to be vertically aligned with the right edge of the widget window.
 
allowNil: aBoolean
Specifies whether the text field may have a blank (nil) value.
 
editable: aBoolean
Specifies whether a user can edit text in the entry field part of the spin button.
 
increment: anInteger
Specifies the amount to increase or decrease a numeric spin button when the corresponding arrow is selected.
 
maximum: anInteger
Specifies a numeric spin button’s maximum value.
 
minimum: anInteger
Specifies a numeric spin button’s minimum value.
 
value: aString
Specifies the initial value of the widget.
 
wrap: aBoolean
Specifies whether the spin button should cycle or stop upon reaching the end of the collection, or max or min for a numeric spin button.
Callbacks & Events
Activate Callback
These callbacks are triggered when the user presses the default action key. This is typically a carriage return.
 
Decrement Callback
These callbacks are triggered when the user decreases the spin button value by one step. This can happen either when the down arrow key is pressed or when the down arrow button is selected with the mouse.
 
Focus Callback
These callbacks are triggered before the entry field has accepted input focus.
 
Increment Callback
These callbacks are triggered when the user increases the spin button value by one step. This can happen either when the up arrow key is pressed or the up arrow button is selected with the mouse.
 
Losing Focus Callback
These callbacks are triggered before the entry field loses input focus.
 
Modify Verify Callback
These callbacks are triggered before text is deleted from or inserted into the widget. This callback can be used to check a character value after it is entered by the user and before it is accepted by the control.
Call data arguments:
doit - Indicates whether the action that invoked the callback is performed.
Setting doit to false negates the action.
text - a String which contains the text which is to be inserted.
currInsert - the current position of the insert cursor.
startPos - the starting position of the text to modify.
endPos - the ending position of the text to modify.
 
Value Changed Callback
These callbacks are triggered after text is deleted from or inserted into the widget. This callback can be used to retrieve the current value of the widget.
Editor
Alignment
Specifies the text alignment used by the widget.
Left - Causes the left side of the line of text to be vertically aligned with the left edge of the widget window.
Center - Causes the center of the line of text to be vertically aligned in the center of the widget window.
Right - Causes the right side of the line of text to be vertically aligned with the right edge of the widget window.
 
Allow Nil
Specifies whether the text field may have a blank (nil) value.
 
Border Width
Specifies the width of the border that surrounds the widget’s window on all four sides. The width is specified in pixels. A width of zero means that no border will show.
Border - Causes the widget to have a border.
No Border - Causes the widget to have no border.
 
Editable
Specifies whether a user can edit text in the entry field part of the spin button.
 
Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
 
Increment
Specifies the amount to increase or decrease a numeric spin button when the corresponding arrow is selected.
 
Maximum
Specifies a numeric spin button’s maximum value.
 
Minimum
Specifies a numeric spin button’s minimum value.
 
Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.
 
Value
Specifies the initial value of the widget.
 
Wrap
Specifies whether the spin button should cycle or stop upon reaching the end of the collection, or max or min for a numeric spin button.
Example
The following example code creates a WkNumericEditor with an initial value of 50 and a maximum and minimum bounds of 100 and –100 respectively. A center alignmnet has also been specified.
aWkNumericEditor := WkNumericEditor
createWidget: 'aWkNumericEditor'
parent: self form
argBlock: [:w | w
x: 48;
y: 77;
width: 148;
height: 24;
maximum: 100;
minimum: -100;
alignment: XmALIGNMENTCENTER;
value: 50;
increment: 5;
scale].
WkRadioButton
WkRadioButton provides a customizable version of a standard radio button. It has a boolean value that is set to true when the box is checked and false when the box is unchecked. The value is toggled on and off by clicking on the radio button. The state of a checkbox can be queried and changed using the #getState and #setState:notify: messages, respectively. Radiobuttons call their valueChanged callback when their state is changed. The textual label that appears to the right of the check box can be changed at runtime with the #labelString: message.
Protocol
alignment: resourceValue
Sets the horizontal alignment for the widget's image.
check
Set the receiver's state to checked (true).
click
Programatically click the button.
drawPolicy: anInteger
Specifies the drawing policy used in rendering buttons. The drawing policy determines two things for a button:
1. how the button draws itself so it looks like a button;
2. how the button animates when pressed.
Default: XmFLATDRAWPOLICY (Flat)
Valid resource values:
XmSHADOWEDTWOSTATEDRAWPOLICY (Shadowed Two State) - Buttons are drawn with a 3D shadowed outline and exhibit a simple 2-state (OFF and ON) state rendering.
XmSHADOWEDTHREESTATEDRAWPOLICY (Shadowed Three State) - Buttons are drawn with a 3D shadowed outline and exhibit a 3-state (OFF, ON, and PRESSED) state rendering.
XmOUTLINEDRAWPOLICY (Outlined) - Buttons are drawn with a simple etched (non-shadowed) outline and exhibit a 2-state (OFF and ON) state rendering.
XmFLATDRAWPOLICY (Flat) - Buttons are drawn flat without a 3D shadow.
 
getState
Answer the state of the checkbox.
 
horizontalAlignment: anInteger
Specifies the horizontal alignment for the widget's image.
Default: XmALIGNMENTBEGINNING (Left)
Valid resource values:
XmALIGNMENTBEGINNING (Left) - Causes the center of the image to be horizontally aligned with the left edge of the widget's window.
XmALIGNMENTCENTER (Center) - Causes the center of the image to be horizontally aligned in the center of the widget's window.
XmALIGNMENTEND (Right) - Causes the center of the image to be horizontally aligned with the right edge of the widget's window.
 
labelCheckedString: aString
Specifies the renderable object (string) which draws on the face of the widget when it is checked.
 
labelInsensitiveString: aString
Specifies the renderable object (string) which draws on the face of the widget when it is disabled.
 
labelPressedString: aString
Specifies the renderable object (string) which draws on the face of the widget when it is pressed.
 
labelString: aString
Specifies the renderable object (string) which draws on the face of the widget.
 
mnemonic: aCharacter
Provides the user with alternate means for selecting a button.
 
orientation: anInteger
Specifies whether the image and label are displayed vertically or horizontally.
Default: XmHORIZONTAL (Horizontal)
Valid resource values:
XmVERTICAL (Vertical) - Displays the image and label vertically.
XmHORIZONTAL (Horizontal) - Displays the image and label horizontally.
 
set: aBoolean
Displays the button in its selected state if set to true.
 
setState: newState notify: notify
Sets or changes the EwToggleButton's current state.
newState - Specifies a Boolean value that indicates whether the checkbox state is selected or unselected. If true, the button state is selected; if false, button state is unselected. notify - Indicates whether valueChangedCallback is it can be either true or false.
 
turnOff
Set the receiver's state to off (false).
 
turnOn
Set the receiver's state to on (true).
 
uncheck
Set the receiver's state to unchecked (false).
 
verticalAlignment: anInteger
Specifies the vertical alignment for the widget's image.
Default: XmALIGNMENTCENTER (Center)
Valid resource values:
XmALIGNMENTCENTER (Center) - Causes the center of the image to be vertically aligned in the center of the widget's window.
XmALIGNMENTTOP (Top) - Causes the top edge of the image to be vertically aligned with the top edge of the widget's window.
XmALIGNMENTBOTTOM (Bottom) - Causes the center of the image to be vertically aligned in the center of the widget's window.
Callbacks & Events
Arm Callback
These callbacks are triggered when the button is armed. Buttons are armed and appear pressed whenever the moused is pressed within the button and not yet released. If the mouse is moved outside of the button while still pressed, the button will be disarmed and appear unpressed. If the mouse is released while still in the button, the button is activated
 
Default Action Callback
These callbacks are triggered when the widget is double clicked.
 
Disarm Callback
These callbacks are triggered when the button is disarmed. Buttons are disarmed whenever the mouse is moved outside of the button after it has been armed. Moving the mouse back over the button while the mouse button is still down will cause the button to become rearmed.
 
Value Changed Callback
These callbacks are triggered when the checkbox value is changed.
Call data arguments:
set - a Boolean value indicating if the checkbox is toggle on (true) or off (false).
Editor
Border Width
Specifies the width of the border that surrounds the widget’s window on all four sides. The width is specified in pixels. A width of zero means that no border will show.
Border - Causes the widget to have a border.
No Border - Causes the widget to have no border.
 
Draw Policy
Specifies the drawing policy used in rendering buttons. The drawing policy determines two things for a button:
1. how the button draws itself so it looks like a button;
2. how the button animates when pressed.
Shadowed Two State - Buttons are drawn with a 3D shadowed outline and exhibit a simple 2-state (OFF and ON) state rendering.
Shadowed Three State - Buttons are drawn with a 3D shadowed outline and exhibit a 3-state (OFF, ON, and PRESSED) state rendering.
Outlined - Buttons are drawn with a simple etched (non-shadowed) outline and exhibit a 2-state (OFF and ON) state rendering.
Flat - Buttons are drawn flat without a 3D shadow.
 
Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
 
Horizontal Alignment
Specifies the horizontal alignment for the widget's image.
Left - Causes the center of the image to be horizontally aligned with the left edge of the widget's window.
Center - Causes the center of the image to be horizontally aligned in the center of the widget's window.
Right - Causes the center of the image to be horizontally aligned with the right edge of the widget's window.
 
Label - Default
Specifies the default label string.
 
Label - Pressed
Specifies the label string when the widget is pressed.
 
Label - Disabled
Specifies the label string when the widget is disabled.
 
Label - Checked
Specifies the label string when the widget is checked.
 
Mnemonic
Provides the user with alternate means for selecting a button.
 
Orientation
Specifies whether the image and label are displayed vertically or horizontally.
Vertical - Displays the image and label vertically.
Horizontal - Displays the image and label horizontally.
 
Set
Displays the button in its selected state if set to true.
 
Vertical Alignment
Specifies the vertical alignment for the widget's image.
Center - Causes the center of the image to be vertically aligned in the center of the widget's window.
Top - Causes the top edge of the image to be vertically aligned with the top edge of the widget's window.
Bottom - Causes the center of the image to be vertically aligned in the center of the widget's window.
 
Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.
Example
The following example code creates a blue WkRadioButton that is oriented vertically (e.g., checkbox above the label) and centered horizontally within its bounds.
aWkRadioButton := WkRadioButton
createWidget: 'aWkRadioButton'
parent: self form
argBlock: [:w | w
x: 50;
y: 54;
width: 88;
height: 28;
foregroundColor: (CgRGBColor
red: 16r0
green: 16r0
blue: 16rFF00);
horizontalAlignment: XmALIGNMENTCENTER;
labelString: 'RadioButton';
orientation: XmVERTICAL;
scale].
 
WkSpinButton
The WkSpinButton widget provides a compact editor for choosing one string from a set of choices. This functionality is similar to a list box or combo box, but it uses two small arrows to allow the user to scroll through the possible choices, one at a time. Since a spin button does not display all of the choices at once, it is best suited for sets of choices that have obvious members. And because the choices are stepped through in order, the spin button makes the most sense when the set of choices are familiarly ordered. Examples would be the days of the week or the answers to a survey question (Strongly Agree, Agree, No Opinion, Disagree, Strongly Disagree).
Spin buttons take as their contents an OrderedCollection of strings. The strings can be displayed in the spin button in one of three formats: left justified, right justified, or centered. When a new item is selected by the user, the valueChanged callback will occur.
A user can increment or decrement the values using up/down arrow keys or by selecting the up/down buttons. A user can change the value in an editable spin button by typing in the entry field.
Protocol
alignment: anInteger
Specifies the text alignment used by the widget.
Default: XmALIGNMENTEND (Right)
Valid resource values:
XmALIGNMENTBEGINNING (Left) - Causes the left side of the line of text to be vertically aligned with the left edge of the widget window.
XmALIGNMENTCENTER (Center) - Causes the center of the line of text to be vertically aligned in the center of the widget window.
XmALIGNMENTEND (Right) - Causes the right side of the line of text to be vertically aligned with the right edge of the widget window.
 
allowNil: aBoolean
Specifies whether the text field may have a blank (nil) value.
 
editable: aBoolean
Specifies whether a user can edit text in the entry field part of the spin button.
 
items: anOrderedCollection
Specifies the list of Strings being spun over.
 
value: aString
Specifies the initial value of the widget.
 
wrap: aBoolean
Specifies whether the spin button should cycle or stop upon reaching the end of the collection, or max or min for a numeric spin button.
Callbacks & Events
Activate Callback
These callbacks are triggered when the user presses the default action key. This is typically a carriage return.
 
Decrement Callback
These callbacks are triggered when the user decreases the spin button value by one step. This can happen either when the down arrow key is pressed or when the down arrow button is selected with the mouse.
 
Focus Callback
These callbacks are triggered before the entry field has accepted input focus.
 
Increment Callback
These callbacks are triggered when the user increases the spin button value by one step. This can happen either when the up arrow key is pressed or the up arrow button is selected with the mouse.
 
Losing Focus Callback
These callbacks are triggered before the entry field loses input focus.
 
Modify Verify Callback
These callbacks are triggered before text is deleted from or inserted into the widget. This callback can be used to check a character value after it is entered by the user and before it is accepted by the control.
Call data arguments:
doit - Indicates whether the action that invoked the callback is performed.
Setting doit to false negates the action.
text - a String which contains the text which is to be inserted.
currInsert - the current position of the insert cursor.
startPos - the starting position of the text to modify.
endPos - the ending position of the text to modify.
 
Value Changed Callback
These callbacks are triggered after text is deleted from or inserted into the widget. This callback can be used to retrieve the current value of the widget.
Editor
Alignment
Specifies the text alignment used by the widget.
Left - Causes the left side of the line of text to be vertically aligned with the left edge of the widget window.
Center - Causes the center of the line of text to be vertically aligned in the center of the widget window.
Right - Causes the right side of the line of text to be vertically aligned with the right edge of the widget window.
 
Allow Nil
Specifies whether the text field may have a blank (nil) value.
 
Border Width
Specifies the width of the border that surrounds the widget’s window on all four sides. The width is specified in pixels. A width of zero means that no border will show.
Border - Causes the widget to have a border.
No Border - Causes the widget to have no border.
 
Editable
Specifies whether a user can edit text in the entry field part of the spin button.
 
Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
 
Items
Specifies the list of Strings being spun over.
 
Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.
 
Value
Specifies the initial value of the widget.
 
Wrap
Specifies whether the spin button should cycle or stop upon reaching the end of the collection, or max or min for a numeric spin button.
Example
The following example code creates a WkSpinButton that has been initialized with the days of the week. The initial value has been set to “Sunday”.
spinButton := WkSpinButton
createWidget: 'spinButton'
parent: self form
argBlock: [:w | w
x: 184;
y: 212;
width: 124;
height: 22;
value: 'Sunday';
items: #('Sunday' 'Monday' 'Tuesday'
'Wednesday' 'Thursday' 'Friday' 'Saturday');
scale].
WkTableColumn
The WkTableColumn class defines a single column in an WkTableWidget or WkColumnarListBox widget. In addition to details about the look and feel of the column, it also provides get and set selectors which the application may use to specify the cell value for an item in that column and a list selector for specifying a dropdown list of values for a cell. The cell values may be further augmented through a cell value callback. The column also provides callbacks to notify the application when a cell is about to be edited and when the edit is about to end.
Note: WkTableColumn objects may only be created from within the WkTableWidget or WkColumnarListBox editors.
Protocol
autosize: aBoolean
Specifies whether the column width should be autosized.
 
characterValidation: aSymbol
Specifies the character validation function to use with values entered into cells within the column.
Default: #okAny: (Any)
Valid resource values:
#ok20Comma10: (20Comma10) - Validates whether each character is a valid for a 20,10 field.
#ok7Comma2: (7Comma2) - Validates whether each character is a valid for a 7,2 field.
#ok7Comma4: (7Comma4) - Validates whether each character is a valid for a 7,4 field.
#okAlpha: (Alpha) - Validates whether each character is a valid alpha character ($A - $Z, $a - $z or space).
#okAlphaNoSpace: (AlphaNoSpace) - Validates whether each character is a valid alpha character ($A - $Z, $a - $z).
#okAlphaNumeric: (AlphaNumeric) - Validates whether each character is a valid alpha-numeric character ($A - $Z, $a - $z, $0 - $9, or space).
#okAlphaNumericNoSpace: (AlphaNumericNoSpace) - Validates whether each character is a valid alpha character ($A - $Z, $a - $z, $0 - $9).
#okAny: (Any) - Any character is valid.
#okBoolean: (Boolean) - Validates whether each character is a valid Boolean value (e.g., T, t, F, f, Y, y, N, or n).
#okCurrency: (Currency) - Validates whether each character is a valid currency value.
#okInteger: (Integer) - Validates whether each character is a valid Integer value.
#okNumeric: (Numeric) - Validates whether each character is a valid numeric value.
#okPositive10Comma10: (Positive10Comma10) - Validates whether each character is a valid for a positive 10,10 field.
#okPositiveInteger: (PositiveInteger) - Validates whether each character is a valid positive Integer.
#okPositiveNumeric: (PositiveNumeric) - Validates whether each character is a valid positive numeric value.
 
disabledSelector: aSymbol
Specifies selector sent to the row object to determine whether a cell should be disabled.
 
editable: aBoolean
Specifies whether the cells in this column are editable.
 
etched: aBoolean
Specifies whether this column is to be etched.
 
fieldValidation: aSymbol
Specifies the field validation function to use with values entered into cells within the column.
Default: #okAny (Any)
Valid resource values:
#okAny (Any) - Any characters are valid.
#okCurrency (Currency) - Formats the contents of the field to be a currency value.
#okCurrencyNoDecimal (CurrencyNoDecimal) - Formats the contents of the field to be a currency value without decimal places.
#okDate (Date) - Validates whether the contents of the field are a valid Date value and then formats the Date using the system Date format.
#okInteger (Integer) - Formats the contents of the field to be an Integer value.
#okNumber (Number) - Formats the contents of the field to be a numeric (e.g., Float) value.
#okPhoneNumberExtUS (PhoneNumberExtUS) - Validates and formats the contents of the field to be a US phone number with optional extension. Valid formats are: (999) 999-9999, 999-9999, x999, (999) 999-9999 x999.
#okPhoneNumberUS (PhoneNumberUS) - Validates and formats the contents of the field to be a US phone number. Valid formats are: (999) 999-9999, 999-9999.
#okRound2 (Round2) - Formats the contents of the field to be rounded to 2 decimal places.
#okRound3 (Round3) - Formats the contents of the field to be rounded to 3 decimal places.
#okSSN (SSN) - Validates and formats the contents of the field to be a US Social Security Number. Format is: 999-99-9999.
#okZipCodeUS (ZipCodeUS) - Validates and formats the contents of the field to be a US Zip Code. Valid format are: 99999 or 99999-9999.
 
getSelector: aSymbol
Specifies selector sent to the row object to retrieve the data for the cell.
 
heading: aString
Specifies the heading object to be displayed at the top of the column.
 
horizontalAlignment: anInteger
Specifies how the cells in this column should be aligned horizontally.
Default: XmALIGNMENTBEGINNING (Left)
Valid resource values:
XmALIGNMENTBEGINNING (Left) - Align the cells to the left.
XmALIGNMENTCENTER (Center) - Align the cells to the center.
XmALIGNMENTEND (Right) - Align the cells to the right.
 
horizontalHeadingAlignment: anInteger
Specifies how this column’s heading should be aligned horizontally.
Default: XmALIGNMENTBEGINNING (Left)
Valid resource values:
XmALIGNMENTBEGINNING (Left) - Align the heading to the left.
XmALIGNMENTCENTER (Center) - Align the heading to the center.
XmALIGNMENTEND (Right) - Align the heading to the right.
 
listSelector: aSymbol
Specifies selector sent to the row object to retrieve a list of values to populate the drop down list in the cell.
 
minWidth: anInteger
Specifies the minimum width of the column in pixels. This minimum applys to autosizing and user resizing operations.
 
name: aString
Specifies the name of the column. This name may be used to programatically access the column. Note that this is distint from the heading of the column.
 
reorderable: aBoolean
Specifies whether the column is reorderable (can be draged left and right).
 
resizable: aBoolean
Specifies whether the column is resizable by the user. If so, the user can drag the right side of the column heading to change the column width
 
setSelector: aSymbol
Specifies selector sent to the row object to store data entered into the cell.
 
showInUse: aBoolean
Specifies whether the column should show the inUse emphasis for each item.
 
sortable: aBoolean
Specifies whether the column is sortable.
 
verticalAlignment: anInteger
Specifies how the cells and heading in this column should be aligned vertically.
Default: XmALIGNMENTBEGINNING (Top)
Valid resource values:
XmALIGNMENTBEGINNING (Top) - Align the cells to the top.
XmALIGNMENTCENTER (Center) - Align the cells to the vertical center.
XmALIGNMENTEND (Bottom) - Align the cells to the bottom.
 
verticalSeparatorThickness: anInteger
Specifies the thickness of the line shown to the right of each cell in the column.
 
width: anInteger
Specifies the width of the column in pixels. This does not includes the width of any emphasis or vertical separator.
Callbacks & Events
Begin Edit Callback
These callbacks are triggered when an item is about to be edited.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
doit - indicates whether the action that invoked the callback is performed.
editPolicy - the edit policy to be used to edit the cell value.
value - the value of the cell which is about to be edited.
 
Cell Value Callback
These callbacks are triggered when an item’s cell value is needed for this column.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
column - the EwTableColumn for which a cell value is needed.
value - the value of the cell which is about to be edited.
 
End Edit Callback
These callbacks are triggered when an item is done being edited.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
doit - indicates whether the action that invoked the callback is performed.
editPolicy - the edit policy to be used to edit the cell value.
value - the value of the cell which is about to be edited.
 
WkTableWidget
The WkTableWidget widget provides a vertical, multi-column tree of items which shows a row of cells for each item in the list. Cells are edited in-line, simply by selecting them with the mouse or keyboard, and changing the text with the text editor that appears in the selected cell. The items in the list are typically actual application objects, not strings or arrays. For example, the items (rows) might be employee objects, and the columns might show the name, salary, and hire date for each employee. The application should only set the root level items in the tree as the items in the widget. The descendants of those root items can then be shown by clicking on the collapse/expand icons.
The programmer chooses how the objects in the table will be viewed by defining a collection of fields, one for each column. These fields are each instances of the class WkTableColumn, and describe the header, font, justification, field width, fore and back color, validation functions and accessor methods for a particular column. The header is the string that will be displayed at the top of the listbox for that field. The font is the font used to display the column. The justification can be one of left, right, and center. The field width is the number of pixels wide that this field should be; if it is autosizable, the field will be as wide as the widest value displayed in this column. The fore and back colors affect the presentation of data in the cells. The validation functions can be any of those supported by WbEnhancedText. The accessor methods are the messages which will be sent to the object to retrieve a string to display for this field and to update the object when the user changes a cell’s value.
The visual aspect of each columns can be further augmented by using the cellValueCallback. The application may hook this callback on each column. This callback fires whenever the widget needs to know what value to put in a cell for a given item. The application can then set the callData value to be the renderable object (see below) which is to reside in the cell. For example, when the widget needs to place an employee’s salary in the salary column, it fires the callValueCallback. The callData tells for which employee the salary is needed (callData item). The application might hook the cellValueCallback from the Salary column to a method like:
salary: aWidget clientData: clientData callData: callData
“The widget needs an employee’s salary.”
| employee |
employee := callData item.
callData value: employee salary.
To access cells in the table, use the methods #atRow:column: and #atRow:column:put:. These can take either numeric indices, or the string names of the corresponding row or column.
The application may or may not hook the headingCellValueCallback. Column headings can be set via the WkTableColumn>>heading: method or via the headingCellValueCallback.
Both the headingCellValueCallback and cellValueCallback can be used to set color for a particular cell. Colors can be specified for the foreground, background, selectedForeground, and selectedBackground of a cell
The objects used for cell values and headings are typically Strings, Numbers, and CgIcons, but this is not a requirement. It is possible for an application to use any object as the cell value or heading. Any item which understands #ewHeightUsing:, #ewWidthUsing: and #ewDrawUsing: (called a “renderable object”) can be used for a cell value. Since String, Number, and CgIcon already implement the standard renderable object protocol, they can easily be used. Also, since Object provides default renderable behavior, any object can be rendered, although the default rendering is to render the object’s printString.
Navigation, selection, and editing modes determine the operation of a table pane at runtime. Two navigation modes govern whether the right and left arrow keys move the input focus between the characters within a cell or between cells. In the default mode, Arrow Keys Edit, the arrow keys move within a cell; Ctrl plus right or left arrow moves between cells. In Arrow Keys Move mode, the right and left arrow keys move the focus between cells.
If the entire table pane is in Read Only mode, arrow keys move between cells and no alphanumeric keyboard input is accepted. Columns or individual cells can be set to read only or disabled.
Cells can behave like simple text entry fields, drop-down lists, combo boxes or check boxes. If editing is allowed in a cell, it processes normal keyboard input according to the type of cell. For example, if a cell contains a drop-down list, you can open the list by clicking on the downward pointing arrow that is visible when the cell has focus and move the selection in the list with the up and down arrow keys.
Cell editing can take place automatically or under program control. For cell editing to be automatic, the widget must have editable true, and the columns in which cells may be edited must also have editable true. Under program control, this is not required.
When a cell is about to be edited, either because the user clicked in it or because the program called #editCellAt: or #editSelectedCell, the column fires its beginEditCallback. The application may hook this callback to augment the default cell editing process. At a minimum, the callData doit: must be set to true to allow editing to begin (this is the default).
The callData also includes a default editPolicy. The edit policy defines the type of widget to be used for editing as well as some other edit semantics. The default edit policy is an WkTextEditPolicy set up to use a single-line CwText as the edit widget or an WkComboBoxEditPolicy set up to use a combo box as the edit widget. The application can substitute a more appropriate edit policy for the cell about to be edited. Applications can define their own custom edit policies by overriding the behavior in EwEditPolicy as required. The supplied subclasses of EwEditPolicy serve as good examples for this.
When editing is about to end, or when the value in the edit widget has been changed (the exact details of when a change has occurred depend on the edit policy), the column automatically updates the appropriate application object using the #setSelector:. The column also fires its endEditCallback. The callData includes the old value and the new value. The application can hook this callback and use the newValue to change some application object. The cell is then automatically refreshed after the callback fires, so the new value is obtained and displayed.
The WkTableWidget supports Cell, Single, Multi, and Extended selection modes. Cell select mode is the default mode of operation. In this mode, you can select single cells only; clicking on row headers has no effect. In single select mode, the table acts like a single select list box when either a row header or a disabled/read-only cell is selected. Clicking on a cell that supports data entry causes the cell to be selected and the row selection to be lost. In multi select mode, the table behaves like a multiple select list box. Multiple rows may be selected and deselected. In extended select mode, the table emulates an extended select list box. Without modifier keys, extended select mode acts like single select mode. If the Shift or Ctrl keys are held down, multiple rows can be selected.
Setting up the children for each object is done similarly: at initialization time, you supply the list box with a message to send to each object in the list box to retrieve a collection of its children. This is accomplished by sending the message #childrenSelector: to the WkTableWidget, with a symbol matching the message you want sent. If no children method is provided, the list box will not be hierarchical, and will act as a normal list box.
As mentioned above, each object in the list box can have an icon associated with it. As with #childrenSelector:, this is accomplished by supplying an #iconSelector: to the list box at initialization time. The associated method will then be sent to each object in the list, giving the object the opportunity to pass back an icon (or any other renderable object including nil if no icon should be displayed). If no #iconSelector: is specified, the list box will not display an icons. An optional different icon may be displayed when the object is expanded via sending #iconExpandSelector: to the list box.
The hierarchical aspect of the list be further augmented by using the visualInfoCallback and the childrenCallback. The application must hook the visualInfoCallback and set the callData hasChildren to true or false to indicate whether the item in callData item has children. The application must also hook the childrenCallback and set the callData value to be the list of children for the item in callData item. The childrenCallback only fires for items for which hasChildren is true.
The hierarchyPolicy determines how the hierarchy is to be shown. This includes what the indentation level should be as well as whether to draw lines connecting the items and whether to show some kind of button beside items which have children. By default the hierarchyPolicy is an instance of EwHierarchyPolicy with lines set to true. The other hierarchy policy class provided is EwIconHierarchyPolicy. This class shows an icon beside each item to act as an expand/collapse button. The application can specify which icon to use in different situations so that the button can animate properly as it is pressed. The indentation, lines, and buttons are only shown in the first column.
Protocol
addedAt: position count: count
Item(s) were added to the collection of root items at the specified position. The position is specified as an index in the collection of root items only. Refresh the list.
 
applicationDrawnBackground: aBoolean
Specifies whether the application wants the Draw Background Callback to fire when an item’s background needs to be drawn. If this value is false, then the widget will draw the normal default background for each selected and non-selected item.
 
allowCellEditingInRowSelectModes: aBoolean
Specifies whether cell editing is allowed in row select modes.
 
atRow: row column: column
Answer the string that is at column@row. If there is no value, an empty string will be returned. If there are labels (or name) associated with a given row or column, the argument for that coordinate may be a string corresponding to the label (or column name). Example include: 1@'Name', 'Name'@1, 'Name'@'Year', 1@1
 
atRow: row column: column put: newValue
Set the value that is at column@row to newValue. If there are labels (or name) associated with a given row or column, the argument for that coordinate may be a string corresponding to the label (or column name). Example include: 1@'Name', 'Name'@1, 'Name'@'Year', 1@1
 
autosize: aBoolean
Specifies whether the autosizable columns should be autosized whenever the widget resizes.
 
autoSizeColumnWidths
Autosize all of the autosizable columns
 
autoSizeColumnWidthsIfPossible
Autosize all of the autosizable columns if autosize is turned on
 
buttonPolicy: anInteger
Specifies how the hierarchy buttons should be displayed (e.g., as buttons, as triangles or not at all.
Default: XmTREEHIERARCHYBUTTONS (Buttons)
Valid resource values:
XmTREEHIERARCHYBUTTONS (Buttons) - Causes hiearchy expand/collapse indicators to be displayed as buttons.
XmTREEHIERARCHYTRIANGLES (Triangles) - Causes hiearchy expand/collapse indicators to be displayed as triangles.
XmTREEHIERARCHYNONE (None) - Suppresses the display of any expand/collapse indicators.
 
cancelEdit
Call the end edit callbacks and proceed with a cancel of the edit if approved. Hide the edit widget only if the end was approved. The last committed value for the edited item will be provided as the newValue during the endEditCallback. Edit changes are committed when the updateEdit or endEdit API is invoked. This method will answer whether or not the cancelEdit was approved.
 
cellAt: aPoint
Answer the value that is at aPoint.
 
cellAt: aPoint put: newValue
Set the value that is at aPoint to newValue.
 
cellBackgroundColor: aCgRGBColor
Specifies the background color for cells.
 
cellTabbingPolicy: anInteger
Specifies how tabbing should occur amongst cells.
Default: XmACROSSROWS (Across Rows)
Valid resource values:
XmACROSSROWS (Across Rows) - When the last cell in a row is reached when tabbing forward, go to the first cell in the next row. When the first cell in a row is reached when tabbing backwards, go to the last cell in the previous row.
XmAPPLICATIONDEFINED (Application Defined) - Tabbing behavior is defined by the application. To use this option, the application must hook the Cell Tab Callback.
XmWITHINROW (Within Row) - When the last cell in a row is reached when tabbing forward, go to the first cell in the same row. When the first cell in a row is reached when tabbing backwards, go to the last cell in the same row.
 
childrenSelector: aSymbol
Specifies a unary selector sent to an item to return its children.
 
colorSelector: aSymbol
Specifies a unary selector sent to an item to return its label color.
 
cursorPolicy: anInteger
Specifies how cursor keys will be treated.
Default: XmARROWKEYSEDIT (Edit)
Valid resource values:
XmARROWKEYSEDIT (Edit) - Causes the arrow keys to move within a cell.
XmARROWKEYSMOVE (Move) - Causes the arrow keys to move betwenn cells.
 
cursorToCell: cellPoint
Move the focus for the receiver to the given cell. Cursored emphasis will be placed on the cell. This API can be used after the widget has been created and initially exposed. The API is only valid when the selectionPolicy is XmCELLSINGLESELECT or XmCELLBLOCKSELECT.
 
deferRefreshWhile: aBlock
Minimize the repainting done while aBlock is being evaluated. This message may be safely nested. This message does not guarantee minimal repainting. Rather, it serves as a hint to the widget so that, where possible and appropriate, repainting can be deferred until the block has finished being evaluated.
 
deleteAllItems
This message deletes all items from the list.
 
deletedAt: position count: count
Item(s) were deleted from the collection of root items at the specified position. The position is specified as an index in the collection of root items only. Refresh the list.
 
deselectAllCells
Deselect all cells. A selection callback is not triggered.
 
deselectAllItems
Deselect and remove all elements from the selectedItems list. A selection callback is not triggered.
 
deselectCell: cellPoint
Deselect a cell by item and column position. A selection callback is not triggered. This function is only valid if the selectionPolicy value is XmCELLSINGLESELECT.
 
deselectColumn: column
Deselect the column given. This message unhighlights the heading of the specified column.
 
deselectItem: item
Deselect and remove the specified item from the selected list. A selection callback is not triggered.
 
deselectPos: position
Deselect and remove an item from the selected list by position. A selection callback is not triggered.
 
disabledBackgroundColor: aCgRGBColor
Specifies the background color for disabled cells.
 
disabledForegroundColor: aCgRGBColor
Specifies the foreground color for disabled cells.
 
disabledSelector: aSymbol
Specifies selector sent to the row object to determine whether the row should be disabled.
 
editable: aBoolean
Specifies whether the cells in the table are editable. For a cell to be editable, the table widget must be editable, the column must be editable, and the application must hook the Begin Edit Callback and set the callData doit to true
 
editCellAt: cellPoint
Edit a cell in the list by item and column position. This message highlights a table cell at the specified point and begins editing on it by calling the beginEdit callback. If editing is already in progress, the endEdit API will be invoked and if the end edit is successful, editing for the new cell will begin. This API will provide cell editing behavior independent of the values of the WkTableWidget>>editable, WkTableColumn>>editable, and WkTableWidget>>selectionPolicy resources. It is used to trigger editing by some means other than cell selection.
 
editSelectedCell
Begin editing the selected cell. If editable is true, this message is not needed, since selecting a cell automatically edits it. Otherwise, this calls the beginEdit callback. If editing is already in progress, the endEdit API will be invoked and if the end edit is successful, editing for the new cell will begin.
 
endEdit
Call the end edit callbacks and proceed with an end to the edit if approved. Hide the edit widget only if the end was approved. Answer whether the end was approved.
 
expandCollapsePos: position notify: notify
Expand or collapse an item in the list by position to show or hide its children. If it is expanded, collapse it. If it is collapsed, expand it.
 
getItemPos: position
Answer the item in the list by position. This message answers a list item at the specified position or nil if position is greater than the size of the list. This message only accesses the list if the item is not visible.
 
getMatchPos: item
This message returns an Array of Integer positions where a specified item is found in the items list. If the item does not occur in the list the resulting Array is empty.
 
getSelectedPos
Return an Array containing the positions of every selected item in the list.
 
hasChildrenSelector: aSymbol
Set the unary selector sent to an item to return whether it has children.
 
headingBackgroundColor: aCgRGBColor
Specifies the background color for headers.
 
headingFont: aString
Specifies the font list associated with the headings.
 
headingForegroundColor: aCgRGBColor
Specifies the foreground color for headers.
 
headingHeight: anInteger
Specifies the height, in pixels, of the table's heading row. If unspecified (i.e., a nil value), the heading height will be automatically calculated to be the height of the tallest heading cell value. This height does not include sizings for etching, the heading separator, or other margins.
 
headingSeparatorThickness: anInteger
Specifies the thickness of the horizontal line separating the column headings from the rest of the table.
 
headingVisualStyle: anInteger
Defines the how the cells are displayed.
Default: XmETCHCELLS (Etch Cells)
Valid resource values:
XmFLAT (Flat) - Looks like a list box.
XmETCHROWS (Etch Rows) - Each row is etched.
XmETCHCELLS (Etch Cells) - Each cell in an etched column is individually etched.
 
hierarchyPolicy: resourceValue
Specifies how to display and manage the hierarchy. For more information about hierarchy policies, refer to EwHierarchy and its subclasses.
 
iconExpandSelector: aSymbol
Specifies a unary selector sent to an item to return its expanded icon.
 
iconSelector: aSymbol
Specifies a unary selector sent to an item to return its icon.
 
indentationWidth: anInteger
Specifies how many pixels each level of the hierarchy should be indented.
 
indexAtPoint: aPoint
Answer the index of the item in the list which lies beneath the point given. If no item lies beneath the point or if the widget has not been drawn yet, then answer nil.
 
indexOf: item
Answer the index of the item given in the list or 0 if the item is not present in the list.
 
indexOfVisibleItem: item
Answer the index of item if it is visible, nil if it is not.
 
initialStateSelector: aSymbol
Specifies a unary selector sent to an item to return its initial state (expanded or not).
 
isDisabled: item
Answer whether the item is disabled.
 
isEditingInProgress
Answer whether a cell is being edited.
 
isExpandedPos: position
Answer whether an item in the list by position is expanded to show its children.
 
isSelected: index
Answer whether the item is selected
 
itemAtPoint: aPoint
Answer the item in the list which lies beneath the point given.If no item lies beneath the point, then answer nil.
 
itemCount
Specifies the total number of items. This number might not match XmNitems, since this number is the size of the expanded hierarchy. It is automatically updated by the list whenever an element is added to or deleted from the list."
 
itemExists: item
Answer whether a specified item is in the list.
 
itemHeight: anInteger
Specifies the height in pixels of items in the list. This includes the margin height on the top and bottom of the item as well as two pixels for emphasis.
 
itemIsVisible: item
Check if a specified item is in the portion of the list that is currently visible. Answer true if it is even partially visible, false if it is not visible.
 
items: anOrderedCollection
An array of objects that are to be displayed as the list items.
 
itemsDo: aBlock
Evaluate aBlock for each item in the receiver's list.
 
lines: aBoolean
Specifies whether the widget should display hierarchy lines.
 
lockedColumns: anInteger
Specifies the number of columns to be locked down on the left side of the table. A column can be locked only if its preceding column is also locked. When scrolling, the locked columns remain fixed on the left side and all other columns scroll under the locked columns. This value must be no greater than the number of columns.
 
parentOfItem: anItem
Answer the parent of the item given in the hierarchy or false if it is not in the expanded hierarchy. Answer nil if it is a root item.
 
refreshCell: cellPoint
Refresh a cell by item and column position.
 
refreshHierarchyPos: position
Refresh an item in the list by position. Also reobtain the item's children.
 
refreshItem: item
Refresh an item in the list.
 
refreshNodeAt: position
Refresh the node at the given position. Answer whether or not a full refresh occurred.
 
refreshPos: position
Refresh an item in the list by position.
 
reorderable: aBoolean
Specifies whether all of the columns should be reorderable (can be draged left and right).
 
resizable: aBoolean
Specifies whether all of the columns should be resizable by the user. If so, the user can drag the right side of a column heading to change the column width.
 
rowLabelSelector: aSymbol
Specifies a unary selector sent to an item to return its row label.
 
rowSeparators: aBoolean
Specifies whether the rows are separated by a horizontal line.
 
scrollHorizontal: aBoolean
This resource specifies whether a horizontal scroll bar should be used for the list.
 
selectableColumns: aBoolean
Defines whether the user may select columns by clicking on their headings.
 
selectCell: cellPoint notify: notify
Select a cell in the list by item and column position. This message selects a cell at the specified point and makes it be the selected cell. If editing is in progress, the endEdit API will be invoked and selection will proceed only if the edit is ended successfully. If the specified cell is editable, the begin edit callback will be fired (i.e., the table is editable and the cell's column is editable).
 
selectCells: cellPoints notify: notify
Select a group of cells in the list by column and item position.
 
selectColumn: column
Select the column given. This message selects the heading of the specified column.
 
selectedCell
Specifies a Point whose x component is the index of the column of the selected cell and whose y component is the index of the item (row) of the selected cell. If nil, then no cell is selected. Note: This resource is only relevant if the selection policy is XmCELLSINGLESELECT."
 
selectedCells
A Collection of Points each of whose x component is the index of the column of a selected cell and whose y component is the index of the item (row) of a selected cell. If empty,then no cell is selected. Note: This resource is only relevant if the selection policy is XmCELLSINGLESELECT or XmCELLEXTENDEDSELECT."
 
selectedColumns: resourceValue
Specifies the columns which are selected.
 
selectedIndex
Answer the index of the selected item
 
selectedItem
Answer the item selected in the list.
 
selectedItemCount
Specifies the number of objects in the selected items list.
 
selectedItems: anOrderedCollection
An OrderedCollection of Objects that represents the list items that are currently selected, either by the user or the application.
 
selectionPolicy: anInteger
Defines the interpretation of the selection action.
Default: XmBROWSESELECT (Browse Select)
Valid resource values:
XmSINGLESELECT (Single Select) - Allows only single selections. Under Windows, this is the same as Browse Select
XmMULTIPLESELECT (Multiple Select) - Allows multiple items to be selected. The selection of an item is toggled when it is clicked on. Clicking on an item does not deselect previously selected items.
XmEXTENDEDSELECT (Extended Select) - Allows multiple items to be selected, either by dragging the selection or by clicking on items with a modifier key held down. Clicking on an item without a modifier key held down deselects all previously selected items.
XmBROWSESELECT (Browse Select) - Allows only single selection. The selection changes when the mouse is dragged. This is the default Selection Policy. Under Windows, this is the same as Single Select
XmREADONLYSELECT (Read Only Select) - Allows navigation, but no selection or callbacks.
XmCELLSINGLESELECT (Cell Single Select) - Allows single selection of cells.
XmCELLBLOCKSELECT (Cell Block Select) - Allows selection of a rectangular block of cells.
 
selectItem: item notify: notify
Select an item in the list. This message selects and adds the specified item to the current selected list. The cursor moves to the newly selected item.
 
selectPos: position notify: notify
Select an item in the list by position. This message selects a list item at the specified position and adds it to the list of selected items.
 
separatorColor: aCgRGBColor
Specifies the separator color.
 
separatorsToExtremes: aBoolean
Defines whether row and column separators are to be extended to the extreme right and bottom edges of the table.
 
setBottomItem: item
Make the given item the last visible item in the list. The item can be any valid item in the list.
 
setBottomPos: position
Make an item the last visible item in the list by position. This message makes the item at the specified position the last visible item in the list.
 
setFirstColumnPos: position
Make a column the first visible column by position. This message makes the column at the given position the first visible column. If this column is locked, this message has no effect. If there are locked columns and this column is not locked, then this column becomes the first column visible beyond the locked columns.
 
setItem: item
Make the given item the first visible item in the list. The item can be any valid item in the list.
 
setLastColumnPos: position
Make a column the last visible column by position. This message makes the column at the given position the last visible column. If this column is locked, this message has no effect. If there are locked columns and this column is not locked, then this column becomes the last column visible.
 
setPos: position
Make an item the first visible item in the list by position. This message makes the item at the given position the first visible position in the list.
 
showColumnHeading: aBoolean
Specifies whether the column heading should be displayed.
 
showGrid: aBoolean
Set whether horizontal and vertical grid lines should be displayed.
 
showLines: aBoolean
Set whether vertical separator lines should be displayed.
 
showRowHeading: aBoolean
Specifies whether the row heading should be displayed.
 
sortable: aBoolean
Specifies whether all of the columns should be sortable.
 
sortOn: column ascending: aBoolean
Sort the items based on <column> either ascending or descending.
 
topItemPosition: anInteger
Specifies the Integer position of the item that is the first visible item in the list.
 
visibleItemCount
Specifies the number of items that can fit in the visible space of the list. Until the list is realized, this answers 0.
 
visualStyle: anInteger
Defines the how the cells are displayed.
Default: XmFLAT (Flat)
Valid resource values:
XmFLAT (Flat) - Looks like a list box.
XmETCHROWS (Etch Rows) - Each row is etched.
XmETCHCELLS (Etch Cells) - Each cell in an etched column is individually etched.
Callbacks & Events
Browse Selection Callback
These callbacks are triggered when an item is selected in the browse selection mode. It is only valid when Selection Policy is Browse Select.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
 
Cell Block Selection Callback
These callbacks are triggered when a block of cells is selected in cell block selection mode.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
columnPosition - the Integer position of the selected column.
columnPositions - a Collection of Integers representing the selected columns.
selectedCells - a Set of Points representing the selected cells.
 
Cell Single Selection Callback
These callbacks are triggered when an item is selected in cell single selection mode.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
columnPosition - the Integer position of the selected column.
columnPositions - a Collection of Integers representing the selected columns.
selectedCells - a Set of Points representing the selected cells.
 
Children Callback
These callbacks are triggered when an item’s list of children is needed.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
children - the value of children for the item in the callback.
 
Column Heading Selection Callback
These callbacks are triggered when a column heading is selected
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
columnPosition - the Integer position of the selected column.
columnPositions - a Collection of Integers representing the selected columns.
selectedCells - a Set of Points representing the selected cells.
 
Default Action Callback
These callbacks are triggered when an item is double clicked.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
 
Draw Background Callback
These callbacks are triggered when an item’s background needs to be drawn.
Call data arguments:
item - the item which is the selected item.
doit - indicates whether the action that invoked the callback is performed.
value - the value which is the renderable whose background needs drawing.
selected - indicates whether the item whose background needs to be drawn is selected.
renderContext - the render context to be used in drawing the item’s background
columnPosition - the Integer position of the column of the cell whose background needs to be drawn.
heading - indicates whether the cell whose background needs to be drawn is a heading cell.
 
Expand Collapse Callback
These callbacks are triggered when an item is expanded or collapsed.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
 
Extended Selection Callback
These callbacks are triggered when items are selected using the extended selection mode. It is only valid when Selection Policy is Extended Select.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
 
Modify Verify Callback
These callbacks are triggered when the selection is about to be changed. The application may ‘undo’ the selection change by setting the doit field of the callData to false.
Call data arguments:
doit - Indicates whether the action that invoked the callback is performed.
Setting doit to false negates the action.
 
Multiple Selection Callback
These callbacks are triggered when an item is selected in multiple selection mode. It is only valid when Selection Policy is Multiple Select.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
 
Single Selection Callback
These callbacks are triggered when an item is selected in single selection mode. It is only valid when Selection Policy is Single Select.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
selectedItemCount - the integer number of selected items.
selectedItemPositions - a Collection containing the integer positions of the selected items.
selectedItems - a Collection of items which are the selected items.
 
Visual Info Callback
These callbacks are triggered when an item’s icon, label and isInUse are needed. The application MUST hook this callback and set the callData icon to the CgIcon (or other renderable object) to be displayed as the icon for the item in callData item. It must also set the callData label to the String (or other renderable object) to be displayed as the label for the item.
Call data arguments:
item - the item which is the selected item.
itemPosition - the integer position of the selected item in the list.
isInUse - the inUse status (Boolean) which is the default to be used for the item in the callback.
icon - the icon which is the default icon to be used for the item in the callback.
label - the label which is the default label to be used for the item in the callback.
hasChildren - indicates whether the item has children or not.
Editor
Allow Cell Editing In Row Select Modes
Specifies whether cell editing is allowed in row select modes.
 
Application Drawn Background
Specifies whether the application wants the Draw Background Callback to fire when an item’s background needs to be drawn. If this value is false, then the widget will draw the normal default background for each selected and non-selected item.
 
Autosize
Specifies whether the autosizable columns should be autosized whenever the widget resizes.
 
Button Policy
Specifies how the hierarchy buttons should be displayed (e.g., as buttons, as triangles or not at all.
Buttons - Causes hiearchy expand/collapse indicators to be displayed as buttons.
Triangles - Causes hiearchy expand/collapse indicators to be displayed as triangles.
None - Suppresses the display of any expand/collapse indicators.
 
Border Width
Specifies the width of the border that surrounds the widget’s window on all four sides. The width is specified in pixels. A width of zero means that no border will show.
Border - Causes the widget to have a border.
No Border - Causes the widget to have no border.
 
Cell Tabbing Policy
Specifies how tabbing should occur amongst cells.
Across Rows - When the last cell in a row is reached when tabbing forward, go to the first cell in the next row. When the first cell in a row is reached when tabbing backwards, go to the last cell in the previous row.
Application Defined - Tabbing behavior is defined by the application. To use this option, the application must hook the Cell Tab Callback.
Within Row - When the last cell in a row is reached when tabbing forward, go to the first cell in the same row. When the first cell in a row is reached when tabbing backwards, go to the last cell in the same row.
 
Children Selector
Specifies a unary selector sent to an item to return its children.
 
Color Selector
Specifies a unary selector sent to an item to return its label color.
 
Cursor Policy
Specifies how cursor keys will be treated.
Edit - Causes the arrow keys to move within a cell.
Move - Causes the arrow keys to move between cells.
 
Disabled Selector
Specifies selector sent to the row object to determine whether the row should be disabled.
 
Editable
Specifies whether the cells in the table are editable. For a cell to be editable, the table widget must be editable, the column must be editable, and the application must hook the Begin Edit Callback and set the callData doit to true
 
Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
 
Has Children Selector
Specifies selector sent to the row object to determine whether it has children.
 
Heading Separator Thickness
Specifies the thickness of the horizontal line separating the column headings from the rest of the table.
 
Heading Visual Style
Defines the how the cells are displayed.
Etch Cells - Each cell in an etched column is individually etched.
Etch Rows - Each row is etched.
Flat - Looks like a list box.
 
Icon Expand Selector
Specifies a unary selector sent to an item to return its expanded icon.
 
Icon Selector
Specifies a unary selector sent to an item to return its icon.
 
Indentation Width
Specifies how many pixels each level of the hierarchy should be indented.
 
Initial State Selector
Specifies a unary selector sent to an item to return its initial state (expanded or not).
 
Item Height
Specifies the height in pixels of items in the list. This includes the margin height on the top and bottom of the item as well as two pixels for emphasis.
 
Lines
Specifies whether the widget should display hierarchy lines.
 
Locked Columns
Specifies the number of columns to be locked down on the left side of the table. A column can be locked only if its preceding column is also locked. When scrolling, the locked columns remain fixed on the left side and all other columns scroll under the locked columns. This value must be no greater than the number of columns.
 
Row Separators
Specifies whether the rows are separated by a horizontal line.
 
Scroll Horizontal
This resource specifies whether a horizontal scroll bar should be used for the list.
 
Selectable Columns
Defines whether the user may select columns by clicking on their headings.
 
Selection Policy
Defines the interpretation of the selection action.
Browse Select - Allows only single selection. The selection changes when the mouse is dragged. This is the default Selection Policy. Under Windows, this is the same as Single Select
Cell Block Select - Allows selection of a rectangular block of cells.
Cell Single Select - Allows single selection of cells.
Extended Select - Allows multiple items to be selected, either by dragging the selection or by clicking on items with a modifier key held down. Clicking on an item without a modifier key held down deselects all previously selected items.
Multiple Select - Allows multiple items to be selected. The selection of an item is toggled when it is clicked on. Clicking on an item does not deselect previously selected items.
Read Only Select - Allows navigation, but no selection or callbacks.
Single Select - Allows only single selections. Under Windows, this is the same as Browse Select
 
Separators To Extremes
Defines whether row and column separators are to be extended to the extreme right and bottom edges of the table.
 
Set Heading Font
Specifies the font list associated with the headings.
 
Show Column Heading
Specifies whether the column heading should be displayed.
 
Show Row Heading
Specifies whether the row heading should be displayed.
 
Sortable
Specifies whether all of the columns should be sortable.
 
Top Item Position
Specifies the Integer position of the item that is the first visible item in the list.
 
Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.
 
Visual Style
Defines the how the cells are displayed.
Etch Cells - Each cell in an etched column is individually etched.
Etch Rows - Each row is etched.
Flat - Looks like a list box.
Column Editor
Autosize
Specifies whether the column width should be autosized.
 
Background Color
Specifies selector sent to the row object to retrieve the background color for the cell. The color may also be hardcoded.
 
Callbacks
Launches the Callback Editor on the edited column.
 
Character Validation
Specifies the character validation function to use with values entered into cells within the column.
20Comma10 - Validates whether each character is a valid for a 20,10 field.
7Comma2 - Validates whether each character is a valid for a 7,2 field.
7Comma4 - Validates whether each character is a valid for a 7,4 field.
Alpha - Validates whether each character is a valid alpha character ($A - $Z, $a - $z or space).
AlphaNoSpace - Validates whether each character is a valid alpha character ($A - $Z, $a - $z).
AlphaNumeric - Validates whether each character is a valid alpha-numeric character ($A - $Z, $a - $z, $0 - $9, or space).
AlphaNumericNoSpace - Validates whether each character is a valid alpha character ($A - $Z, $a - $z, $0 - $9).
Any - Any character is valid.
Boolean - Validates whether each character is a valid Boolean value (e.g., T, t, F, f, Y, y, N, or n).
Currency - Validates whether each character is a valid currency value.
Integer - Validates whether each character is a valid Integer value.
Numeric - Validates whether each character is a valid numeric value.
Positive10Comma10 - Validates whether each character is a valid for a positive 10,10 field.
PositiveInteger - Validates whether each character is a valid positive Integer.
PositiveNumeric - Validates whether each character is a valid positive numeric value.
 
Disabled Selector
Specifies selector sent to the row object to determine whether a cell should be disabled.
 
Editable
Specifies whether the cells in this column are editable.
 
Etched
Specifies whether this column is to be etched.
 
Field Validation
Specifies the field validation function to use with values entered into cells within the column.
Any - Any characters are valid.
Currency - Formats the contents of the field to be a currency value.
CurrencyNoDecimal - Formats the contents of the field to be a currency value without decimal places.
Date - Validates whether the contents of the field are a valid Date value and then formats the Date using the system Date format.
Integer - Formats the contents of the field to be an Integer value.
Number - Formats the contents of the field to be a numeric (e.g., Float) value.
PhoneNumberExtUS - Validates and formats the contents of the field to be a US phone number with optional extension. Valid formats are: (999) 999-9999, 999-9999, x999, (999) 999-9999 x999.
PhoneNumberUS - Validates and formats the contents of the field to be a US phone number. Valid formats are: (999) 999-9999, 999-9999.
Round2 - Formats the contents of the field to be rounded to 2 decimal places.
Round3 - Formats the contents of the field to be rounded to 3 decimal places.
SSN - Validates and formats the contents of the field to be a US Social Security Number. Format is: 999-99-9999.
ZipCodeUS - Validates and formats the contents of the field to be a US Zip Code. Valid format are: 99999 or 99999-9999.
 
Foreground Color
Specifies selector sent to the row object to retrieve the foreground color for the cell. The color may also be hardcoded.
 
Get Selector
Specifies selector sent to the row object to retrieve the data for the cell.
 
Heading
Specifies the heading object to be displayed at the top of the column.
 
Horizontal Alignment
Specifies how the cells in this column should be aligned horizontally.
Center - Align the cells to the center.
Left - Align the cells to the left.
Right - Align the cells to the right.
 
Horizontal Heading Alignment
Specifies how this column’s heading should be aligned horizontally.
Center - Align the heading to the center.
Left - Align the heading to the left.
Right - Align the heading to the right.
 
List Selector
Specifies selector sent to the row object to retrieve a list of values to populate the drop down list in the cell.
 
Minimum Width
Specifies the minimum width of the column in pixels. This minimum applys to autosizing and user resizing operations.
 
Name
Specifies the name of the column. This name may be used to programatically access the column. Note that this is distint from the heading of the column.
 
Reorderable
Specifies whether the column is reorderable (can be draged left and right).
 
Resizable
Specifies whether the column is resizable by the user. If so, the user can drag the right side of the column heading to change the column width
 
Set Font
Set the font for the edited column.
 
Set Selector
Specifies selector sent to the row object to store data entered into the cell.
 
Show In Use
Specifies whether the column should show the inUse emphasis for each item.
 
Sortable
Specifies whether the column is sortable.
 
Vertical Alignment
Specifies how the cells and heading in this column should be aligned vertically.
Bottom - Align the cells to the bottom.
Center - Align the cells to the vertical center.
Top - Align the cells to the top.
 
Vertical Separator Thickness
Specifies the thickness of the line shown to the right of each cell in the column.
 
Width
Specifies the width of the column in pixels. This does not includes the width of any emphasis or vertical separator.
Example
The following example code creates a WkTableWidget used to view a person object. The widget specifies a children selector that will be used to display person objects hierarchically. The disabled selector is used to determine whether a particular row is disabled or not. The color selector is used to query each row object for its preferred foreground color (which may be overridden by individual columns). The reorderable and sortable flags determine whether the user will be able to reorder the columns by dragging them left and right and sort them in place by clicking on the column headers. The heading font has been set to a 14 point Times Roman.
The widget defines five columns: first name, last name, company, shoe size and exec status. For each column, get and set selectors are specified which are used to query the person object a particular row for the data to display in the column and to update the person object when the user has entered new data. Columns can specify their heading, alignment, width, font, character and field validations, and foreground and background colors. Note that the company column hardcodes its colors while the shoe size specifies selectors. This means that each row of the shoe size column may have different foreground and background colors depending on the values returned from the various person objects. The company column also specifies a list selector that is a signal to the widget to use a drop down list as the column editor. The values returned by sending the list selector to the row object are used to populate the list (each row object can actually supply its own list). The exec column returns boolean cell values. The widget will automatically display boolean values as checked and unchecked check boxes without further developer intervention.
This example corresponds to the top image at the beginning of the WkTableWidget section.
tableWidget := WkTableWidget
createWidget: 'tableWidget'
parent: self form
argBlock: [:w | w
x: 4;
y: 4;
width: 612;
height: 296;
headingFont: '-*-times new roman-bold-r-
normal-*-*-140-*-*-p-*-*-*';
headingSeparatorThickness: 1;
childrenSelector: #'children';
colorSelector: #'color';
disabledBackgroundColor: (Color
red: 16rCCCC
green: 16rCCCC
blue: 16rCCCC);
disabledSelector: #'disabled';
reorderable: true;
sortable: true;
columns: (OrderedCollection new
add: (WkTableColumn new
heading: 'Last Name';
verticalAlignment: XmALIGNMENTCENTER;
width: 132;
characterValidation: #okAlpha:;
disabledSelector: #'lastNameDisabled';
getSelector: #'lastName';
setSelector: #'lastName:';
yourself);
add: (WkTableColumn new
editable: false;
heading: 'First Name';
horizontalAlignment: XmALIGNMENTCENTER;
verticalAlignment: XmALIGNMENTCENTER;
width: 133;
font: '-*-times new roman-bold-i-
normal-*-*-120-*-*-p-*-*-*';
getSelector: #'firstName';
setSelector: #'firstName:';
yourself);
add: (WkTableColumn new
heading: 'Company';
verticalAlignment: XmALIGNMENTCENTER;
width: 123;
backgroundColor: (CgRGBColor
red: 16rFFFF
green: 16rFFFF
blue: 16r0);
foregroundColor: (CgRGBColor
red: 16rFFFF
green: 16r0
blue: 16r0);
getSelector: #'company';
listSelector: #'companyList';
setSelector: #'company:';
yourself);
add: (WkTableColumn new
editable: false;
heading: 'Shoe Size';
horizontalAlignment: XmALIGNMENTEND;
horizontalHeadingAlignment:
XmALIGNMENTEND;
verticalAlignment: XmALIGNMENTCENTER;
width: 64;
autosize: false;
backgroundColor: #'shoeSizeBackColor';
foregroundColor: #'shoeSizeColor';
getSelector: #'shoeSize';
listSelector: #'shoeSizeList';
setSelector: #'shoeSize:';
yourself);
add: (WkTableColumn new
heading: 'Exec';
horizontalAlignment: XmALIGNMENTCENTER;
verticalAlignment: XmALIGNMENTCENTER;
width: 96;
getSelector: #'executive';
setSelector: #'executive:';
sortable: false;
yourself);
yourself);
scale].
 
WkTimeEditor
As its name implies, the WkTimeEditor widget provides a convenient control for editing times. It contains three fields for setting the hours, minutes, and meridian of a time value. Since it is specifically designed for time manipulation, it assures that any time entered is guaranteed to be valid.
WkTimeEditors allow the user to edit a time by manipulating the hour, minute and meridian fields as if they were WkNumericEditors. When a time pane has the input focus, there is one current field. That field (hour, minute, or meridian value) can be edited using either the arrow buttons or by using the keyboard to type the value. The current field can be selected by using the mouse or the left and right arrow keys. Correct times are enforced; e.g. incrementing past 59 minutes or 23 hours will increment the related fields correctly.
WkTimeEditor provides a variety of styles to allow for flexibility in choosing a time format. These styles mirror the settings dialog provided by Windows, and should allow all supported cultural time variations, including changing the separator (usually “:”), switching between 12 hour and 24 hour format, and showing hour leading zeros or different meridian strings (usually AM/PM).
The contents of a WkTimeEditor is a Time object, both for setting and retrieving the current value. A user can increment or decrement the values using up/down arrow keys or by selecting the up/down buttons. A user can change the value in an editable spin button by typing in the entry field.
Protocol
alignment: anInteger
Specifies the text alignment used by the widget.
Default: XmALIGNMENTEND (Right)
Valid resource values:
XmALIGNMENTBEGINNING (Left) - Causes the left side of the line of text to be vertically aligned with the left edge of the widget window.
XmALIGNMENTCENTER (Center) - Causes the center of the line of text to be vertically aligned in the center of the widget window.
XmALIGNMENTEND (Right) - Causes the right side of the line of text to be vertically aligned with the right edge of the widget window.
 
allowNil: aBoolean
Specifies whether the text field may have a blank (nil) value.
 
amString: aString
Specifies the string used for AM time values in 12 hour mode.
 
editable: aBoolean
Specifies whether a user can edit text in the entry field part of the spin button.
 
leadingZero: aBoolean
Specifies whether the hour field is displayed with a leading zero.
 
maximum: anInteger
Specifies a numeric spin button’s maximum value.
 
minimum: anInteger
Specifies a numeric spin button’s minimum value.
 
pmString: aString
Specifies the string used for PM time values in 12 hour mode.
 
separator: aCharacter
Specifies the separator character used to separate the hour and minute fields.
 
twelveHour: aBoolean
Specifies whether the time is displayed in 12 hour format or not.
 
value: aString
Specifies the initial value of the widget.
 
wrap: aBoolean
Specifies whether the spin button should cycle or stop upon reaching the end of the collection, or max or min for a numeric spin button.
Callbacks & Events
Activate Callback
These callbacks are triggered when the user presses the default action key. This is typically a carriage return.
 
Decrement Callback
These callbacks are triggered when the user decreases the spin button value by one step. This can happen either when the down arrow key is pressed or when the down arrow button is selected with the mouse.
 
Focus Callback
These callbacks are triggered before the entry field has accepted input focus.
 
Increment Callback
These callbacks are triggered when the user increases the spin button value by one step. This can happen either when the up arrow key is pressed or the up arrow button is selected with the mouse.
 
Losing Focus Callback
These callbacks are triggered before the entry field loses input focus.
 
Modify Verify Callback
These callbacks are triggered before text is deleted from or inserted into the widget. This callback can be used to check a character value after it is entered by the user and before it is accepted by the control.
Call data arguments:
doit - Indicates whether the action that invoked the callback is performed.
Setting doit to false negates the action.
text - a String which contains the text which is to be inserted.
currInsert - the current position of the insert cursor.
startPos - the starting position of the text to modify.
endPos - the ending position of the text to modify.
 
Value Changed Callback
These callbacks are triggered after text is deleted from or inserted into the widget. This callback can be used to retrieve the current value of the widget.
Editor
Alignment
Specifies the text alignment used by the widget.
Left - Causes the left side of the line of text to be vertically aligned with the left edge of the widget window.
Center - Causes the center of the line of text to be vertically aligned in the center of the widget window.
Right - Causes the right side of the line of text to be vertically aligned with the right edge of the widget window.
 
Allow Nil
Specifies whether the text field may have a blank (nil) value.
 
AM String
Specifies the string used for AM time values in 12 hour mode.
 
Border Width
Specifies the width of the border that surrounds the widget’s window on all four sides. The width is specified in pixels. A width of zero means that no border will show.
Border - Causes the widget to have a border.
No Border - Causes the widget to have no border.
 
Editable
Specifies whether a user can edit text in the entry field part of the spin button.
 
Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
 
Leading Zero
Specifies whether the hour field is displayed with a leading zero.
 
Maximum
Specifies a numeric spin button’s maximum value.
 
Minimum
Specifies a numeric spin button’s minimum value.
 
PM String
Specifies the string used for PM time values in 12 hour mode.
 
Separator
Specifies the separator character used to separate the hour and minute fields.
 
Twelve Hour
Specifies whether the time is displayed in 12 hour format or not.
 
Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.
 
Value
Specifies the initial value of the widget.
 
Wrap
Specifies whether the spin button should cycle or stop upon reaching the end of the collection, or max or min for a numeric spin button.
Example
The following example code creates a WkTimeEditor that displays the time in 24 hour mode (e.g., 23:00 rather than 11:00 PM) with a center alignment and the leading zero on the hour field suppressed.
aWkTimeEditor := WkTimeEditor
createWidget: 'aWkTimeEditor'
parent: self form
argBlock: [:w | w
x: 100;
y: 137;
width: 148;
height: 24;
alignment: XmALIGNMENTCENTER;
twelveHour: false;
leadingZero: false;
scale].
 
WkValueSet
The WkValueSet widget provides a means for selecting one item from a set of pictorial choices. It consists of a two-dimensional grid of graphical cells, where only one cell is selected at a time. ValueSets are very popular interface components, used for creating such GUI objects as tool bars, ribbons, paging buttons, and color choosers. Note that valuesets are useful in situations where one item is always selected from a group of choices. For applications where choosing an item will issue a command rather than make a selection, the WkImageButton classes should be used instead.
The user can select a particular item by clicking on it directly with the mouse, or using the arrow keys to move the selection. When an item is selected it notifies the single selection callback.
Each cell may contain a label, an image and/or a color. To set the contents of a cell, the method #cellAt:put: is provided. The object put into a cell can be an renderable object (e.g., an image, a String, or a Color). By default WindowBuilder Pro will use instances of WbLabelledImage which may be composed of an image, a label and specify a background color.
Two methods are provided to retrieve the valueset’s selection: #itemPosition returns the point representing the column and row of the current selection, and #item returns the actual object in the selected cell.
Protocol
drawPolicy: anInteger
Specifies the drawing policy used in rendering buttons on the valueset. The drawing policy determines two things for a button:
how the button draws itself so it looks like a button
how the button animates when pressed
Default: XmSHADOWEDTHREESTATEDRAWPOLICY (Shadowed Three State)
Valid resource values:
XmSHADOWEDTWOSTATEDRAWPOLICY (Shadowed Two State) - Buttons are drawn with a 3D shadowed outline and exhibit a simple 2-state (OFF and ON) state rendering.
XmSHADOWEDTHREESTATEDRAWPOLICY (Shadowed Three State) - Buttons are drawn with a 3D shadowed outline and exhibit a 3-state (OFF, ON, and PRESSED) state rendering.
XmOUTLINEDRAWPOLICY (Outlined) - Buttons are drawn with a simple etched (non-shadowed) outline and exhibit a 2-state (OFF and ON) state rendering.
XmFLATDRAWPOLICY (Flat) - Buttons are drawn flat without a 3D shadow.
 
numColumns: anInteger
Specifies the number of columns that are made to accommodate the receiver’s buttons. This attribute always sets the x-axis dimension.
 
numRows: anInteger
Specifies the number of rows that are made to accommodate the receiver's buttons. This attribute always sets the y-axis dimension.
 
selection: aPoint
Specifies the widget's initial selection.
Callbacks & Events
Default Action Callback
These callbacks are triggered when the widget is double clicked.
Call data arguments:
item - the selected item.
itemPosition - the point position of the selected item in the value set.
Single Selection Callback
These callbacks are triggered when a value set item is clicked.
Call data arguments:
item - the selected item.
itemPosition - the point position of the selected item in the value set.
Editor
Border Width
Specifies the width of the border that surrounds the widget’s window on all four sides. The width is specified in pixels. A width of zero means that no border will show.
Border - Causes the widget to have a border.
No Border - Causes the widget to have no border.
 
Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
Draw Policy
Specifies the drawing policy used in rendering buttons on the valueset. The drawing policy determines two things for a button:
1.
2.
Shadowed Two State - Buttons are drawn with a 3D shadowed outline and exhibit a simple 2-state (OFF and ON) state rendering.
Shadowed Three State - Buttons are drawn with a 3D shadowed outline and exhibit a 3-state (OFF, ON, and PRESSED) state rendering.
Outlined - Buttons are drawn with a simple etched (non-shadowed) outline and exhibit a 2-state (OFF and ON) state rendering.
Flat - Buttons are drawn flat without a 3D shadow.
 
Num Columns
Specifies the number of columns that are made to accommodate the receiver’s buttons. This attribute always sets the x-axis dimension.
 
Num Rows
Specifies the number of rows that are made to accommodate the receiver's buttons. This attribute always sets the y-axis dimension.
 
Selection
Specifies the widget's initial selection.
 
Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.
Cell Editor
Background Color
Specifies the background color for the cell.
 
Foreground Color
Specifies the foreground color for the cell.
 
Label - Default
Specifies the default label string.
 
Label - Pressed
Specifies the label string when the widget is pressed.
 
Label - Disabled
Specifies the label string when the widget is disabled.
 
Label - Checked
Specifies the label string when the widget is checked.
 
Image - Default
Specifies the default label image.
 
Image - Pressed
Specifies the label image when the widget is pressed.
 
Image - Disabled
Specifies the label image when the widget is disabled.
 
Image - Checked
Specifies the label image when the widget is checked.
Example
The following example code creates a WkValueSet that has been set up as a two by two grid containing the letters “A” through “D”.
aWkValueSet := WkValueSet
createWidget: 'aWkValueSet'
parent: aCwForm
argBlock: [:w | w
x: 12;
y: 8;
width: 92;
height: 64;
atRow: 1 column: 1 put:
(WbLabeledImage stateDriven
image: nil label: 'A';
yourself);
atRow: 1 column: 2 put:
(WbLabeledImage stateDriven
image: nil label: 'B';
yourself);
atRow: 2 column: 1 put:
(WbLabeledImage stateDriven
image: nil label: 'C';
yourself);
atRow: 2 column: 2 put:
(WbLabeledImage stateDriven
image: nil label: 'D';
yourself);
scale].
The next example code creates a WkValueSet that has been set up as a two by two grid containing colors red, green, blue and yellow
aWkValueSet := WkValueSet
createWidget: 'aWkValueSet'
parent: aCwForm
argBlock: [:w | w
x: 116;
y: 8;
width: 92;
height: 64;
atRow: 1 column: 1 put:
(WbLabeledImage stateDriven
image: nil;
backgroundColor: (CgRGBColor
red: 16rFFFF green: 16r0 blue: 16r0);
yourself);
atRow: 1 column: 1 put:
(WbLabeledImage stateDriven
image: nil;
backgroundColor: (CgRGBColor
red: 16r0 green: 16rFFFF blue: 16r0);
yourself);
atRow: 1 column: 1 put:
(WbLabeledImage stateDriven
image: nil;
backgroundColor: (CgRGBColor
red: 16r0 green: 16r0 blue: 16rFFFF);
yourself);
atRow: 1 column: 1 put:
(WbLabeledImage stateDriven
image: nil;
backgroundColor: (CgRGBColor
red: 16rFFFF
green: 16rFFFF
blue: 16r0);
yourself);
scale].
 
WkVerticalBarGauge
The WkVerticalBarGauge widget provides a visual indication of a magnitude within a given range. It can be used to represent such values as the amount of gas left in a gas tank, or the remaining balance in a bank account. It is also often used to indicate the amount of time spent/remaining on a long compute-bound processing task, such as reading a file or sorting a list.
The gauges provided in WidgetKit/Controls can either be rectangular or circular. The rectangular versions, WkHorizontalBarGauge and WkVerticalBarGauge, show a rectangular bar to indicate the current value of the gauge (increasing to the right and upwards, respectively). The WkCircularGauge fills the wedge of a circle to indicate its value.
The direction of the progress can be specified (bottom-top or top-bottom). The size of the progress bar’s completion indication is controlled by the value, minimum and maximum resources. The progress bar’s completion indication can either be a color (foregroundColor resource) or any renderable image (such as an icon or bitmap -- ribbonImage resource). The uncompleted progress indication is a color (backgroundColor resource). A label can be drawn centered in the progress bar. This can either be a percentage complete (value / (max - min)), displayed automatically by the progress bar (howPercentage resource), or any defined renderable image as the label (image resource).
Protocol
direction: anInteger
Specifies the direction the progress bar moves in.
Default: XmFORWARD (Forward)
Valid resource values:
XmFORWARD (Forward) - The progress bar moves forward. For horizontal progress bars, this is left-to-right. For vertical progress bars, this is top-to-bottom.
XmREVERSE (Reverse) - The progress bar moves backwards. For horizontal progress bars, this is right-to-left. For vertical progress bars, this is bottom-to-top.
 
fractionComplete: anInteger
Specifies the current amount of progress to show in the progress bar. This resource is a fraction, denoting a number between 0 and 1. For example, 1/10 specifies 10 % complete. 1 represents 100 % complete.
 
gaugeStyle: anInteger
Specifies the gauge's gauge style.
Default: XmSOLID (Solid)
Valid resource values:
XmSTEP (Step) - The gauge is drawn in discrete steps (Win95 style).
XmSOLID (Solid) - The gauge is drawn as a solid bar.
 
image: aPixmap
Specifies the renderable object which draws as the label of the progress bar. The label is displayed only if the showPercentage resource value is false. Note that the image label is drawn twice, in the foreground and background colors, so that the label appears ‘reversed’ over the actual foreground and background colors of the progress bar. If a ribbon image is being used, then the label is drawn once, using the foreground color.
 
imageColor: aCgRGBColor
Specifies the color of the label drawn according to the image resource, or the color of the percentage complete label, according to the showPercentage resource. If the resource value is nil, then the label is drawn in reverse color over the colors of the progress bar (foreground color) and the background color.
 
maximum: anInteger
Specifies the gauge's maximum value.
 
minimum: anInteger
Specifies the gauge's minimum value.
 
ribbonImage: aPixmap
Specifies the renderable object which draws as the completed ribbon of the progress bar. This object is drawn instead of a color strip. Note that when a ribbon image is used, a label (the showPercentage or image resources) will be drawn using the imageColor resource, or if that is nil, the foregroundColor resource.
 
setValue: anInteger
Sets the gauge's position between minimum and maximum and triggers the value changed callback.
 
shadowType: anInteger
Specifies the drawing style for the frame around the progress bar widget.
Default: XmSHADOWIN (Shadow In)
Valid resource values:
XmSHADOWNONE (Shadow None) - No frame is drawn.
XmSHADOWIN (Shadow In) - Draws a frame such that it appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed.
XmSHADOWOUT (Shadow Out) - Draws a frame such that it appears outset.
 
shadowWidth: anInteger
Specifies the width for the border
 
showPercentage: aBoolean
Specifies the whether a label showing the percentage completed is shown in the progress bar. If true, then the string ‘X %’ is show in the progress bar, where X is the percentage of progress completed. If false, then no percentage label is shown.
 
tickSize: anInteger
Specifies the gauge's tick size. Only valid when the gaugeStyle is set to step. If the value is set to zero, the widget will use the default setting (determined by the size of the widget).
 
value: anInteger
Specifies the gauge's position between minimum and maximum.
Callbacks & Events
Value Changed Callback
These callbacks are triggered after widget’s value has been changed.
Editor
Enabled
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
Direction
Specifies the direction the progress bar moves in.
Forward - The progress bar moves forward. For horizontal progress bars, this is left-to-right. For vertical progress bars, this is top-to-bottom.
Reverse - The progress bar moves backwards. For horizontal progress bars, this is right-to-left. For vertical progress bars, this is bottom-to-top.
 
Image
Specifies the renderable object which draws as the label of the progress bar. The label is displayed only if the showPercentage resource value is false. Note that the image label is drawn twice, in the foreground and background colors, so that the label appears ‘reversed’ over the actual foreground and background colors of the progress bar. If a ribbon image is being used, then the label is drawn once, using the foreground color.
 
Maximum
Specifies the gauge's maximum value.
 
Minimum
Specifies the gauge's minimum value.
 
Ribbon Image
Specifies the renderable object which draws as the completed ribbon of the progress bar. This object is drawn instead of a color strip. Note that when a ribbon image is used, a label (the showPercentage or image resources) will be drawn using the imageColor resource, or if that is nil, the foregroundColor resource.
 
Shadow Type
Specifies the drawing style for the frame around the progress bar widget.
Shadow None - No frame is drawn.
Shadow In - Draws a frame such that it appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed.
Shadow Out - Draws a frame such that it appears outset.
 
Shadow Width
Specifies the width for the border
 
Show Percentage
Specifies the whether a label showing the percentage completed is shown in the progress bar. If true, then the string ‘X %’ is show in the progress bar, where X is the percentage of progress completed. If false, then no percentage label is shown.
 
Style
Specifies the gauge's gauge style.
Step - The gauge is drawn in discrete steps (Win95 style).
Solid - The gauge is drawn as a solid bar.
 
Tick Size
Specifies the gauge's tick size. Only valid when the gaugeStyle is set to step. If the value is set to zero, the widget will use the default setting (determined by the size of the widget).
 
Value
Specifies the slider current position along the scale, between minimum and maximum.
 
Visible
Maps the widget (makes visible) as soon as it is both realized and managed, if set to True. If set to False, the client is responsible for mapping and unmapping the widget.
Example
The following example code creates a WkVerticalBarGauge where the bar color is blue, the border width is 2 and the percentage complete is displayed in the center of the widget.
aWkVerticalBarGauge:= WkVerticalBarGauge
createWidget: 'aWkVerticalBarGauge'
parent: self form
argBlock: [:w | w
x: 24;
y: 28;
width: 36;
height: 164;
foregroundColor: (CgRGBColor
red: 16r0
green: 16r0
blue: 16rFFFF);
shadowWidth: 2;
showPercentage: true;
scale].
The next example code creates a WkVerticalBarGauge with a outset shadow border where the ribbon image (indicating percentage completion) is an image.
aWkVerticalBarGauge := WkVerticalBarGauge
createWidget: 'aWkVerticalBarGauge'
parent: self form
argBlock: [:w | w
x: 24;
y: 28;
width: 64;
height: 216;
shadowType: XmSHADOWOUT;
ribbonImage: (WbPixmap
fromFile: 'GRENLGHT.BMP');
scale].