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

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

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

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD