# button widget A GtkButton containing either a GtkLabel, a GtkImage or both packed inside a GtkHBox or GtkVBox ## Definition
    <button yes no ok cancel help tag_attr="value"...>
    	<label>text</label>
    	<variable>varname</variable>
    	<height>value</height>
    	<width>value</width>
    	<input file>filename</input>
    	<input file icon="image"></input>
    	<input file stock="gtk-image"></input>
    	<sensitive>state</sensitive>
    	<action>activity</action>...
    	<action signal="type">activity</action>...
    	<action function="type">parameter</action>...
    </button>
"..." denotes acceptance of multiples of the same thing. ## Tag Attributes See the GtkButton widget and ancestor class properties. The following custom tag attributes are available:
Name | Description | Value | Since
--- | --- | --- | ---
space-expand | Pack widget expanding into space | `true` or `false` | 0.7.21
space-fill | Pack widget filling space | `true` or `false` | 0.7.21
block-function-signals | Block signal emissions from functions | `true` or `false` | 0.7.21
file-monitor | Emit signal when input file(s) change | `true` or `false` | 0.8.1
auto-refresh | Auto refresh when input file(s) change | `true` or `false` | 0.8.1
image-position[1] | Image position relative to label | `0`, `1`, `2`, `3` (left, right, top, bottom) | 0.7.21
homogeneous[2] | Horizontal uniformity of an image with label | `true` or `false` | 0.8.1
theme-icon-size | The size of the GTK theme icon | An integer > `0` or `-1` to ignore | 0.8.1
stock-icon-size | The size of the GTK stock icon | `0` to `6` (see GtkIconSize) | 0.8.1
## Directives Some of these may have tag attribute equivalents.
Name | Description | Contents | Since
--- | --- | --- | ---
label | Initial text |  |
variable | Variable name |  |
variable export="false" | Variable name, not exported to shell |  | 0.8.3
height | Image scaling dimension | An integer > `0` or `-1` to ignore | 0.7.21
width | Image scaling dimension | An integer > `0` or `-1` to ignore | 0.7.21
input file | Data input source | Image filename |
input file icon="image"[3] | GTK theme icon name |  |
input file stock="gtk-image"[4] | GTK stock icon ID | `gtk-about`, `gtk-add`, ... (full list) |
sensitive | Sensitive state | `true` or `false` | 0.7.21
action | Execute command on default signal | Shell command |
action | Perform function on default signal | function:parameter |
action signal="type" | Execute command on signal | Shell command |
action signal="type" | Perform function on signal | function:parameter |
action function="type" | Perform function on default signal | parameter | 0.8.3
action condition="type" | Execute command on default signal conditionally | Shell command | 0.8.3
action condition="type" | Perform function on default signal conditionally | function:parameter | 0.8.3
action signal="type" condition="type" | Execute command on signal conditionally | Shell command | 0.8.3
action signal="type" condition="type" | Perform function on signal conditionally | function:parameter | 0.8.3
action function="type" condition="type" | Perform function on default signal conditionally | parameter | 0.8.3
## Signals The default signal is "clicked", emitted when the button has been activated (pressed and released). The "file-changed" signal is emitted if file-monitor is true and the input file being monitored has changed. The following signals are connected-up for all widgets: button-press-event, button-release-event, configure-event, enter-notify-event, leave-notify-event, focus-in-event, focus-out-event, hide, show, realize, key-press-event, key-release-event, map-event, unmap-event ## Functions The following functions can be performed upon this widget by any widget capable of emitting signals:
Type | Description | Parameter | Since
--- | --- | --- | ---
enable | Sensitise widget | Variable name |
disable | Desensitise widget | Variable name |
show | Show widget | Variable name | 0.8.1
hide | Hide widget | Variable name | 0.8.1
activate | Activate widget | Variable name | 0.8.1
grabfocus | Grab input focus | Variable name | 0.8.1
refresh | Reload input data | Variable name | 0.7.21
The following general functions can be performed by any widget capable of emitting signals:
Type | Description | Parameter | Since
--- | --- | --- | ---
break | Break out of actions list | None | 0.8.3
command | Execute command | Shell command |
exit | Exit dialog | A value for the `EXIT` variable |
closewindow | Close dialog | Variable name |
launch | Launch dialog | Variable name |
presentwindow | Present dialog | Variable name | 0.8.1
## Conditions The following conditions can be used within the condition attribute of action directives:
Type | Description | Argument | Since
--- | --- | --- | ---
active_is_true(argument) | Active state of toggle widget | Variable name | 0.8.3
active_is_false(argument) | Active state of toggle widget | Variable name | 0.8.3
command_is_true(argument) | Output of shell command | Shell command | 0.8.3
command_is_false(argument) | Output of shell command | Shell command | 0.8.3
file_is_true(argument) | Contents of a file | Filename | 0.8.3
file_is_false(argument) | Contents of a file | Filename | 0.8.3
sensitive_is_true(argument) | Sensitive state of widget | Variable name | 0.8.3
sensitive_is_false(argument) | Sensitive state of widget | Variable name | 0.8.3
visible_is_true(argument) | Visible state of widget | Variable name | 0.8.3
visible_is_false(argument) | Visible state of widget | Variable name | 0.8.3
true means "true", "yes" or a non-zero value, false means "false", "no" or zero, therefore the shell command is expected to echo one of these values to stdout. ## Notes 1. The existing "image-position" GTK+ property -- normally only applicable to stock buttons -- has been extended to apply to all Gtkdialog buttons. 2. The existing "homogeneous" GTK+ property -- applicable to the hbox and vbox -- can be used here to effect the box inside the button when including an image and a label. 3. Theme icons default to 20 and do not scale or refresh (the "theme-icon-size" custom tag attribute can be used to request a size). 4. Stock icons default to GTK_ICON_SIZE_BUTTON and do not scale or refresh (the "stock-icon-size" custom tag attribute can be used to request a size). button, checkbox, colorbutton, comboboxentry, comboboxtext, combobox, edit, entry, eventbox, expander, fontbutton, frame, hbox, hscale, hseparator, list, menubar, menuitemseparator, menuitem, menu, notebook, pixmap, progressbar, radiobutton, separator, spinbutton, statusbar, table, terminal, text, timer, togglebutton, tree, vbox, vscale, vseparator, window,