gtk.AccelMap
Prev | The gtk Class Reference | Next

## gtk.AccelMap

gtk.AccelMap — Loadable keyboard accelerator specifications (new in PyGTK 2.10)

## Synopsis

    class gtk.AccelMap(gobject.GObject):

    Functions
        def gtk.accel_map_add_entry(accel_path, accel_key, accel_mods)
        def gtk.accel_map_lookup_entry(accel_path)
        def gtk.accel_map_change_entry(accel_path, accel_key, accel_mods, replace)
        def gtk.accel_map_foreach(foreach_func, data=None)
        def gtk.accel_map_foreach_unfiltered(foreach_func, data=None)
        def gtk.accel_map_get()
        def gtk.accel_map_load(file_name)
        def gtk.accel_map_save(file_name)
        def gtk.accel_map_load_fd(fd)
        def gtk.accel_map_save_fd(fd)
        def gtk.accel_map_lock_path(accel_path)
        def gtk.accel_map_unlock_path(accel_path)
        def gtk.accel_map_add_filter(filter_pattern)
        def gtk.accel_groups_from_object(object)

## Ancestry

    +-- gobject.GObject
      +-- gtk.AccelMap

## gtk.AccelMap Signal Prototypes

gobject.GObject Signal Prototypes

"changed" | `def callback(`object`, `accel_path`, `accel_key`, `accel_mods`, `user_param1`, `...`)`

## Description

## Functions

### gtk.accel_map_add_entry

        def gtk.accel_map_add_entry(accel_path, accel_key, accel_mods)

`accel_path` : | a valid accelerator path
`accel_key` : | the accelerator key
`accel_mods` : | the accelerator modifiers

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.accel_map_add_entry`() function registers a new accelerator specified by `accel_key` and `accel_mods` with the global accelerator map. The accelerator will be associated with the accelerator path specified by `accel_path`. This function should only be called once per `accel_path` with the canonical `accel_key` and `accel_mods` for this path. To change the accelerator during runtime programatically, use the `gtk.accel_map_change_entry`() function. 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...".

### gtk.accel_map_lookup_entry

        def gtk.accel_map_lookup_entry(accel_path)

`accel_path` : | a valid accelerator path
Returns : | a 2-tuple containing the keyval and modifier mask corresponding to `accel_path` or `None` if not valid

The `gtk.accel_map_lookup_entry`() function returns a 2-tuple containing the keyval and modifier mask corresponding to the accelerator path specified by `accel_path` or `None` if `accel_path` is not a valid accelerator path.

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

### gtk.accel_map_change_entry

        def gtk.accel_map_change_entry(accel_path, accel_key, accel_mods, replace)

`accel_path` : | a valid accelerator path
`accel_key` : | the new accelerator key
`accel_mods` : | the new accelerator modifiers
`replace` : | if `True` other accelerators may be deleted if conflicting
Returns : | `True` if the accelerator could be changed

The `gtk.accel_map_change_entry`() function changes the keyval and modifier mask currently associated with the accelerator path specified by `accel_path` to the values specified by `accel_key` and `accel_mods` respectively. Due to conflicts with other accelerators, a change may not always be possible. If `replace` is `True` the 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.

### gtk.accel_map_foreach

        def gtk.accel_map_foreach(foreach_func, data=None)

`foreach_func` : | function to be executed for each accel map entry which is not filtered out
`data` : | data to be passed into `foreach_func`

### Note

This function is available in PyGTK 2.10 and above.

Loops over the entries in the accelerator map whose accel path doesn't match any of the filters added with the `gtk.accel_map_add_filter`() function, and executes `foreach_func` on each. The signature of `foreach_func` is:

      def foreach_func(accel_path, accel_key, accel_mode, changed, user_data):

where `accel_path`, `accel_key` and `accel_mode` describe the accel map accelerator entry and the `changed` parameter indicates whether this accelerator was changed during runtime ( and thus, would need saving during an accelerator map dump). `user_data` is `data` if `data` was specified. See the `gtk.accel_map_add_entry`() function for more information.

### gtk.accel_map_foreach_unfiltered

        def gtk.accel_map_foreach_unfiltered(foreach_func, data=None)

`foreach_func` : | function to be executed for each accel map entry
`data` : | data to be passed into `foreach_func`

### Note

This function is available in PyGTK 2.10 and above.

Loops over all entries in the accelerator map, and executes `foreach_func` on each. The signature of `foreach_func` is:

      def foreach_func(accel_path, accel_key, accel_mode, changed, user_data):

where `accel_path`, `accel_key` and `accel_mode` describe the accel map accelerator entry and the `changed` parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump). `user_data` is `data` if `data` was specified. See the `gtk.accel_map_add_entry`() function for more information.

### gtk.accel_map_get

        def gtk.accel_map_get()

Returns : | the global `gtk.AccelMap` object

### Note

This function is available in PyGTK 2.10 and above.

Gets the singleton global `gtk.AccelMap` object. This object is useful only for notification of changes to the accelerator map via the "changed" signal. it has no methods or properties.

### gtk.accel_map_load

        def gtk.accel_map_load(file_name)

`file_name` : | the file containing accelerator specifications

The `gtk.accel_map_load`() function parses the file (specified by `file_name`) previously saved with the `gtk.accel_map_save`() function for accelerator specifications, and propagates them accordingly.

### gtk.accel_map_save

        def gtk.accel_map_save(file_name)

`file_name` : | the file to save the accelerator specifications in

The `gtk.accel_map_save`() function saves current accelerator specifications (accelerator path, key and modifiers) to the file specified by `file_name`. The file is written in a format suitable to be read back in by the `gtk.accel_map_load`() function.

### gtk.accel_map_load_fd

        def gtk.accel_map_load_fd(fd)

`fd` : | a Python file object or an integer file descriptor

The `gtk.accel_map_load_fd`() function loads the accelerator map from the open Python file object specified by `fd`. `fd` may also be an integer file descriptor. See the `gtk.accel_map_load`() function.

### gtk.accel_map_save_fd

        def gtk.accel_map_save_fd(fd)

`fd` : | a Python file object or an integer file descriptor

The `gtk.accel_map_save_fd`() function saves the accelerator map into the open Python file object specified by fd. `fd` may also be an integer file descriptor. See the `gtk.accel_map_save`() function.

### gtk.accel_map_lock_path

        def gtk.accel_map_lock_path(accel_path)

`accel_path` : | a valid accelerator path

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.accel_map_lock_path`() function locks the accelerator path specified by `accel_path`. If the accelerator map doesn't yet contain an entry for `accel_path`, 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 the `gtk.accel_map_unlock_path`() function. Refer to the `gtk.accel_map_change_entry`() function for information about runtime accelerator changes.

If called more than once, `accel_path` remains locked until the `gtk.accel_map_unlock_path`() function has been called an equivalent number of times.

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

### gtk.accel_map_unlock_path

        def gtk.accel_map_unlock_path(accel_path)

`accel_path` : | a valid accelerator path

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.accel_map_unlock_path`() function undoes the last call to the `gtk.accel_map_lock_path`() function on the accelerator path specified by `accel_path`. Refer to the `gtk.accel_map_lock_path`() function for information about accelerator path locking.

### gtk.accel_map_add_filter

        def gtk.accel_map_add_filter(filter_pattern)

`filter_pattern` : | a glob-style pattern
Returns : |

The `gtk.accel_map_add_filter`() function adds the filter pattern specified by `filter_pattern` to the global list of accel path filters. The pattern specified by `filter_pattern` contain '*' and '?' wildcards with similar semantics as the Python `glob.py` and `fnmatch.py` modules: '*' matches an arbitrary, possibly empty, string, '?' matches an arbitrary character. Note that in contrast to `glob.py`, the '/' character can be matched by the wildcards, there are no '[...]' character ranges and '*' and '?' can not be escaped to include them literally in a pattern. Accelerator map entries whose accelerator path matches one of the filters are skipped by the `gtk.accel_map_foreach`() function. This function is intended for `PyGTK` modules that create their own menus, but don't want them to be saved into the applications accelerator map dump.

## Signals

### The "changed" gtk.AccelMap Signal

        def callback(object, accel_path, accel_key, accel_mods, user_param1, ...)

`object` : | the global accel map object
`accel_path` : | the path of the accelerator that changed
`accel_key` : | the key value for the new accelerator
`accel_mods` : | the modifier mask for the new accelerator
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.4 and above.

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

Prev | Up | Next
gtk.AccelLabel | Home | gtk.Accessible