gtk.Button
Prev | The gtk Class Reference | Next

## gtk.Button

gtk.Button — A pushbutton widget that issues a signal when clicked.

## Synopsis

    class gtk.Button(gtk.Bin):
        gtk.Button(label=None, stock=None, use_underline=True)
        def pressed()
        def released()
        def clicked()
        def enter()
        def leave()
        def set_relief(newstyle)
        def get_relief()
        def set_label(label)
        def get_label()
        def set_use_underline(use_underline)
        def get_use_underline()
        def set_use_stock(use_stock)
        def get_use_stock()
        def set_focus_on_click(focus_on_click)
        def get_focus_on_click()
        def set_alignment(xalign, yalign)
        def get_alignment()
        def set_image(image)
        def get_image()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.Button

## gtk.Button Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"focus-on-click" | Read/Write | If `True` the button grabs focus when it is clicked with the mouse. Default value: `True`. This property is available in GTK+ 2.4 and above.
"image" | Read/Write | The child widget to appear next to the button text. Default value: `None`. This property is available in GTK+ 2.6 and above.
"image-position" | Read/Write | The position of the image relative to the text inside the button. One of the GTK Position Type Constants. Default value: `gtk.POS_LEFT`. This property is available in GTK+ 2.10 and above.
"label" | Read/Write | Text of the label widget inside the button, if the button contains a label widget. Default value: `None`.
"relief" | Read/Write | The border relief style. One of: `gtk.RELIEF_NORMAL`, `gtk.RELIEF_HALF` or `gtk.RELIEF_NONE`. Default value: `gtk.RELIEF_NORMAL`.
"use-stock" | Read/Write | If `True`, the label text is used to pick a stock item instead of being displayed. Default value: `False`.
"use-underline" | Read/Write | If `True`, an underscore in the text indicates the next character should be underlined and used for the mnemonic accelerator key if it is the first character so marked. Default value: `False`.
"xalign" | Read/Write | If the child of the button is a `gtk.Misc` or `gtk.Alignment`, this property can be used to control it's horizontal alignment. The value ranges from 0.0 to 1.0 representing the fraction of freespace to the left of the widget. Default value: 0.5. This property is available in GTK+ 2.4 and above.
"yalign" | Read/Write | If the child of the button is a `gtk.Misc` or `gtk.Alignment`, this property can be used to control it's vertical alignment. The value ranges from 0.0 to 1.0 representing the fraction of freespace above the widget. Default value: 0.5. This property is available in GTK+ 2.4 and above.

## gtk.Button Style Properties

gtk.Widget Style Properties

"child-displacement-x" | Read | The number of pixels in the x direction to move the child when the button is depressed. Default value: 0
"child-displacement-y" | Read | The number of pixels in the y direction to move the child when the button is depressed. Default value: 0
"default-border" | Read | The extra space to add for `gtk.CAN_DEFAULT` buttons as a `gtk.Border`
"default-outside-border" | Read | The extra space to add for `gtk.CAN_DEFAULT` buttons always drawn outside the border as a `gtk.Border`
"displace-focus" | Read | If `True` the "child-displacement-x" and "child-displacement-y" properties should also affect the focus rectangle. Default value: `False`. This property is available in GTK+ 2.6 and above.
"inner-border" | Read | The border between the button edges and child as a `gtk.Border`. This property is available in GTK+ 2.10 and above.

## gtk.Button Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"activate" | `def callback(`button`, `user_param1`, `...`)`
"clicked" | `def callback(`button`, `user_param1`, `...`)`
"enter" | `def callback(`button`, `user_param1`, `...`)`
"leave" | `def callback(`button`, `user_param1`, `...`)`
"pressed" | `def callback(`button`, `user_param1`, `...`)`
"released" | `def callback(`button`, `user_param1`, `...`)`

## Description

The `gtk.Button` widget is usually displayed as a pushbutton with a text label (`gtk.Label`) though it can contain any valid widget. The `gtk.Button` is generally used to attach a callback function or method that is called when the button is clicked. Buttons generate signals that indicate:

- "clicked" - the user pressed and released a mouse button over the button
- "pressed" - the user pressed a mouse button over the button
- "released" - the user released a mouse button over the button
- "enter" - the pointer entered the button
- "leave" - the pointer left the button

The "clicked" signal is usually the only signal that an application needs to handle.

If a label is being used by the button its text (the "label" property) is retrieved using the `get_label`() method. The label text is changed using the `set_label`() method.

The property ("use_underline") that tells a button to use the first underscore to indicate a mnemonic key is changed using the `set_use_underline`(). method. It can be retrieved using the `get_use_underline`() method.

The button's relief style (the "relief" property) is retrieved using the method `get_relief`(). The relief style is set to one of `gtk.RELIEF_NONE`, `gtk.RELIEF_HALF` or `gtk.RELIEF_NORMAL` using the method `set_relief`().

## Constructor

        gtk.Button(label=None, stock=None, use_underline=True)

`label` : | the text to be displayed by the button label including an underscore to indicate the mnemonic character if desired or `None` if no label is required.
`stock` : | the stock id identifying the stock image and text to be used in the button or `None` if no stock id is to be used.
`use_underline` : | if `True`, an underscore in the text indicates the next character should be underlined and used for the mnemonic accelerator key if it is the first character so marked. Available in PyGTK 2.4 and above.
Returns : | a new button object

Creates a new button widget with the content depending on the parameters: `label`, `stock` and `use_underline`. The default values for `stock` and `label` are `None` and, in PyGTK 2.4 and above, `use_underline` is available and defaults to `True`. If both `label` and `stock` are specified `stock` takes precedence. If neither is specified the button is created with no child widget. A child widget can be added later with the `add`() method.

If `stock` is specified the "use-stock" property will be set to `True`.

If `label` is specified the "label" property will be set with the text of the label, the "use_underline" property will be set to `True` and any characters that are preceded by an underscore are underlined (use two underscores to insert an underscore in a label). The first underscored character will become the mnemonic character used as the keyboard accelerator for the button when pressed simultaneously with the Alt key. In PyGTK 2.4 and above the "use-underline" property can be set by using the optional `use_underline` parameter.

## Methods

### gtk.Button.pressed

        def pressed()

The `pressed`() method emits the "pressed" signal to the button.

### gtk.Button.released

        def released()

The `released`() method emits the "released" signal to the button.

### gtk.Button.clicked

        def clicked()

The `clicked`() method emits the "clicked" signal to the button.

### gtk.Button.enter

        def enter()

The `enter`() method emits the "enter" signal to the button.

### gtk.Button.leave

        def leave()

The `leave`() method emits the "leave" signal to the button.

### gtk.Button.set_relief

        def set_relief(newstyle)

`newstyle` : | one of `gtk.RELIEF_NONE`, `gtk.RELIEF_NORMAL` or `gtk.RELIEF_HALF`

The `set_relief`() method sets the relief style of the edges of the button. Three styles exist, `gtk.RELIEF_NORMAL`, `gtk.RELIEF_HALF`, `gtk.RELIEF_NONE`. The default style is, as one can guess, `gtk.RELIEF_NORMAL`.

### gtk.Button.get_relief

        def get_relief()

Returns : | the relief style

The `get_relief`() method retrieves the current relief style (the "relief" property) set for the button.

### gtk.Button.set_label

        def set_label(label)

`label` : | a string to be set as the text in the button label

The `set_label`() method sets the text of the button label to `label` (also sets the "label" property). This string is also used to select the stock item if the "use_stock" property is `True` and the string references a stock item. Any previously set labels will be cleared.

### gtk.Button.get_label

        def get_label()

Returns : | the text of the label widget.

The `get_label`() method retrieves the text from the label of the button, as set by `set_label`() or by the `gtk.Button`() constructor. This string is owned by the widget and must not be modified or freed. If the label text has not been set the return value will be `None`. This will be the case if you create an empty button with `gtk.Button`() to use as a container.

### gtk.Button.set_use_underline

        def set_use_underline(use_underline)

`use_underline` : | `True` if underscores in the text indicate mnemonics

The `set_use_underline`() method sets the "use_underline" property to the value of `use_underline`. If `use_underline` is `True`, an underscore in the text of the button label indicates that the next character should be underlined and used for the mnemonic accelerator key if it is also the first underlined character.

### gtk.Button.get_use_underline

        def get_use_underline()

Returns : | `True` if an underscore in the button label indicates the mnemonic accelerator keys.

The `get_use_underline`() method returns whether the "use_underline" property is `True` meaning that an underscore in the button label indicates a mnemonic. See `set_use_underline`().

### gtk.Button.set_use_stock

        def set_use_stock(use_stock)

`use_stock` : | If `True` the button should use a stock item

The `set_use_stock`() method sets the "use_stock" property to the value of `use_stock`. If `use_stock` is `True`, the label set on the button is used as a stock id to select the stock item for the button.

### gtk.Button.get_use_stock

        def get_use_stock()

Returns : | the value of the "use_stock" property.

The `get_use_stock`() method returns the value of the "use_stock" property. If `True` the button label is used to select a stock item instead of being used directly as the label text.

### gtk.Button.set_focus_on_click

        def set_focus_on_click(focus_on_click)

`focus_on_click` : | If `True` the button grabs focus when clicked with the mouse.

### Note

This method is available in PyGTK 2.4 and above.

The `set_focus_on_click`() method sets the "focus-on-click" property to the value of `focus_on_click`. If `focus_on_click` is `True`, the button grabs focus when it is clicked by the mouse.

### gtk.Button.get_focus_on_click

        def get_focus_on_click()

Returns : | the value of the "focus-on-click" property.

### Note

This method is available in PyGTK 2.4 and above.

The `get_focus_on_click`() method returns the value of the "focus-on-click" property. If `True` the button grabs focus when it is clicked by the mouse .

### gtk.Button.set_alignment

        def set_alignment(xalign, yalign)

`xalign` : | the horizontal alignment of the child widget. The value ranges from 0.0 to 1.0 and represents the fraction of freespace to the left of the child widget.
`yalign` : | the vertical alignment of the child widget. The value ranges from 0.0 to 1.0 and represents the fraction of freespace above the child widget.

### Note

This method is available in PyGTK 2.4 and above.

The `set_alignment`() method sets the "xalign" and "yalign" properties to the value of `xalign` and `yalign` respectively. This property has no effect unless the child is a `gtk.Misc` or a `gtk.Alignment`.

### gtk.Button.get_alignment

        def get_alignment()

Returns : | a 2-tuple containing the values of the "xalign" and "yalign" properties.

### Note

This method is available in PyGTK 2.4 and above.

The `get_alignment`() method returns the values of the "xalign" and "yalign" properties. See the `set_alignment`() method for more information.

### gtk.Button.set_image

        def set_image(image)

`image` : | the widget to set as the image for the button.

### Note

This method is available in PyGTK 2.6 and above.

The `set_image`() method sets the "image" property to the value of `image`. This property has no effect unless the "gtk-button-images" property is `True`. See the `gtk.Settings` reference for more information. Note you do not have to call the `gtk.Widget.show`() method for `image`.

### gtk.Button.get_image

        def get_image()

Returns : | the `gtk.Widget` used as the button image or `None` if there is no image.

### Note

This method is available in PyGTK 2.6 and above.

The `get_image`() method returns the value of the "image" property. See the `set_image`() method for more information.

## Signals

### The "activate" gtk.Button Signal

        def callback(button, user_param1, ...)

`button` : | the button that received the "activate" signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "activate" signal is emitted when the `gtk.Widget.activate`() method is called. For a button it causes the "clicked" signal to be emitted.

### The "clicked" gtk.Button Signal

        def callback(button, user_param1, ...)

`button` : | the button that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "clicked" signal is emitted when the mouse button is pressed and released while the pointer is over the button.

### The "enter" gtk.Button Signal

        def callback(button, user_param1, ...)

`button` : | the button that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "enter" signal is emitted when the pointer enters the button.

### The "leave" gtk.Button Signal

        def callback(button, user_param1, ...)

`button` : | the button that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "leave" signal is emitted when the pointer leaves the button.

### The "pressed" gtk.Button Signal

        def callback(button, user_param1, ...)

`button` : | the button that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "pressed" signal is emitted when the mouse button is pressed while the pointer is over the button.

### The "released" gtk.Button Signal

        def callback(button, user_param1, ...)

`button` : | the button that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "released" signal is emitted when the button is released no matter where the pointer is.

Prev | Up | Next
gtk.Box | Home | gtk.ButtonBox