Action (java-gnome 4.1.3 API Documentation)

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.

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.Activated.
    
    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

Class Action

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class org.freedesktop.bindings.Pointer

Methods inherited from class Object

Constructor Detail

Action

Action

Action

Action

Action

Action

Action

Action

Method Detail

connect

createMenuItem

createToolItem

emitActivate

getSensitive

getTooltip

getVisible

isSensitive

isVisible

setAccelerator

setSensitive

setTooltip

setVisible