org.gnome.gtk

## Class Action

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Action

- Direct Known Subclasses:
    RecentAction, ToggleAction

      public class Action
      extends Object

  Actions represent an operation that the user can perform from one of several GUI places.

  Usually, an application provides several ways to let users execute an operation, for example the "Open File..." shows up in Menus, Toolbars, and elsewhere. If an operation can be executed from several GUI places, it seems logical that such different places appear similar to the user. Namely, they should have the same textual label, the same icon, and certainly the same accelerator key. This way, if the user is accustomed to executing an operation from the Toolbar and then sees the equivalent operation in as a MenuItem with the same icon and label, she will know that both will do the same thing. It thus seems reasonable that both MenuItem and ToolButton share some Object where the common information is stored, and this is indeed the role of the Action class.

  An Action holds information about an operation that could be executed from different places. This information includes the label that is shown to the user, the icon, and the tooltip (popup help message). It also stores state information, such as whether the action is "visible" or "sensitive". When this information changes, all the Action proxies (i.e. the Widgets such as MenuItems or ToolButtons related to it) are also all changed properly.

  Each Action has an `Action.Activate` signal emitted when any of its proxies are triggered. Thus you can just connect one signal to start the needed operation, instead of having to connect to the `Action.Activate` signal of each of various proxies.

  Once you have created an Action, you can get proxies for it with the `createMenuItem()` and `createToolItem()` methods.

  Incidentally, you can still use Actions even if you only plan to let the user execute operations from a single place in your application; they're a useful technique to concentrate the code handling of user activity.

  Since:
    4.0.4
  Author:
    Vreixo Formoso, Andrew Cowie
  See Also:
    `ActionGroup`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Action.Activate` Signal emitted when the Action is activated.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Action(String name, Stock stock)` Create a new Action from a Stock item.
    `Action(String name, Stock stock, Action.Activate handler)` Create a new Action based on a Stock item, and connect a handler to its `Action.Activate` signal.
    `Action(String name, String label)` Create a new Action.
    `Action(String name, String label, Action.Activate handler)` Create a new Action, and connect a handler to its `Action.Activate` signal.
    `Action(String name, String label, String tooltip, Icon icon)` Create a new Action.
    `Action(String name, String label, String tooltip, Icon icon, Action.Activate handler)` Create a new Action, and connect a handler to its `Action.Activate` signal.
    `Action(String name, String label, String tooltip, Stock stock)` Create a new Action.
    `Action(String name, String label, String tooltip, Stock stock, Action.Activate handler)` Create a new Action, and connect a handler to its `Action.Activate` signal.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(Action.Activate handler)` Connect a handler to the `Action.Activate` signal.
    `MenuItem` | `createMenuItem()` Create a MenuItem from this Action.
    `ToolItem` | `createToolItem()` Creates a ToolItem from this Action.
    `void` | `emitActivate()` Activates the Action.
    `boolean` | `getSensitive()` Return whether this Action itself is enabled to be activated by the user.
    `String` | `getTooltip()` Get the tooltip for the Action.
    `boolean` | `getVisible()` Return whether the Action itself is visible.
    `boolean` | `isSensitive()` Returns whether the action is effectively sensitive, i.e., if both the Action and the ActionGroup it belongs to are enabled.
    `boolean` | `isVisible()` Is the Action visible on the screen?
    `void` | `setAccelerator(AcceleratorGroup group, Keyval keyval, ModifierType modifier)` Specify a key binding to trigger this Action.
    `void` | `setSensitive(boolean sensitive)` Set if the Action is available to be activated by the user.
    `void` | `setTooltip(String tooltip)` Set a tooltip (little help message appearing in a hover) for the Action.
    `void` | `setVisible(boolean visible)` Set whether the Action is visible to users.

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

      `toString`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### Action

          public Action(String name,
                Stock stock)

      Create a new Action from a Stock item. The message and tooltip will be supplied by GTK automatically.
      Since:
        4.0.7

    - #### Action

          public Action(String name,
                Stock stock,
                Action.Activate handler)

      Create a new Action based on a Stock item, and connect a handler to its `Action.Activate` signal. Complements the `<init>(String, Stock)` constructor.
      Since:
        4.0.9

    - #### Action

          public Action(String name,
                String label)

      Create a new Action.
      Parameters:
        `name` - A unique name for the Action.
        `label` - The text that will be displayed in the proxy Widgets. You usually will want to localize it to the user language.
      Since:
        4.0.4

    - #### Action

          public Action(String name,
                String label,
                Action.Activate handler)

      Create a new Action, and connect a handler to its `Action.Activate` signal.
      Parameters:
        `name` - A unique name for the Action.
        `label` - The label that will be displayed in the proxy Widgets. You usually will want to localize it to the user language.
        `handler` - A handler to connect to the `Action.Activate` signal. Usually will will start from here the operation related to the Action.
      Since:
        4.0.4

    - #### Action

          public Action(String name,
                String label,
                String tooltip,
                Icon icon)

      Create a new Action.
      Parameters:
        `name` - A unique name for the Action.
        `label` - The text that will be displayed in the proxy Widgets. You usually will want to localize it to the user language.
        `tooltip` - A Tooltip or little help message for the Action. Also localized.
        `icon` - The Icon to display in proxy Widgets.
      Since:
        4.0.19

    - #### Action

          public Action(String name,
                String label,
                String tooltip,
                Icon icon,
                Action.Activate handler)

      Create a new Action, and connect a handler to its `Action.Activate` signal.
      Parameters:
        `name` - A unique name for the Action.
        `label` - The text that will be displayed in the proxy Widgets. You usually will want to localize it to the user language.
        `tooltip` - A Tooltip or little help message for the Action. Also localized.
        `icon` - The Icon to display in proxy Widgets.
        `handler` - A handler to connect to the `Action.Activate` signal. Typically this will be used to actually start the operation related to this Action.
      Since:
        4.0.19

    - #### Action

          public Action(String name,
                String label,
                String tooltip,
                Stock stock)

      Create a new Action.
      Parameters:
        `name` - A unique name for the Action.
        `label` - The text that will be displayed in the proxy Widgets. You usually will want to localize it to the user language.
        `tooltip` - A Tooltip or little help message for the Action. Also localized.
        `stock` - The Stock icon to display in proxy Widgets.
      Since:
        4.0.4

    - #### Action

          public Action(String name,
                String label,
                String tooltip,
                Stock stock,
                Action.Activate handler)

      Create a new Action, and connect a handler to its `Action.Activate` signal.
      Parameters:
        `name` - A unique name for the Action.
        `label` - The text that will be displayed in the proxy Widgets. You usually will want to localize it to the user language.
        `tooltip` - A Tooltip or little help message for the Action. Also localized.
        `stock` - The stock icon to display in proxy Widgets.
        `handler` - A handler to connect to the `Action.Activate` signal. Typically this will be used to actually start the operation related to this Action.
      Since:
        4.0.4

  - ### Method Detail

    - #### connect

          public void connect(Action.Activate handler)

      Connect a handler to the `Action.Activate` signal.
      Since:
        4.0.4

    - #### createMenuItem

          public MenuItem createMenuItem()

      Create a MenuItem from this Action.

      You can add the returned MenuItem to a `Menu`. The MenuItem will have the same label, icon or accelerator of this Action, and when the user activates the MenuItem, this Action will `Action.Activate` too.

      Since:
        4.0.4

    - #### createToolItem

          public ToolItem createToolItem()

      Creates a ToolItem from this Action.

      You can add the returned ToolItem to a `Toolbar`. The ToolItem will have the same Label, icon, tooltips or accelerator of this Action, and when the user clicks it, this Action will be `Action.Activate`d.

      Since:
        4.0.4

    - #### emitActivate

          public void emitActivate()

      Activates the Action.

      Programmatically cause this Action to fire its `Action.Activate` signal. Note that this has no effect if the Action is not currently sensitive.

      Since the Action is automatically activated when user activates one of its proxies (selecting the specific MenuItem or clicking the ToolButton that goes with this Action), normally you don't need this. However, in some cases you want to activate the Action in your application code. Use this there.

      Since:
        4.0.8

    - #### getSensitive

          public boolean getSensitive()

      Return whether this Action itself is enabled to be activated by the user. Note that this doesn't necessarily mean effective sensitivity due to the effect of ActionGroups; see `isSensitive()` for that.
      Since:
        4.0.4

    - #### getTooltip

          public String getTooltip()

      Get the tooltip for the Action.
      Since:
        4.0.4

    - #### getVisible

          public boolean getVisible()

      Return whether the Action itself is visible. Note that this doesn't necessarily mean effective visibility.
      Since:
        4.0.4
      See Also:
        `isVisible()`, `setVisible(boolean)`

    - #### isSensitive

          public boolean isSensitive()

      Returns whether the action is effectively sensitive, i.e., if both the Action and the ActionGroup it belongs to are enabled.
      Since:
        4.0.4

    - #### isVisible

          public boolean isVisible()

      Is the Action visible on the screen?
      Returns:
        `true` when both the Action and the ActionGroup it belongs to are visible, `false` otherwise.
      Since:
        4.0.4
      See Also:
        `setVisible(boolean)`

    - #### setAccelerator

          public void setAccelerator(AcceleratorGroup group,
                            Keyval keyval,
                            ModifierType modifier)

      Specify a key binding to trigger this Action. You need to use the same group object as was (or will be) passed to Window's `addAcceleratorGroup()`.
      Since:
        4.0.16

    - #### setSensitive

          public void setSensitive(boolean sensitive)

      Set if the Action is available to be activated by the user. When an Action is not sensitive, all its ToolItem or MenuItem proxies are likewise disabled, meaning the user can't activate any of them.

      You usually will want to deactivate an Action when its operation makes no sense in current application status. For example, in a text editor you should probably disable the "Save" Action when there is no document is open or when current document hasn't been changed.

      When not sensitive, Action proxies are displayed differently than enabled proxies (usually in grey color). That way, user knows the Action has no application in the current program state, and she needs to do something before the disabled Action becomes applicable.

      However, when a full Menu on a MenuBar needs to be disabled, generally a better idea is to `setVisible(false)` it.

      Finally, note that setting an Action sensitive doesn't always mean it will be actually sensitive, as you also need to make sensitive the ActionGroup the Action belongs to (see `isSensitive()`).

      An Action starts life sensitive (ie, `true`).

      Since:
        4.0.4

    - #### setTooltip

          public void setTooltip(String tooltip)

      Set a tooltip (little help message appearing in a hover) for the Action.
      Since:
        4.0.4

    - #### setVisible

          public void setVisible(boolean visible)

      Set whether the Action is visible to users.

      When an Action is not visible, any associated proxies, such as MenuItems or ToolItems are hidden to the used.

      In most cases, it's a better idea to `setSensitive(false)` an Action instead of make it not visible. That way, users can see that such operation exists in the application, but they need to do some operations before it becomes available.

      However, when a full Menu is disabled, this could be a good option. For example, on a text edit application, you could hide the "Edit" menu when there's no opened document.

      Finally, note that setting an Action visible doesn't always mean it will be actually displayed, as you also need to make visible the ActionGroup the Action belongs to (see `isVisible()` for details).

      Since:
        4.0.4