gi-gtk-3.0.43: Gtk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.AccelMap

Contents

- Exported types
- Methods
  - addEntry
  - addFilter
  - changeEntry
  - foreach
  - foreachUnfiltered
  - get
  - load
  - loadFd
  - loadScanner
  - lockPath
  - lookupEntry
  - save
  - saveFd
  - unlockPath
- Signals
  - changed

Description

Accelerator maps are used to define runtime configurable accelerators. Functions for manipulating them are are usually used by higher level convenience mechanisms like `UIManager` and are thus considered “low-level”. You’ll want to use them if you’re manually creating menus that should have user-configurable accelerators.

An accelerator is uniquely defined by: * accelerator path * accelerator key * accelerator modifiers

The accelerator path must consist of “<WINDOWTYPE>/Category1/Category2/.../Action”, where WINDOWTYPE should be a unique application-specific identifier that corresponds to the kind of window the accelerator is being used in, e.g. “Gimp-Image”, “Abiword-Document” or “Gnumeric-Settings”. The “Category1/.../Action” portion is most appropriately chosen by the action the accelerator triggers, i.e. for accelerators on menu items, choose the item’s menu path, e.g. “File/Save As”, “Image/View/Zoom” or “Edit/Select All”. So a full valid accelerator path may look like: “<Gimp-Toolbox>/File/Dialogs/Tool Options...”.

All accelerators are stored inside one global `AccelMap` that can be obtained using `accelMapGet`. See [Monitoring changes][monitoring-changes] for additional details.

# Manipulating accelerators

New accelerators can be added using `accelMapAddEntry`. To search for specific accelerator, use `accelMapLookupEntry`. Modifications of existing accelerators should be done using `accelMapChangeEntry`.

In order to avoid having some accelerators changed, they can be locked using `accelMapLockPath`. Unlocking is done using `accelMapUnlockPath`.

# Saving and loading accelerator maps

Accelerator maps can be saved to and loaded from some external resource. For simple saving and loading from file, `accelMapSave` and `accelMapLoad` are provided. Saving and loading can also be done by providing file descriptor to `accelMapSaveFd` and `accelMapLoadFd`.

# Monitoring changes

`AccelMap` object is only useful for monitoring changes of accelerators. By connecting to AccelMap::changed signal, one can monitor changes of all accelerators. It is also possible to monitor only single accelerator path by using it as a detail of the AccelMap::changed signal.

Synopsis

- newtype AccelMap = AccelMap (ManagedPtr AccelMap)
- class (GObject o, IsDescendantOf AccelMap o) => IsAccelMap o
- toAccelMap :: (MonadIO m, IsAccelMap o) => o -> m AccelMap
- accelMapAddEntry :: (HasCallStack, MonadIO m) => Text -> Word32 -> [ModifierType] -> m ()
- accelMapAddFilter :: (HasCallStack, MonadIO m) => Text -> m ()
- accelMapChangeEntry :: (HasCallStack, MonadIO m) => Text -> Word32 -> [ModifierType] -> Bool -> m Bool
- accelMapForeach :: (HasCallStack, MonadIO m) => Ptr () -> AccelMapForeach -> m ()
- accelMapForeachUnfiltered :: (HasCallStack, MonadIO m) => Ptr () -> AccelMapForeach -> m ()
- accelMapGet :: (HasCallStack, MonadIO m) => m AccelMap
- accelMapLoad :: (HasCallStack, MonadIO m) => [Char] -> m ()
- accelMapLoadFd :: (HasCallStack, MonadIO m) => Int32 -> m ()
- accelMapLoadScanner :: (HasCallStack, MonadIO m) => Scanner -> m ()
- accelMapLockPath :: (HasCallStack, MonadIO m) => Text -> m ()
- accelMapLookupEntry :: (HasCallStack, MonadIO m) => Text -> m (Bool, AccelKey)
- accelMapSave :: (HasCallStack, MonadIO m) => [Char] -> m ()
- accelMapSaveFd :: (HasCallStack, MonadIO m) => Int32 -> m ()
- accelMapUnlockPath :: (HasCallStack, MonadIO m) => Text -> m ()
- type AccelMapChangedCallback = Text -> Word32 -> [ModifierType] -> IO ()
- afterAccelMapChanged :: (IsAccelMap a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => AccelMapChangedCallback) -> m SignalHandlerId
- onAccelMapChanged :: (IsAccelMap a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => AccelMapChangedCallback) -> m SignalHandlerId

# Exported types

newtype AccelMap Source #

Memory-managed wrapper type.

Constructors

AccelMap (ManagedPtr AccelMap) |

#### Instances

Instances details

Eq AccelMap Source # |
Instance details Defined in GI.Gtk.Objects.AccelMap Methods (==) :: AccelMap -> AccelMap -> Bool Source # (/=) :: AccelMap -> AccelMap -> Bool Source #
GObject AccelMap Source # |
Instance details Defined in GI.Gtk.Objects.AccelMap
ManagedPtrNewtype AccelMap Source # |
Instance details Defined in GI.Gtk.Objects.AccelMap Methods toManagedPtr :: AccelMap -> ManagedPtr AccelMap Source #
TypedObject AccelMap Source # |
Instance details Defined in GI.Gtk.Objects.AccelMap Methods glibType :: IO GType Source #
HasParentTypes AccelMap Source # |
Instance details Defined in GI.Gtk.Objects.AccelMap
IsGValue (Maybe AccelMap) Source # | Convert `AccelMap` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.AccelMap Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe AccelMap -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe AccelMap) Source #
type ParentTypes AccelMap Source # |
Instance details Defined in GI.Gtk.Objects.AccelMap type ParentTypes AccelMap = '[Object]

class (GObject o, IsDescendantOf AccelMap o) => IsAccelMap o Source #

Type class for types which can be safely cast to `AccelMap`, for instance with `toAccelMap`.

#### Instances

Instances details

(GObject o, IsDescendantOf AccelMap o) => IsAccelMap o Source # |
Instance details Defined in GI.Gtk.Objects.AccelMap

toAccelMap :: (MonadIO m, IsAccelMap o) => o -> m AccelMap Source #

Cast to `AccelMap`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

## addEntry

accelMapAddEntry Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `accelPath`: valid accelerator path
-> Word32 | `accelKey`: the accelerator key
-> [ModifierType] | `accelMods`: the accelerator modifiers
-> m () |

Registers a new accelerator with the global accelerator map. This function should only be called once per `accelPath` with the canonical `accelKey` and `accelMods` for this path. To change the accelerator during runtime programatically, use `accelMapChangeEntry`.

Set `accelKey` and `accelMods` to 0 to request a removal of the accelerator.

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

## addFilter

accelMapAddFilter Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `filterPattern`: a pattern (see `PatternSpec`)
-> m () |

Adds a filter to the global list of accel path filters.

Accel map entries whose accel path matches one of the filters are skipped by `accelMapForeach`.

This function is intended for GTK+ modules that create their own menus, but don’t want them to be saved into the applications accelerator map dump.

## changeEntry

accelMapChangeEntry Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `accelPath`: a valid accelerator path
-> Word32 | `accelKey`: the new accelerator key
-> [ModifierType] | `accelMods`: the new accelerator modifiers
-> Bool | `replace`: `True` if other accelerators may be deleted upon conflicts
-> m Bool | Returns: `True` if the accelerator could be changed, `False` otherwise

Changes the `accelKey` and `accelMods` currently associated with `accelPath`. Due to conflicts with other accelerators, a change may not always be possible, `replace` indicates whether other accelerators may be deleted to resolve such conflicts. A change will only occur if all conflicts could be resolved (which might not be the case if conflicting accelerators are locked). Successful changes are indicated by a `True` return value.

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

## foreach

accelMapForeach Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `data`: data to be passed into `foreachFunc`
-> AccelMapForeach | `foreachFunc`: function to be executed for each accel map entry which is not filtered out
-> m () |

Loops over the entries in the accelerator map whose accel path doesn’t match any of the filters added with `accelMapAddFilter`, and execute `foreachFunc` on each. The signature of `foreachFunc` is that of `AccelMapForeach`, the `changed` parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump).

## foreachUnfiltered

accelMapForeachUnfiltered Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `data`: data to be passed into `foreachFunc`
-> AccelMapForeach | `foreachFunc`: function to be executed for each accel map entry
-> m () |

Loops over all entries in the accelerator map, and execute `foreachFunc` on each. The signature of `foreachFunc` is that of `AccelMapForeach`, the `changed` parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump).

## get

accelMapGet Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m AccelMap | Returns: the global `AccelMap` object

Gets the singleton global `AccelMap` object. This object is useful only for notification of changes to the accelerator map via the changed signal; it isn’t a parameter to the other accelerator map functions.

Since: 2.4

## load

accelMapLoad Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [Char] | `fileName`: a file containing accelerator specifications, in the GLib file name encoding
-> m () |

Parses a file previously saved with `accelMapSave` for accelerator specifications, and propagates them accordingly.

## loadFd

accelMapLoadFd Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Int32 | `fd`: a valid readable file descriptor
-> m () |

Filedescriptor variant of `accelMapLoad`.

Note that the file descriptor will not be closed by this function.

## loadScanner

accelMapLoadScanner Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Scanner | `scanner`: a `Scanner` which has already been provided with an input file
-> m () |

`Scanner` variant of `accelMapLoad`.

## lockPath

accelMapLockPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `accelPath`: a valid accelerator path
-> m () |

Locks the given accelerator path. If the accelerator map doesn’t yet contain an entry for `accelPath`, a new one is created.

Locking an accelerator path prevents its accelerator from being changed during runtime. A locked accelerator path can be unlocked by `accelMapUnlockPath`. Refer to `accelMapChangeEntry` for information about runtime accelerator changes.

If called more than once, `accelPath` remains locked until `accelMapUnlockPath` has been called an equivalent number of times.

Note that locking of individual accelerator paths is independent from locking the `AccelGroup` containing them. For runtime accelerator changes to be possible, both the accelerator path and its `AccelGroup` have to be unlocked.

Since: 2.4

## lookupEntry

accelMapLookupEntry Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `accelPath`: a valid accelerator path
-> m (Bool, AccelKey) | Returns: `True` if `accelPath` is known, `False` otherwise

Looks up the accelerator entry for `accelPath` and fills in `key`.

## save

accelMapSave Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [Char] | `fileName`: the name of the file to contain accelerator specifications, in the GLib file name encoding
-> m () |

Saves current accelerator specifications (accelerator path, key and modifiers) to `fileName`. The file is written in a format suitable to be read back in by `accelMapLoad`.

## saveFd

accelMapSaveFd Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Int32 | `fd`: a valid writable file descriptor
-> m () |

Filedescriptor variant of `accelMapSave`.

Note that the file descriptor will not be closed by this function.

## unlockPath

accelMapUnlockPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `accelPath`: a valid accelerator path
-> m () |

Undoes the last call to `accelMapLockPath` on this `accelPath`. Refer to `accelMapLockPath` for information about accelerator path locking.

Since: 2.4

# Signals

## changed

type AccelMapChangedCallback Source #

Arguments

= Text | `accelPath`: the path of the accelerator that changed
-> Word32 | `accelKey`: the key value for the new accelerator
-> [ModifierType] | `accelMods`: the modifier mask for the new accelerator
-> IO () |

Notifies of a change in the global accelerator map. The path is also used as the detail for the signal, so it is possible to connect to changed::`accel_path`.

Since: 2.4

afterAccelMapChanged :: (IsAccelMap a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => AccelMapChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the changed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after accelMap #changed callback

This signal admits a optional parameter `detail`. If it's not `Nothing`, we will connect to “`changed::detail`” instead.

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onAccelMapChanged :: (IsAccelMap a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => AccelMapChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the changed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on accelMap #changed callback

This signal admits a optional parameter `detail`. If it's not `Nothing`, we will connect to “`changed::detail`” instead.