All Widgets
Protocol
addCallback: callbackName receiver: receiver selector: selector
clientData: clientData
Add a callback to one of the receiver’s callback lists. Generally speaking, a widget expecting to interact with an application will declare one or more callback lists as resources; the application adds callbacks to these callback lists, which will be invoked whenever the predefined callback conditions are met. Callback lists are resources, so that the application can set or change the function that will be invoked.
Callbacks are not necessarily invoked in response to any event; a widget can call the specified routines at any arbitrary point in its code, whenever it wants to provide a ‘hook’ for application interaction. For example, all widgets provide a destroyCallback resource to allow applications to interpose a routine to be executed when the widget is destroyed.
This message adds a new callback to the end of the callback list. A callback will be invoked as many times as it occurs in the callback list.
callbackName | The resource name of the callback list to which the callback is to be appended. |
receiver | The object to send the callback message to. |
selector | The 3-parameter message selector to send (WindowBuilder Pro also supports unary message selectors). |
clientData | An object to be passed to the receiver of the callback message as the clientData parameter when the callback is invoked, or nil. |
addEventHandler: eventMask receiver: receiver selector: selector
clientData: clientData
Register an event handler. This message registers with the dispatch mechanism. The handler thus registered will be called when an event matching the eventMask occurs in the receiver. This message can be sent at any time during the widget’s lifetime.
A handler may be registered with the same clientData to handle multiple events. Further, more than one event handler can be registered for a given event. If multiple handlers are registered, the handlers will all be called, but in an indeterminate order.
NOTE:
1. Event handlers are not supported for menu bars, menus or any widget that is part of a menu.
2. Event handlers are not supported for ‘private’ pseudo-widgets that make up the implementation of widgets such as scrolled text, scrolled list, combo box, scale, and scrolled window. Depending on the particular platform, such private widgets may or may not actually exist.
3. Exposure events are not supported through the event handler mechanism. Widgets that support exposure notification (e.g. CwDrawingArea and CwDrawnButton) provide callbacks for this purpose.
4. Since the proper event to trigger a menu popup varies among different platforms, the ButtonMenuMask is defined to select for the correct event for the platform, and should always be used for event handlers which pop up menus.
eventMask | An integer valued event mask specifying the events interest. The eventMask parameter is constructed as a bitwise OR of the individual event masks. |
receiver | The object to send the event handler message to. |
selector | The 3-parameter message selector to send (WindowBuilder Pro also supports unary message selectors). |
clientData | An object to be passed to the receiver of the event handler as the clientData parameter when the event handler is invoked, or nil. |
allChildren
Answer a collection of all of the receiver’s children.
allMajorChildren
Answer a collection of all of the receiver’s major children. This collection excludes widgets such as the scrollbar children of a scrolled list.
allParents
Answer a collection of the receiver’s parents until the top level shell is reached.
ancestorSensitive
Specifies whether the immediate parent of the widget will react to input events.
backgroundColor: aCgRGBColor
Specifies the background drawing color. NOTE: The particular aspects of the widget’s appearance which are affected by changing this resource are dependent on platform-specific styles and capabilities and vary from platform to platform.
basicWidget
Answer the receiver’s basic widget. The basic widget is any instance of a subclass of CwBasicWidget.
Extended widgets are implemented using basic widgets, or other extended widgets. While extended widgets are normally implemented using portable calls available from basic widgets, basic widgets are highly platform specific, and are normally implemented by the native windowing or operating system. While the #primaryWidget message for an extended widget may answer another extended widget, the #basicWidget message always returns the basic widget at the end of the chain i.e. the basic widget which represents the extended widget(s) to the native window system.
For CwBasicWidget’s, this message returns the receiver itself. For CwExtendedWidgets, this message (recursively) returns the basic widget of the receiver’s primary widget.
borderWidth: anInteger
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.
Default: 0 (No Border)
Valid resource values:
0 (No Border) - Causes the widget to have no border.
1 (Border) - Causes the widget to have a border.
boundingBox
Answer a rectangle whose origin is the receiver’s x @ y and whose extent is the receiver’s width @ height.
bringToFront
Move the receiver to the top of the stacking order among the receiver’s siblings.
bringToFrontOf: aCwWidget
Move the receiver in front of aCwWidget in the stacking order among the receiver’s siblings.
children
Answer a collection of the children of the receiver.
configureWidget: x y: y width: width height: height borderWidth: borderWidth
Move and/or resize the receiver, bypassing normal geometry management. This message moves and/or resizes a widget according to the specified width, height, and position values. It returns immediately if the specified geometry fields are the same as the old values. Otherwise, it writes the new x, y, width, height, and borderWidth values into the widget and, if the widget is realized, make the changes visible on the display. A parent widget can use this message to set the geometry of its children. It may also be used to reconfigure a sibling widget.
If only the size of a widget is to be changed, #resizeWidget:... is simpler to use; similarly, if only the location of a widget is to be changed, use #moveWidget:...
Note that once a widget is resized or otherwise reconfigured by its parent, it may need to do additional processing in its own resize method. Widgets usually need to know when they have changed size so that they can lay out their displayed data again to match the new size. When a parent resizes a child, it calls #resizeWidget:...
x,y | The receiver’s new integer x and y coordinates. |
width,height,borderWidth | The receiver’s new integer dimensions. |
corner
Answer a Point which is the receiver’s (x + width) @ (y + height).
deferRedraw: aBlock
Hint that widget display updates for the receiver should be deferred during execution of a block of code. This message is provided as a mechanism to allow the application to provide a hint that the widget updates caused by operations executed in the provided block should be deferred and performed all at once when execution of the block is completed.
The actual effect varies from platform to platform. In general, this should only be used when testing shows it to provide a visual improvement on one or more platforms.
NOTE: Care must be taken not to return out of the middle of aBlock.
destroyWidget
Destroy the receiver and its children and release all associated OS resources. When an application needs to perform additional processing during the destruction of a widget, it should register a destroy callback message for the widget. The destroy callback list is identified by the resource name XmNdestroyCallback. The destroy callback is called just prior to destroying the widget.
display
Answer the CgDisplay associated with the receiver.
disable
Disable the widget.
disableAll
Disable the receiver and all its children, forwarding the #disable message to all children. Sending #disableAll will result in all children updating their visual appearance to indicate that they are disabled, whereas #disable does not.
dynamicPopupMenu: aSymbolOrWbMenu owner: aWbApplication
Add a dynamic popup menu to the receiver. aSymbolOrWbMenu can either be a WbMenu or a symbol that when executed in the context of aWbApplication returns a WbMenu. aSymbol will be evaluated every time the menu is requested
enable
Enable the widget.
enableAll
Enable the receiver and all its children, forwarding the #enable message to all children. Sending #enableAll will result in all children updating their visual appearance to indicate that they are enabled, whereas #enable does not.
enabled: aBoolean
Determines whether a widget will react to input events. Disabled (insensitive) widgets do not react to input events.
extendedWidget
Answer the extended widget that manages the receiver.
extendedWidgetOrSelf
Answer the extended widget that manages the receiver. If none exists, answer the receiver.
extent
Answer a Point which is the receiver’s width @ height.
font: aFontName
Set the font of the receiver to aFontName.
foregroundColor: aCgRGBColor
Specifies the foreground drawing color. NOTE: The particular aspects of the widget’s appearance which are affected by changing this resource are dependent on platform-specific styles and capabilities and vary from platform to platform.
hasChildren
Answer whether the receiver has children.
hasFocus
Answer true if the receiver has keyboard focus. Otherwise answer false.
height: anInteger
Specifies the height of the widget’s window in pixels, not including the border area.
helpFile: aString
Specifies the help file to use for the widget.
helpKeysId: aString
Specifies the help keys ID for the widget.
helpTitle: aString
Specifies the help title for the widget.
helpTopicId: aString
Specifies the help topic ID for the widget.
hideWindow
Make the receiver invisible.
isVisible
Answer true if the window is visible.
manageChild
Add the receiver to its parent’s list of managed children. This message brings a child widget under the geometry management of its parent. A widget cannot be made visible until it is managed.
mapWidget
Map the receiver to its display. This message maps a widget’s window to its display, causing it to become visible. A widget must be realized before it can be mapped.
moveWidget: x y: y
Move the receiver on the display. This returns immediately if the specified geometry fields for the widget are the same as the old values. Otherwise, this message writes the new x and y values into the widget and, if the widget is realized, moves the widget on the display.
name
Answer the receiver’s name.
navigationType: anInteger
Specifies if tab group navigation is activated for this widget.
Default: XmNONE (None)
Valid resource values:
XmNONE (None) - Indicates that the Widget is not a navigation group
XmTABGROUP (Group) - Indicates that the Widget is included automatically in keyboard navigation
origin
Answer a Point which is the receiver’s x @ y.
owner
Answer the owner of the receiver.
parent
Answer the parent widget of the receiver, or nil if the receiver has no parent.
popupMenu
Answer the popupMenu property (generally a symbol).
popupMenu: aSymbolOrWbMenu
Add a popup menu to the receiver. aSymbolOrWbMenu can either be a WbMenu or a symbol that when executed in the context of the receiver’s owner returns a WbMenu.
popupMenu: aSymbolOrWbMenu owner: aWbApplication
Add a popup menu to the receiver. aSymbolOrWbMenu can either be a WbMenu or a symbol that when executed in the context of aWbApplication returns a WbMenu.
primaryWidget
Answer the receiver’s primary widget. The primary widget is any instance of a subclass of CwWidget. For CwBasicWidget’s, the primaryWidget is the receiver itself. For CwExtendedWidgets, the primaryWidget is another CwExtendedWidget, or a CwBasicWidget.
properties
Answer the receiver’s property dictionary.
properties: anIdentityDictionary
Set the receiver’s property dictionary.
propertyAt: aSymbol
Answer the receiver’s property named aSymbol.
propertyAt: aSymbol ifAbsent: aBlock
Answer the receiver’s property named aSymbol. If no such property exists, evaluate aBlock.
propertyAt: aSymbol ifAbsentPut: aBlock
Answer the receiver’s property named aSymbol. If no such property exists, store the value of aBlock there.
propertyAt: aSymbol ifMissing: anObject
Answer the receiver’s property named aSymbol. If no such property exists, store anObject there.
propertyAt: aSymbol put: anObject
Set the receiver’s property named aSymbol to anObject.
realChildren
Answer a collection of all of the receivers real children.
realizeWidget
Realize the receiver on the display. This message causes widgets to set create their windows on the display, and perform their final initializations.
realWidget
Answer the receiver’s real widget. For most widgets, this is the widget itself. For tightly coupled scrolling widgets, it is the scrolling widget’s work window.
redraw
Force the receiver and all children to redraw.
redrawOff
Set redraw off.
redrawOn
Set redraw on.
redraw: x y: y width: width height: height
Force the receiver and all children to redraw the specified area of the receiver.
removeAllCallbacks: callbackName
Delete all callbacks from a callback list. This message removes all the widget’s callback messages identified by callbackName, regardless of the value of the clientData associated with each message. This is in contrast to #removeCallback:... and #removeCallbacks:..., which remove the specified callback only if a specified clientData argument also matches.
callbackName | The resource name of the callback list to which the callback is to be appended. |
removeCallback: callbackName receiver: receiver selector: selector clientData: clientData
Delete a callback from a callback list. This message removes a callback message identified by callbackName.
The callback is removed only if both the callback object and clientData match a callback/data pair on the list. No warning message is generated if a callback to be removed fails to match a callback or clientData on the list. Use #removeAllCallbacks:... if you want to remove a particular callback regardless of the value of its clientData.
callbackName | The resource name of the callback list from which the callback is to be deleted. |
receiver | The object to match against the callback receiver in the callback list. |
selector | The 3-parameter message selector which is to be used to match against the callback in the callback list. |
clientData | The object to match with the clientData object in the callback list entry. |
removeEventHandler: eventMask receiver: receiver selector: selector
clientData: clientData
Remove a previously registered event handler. This message stops the specified handler from being called in response to the specified events.
A handler is removed only if both the event handler receiver, selector, and clientData match a previously registered handler/clientData pair.
If a handler to be removed fails to match, or if it has been registered with a different value of clientData, this message returns without reporting an error.
To stop a handler from being called at all, all events for which it is registered must be provided in eventMask. Otherwise, the handler remains registered for the remaining events.
eventMask | An integer valued event mask specifying the events of interest. The eventMask parameter is constructed as a bitwise OR of the individual event masks. |
receiver | The object to match against the event handler receiver in the callback list. |
selector | The 3-parameter message selector which is to be used to match against the event handler in the callback list. |
clientData | An object to be passed to the receiver of the event handler message as the clientData parameter when the event handler is invoked, or nil. |
resizeWidget: width height: height borderWidth: borderWidth
Resize a child or sibling widget, bypassing normal geometry management. This message is customarily used by a parent to resize its children.
This message returns immediately if the specified geometry fields are the same as the old values. Otherwise, it writes the new width, height, and borderWidth values into the widget and, if the widget is realized, makes the changes visible.
width,height,borderWidth | The receiver’s new integer dimensions. |
scale
Scale the receiver as needed. This insures that windows laid out under one resolution will look OK under other resolutions.
scaleFactor: aPoint
Set the scaling factor to use in laying out the window.
screen
Return the screen for the specified widget. This message returns a CgScreen which describes the screen that the widget is displayed on.
scrolledWidget
Answer the receiver’s scrolling widget. For most widgets, this is the widget itself. For tightly coupled scrolling widgets, it is the widget’s scrolling parent.
sendToBack
Move the receiver to the bottom of the stacking order among the receiver’s siblings.
sendToBackOf: aCwWidget
Move the receiver behind aCwWidget in the stacking order among the receiver’s siblings.
setInputFocus
This message is used to give the receiver the keyboard input focus. If the receiver is a Shell widget, it is activated and brought to the front. If the receiver is not a shell widget, its shell is activated and brought to the front, and then it is given focus.
There are several general rules governing the transfer of keyboard focus:
•A widget can not receive input focus unless its XmNtraversalOn resource is set to true and the XmNtraversalOn resource for all of its ancestors (not including the shell) is set to true.
•An attempt to set focus to a CwComposite widget that has no children will cause the CwComposite widget to take keyboard focus, allowing keyboard events to be received through an event handler.
•An attempt to set focus to a CwComposite widget that has children will cause the CwComposite widget to immediately transfer the keyboard focus to its first child that can receive focus. CwComposite widgets that have children will not normally take keyboard focus.
setSensitive: sensitive
Set the sensitivity state of a widget. Many widgets have a mode in which they assume a different appearance (for example, grayed out or stippled), do not respond to user events, and become dormant. When dormant, a widget is insensitive. This means that the widget does not respond to user input events.
setValuesBlock: argBlock
This message is provided to allow the values of multiple resources to be set together. Some resources, such as the constraint resources for CwForm are required to be set simultaneously to achieve correct behavior. The argBlock must contain resource set messages to the receiver. The receiver is also passed as the single parameter to the argBlock, and the messages should be sent to this parameter.
shell
Answer the shell widget in which the receiver is contained. Shell widgets answer themselves.
showWindow
Make the receiver visible.
tipText: aString
Specifies the mini/hover help text for the widget.
translateCoords: widgetPoint
Converts widget-relative coordinates to screen-relative coordinates and answer a Point representing the translated coordinates.
widgetPoint | The Point in widget-relative coordinates which is to be translated to screen-relative coordinates. |
traversalOn: aBoolean
Specifies if traversal is activated for this widget.
unmanageChild
Remove a widget from its parent’s managed list.
unmapWidget
Unmap a widget explicitly. This message unmaps a widget’s window from its display, causing it to become invisible.
updateDisplay
Synchronize the display by forcing all pending updates for the receiver’s display to be processed immediately. All updates for the receiver’s display are guaranteed to be processed before the call returns.
NOTE: This can not be called inside an XmNexposeCallback.
updateWidget
Synchronize the display by forcing all pending updates for the receiver to be processed immediately. This may cause pending updates for other widgets to also be processed but at minimum, all updates for the receiver are guaranteed to be processed before the call returns.
NOTE: This can not be called inside an XmNexposeCallback.
visible: aBoolean
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.
wbCursorPosition
Answer the position of the cursor relative to the receiver.
wbHasFocus
Answer whether the receiver has focus.
wbSetFocusToNext
Set focus to the next widget in the z-order order.
widgetNamed: aString
Answer the child of the receiver’s named aString.
width: anInteger
Specifies the width of the widget’s window in pixels, not including the border area.
window
Return the CgWindow associated with the receiver.
NOTE: This may return nil if the receiver has not been realized.
withAllChildren
Answer a collection of all of the receiver and the receiver’s children.
withAllMajorChildren
Answer a collection of all of the receiver and the receiver’s major children.
x: anInteger
Specifies the x-coordinate of the widget’s upper left-hand corner (excluding the border) in relation to its parent widget.
y: anInteger
Specifies the y-coordinate of the widget’s upper left-hand corner (excluding the border) in relation to its parent widget.
Callbacks & Events
About To Close Widget
These callbacks are triggered right before the widget is closed.
About To Manage Widget
These callbacks are triggered right after the widget is created but before it is managed.
About To Open Widget
These callbacks are triggered right before the widget is opened.
Button Press
These event handlers are triggered for any mouse button down events.
Button Release
These event handlers are triggered for any mouse button up events.
Button Menu
These event handlers are triggered for any button menu request events.
Button Motion
These event handlers are triggered for any pointer motion events while any button is down.
Button1 Motion
These event handlers are triggered for any pointer motion events while button 1 is down.
Button2 Motion
These event handlers are triggered for any pointer motion events while button 2 is down.
Button3 Motion
These event handlers are triggered for any pointer motion events while button 3 is down.
Closed Widget
These callbacks are triggered right after the widget is closed.
Destroy Callback
These callbacks are triggered when the widget is destroyed. This provides an opportunity to perform any final cleanup activities such as releasing operating system resources.
Help Callback
These callbacks are triggered when the help key sequence is pressed.
Key Press
These event handlers are triggered for any keyboard key down events.
Key Release
These event handlers are triggered for any keyboard key up events.
Opened Widget
These callbacks are triggered right after the widget is opened.
Pointer Motion
These event handlers are triggered for all pointer motion events.