GI.Gtk.Objects.AccelMap

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.

Exported types

newtype AccelMap

Memory-managed wrapper type.

Constructors

AccelMap (ManagedPtr AccelMap)

Instances

GObject AccelMap

Defined in GI.Gtk.Objects.AccelMap

Methods

gobjectType :: AccelMap -> IO GType

IsObject AccelMap

Defined in GI.Gtk.Objects.AccelMap

IsAccelMap AccelMap

Defined in GI.Gtk.Objects.AccelMap

class GObject o => IsAccelMap o

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

Instances

(GObject a, (UnknownAncestorError AccelMap a :: Constraint)) => IsAccelMap a

Defined in GI.Gtk.Objects.AccelMap

IsAccelMap AccelMap

Defined in GI.Gtk.Objects.AccelMap

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

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

noAccelMap :: Maybe AccelMap

A convenience alias for Nothing :: Maybe AccelMap.

Methods

addEntry

accelMapAddEntry

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

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

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

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

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

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

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

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

Arguments

:: (HasCallStack, MonadIO m)

=> Scanner

scanner: a Scanner which has already been provided with an input file

-> m ()

Scanner variant of accelMapLoad.

lockPath

accelMapLockPath

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

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

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

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

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

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

type C_AccelMapChangedCallback = Ptr () -> CString -> Word32 -> CUInt -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

afterAccelMapChanged :: (IsAccelMap a, MonadIO m) => a -> AccelMapChangedCallback -> m SignalHandlerId

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

genClosure_AccelMapChanged :: AccelMapChangedCallback -> IO Closure

Wrap the callback into a Closure.

mk_AccelMapChangedCallback :: C_AccelMapChangedCallback -> IO (FunPtr C_AccelMapChangedCallback)

Generate a function pointer callable from C code, from a C_AccelMapChangedCallback.

noAccelMapChangedCallback :: Maybe AccelMapChangedCallback

A convenience synonym for Nothing :: Maybe AccelMapChangedCallback.

onAccelMapChanged :: (IsAccelMap a, MonadIO m) => a -> AccelMapChangedCallback -> m SignalHandlerId

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

wrap_AccelMapChangedCallback :: AccelMapChangedCallback -> C_AccelMapChangedCallback

Wrap a AccelMapChangedCallback into a C_AccelMapChangedCallback.