org.gnome.gtk

## Class ToolButton

- 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.ToolItem
              - - org.gnome.gtk.ToolButton

- All Implemented Interfaces:
    Activatable
  Direct Known Subclasses:
    MenuToolButton, ToggleToolButton

      public class ToolButton
      extends ToolItem

  A ToolButton is a ToolItem that displays as a graphical Button.

  This is the item you will want to add in most cases to your application Toolbar(s). It is a acts a like a normal Button, but its appearance is designed to look better on a Toolbar.

  A ToolButton has an image or icon and a Label. The user Toolbar preferences determine whether the Label is actually shown on screen. Even if you disable the Label in your desktop preferences, you should provide a valid Label to your application ToolButtons, as other users will have them showing and your program will look a bit silly without textual labels.

  Since:
    4.0.4
  Author:
    Vreixo Formoso

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ToolButton.Clicked` Signal generated when a user presses and releases a ToolButton, 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.QueryTooltip, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ToolButton(Stock stock)` Creates a new stock ToolButton.
    `ToolButton(Widget iconWidget, String label)` Creates a new ToolButton using the given icon and Label.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(ToolButton.Clicked handler)` Connect a handler to the `ToolButton.Clicked` signal.
    `String` | `getLabel()` Get the text Label previously set with `setLabel()`.
    `Widget` | `getLabelWidget()` Get the Widget used as "label", if any.
    `void` | `setLabel(String label)` Set the Label of the Button.
    `void` | `setLabelWidget(Widget labelWidget)` Set the Widget to be used as the "label" for this ToolButton.

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

      `getExpand, getRelatedAction, setExpand, setIsImportant, setRelatedAction`

    - ### 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, 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

    - #### ToolButton

          public ToolButton(Stock stock)

      Creates a new stock ToolButton. Both the Label and icon will be set properly from the stock item. By using a system stock item, the newly created ToolButton with use the same Label and Image as other GNOME applications. To ensure consistent look and feel between applications, it is highly recommended that you use provided stock item based ToolButtons whenever possible.
      Parameters:
        `stock` - The Stock that will determine the Label and icon on the ToolButton.

    - #### ToolButton

          public ToolButton(Widget iconWidget,
                    String label)

      Creates a new ToolButton using the given icon and Label.
      Parameters:
        `iconWidget` - The Widget to be used as the icon for the ToolButton. Usually you will want to use a Widget that displays a graphic, such as `Image`.
        `label` - The Label for the ToolButton.

  - ### Method Detail

    - #### connect

          public void connect(ToolButton.Clicked handler)

      Connect a handler to the `ToolButton.Clicked` signal.

    - #### getLabel

          public String getLabel()

      Get the text Label previously set with `setLabel()`.
      Returns:
        The Label or `null` if not Label has been set. Note that a `null` return value doesn't mean that the ToolButton doesn't have a Label, as it can have a Widget Label or a Label taken from a stock item.

    - #### getLabelWidget

          public Widget getLabelWidget()

      Get the Widget used as "label", if any.
      Returns:
        The Widget used as label, or `null` if this ToolButton doesn't have a Widget overriding its label.
      See Also:
        `setLabelWidget(Widget)`

    - #### setLabel

          public void setLabel(String label)

      Set the Label of the Button.

      Note that any value of the Label set by this method won't be actually displayed if you have set a Widget Label using `setLabelWidget()`

      Parameters:
        `label` - The String to be used as Label, or `null`.

    - #### setLabelWidget

          public void setLabelWidget(Widget labelWidget)

      Set the Widget to be used as the "label" for this ToolButton.

      Please check `setLabel()` before using this, because in most cases that is what you want.

      Usually ToolButtons have either a text Label set with `setLabel()`, or text automatically determined by a stock item. However, in some cases you will want to provide another kind of Widget as the label, and this method is how.

      Parameters:
        `labelWidget` - A Widget to be used as a Label, or `null` to not use the Widget Label (in this case, the text Label will be used. If the text Label is also `null`, the default stock item label is used. In this later case, if this ToolButton has no stock item, then no Label will be used at all). Note that if you do pass a non- `null` Widget here, this argument will be used as the label despite the text in the normal Label or one generated as a result of using a stock item.