GI.Gtk.Objects.Action

In GTK+ 3.10, GtkAction has been deprecated. Use 'GI.Gio.Interfaces.Action.Action'
instead, and associate actions with 'GI.Gtk.Interfaces.Actionable.Actionable' widgets. Use
'GI.Gio.Objects.MenuModel.MenuModel' for creating menus with 'GI.Gtk.Objects.Menu.menuNewFromModel'.

Actions represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself.

As well as the callback that is called when the action gets activated, the following also gets associated with the action:

• a name (not translated, for path lookup)
• a label (translated, for display)
• an accelerator
• whether label indicates a stock id
• a tooltip (optional, translated)
• a toolbar label (optional, shorter than label)

The action will also have some state information:

• visible (shown/hidden)
• sensitive (enabled/disabled)

Apart from regular actions, there are [toggle actions][GtkToggleAction], which can be toggled between two states and [radio actions][GtkRadioAction], of which only one in a group can be in the “active” state. Other actions can be implemented as Action subclasses.

Each action can have one or more proxy widgets. To act as an action proxy, widget needs to implement Activatable interface. Proxies mirror the state of the action and should change when the action’s state changes. Properties that are always mirrored by proxies are Action:sensitive and Action:visible. Action:gicon, Action:icon-name, Action:label, Action:short-label and Action:stock-id properties are only mirorred if proxy widget has Activatable:use-action-appearance property set to True.

When the proxy is activated, it should activate its action.

Exported types

newtype Action

Constructors

Action (ManagedPtr Action)

Instances

GObject Action

Methods

gobjectType :: Action -> IO GType

IsObject Action

IsAction Action

IsBuildable Action

class GObject o => IsAction o

Instances

(GObject a, UnknownAncestorError Constraint Action a) => IsAction a

IsAction ToggleAction

IsAction Action

IsAction RadioAction

IsAction RecentAction

toAction :: (MonadIO m, IsAction o) => o -> m Action

noAction :: Maybe Action

Methods

activate

actionActivate

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m ()

Deprecated: (Since version 3.10)Use actionGroupActivateAction on a Action instead

Emits the “activate” signal on the specified action, if it isn't insensitive. This gets called by the proxy widgets when they get activated.

It can also be used to manually activate an action.

Since: 2.4

blockActivate

actionBlockActivate

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m ()

Deprecated: (Since version 3.10)Use simpleActionSetEnabled to disable theSimpleAction instead

Disable activation signals from the action

This is needed when updating the state of your proxy Activatable widget could result in calling actionActivate, this is a convenience function to avoid recursing in those cases (updating toggle state for instance).

Since: 2.16

connectAccelerator

actionConnectAccelerator

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m ()

Deprecated: (Since version 3.10)Use Action and the accelerator group on an associatedMenu instead

Installs the accelerator for action if action has an accel path and group. See actionSetAccelPath and actionSetAccelGroup

Since multiple proxies may independently trigger the installation of the accelerator, the action counts the number of times this function has been called and doesn’t remove the accelerator until actionDisconnectAccelerator has been called as many times.

Since: 2.4

createIcon

actionCreateIcon

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> Int32

iconSize: the size of the icon (IconSize) that should be created.

-> m Widget

Returns: a widget that displays the icon for this action.

Deprecated: (Since version 3.10)Use menuItemSetIcon to set an icon on a MenuItem,or containerAdd to add a Image to a Button

This function is intended for use by action implementations to create icons displayed in the proxy widgets.

Since: 2.4

createMenu

actionCreateMenu

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Widget

Returns: the menu item provided by the action, or Nothing.

Deprecated: (Since version 3.10)Use Action and MenuModel instead, and create aMenu with menuNewFromModel

If action provides a Menu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu.

Since: 2.12

createMenuItem

actionCreateMenuItem

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Widget

Returns: a menu item connected to the action.

Deprecated: (Since version 3.10)Use menuItemNew and associate it with a Actioninstead.

Creates a menu item widget that proxies for the given action.

Since: 2.4

createToolItem

actionCreateToolItem

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Widget

Returns: a toolbar item connected to the action.

Deprecated: (Since version 3.10)Use a ToolItem and associate it with a Action usingactionableSetActionName instead

Creates a toolbar item widget that proxies for the given action.

Since: 2.4

disconnectAccelerator

actionDisconnectAccelerator

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m ()

Deprecated: (Since version 3.10)Use Action and the accelerator group on an associatedMenu instead

Undoes the effect of one call to actionConnectAccelerator.

Since: 2.4

getAccelClosure

actionGetAccelClosure

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Closure

Returns: the accel closure for this action. The returned closure is owned by GTK+ and must not be unreffed or modified.

Deprecated: (Since version 3.10)Use Action and Menu instead, which have noequivalent for getting the accel closure

Returns the accel closure for this action.

Since: 2.8

getAccelPath

actionGetAccelPath

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Text

Returns: the accel path for this action, or Nothing if none is set. The returned string is owned by GTK+ and must not be freed or modified.

Deprecated: (Since version 3.10)Use Action and the accelerator path on an associatedMenu instead

Returns the accel path for this action.

Since: 2.6

getAlwaysShowImage

actionGetAlwaysShowImage

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Bool

Returns: True if the menu item proxies will always show their image

Deprecated: (Since version 3.10)Use menuItemGetAttributeValue on a MenuIteminstead

Returns whether action's menu item proxies will always show their image, if available.

Since: 2.20

getGicon

actionGetGicon

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Icon

Returns: The action’s Icon if one is set.

Deprecated: (Since version 3.10)Use Action instead, andmenuItemGetAttributeValue to get an icon from a MenuItemassociated with a Action

Gets the gicon of action.

Since: 2.16

getIconName

actionGetIconName

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Text

Returns: the icon name

Deprecated: (Since version 3.10)Use Action instead, andmenuItemGetAttributeValue to get an icon from a MenuItemassociated with a Action

Gets the icon name of action.

Since: 2.16

getIsImportant

actionGetIsImportant

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Bool

Returns: whether action is important

Deprecated: (Since version 3.10)Use Action instead, and control and monitor whetherlabels are shown directly

Checks whether action is important or not

Since: 2.16

getLabel

actionGetLabel

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Text

Returns: the label text

Deprecated: (Since version 3.10)Use Action instead, and get a label from a menu itemwith menuItemGetAttributeValue. For Actionable widgets, use thewidget-specific API to get a label

Gets the label text of action.

Since: 2.16

getName

actionGetName

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Text

Returns: the name of the action. The string belongs to GTK+ and should not be freed.

Deprecated: (Since version 3.10)Use actionGetName on a Action instead

Returns the name of the action.

Since: 2.4

getProxies

actionGetProxies

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m [Widget]

Returns: a SList of proxy widgets. The list is owned by GTK+ and must not be modified.

Deprecated: (Since version 3.10)

Returns the proxy widgets for an action. See also activatableGetRelatedAction.

Since: 2.4

getSensitive

actionGetSensitive

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Bool

Returns: True if the action itself is sensitive.

Deprecated: (Since version 3.10)Use actionGetEnabled on a Actioninstead

Returns whether the action itself is sensitive. Note that this doesn’t necessarily mean effective sensitivity. See actionIsSensitive for that.

Since: 2.4

getShortLabel

actionGetShortLabel

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Text

Returns: the short label text.

Deprecated: (Since version 3.10)Use Action instead, which has no equivalent of shortlabels

Gets the short label text of action.

Since: 2.16

getStockId

actionGetStockId

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Text

Returns: the stock id

Deprecated: (Since version 3.10)Use Action instead, which has no equivalent of stockitems

Gets the stock id of action.

Since: 2.16

getTooltip

actionGetTooltip

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Text

Returns: the tooltip text

Deprecated: (Since version 3.10)Use Action instead, and get tooltips from associatedActionable widgets with widgetGetTooltipText

Gets the tooltip text of action.

Since: 2.16

getVisible

actionGetVisible

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Bool

Returns: True if the action itself is visible.

Deprecated: (Since version 3.10)Use Action instead, and control and monitor the state ofActionable widgets directly

Returns whether the action itself is visible. Note that this doesn’t necessarily mean effective visibility. See actionIsSensitive for that.

Since: 2.4

getVisibleHorizontal

actionGetVisibleHorizontal

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Bool

Returns: whether action is visible when horizontal

Deprecated: (Since version 3.10)Use Action instead, and control and monitor thevisibility of associated widgets and menu items directly

Checks whether action is visible when horizontal

Since: 2.16

getVisibleVertical

actionGetVisibleVertical

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m Bool

Returns: whether action is visible when horizontal

Deprecated: (Since version 3.10)Use Action instead, and control and monitor thevisibility of associated widgets and menu items directly

Checks whether action is visible when horizontal

Since: 2.16

isSensitive

actionIsSensitive

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Bool

Returns: True if the action and its associated action group are both sensitive.

Deprecated: (Since version 3.10)Use actionGetEnabled on a Actioninstead

Returns whether the action is effectively sensitive.

Since: 2.4

isVisible

actionIsVisible

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> m Bool

Returns: True if the action and its associated action group are both visible.

Deprecated: (Since version 3.10)Use Action instead, and control and monitor the state ofActionable widgets directly

Returns whether the action is effectively visible.

Since: 2.4

new

actionNew

Arguments

:: (HasCallStack, MonadIO m)

=> Text

name: A unique name for the action

-> Maybe Text

label: the label displayed in menu items and on buttons, or Nothing

-> Maybe Text

tooltip: a tooltip for the action, or Nothing

-> Maybe Text

stockId: the stock icon to display in widgets representing the action, or Nothing

-> m Action

Returns: a new Action

Deprecated: (Since version 3.10)Use Action instead, associating it to a widget withActionable or creating a Menu with menuNewFromModel

Creates a new Action object. To add the action to a ActionGroup and set the accelerator for the action, call actionGroupAddActionWithAccel. See the [UI Definition section][XML-UI] for information on allowed action names.

Since: 2.4

setAccelGroup

actionSetAccelGroup

Arguments

:: (HasCallStack, MonadIO m, IsAction a, IsAccelGroup b)

=> a

action: the action object

-> Maybe b

accelGroup: a AccelGroup or Nothing

-> m ()

Deprecated: (Since version 3.10)Use Action and the accelerator group on an associatedMenu instead

Sets the AccelGroup in which the accelerator for this action will be installed.

Since: 2.4

setAccelPath

actionSetAccelPath

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> Text

accelPath: the accelerator path

-> m ()

Deprecated: (Since version 3.10)Use Action and the accelerator path on an associatedMenu instead

Sets the accel path for this action. All proxy widgets associated with the action will have this accel path, so that their accelerators are consistent.

Note that accelPath string will be stored in a GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with internStaticString.

Since: 2.4

setAlwaysShowImage

actionSetAlwaysShowImage

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Bool

alwaysShow: True if menuitem proxies should always show their image

-> m ()

Deprecated: (Since version 3.10)Use menuItemSetIcon on a MenuItem instead, if theitem should have an image

Sets whether action's menu item proxies will ignore the Settings:gtk-menu-images setting and always show their image, if available.

Use this if the menu item would be useless or hard to use without their image.

Since: 2.20

setGicon

actionSetGicon

Arguments

:: (HasCallStack, MonadIO m, IsAction a, IsIcon b)

=> a

action: a Action

-> b

icon: the Icon to set

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and menuItemSetIcon to set anicon on a MenuItem associated with a Action, or containerAdd toadd a Image to a Button

Sets the icon of action.

Since: 2.16

setIconName

actionSetIconName

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Text

iconName: the icon name to set

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and menuItemSetIcon to set anicon on a MenuItem associated with a Action, or containerAdd toadd a Image to a Button

Sets the icon name on action

Since: 2.16

setIsImportant

actionSetIsImportant

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> Bool

isImportant: True to make the action important

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and control and monitor whetherlabels are shown directly

Sets whether the action is important, this attribute is used primarily by toolbar items to decide whether to show a label or not.

Since: 2.16

setLabel

actionSetLabel

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Text

label: the label text to set

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and set a label on a menu item withmenuItemSetLabel. For Actionable widgets, use the widget-specificAPI to set a label

Sets the label of action.

Since: 2.16

setSensitive

actionSetSensitive

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> Bool

sensitive: True to make the action sensitive

-> m ()

Deprecated: (Since version 3.10)Use simpleActionSetEnabled on a SimpleActioninstead

Sets the :sensitive property of the action to sensitive. Note that this doesn’t necessarily mean effective sensitivity. See actionIsSensitive for that.

Since: 2.6

setShortLabel

actionSetShortLabel

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Text

shortLabel: the label text to set

-> m ()

Deprecated: (Since version 3.10)Use Action instead, which has no equivalent of shortlabels

Sets a shorter label text on action.

Since: 2.16

setStockId

actionSetStockId

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Text

stockId: the stock id

-> m ()

Deprecated: (Since version 3.10)Use Action instead, which has no equivalent of stockitems

Sets the stock id on action

Since: 2.16

setTooltip

actionSetTooltip

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Text

tooltip: the tooltip text

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and set tooltips on associatedActionable widgets with widgetSetTooltipText

Sets the tooltip text on action

Since: 2.16

setVisible

actionSetVisible

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: the action object

-> Bool

visible: True to make the action visible

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and control and monitor the state ofActionable widgets directly

Sets the :visible property of the action to visible. Note that this doesn’t necessarily mean effective visibility. See actionIsVisible for that.

Since: 2.6

setVisibleHorizontal

actionSetVisibleHorizontal

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Bool

visibleHorizontal: whether the action is visible horizontally

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and control and monitor thevisibility of associated widgets and menu items directly

Sets whether action is visible when horizontal

Since: 2.16

setVisibleVertical

actionSetVisibleVertical

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> Bool

visibleVertical: whether the action is visible vertically

-> m ()

Deprecated: (Since version 3.10)Use Action instead, and control and monitor thevisibility of associated widgets and menu items directly

Sets whether action is visible when vertical

Since: 2.16

unblockActivate

actionUnblockActivate

Arguments

:: (HasCallStack, MonadIO m, IsAction a)

=> a

action: a Action

-> m ()

Deprecated: (Since version 3.10)Use simpleActionSetEnabled to enable theSimpleAction instead

Reenable activation signals from the action

Since: 2.16

Properties

actionGroup

clearActionActionGroup :: (MonadIO m, IsAction o) => o -> m ()

constructActionActionGroup :: (IsAction o, IsActionGroup a) => a -> IO (GValueConstruct o)

getActionActionGroup :: (MonadIO m, IsAction o) => o -> m (Maybe ActionGroup)

setActionActionGroup :: (MonadIO m, IsAction o, IsActionGroup a) => o -> a -> m ()

alwaysShowImage

constructActionAlwaysShowImage :: IsAction o => Bool -> IO (GValueConstruct o)

getActionAlwaysShowImage :: (MonadIO m, IsAction o) => o -> m Bool

setActionAlwaysShowImage :: (MonadIO m, IsAction o) => o -> Bool -> m ()

gicon

constructActionGicon :: (IsAction o, IsIcon a) => a -> IO (GValueConstruct o)

getActionGicon :: (MonadIO m, IsAction o) => o -> m Icon

setActionGicon :: (MonadIO m, IsAction o, IsIcon a) => o -> a -> m ()

hideIfEmpty

constructActionHideIfEmpty :: IsAction o => Bool -> IO (GValueConstruct o)

getActionHideIfEmpty :: (MonadIO m, IsAction o) => o -> m Bool

setActionHideIfEmpty :: (MonadIO m, IsAction o) => o -> Bool -> m ()

iconName

constructActionIconName :: IsAction o => Text -> IO (GValueConstruct o)

getActionIconName :: (MonadIO m, IsAction o) => o -> m Text

setActionIconName :: (MonadIO m, IsAction o) => o -> Text -> m ()

isImportant

constructActionIsImportant :: IsAction o => Bool -> IO (GValueConstruct o)

getActionIsImportant :: (MonadIO m, IsAction o) => o -> m Bool

setActionIsImportant :: (MonadIO m, IsAction o) => o -> Bool -> m ()

label

constructActionLabel :: IsAction o => Text -> IO (GValueConstruct o)

getActionLabel :: (MonadIO m, IsAction o) => o -> m Text

setActionLabel :: (MonadIO m, IsAction o) => o -> Text -> m ()

name

constructActionName :: IsAction o => Text -> IO (GValueConstruct o)

getActionName :: (MonadIO m, IsAction o) => o -> m Text

sensitive

constructActionSensitive :: IsAction o => Bool -> IO (GValueConstruct o)

getActionSensitive :: (MonadIO m, IsAction o) => o -> m Bool

setActionSensitive :: (MonadIO m, IsAction o) => o -> Bool -> m ()

shortLabel

constructActionShortLabel :: IsAction o => Text -> IO (GValueConstruct o)

getActionShortLabel :: (MonadIO m, IsAction o) => o -> m Text

setActionShortLabel :: (MonadIO m, IsAction o) => o -> Text -> m ()

stockId

constructActionStockId :: IsAction o => Text -> IO (GValueConstruct o)

getActionStockId :: (MonadIO m, IsAction o) => o -> m Text

setActionStockId :: (MonadIO m, IsAction o) => o -> Text -> m ()

tooltip

constructActionTooltip :: IsAction o => Text -> IO (GValueConstruct o)

getActionTooltip :: (MonadIO m, IsAction o) => o -> m Text

setActionTooltip :: (MonadIO m, IsAction o) => o -> Text -> m ()

visible

constructActionVisible :: IsAction o => Bool -> IO (GValueConstruct o)

getActionVisible :: (MonadIO m, IsAction o) => o -> m Bool

setActionVisible :: (MonadIO m, IsAction o) => o -> Bool -> m ()

visibleHorizontal

constructActionVisibleHorizontal :: IsAction o => Bool -> IO (GValueConstruct o)

getActionVisibleHorizontal :: (MonadIO m, IsAction o) => o -> m Bool

setActionVisibleHorizontal :: (MonadIO m, IsAction o) => o -> Bool -> m ()

visibleOverflown

constructActionVisibleOverflown :: IsAction o => Bool -> IO (GValueConstruct o)

getActionVisibleOverflown :: (MonadIO m, IsAction o) => o -> m Bool

setActionVisibleOverflown :: (MonadIO m, IsAction o) => o -> Bool -> m ()

visibleVertical

constructActionVisibleVertical :: IsAction o => Bool -> IO (GValueConstruct o)

getActionVisibleVertical :: (MonadIO m, IsAction o) => o -> m Bool

setActionVisibleVertical :: (MonadIO m, IsAction o) => o -> Bool -> m ()

Signals

activate

type ActionActivateCallback = IO ()

Deprecated: (Since version 3.10)Use SimpleAction::activate instead

type C_ActionActivateCallback = Ptr () -> Ptr () -> IO ()

afterActionActivate :: (IsAction a, MonadIO m) => a -> ActionActivateCallback -> m SignalHandlerId

genClosure_ActionActivate :: ActionActivateCallback -> IO Closure

mk_ActionActivateCallback :: C_ActionActivateCallback -> IO (FunPtr C_ActionActivateCallback)

noActionActivateCallback :: Maybe ActionActivateCallback

onActionActivate :: (IsAction a, MonadIO m) => a -> ActionActivateCallback -> m SignalHandlerId

wrap_ActionActivateCallback :: ActionActivateCallback -> Ptr () -> Ptr () -> IO ()