7.17 Tbcheckbutton widget

local 
   Desc=td(
           lr(glue:nwe
              tbbutton(glue:w
                       text:"tbbutton" )
              tdline(glue:wns)
              tbcheckbutton(glue:w
                            text:"tbcheckbutton")
              tdspace(glue:w width:20)
              tbradiobutton(glue:w
                            text:"tbradiobutton" 
                            init:true 
                            group:radio)
              tbradiobutton(glue:w
                            text:"tbradiobutton" 
                            group:radio)))
in 
   {{QTk.build Desc} show}
end

7.17.1 Description

A tbcheckbutton is a widget that displays a textual string and a bitmap or image. If text is displayed, it is displayed below the bitmap or image if ever here is one defined. A tbcheckbutton has a flat border that gets raised when the mouse cursor gets over it. If the mouse 1 button is clicked, the tbbutton gets a sunken border. A tbcheckbutton is specially suited for toolbar buttons that looks like the toolbars of Netscape or Internet Explorer. When a user invokes the button (by pressing mouse button 1 with the cursor over the button), then the command specified in the action option is invoked and the button is switched on or off.

A tbcheckbutton has four differents states that have their own combinations of colors and border type :

• normal : State when the button is not disabled and when the mouse cursor is not above it. The colors are defined by the foreground and background parameters. The border is defined by the borderwidth and relief parameters. The picture displayed is defined by either by bitmap or image.

• highlighted : State when the button is not disabled and when the mouse cursor is above it. The colors are defined by the highlightforeground and highlightbackground parameters. The border is defined by the highlightborderwidth and highlightrelief parameters. The picture displayed is defined by either by highlightbitmap or highlightimage.

• selected : State when the button is not disabled and when the mouse cursor is above it and the mouse button 1 is currently clicked. The colors are defined by the selectforeground and selectbackground parameters. The border is defined by the selectborderwidth and selectrelief parameters. The picture displayed is defined by either by selectbitmap or selectimage.

• disabled : State when the button is not enabled. The colors are defined by the disabledforeground and disabledbackground parameters. The border is defined by the disabledborderwidth and disabledrelief parameters. The picture displayed is defined by either by disabledbitmap or disabledimage.

7.17.2 Parameter List

Specific Parameters

1 action actionh background bitmap borderwidth disabledbackground disabledbitmap disabledborderwidth disabledforeground disabledimage disabledrelief disabledstate foreground highlightbackground highlightbitmap highlightborderwidth highlightforeground highlightimage highlightrelief image init relief return selectbackground selectbitmap selectborderwidth selectforeground selectimage selectrelief

Non Specific Parameters

feature glue handle look onCreation padx pady text tooltips

7.17.3 Method List

'raise'

'raise'(1:W): If the W argument is omitted then the command raises the widget so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the 'raise' command will insert this widget into the stacking order just above W; this could end up either raising or lowering the widget.

bind

bind(event:E action:A args:LA append:AP): Specifies an action LA to execute when the event E is triggered.

• Actions can be specified either as a procedure, a pair Port#Message or a pair Object#Method (see Section 4.3.3).

• Events are strings (see Section 8.11.1).

• The list of arguments LA specifies supplementary information to pass to the action, like the key code of a keypress, or the mouse coordinates of a mouse button click (see Section 8.11.2). If LA if not specified, nil is assumed.

• The boolean append parameter specifies if the binding overrides the previous binding for this event, or adds a supplementary action. If not specified, false is assumed.

get

get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.

getFocus

getFocus(force:B): if B is false (or by default): if the application currently has the input focus on the widget's display, this command resets the input focus for the widget's display to the widget. If the application doesn't currently have the input focus on the widget's display, the widget will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, it will be redirected it to the widget. If B is true: sets the focus of the widget's display to the widget, even if the application doesn't currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. B must be a boolean.

getGrabStatus

getGrabStatus(1:V): Binds V to the atom none if there is no grab on the widget, to the atom local if there is a local grab and to global if there is a global grab. V must be a free variable.

lower

lower(1:W): If the W argument is omitted then the command lowers the widget so that it is below all of its siblings in the stacking order (it will be obscured by any siblings and will not obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the lower command will insert this widget into the stacking order just below W; this could end up either raising or lowering the widget.

releaseGrab

releaseGrab: Releases the grab on the widget if there is one, otherwise does nothing.

set

set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.

setGrab

setGrab(global:B): Sets a grab on the widget. If B is true then the grab is global, otherwise it is local (B false by default). If a grab was already in effect for this application then it is automatically released. If there is already a grab on the widget and it has the same global/local form as the requested grab, then the command does nothing. Local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either. Warning: whe a grab is set, it is define for the whole Oz process so that it will prevent the user to do input to other windows as well. Moreover a grab is still effective even if the window that contains the grabbed widgets is hidden. B must be a boolean.

winfo

winfo(parameter1:value1 ... parameterX:valueX): This commands works like the get method, but for window-related information. For more details, see Section 8.9.

7.17.4 Detailed Parameters List

1:B: Specifies whether the button is on or off. B must be a boolean. Can be used with the set() and get() methods only.

action:C: Specifies an action to execute right after the user clicked the button. C can take several different forms (see Section 4.3.1).

actionh:C: Similar to the action parameter where then handle of the widget is given as a parameter to the action to be executed. This parameter overrides the action parameter when present.

background:C: or bg:C: Specifies the background color to display when the mouse cursor is not over the widget (if it is not disabled). C must be a valid color (see Section 8.2)

bitmap:B: Specifies the bitmap to display when the mouse cursor is not over the widget (if it is not disabled). If there is an image defined, this option is ignored.

borderwidth:P: Specifies the border width to display when the mouse cursor is not over the widget (if it is not disabled).

disabledbackground:C: Specifies the background color to display when the widget is disabled. C must be a valid color (see Section 8.2)

disabledbitmap:B: Specifies the bitmap to display when the widget is disabled. If there is an image defined, this option is ignored. Is this option is not specified, it defaults to the value of the bitmap parameter.

disabledborderwidth:P: Specifies the border width to display when the the widget is disabled.

disabledforeground:C: Specifies the foreground color to display when the widget is disabled. C must be a valid color (see Section 8.2)

disabledimage:I: Specifies the image to display when the widget is disabled. Is this option is not specified, it defaults to the value of the image parameter.

disabledrelief:A: Specifies the relief to display when the the widget is disabled. Defaults to flat.

disabledstate:A: Specifies one of two states for the button: normal or disabled. In normal state the button is displayed using the foreground and background options. Disabled state means that the button should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the disabledforeground and background options determine how the button is displayed. A must be one of these three atoms: normal or disabled.

foreground:C: or fg:C: Specifies the foreground color to display when the mouse cursor is not over the widget (if it is not disabled). C must be a valid color (see Section 8.2)

highlightbackground:C: Specifies the background color to display when the mouse cursor is over the widget (if it is not disabled). C must be a valid color (see Section 8.2)

highlightbitmap:B: Specifies the bitmap to display when the mouse cursor is over the widget (if it is not disabled). If there is an image defined, this option is ignored. Is this option is not specified, it defaults to the value of the bitmap parameter.

highlightborderwidth:P: Specifies the border width to display when the mouse cursor is over the widget (if it is not disabled).

highlightforeground:C: Specifies the foreground color to display when the mouse cursor is over the widget (if it is not disabled). C must be a valid color (see Section 8.2)

highlightimage:I: Specifies the image to display when the mouse cursor is over the widget (if it is not disabled). Is this option is not specified, it defaults to the value of the image parameter.

highlightrelief:A: Specifies the relief to display when the mouse cursor is over the widget (if it is not disabled). Defaults to raised.

image:I: Specifies the image to display when the mouse cursor is not over the widget (if it is not disabled).

init:B: Specifies whether the button is on or off. B must be a boolean. Can be used at creation time only.

feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.

glue:A: Specifies how a widget must fit in its own available place. A must be an atom that is any combination of n, s, w and e. If a direction is specified, the corresponding border is glued to its neighbor or border of the frame if there is no neighbor. If a direction is not specified, the corresponding border if such that the widget takes just the width or height it needs to draw itself. If none of opposite directions is specified, the widget is centered. For more details, see Section 4.1.

handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.

look:L: Specifies a look to use for the widget. A look specifies default values for the parameters of widgets. This parameter can be specified at creation time only. Moreover changing a look will not change the appearance of widgets that are already displayed with that look. See Section 5.1 for more details.

onCreation:P: When a widget is created, for example by QTk.build, this parameter specifies an action to execute right after the widget has been created, but before returning from the build instruction. It is usefull if one needs the handle of the widget to initialize it in ways not permitted by its description record (for example binding the Enter or Leave mouse events).

padx:P: Specifies how much horizontal external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

pady:P: Specifies how much vertical external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

text:VS: Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify. VS must be a virtual string.

tooltips:VS: Specifies a tooltip for the widget. A tooltip is a small message that appears when the mouse cursor if left still over the widget for a while. If VS is set to nil, no tooltip will appear at all. VS must be a virtual string.

relief:A: Specifies the relief to display when the mouse cursor is not over the widget (if it is not disabled). Defaults to flat.

return:V: When the window is closed, B is bound to true if the checkbutton is selected, false otherwise. V must be a free variable.

selectbackground:C: Specifies the background color to display when the user clicks the widget (if it is not disabled). C must be a valid color (see Section 8.2)

selectbitmap:B: Specifies the bitmap to display when the user clicks the widget (if it is not disabled). If there is an image defined, this option is ignored. Is this option is not specified, it defaults to the value of the bitmap parameter.

selectborderwidth:P: Specifies the border width to display when the user clicks the widget (if it is not disabled).

selectforeground:C: Specifies the foreground color to display when the user clicks the widget (if it is not disabled). C must be a valid color (see Section 8.2)

selectimage:I: Specifies the image to display when the user clicks the widget (if it is not disabled). Is this option is not specified, it defaults to the value of the image parameter.

selectrelief:A: Specifies the relief to display when the user clicks the widget (if it is not disabled). Defaults to sunken.