gtk.Button A pushbutton widget that issues a signal when clicked. Synopsis gtk.Button gtk.Bin gtk.Button labelNone stockNone use_underlineTrue pressed released clicked enter leave set_relief newstyle get_relief set_label label get_label set_use_underline use_underline get_use_underline set_use_stock use_stock get_use_stock set_focus_on_click focus_on_click get_focus_on_click set_alignment xalign yalign get_alignment set_image image get_image set_image_position position get_image_position get_event_window Ancestry +-- gobject.GObject +-- gtk.Object +-- gtk.Widget +-- gtk.Container +-- gtk.Bin +-- gtk.Button Implemented Interfaces gtk.Button implements gtk.Buildable 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 . 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. "image-spacing" Read Spacing in pixels between the image and the label. Allowed values: >=0. Default value: 2. "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" callback button user_param1 ... "clicked" callback button user_param1 ... "enter" callback button user_param1 ... "leave" callback button user_param1 ... "pressed" callback button user_param1 ... "released" 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 labelNone stockNone use_underlineTrue 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 pressed This method is deprecated since PyGTK 2.22 and should not be used in newly-written code. Use the "button-press-event" signal. The pressed() method emits the "pressed" signal to the button. gtk.Button.released released This method is deprecated since PyGTK 2.22 and should not be used in newly-written code. Use the "button-release-event" signal. The released() method emits the "released" signal to the button. gtk.Button.clicked clicked The clicked() method emits the "clicked" signal to the button. gtk.Button.enter enter This method is deprecated since PyGTK 2.22 and should not be used in newly-written code. Use the "enter-notify-event" signal. The enter() method emits the "enter" signal to the button. gtk.Button.leave leave This method is deprecated since PyGTK 2.22 and should not be used in newly-written code. Use the "leave-notify-event" signal. The leave() method emits the "leave" signal to the button. gtk.Button.set_relief 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 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 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 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 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 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 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 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 set_focus_on_click focus_on_click focus_on_click : If True the button grabs focus when clicked with the mouse. 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 get_focus_on_click Returns : the value of the "focus-on-click" property. 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 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. 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 get_alignment Returns : a 2-tuple containing the values of the "xalign" and "yalign" properties. 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 set_image image image : the widget to set as the image for the button. 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 get_image Returns : the gtk.Widget used as the button image or None if there is no image. 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. gtk.Button.set_image_position set_image_position position position : the position of the image relative to the text inside the button. This method is available in PyGTK 2.10 and above. The set_image_position() method sets the position of the image relative to the text inside the button. The value of position can be one of the . gtk.Button.get_image_position get_image_position Returns : the position of the image relative to the text inside the button. This method is available in PyGTK 2.10 and above. The get_image_position() method returns the position of the image relative to the text inside the button. gtk.Button.get_event_window get_event_window Returns : the button's event window if it is realized, None otherwise. This method is available in PyGTK 2.22 and above. The get_event_window() method returns the the button's event window if it is realized, None otherwise. Signals The "activate" gtk.Button Signal 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 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 or when the button is triggered with the keyboard. The "enter" gtk.Button Signal 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) This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code. Use the "enter-notify-event" signal. The "enter" signal is emitted when the pointer enters the button. The "leave" gtk.Button Signal 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) This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code. Use the "leave-notify-event" signal. The "leave" signal is emitted when the pointer leaves the button. The "pressed" gtk.Button Signal 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) This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code. Use the "button-press-event" signal. The "pressed" signal is emitted when the mouse button is pressed while the pointer is over the button. The "released" gtk.Button Signal 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) This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code. Use the "button-release-event" signal. The "released" signal is emitted when the button is released no matter where the pointer is.