<section ID="chapter.widgets.tbradiobutton">
  <TITLE>Tbradiobutton widget</TITLE>

<subsection> <TITLE>Description</TITLE>

<P>
A tbradiobutton 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. 
</P>
<P>
Tbradiobuttons are grouped together with other tbradiobuttons, radiobuttons of menus and radiobuttons by specifying the same atom to the <<group>> parameter. Only one button of a same group can be on at a time.
</P>
<P>
A tbradiobutton has four differents states that have their own combinations of colors and border type :
<LIST>

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

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

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

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

</LIST>

<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>
<ITEM> <<1:B>> : Specifies if the button is on or off. If <<B>> is <<true>> then the button is selelected. All other radiobuttons in the same group are deselected. If <<B>> is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter can be used with the <<set()>> and <<get()>> methods only. <<B>> must be a boolean.

<ITEM> <<init:B>> : Specifies if the button is on or off. If <<B>> is <<true>> then the button is selelected. All other radiobuttons in the same group are deselected. If <<B>> is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter is valid at creation time only. <<B>> must be a boolean.

<ITEM> <<return:V>> : When the window is closed, <<V>> is bound to <<true>> if the radiobutton, false otherwise. This parameter is valid at creation time only. <<V>> must be a free variable.

<ITEM> <<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 <ptr to="misc.color">)

<ITEM> <<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 <ptr to="misc.color">)

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

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

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

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

<ITEM> <<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 <ptr to="misc.color">)

<ITEM> <<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 <ptr to="misc.color">)

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

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

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

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

<ITEM> <<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 <ptr to="misc.color">)

<ITEM> <<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 <ptr to="misc.color">)

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

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

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

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

<ITEM> <<disabledforeground:C>> : Specifies the foreground color to display when the widget is disabled.  <<C>> must be a valid color (see <ptr to="misc.color">)

<ITEM> <<disabledbackground:C>> : Specifies the background color to display when the widget is disabled.  <<C>> must be a valid color (see <ptr to="misc.color">)

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

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

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

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

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

&param_text;

<ITEM> <<action:C>> : Specifies an action to execute juste after the user clicked the button. <<C>> can take several different forms (see <ptr to="basics.events">).

<ITEM> <<group:A>> : Specifies what group the radiobutton belongs to. All radiobuttons that use the same <<A>> belong to the same group (only one can be selected at a time in a group). Valid at necessary at creation time only. <<A>> must be an atom.

&param_glue;
&param_padx;
&param_pady;
&param_feature;
&param_handle;
&param_tooltips;


</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>

<P>
The object you get by an handle on the widget implements the following methods :

<LIST>

&interface_set;
&interface_get;
&interface_bind;
&interface_getFocus;
&interface_setGrab;
&interface_releaseGrab;
&interface_getGrabStatus;
&interface_raise;
&interface_lower;
&interface_winfo;

</LIST>
</section>
