button widget
Gtk2: A GtkButton containing either a GtkLabel, a GtkImage or both packed inside a GtkHBox or GtkVBox
Gtk3: A GtkButton containing either a GtkLabel, a GtkImage or both packed inside a GtkBox
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 - Gtk2) |
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” (Gtk2, Gtk3), 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:
Gtk2: 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
Gtk3: 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 |
| variable_is_true(argument) |
Value of widget |
Variable name |
0.8.5 |
| variable_is_false(argument) |
Value of widget |
Variable name |
0.8.5 |
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
The existing “image-position” (Gtk2, Gtk3) GTK+ property – normally only applicable to stock buttons – has been extended to apply to all Gtkdialog buttons. The existing “homogeneous” (Gtk2, Gtk3) GTK+ property – applicable to the hbox and vbox – can be used here to affect the box inside the button when including an image and a label. 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). 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,
chooser,
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,
|