org.gnome.gtk

## Class Button

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Widget
        - - org.gnome.gtk.Container
          - - org.gnome.gtk.Bin
            - - org.gnome.gtk.Button

- All Implemented Interfaces:
    Activatable
  Direct Known Subclasses:
    ColorButton, FontButton, LinkButton, ScaleButton, ToggleButton

      public class Button
      extends Bin
      implements Activatable

  A Widget that emits a signal when clicked on. Button can hold any just about any other Widget as its child. The most commonly used child is a Label, and there are convenience methods to help you just create a button with the given text automatically, notably the `Button(String)` constructor.

  Since Button is a Bin it strictly only has one child. Internally, however, it may have both an icon image and some text (which is the look commonly seen in the action buttons in Dialog boxes). You can add such an image to a Button by calling `setImage()`; this works alongside and with `setLabel()`. The machinery within Button will manage creating the necessary internal structure (HBoxes, Alignments, etc).

  Since:
    4.0.0
  Author:
    Andrew Cowie, Vreixo Formoso, Mario Torre

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Button.Clicked` Event generated when a user presses and releases a button, causing it to activate.

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Widget

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Button()` Create an "empty" button to use as a Container.
    `Button(Stock stock)` Create a new Button with a Label and Image from a StockItem.
    `Button(String text)` Create a button with a Label as its child.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(Button.Clicked handler)` Hook up a handler to receive `Button.Clicked` events on this Button.
    `void` | `emitClicked()` Cause a `Button.Clicked` signal to be emitted.
    `float` | `getAlignmentX()` Get the horizontal alignment of the child Widget within this Button.
    `float` | `getAlignmentY()` Get the vertical alignment of the child Widget within this Button.
    `Image` | `getImage()` Get the Image associated with this Button.
    `String` | `getLabel()` Get the text showing on the Button.
    `Action` | `getRelatedAction()` Get the Action that is triggered when this Activatable is activated, if any.
    `ReliefStyle` | `getRelief()` Get the relief style in use around this Button.
    `void` | `setAlignment(float xalign, float yalign)` Set the alignment of the child Widget within the Button.
    `void` | `setFocusOnClick(boolean setting)` Set whether clicking the Button will cause the Button to grab the focus.
    `void` | `setImage(Image image)` Paint an arbitrary Image over this Button.
    `void` | `setLabel(String text)` Set the text showing in the Button.
    `void` | `setRelatedAction(Action action)` Set the Action that is triggered when this Activatable is activated.
    `void` | `setRelief(ReliefStyle style)` Set the "relief" style used to determine how the edges of this Button will be decorated.

    - ### Methods inherited from class org.gnome.gtk.Bin

      `getChild`

    - ### Methods inherited from class org.gnome.gtk.Container

      `add, getChildren, remove, setBorderWidth`

    - ### Methods inherited from class org.gnome.gtk.Widget

      `activate, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Button

          public Button()

      Create an "empty" button to use as a Container. You'll need to `add()` the Widget which will be the Button's child.

      For most uses `setImage()` and `setLabel()` will more than take care of things; they can be used together.

      Since:
        4.0.0

    - #### Button

          public Button(Stock stock)

      Create a new Button with a Label and Image from a StockItem. By using a system StockItem, the newly created Button with use the same Label and Image as other GNOME applications. To ensure consistent look-n-feel between applications, it is highly recommend that you use provided StockItems whenever possible.
      Parameters:
        `stock` - The stock item that will determine the text and icon of the Button.
      Since:
        4.0.4

    - #### Button

          public Button(String text)

      Create a button with a Label as its child. Simply specify the text you want for the Label and a Button will be created accordingly. This is quite a common case - in fact, we're generally more used to thinking of Buttons as being Labels that you can press than as arbitrary Widget Containers.

      Note that you can use `setImage()` on a Button created this way.

      Parameters:
        `text` - the text you wish on the Label that will be created in the Button.
      Since:
        4.0.0

  - ### Method Detail

    - #### connect

          public void connect(Button.Clicked handler)

      Hook up a handler to receive `Button.Clicked` events on this Button. See `Button.Clicked` for a detailed discussion of how to connect signals.
      Since:
        4.0.0

    - #### emitClicked

          public void emitClicked()

      Cause a `Button.Clicked` signal to be emitted.
      Since:
        4.0.6

    - #### getAlignmentX

          public float getAlignmentX()

      Get the horizontal alignment of the child Widget within this Button. The return will range from 0.0 (full left) to 1.0 (full right).

    - #### getAlignmentY

          public float getAlignmentY()

      Get the vertical alignment of the child Widget within this Button. The return will range from 0.0 (top) to 1.0 (bottom).

    - #### getImage

          public Image getImage()

      Get the Image associated with this Button.
      Returns:
        the Widget associated with this Button using the `setImage()` method, or `null` if the Button doesn't have one set.
      Since:
        4.0.5

    - #### getLabel

          public String getLabel()

      Get the text showing on the Button.
      Returns:
        the text of the Label, or `null` if the no-arg constructor was used and you've just got an arbitrary Widget-containing-Button, not the more usual Button-with-Label.
      Since:
        4.0.0

    - #### getRelatedAction

          public Action getRelatedAction()

      Description copied from interface: `Activatable`
      Get the Action that is triggered when this Activatable is activated, if any.
      Specified by:
        `getRelatedAction` in interface `Activatable`

    - #### getRelief

          public ReliefStyle getRelief()

      Get the relief style in use around this Button.
      Since:
        4.0.1

    - #### setAlignment

          public void setAlignment(float xalign,
                          float yalign)

      Set the alignment of the child Widget within the Button. This has no impact unless the child of the Button is a Misc (which of course the default child, a Label, is).
      Parameters:
        `xalign` - from 0.0f representing fully left-aligned through 1.0f representing fully right-aligned.
        `yalign` - from 0.0f for fully top-aligned through 1.0f for fully bottom-aligned

    - #### setFocusOnClick

          public void setFocusOnClick(boolean setting)

      Set whether clicking the Button will cause the Button to grab the focus. The default is `true`, the behaviour you're accustomed to with regular Buttons. Setting this to `false` is only used in unusual situations like toolboxes where you don't want to steal focus away from where the main action is taking place.
      Since:
        4.0.8

    - #### setImage

          public void setImage(Image image)

      Paint an arbitrary Image over this Button. If this is used on an empty Button then the Button will be the size of the Image and will what is activatable. On the other hand, you can use this in conjunction with `setLabel()` in which case you will get an icon on the left and the label text on the right.
      Since:
        4.0.5

    - #### setLabel

          public void setLabel(String text)

      Set the text showing in the Button.

      If you created an empty Button without a Label using `Button()`, this will create a Label nested in an Alignment for you. That won't work if you create an empty Button then put a custom Widget in place with `add()` instead of employing this method and/or `setImage()`).

      Since:
        4.0.0

    - #### setRelatedAction

          public void setRelatedAction(Action action)

      Description copied from interface: `Activatable`
      Set the Action that is triggered when this Activatable is activated.

      This replaced Action's connectProxy().

      Specified by:
        `setRelatedAction` in interface `Activatable`

    - #### setRelief

          public void setRelief(ReliefStyle style)

      Set the "relief" style used to determine how the edges of this Button will be decorated. The default is `NORMAL` which results in a Button just as you would expect, screaming out to be pressed! There are two other variations, see `ReliefStyle` for details.
      Since:
        4.0.1