diff options
Diffstat (limited to 'man/9/radiobutton')
| -rw-r--r-- | man/9/radiobutton | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/man/9/radiobutton b/man/9/radiobutton new file mode 100644 index 00000000..a439e224 --- /dev/null +++ b/man/9/radiobutton @@ -0,0 +1,192 @@ +.TH RADIOBUTTON 9 +.SH NAME +radiobutton \- Create and manipulate radiobutton widgets +.SH SYNOPSIS +\f5radiobutton\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -disabledcolor -justify +-activeforeground -font -relief +-anchor -foreground -takefocus +-background -highlightcolor -text +-bitmap -highlightthickness -underline +-borderwidth -image +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -command \fIcommand\fP +Specifies a Tk command to associate with the button. This command +is typically invoked when mouse button 1 is released over the button +window. The button's global variable (\f5-variable\fR option) will +be updated before the command is invoked. +.TP +.B -height \fIdist\fP +Specifies a desired height for the button. +If this option isn't specified, the button's desired height is computed +from the size of the image or bitmap or text being displayed in it. +.TP +.B -indicatoron \fIboolean\fP +Specifies whether or not the indicator should be drawn. +If false, the \f5relief\fP option is ignored and the widget's +relief is always \f5sunken\fP if the widget is selected +and \f5raised\fP otherwise. +.TP +.B -selectcolor \fIcolour\fP +Specifies a background colour to use when the button is selected. +If \f5indicatoron\fR is true, the colour applies to the indicator. +If \f5indicatoron\fR is false, this colour is used as the background +for the entire widget, in place of \f5background\fR or \f5activebackground\fR, +whenever the widget is selected. +If specified as an empty string, no special colour is used for +displaying when the widget is selected. +.ig +.TP +.B -selectimage \fIimage\fP +Specifies an image to display (in place of the \f5image\fR option) +when the radiobutton is selected. +This option is ignored unless the \f5image\fR option has been +specified. +.. +.TP +.B -state \fIstate\fP +Specifies one of three states for the radiobutton: \f5normal\fR, \f5active\fR, +or \f5disabled\fR. In normal state the radiobutton is displayed using the +\f5foreground\fR and \f5background\fR options. The active state is +typically used when the pointer is over the radiobutton. In active state +the radiobutton is displayed using the \f5activeforeground\fR and +\f5activebackground\fR options. Disabled state means that the radiobutton +should be insensitive: the default bindings will refuse to activate +the widget and will ignore mouse button presses. +In this state the \f5disabledcolor\fR and +\f5background\fR options determine how the radiobutton is displayed. +.TP +.B -value \fIstring\fP +Specifies value to store in the button's associated variable whenever +this button is selected. +.TP +.B -variable \fIstring\fP +Specifies name of global variable to set whenever this button is +selected. Changes in this variable also cause the button to select +or deselect itself. +Defaults to the value \f5selectedButton\fR. +.TP +.B -width \fIdist\fP +Specifies a desired width for the button. +If this option isn't specified, the button's desired width is computed +from the size of the image or bitmap or text being displayed in it. +.SH DESCRIPTION +The \f5radiobutton\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a radiobutton widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the radiobutton such as its colours, font, +text, and initial relief. The \f5radiobutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A radiobutton is a widget that displays a textual string, bitmap or image +and a diamond called an \fIindicator\fR. +If text is displayed, it must all be in a single font, but it +can occupy multiple lines on the screen (if it contains newlines) and +one of the characters may optionally be underlined using the +\f5underline\fR option. A radiobutton has +all of the behaviour of a simple button: it can display itself in either +of three different ways, according to the \f5state\fR option; +it can be made to appear +raised, sunken, or flat; and it invokes +a Tk command whenever mouse button 1 is clicked over the +check button. +.PP +In addition, radiobuttons can be \fIselected\fR. +If a radiobutton is selected, the indicator is normally +drawn with a sunken relief and a special colour, and +a Tk variable associated with the radiobutton is set to a particular +value. +If the radiobutton is not selected, the indicator is drawn with a +raised relief and no special colour. +Typically, several radiobuttons share a single variable and the +value of the variable indicates which radiobutton is to be selected. +When a radiobutton is selected it sets the value of the variable to +indicate that fact; each radiobutton also monitors the value of +the variable and automatically selects and deselects itself when the +variable's value changes. +By default the variable \f5selectedButton\fR +is used; its contents give the name of the button that is +selected, or the empty string if no button associated with that +variable is selected. +The name of the variable for a radiobutton, +plus the variable to be stored into it, may be modified with options +on the command line. +Configuration options may also be used to modify the way the +indicator is displayed (or whether it is displayed at all). +By default a radiobutton is configured to select itself on button clicks. +.SH "WIDGET COMMAND" +The \f5radiobutton\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for radiobutton widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5radiobutton\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5radiobutton\fR +command. +.TP +\fIpathName \f5deselect\fR +Deselects the radiobutton and sets the associated variable to an +empty string. +If this radiobutton was not currently selected, the command has +no effect. +.TP +\fIpathName \f5invoke\fR +Does just what would have happened if the user invoked the radiobutton +with the mouse: selects the button and invokes +its associated Tk command, if there is one. +The return value is the return value from the Tk command, or an +empty string if there is no command associated with the radiobutton. +This command is ignored if the radiobutton's state is \f5disabled\fR. +.TP +\fIpathName \f5select\fR +Selects the radiobutton and sets the associated variable to the +value corresponding to this widget. + +.SH BINDINGS +Tk automatically creates bindings for radiobuttons that give them +the following default behaviour: +.IP [1] +The radiobutton activates whenever the mouse passes over it and deactivates +whenever the mouse leaves the radiobutton. +.IP [2] +When mouse button 1 is pressed over a radiobutton it is invoked (it +becomes selected and the command associated with the button is +invoked, if there is one). +.PP +If the radiobutton's state is \f5disabled\fR then none of the above +actions occur: the radiobutton is completely non-responsive. +.PP +The behaviour of radiobuttons can be changed by defining new bindings for +individual widgets. +.SH SEE ALSO +.IR button (9), +.IR checkbutton (9), +.IR choicebutton (9), +.IR options (9), +.IR types (9) |