gtk.AccelGroup
Prev | The gtk Class Reference | Next

## gtk.AccelGroup

gtk.AccelGroup — a group of accelerators for a Window hierarchy

## Synopsis

    class gtk.AccelGroup(gobject.GObject):
        gtk.AccelGroup()
        def lock()
        def unlock()
        def connect(accel_key, accel_mods, accel_flags, callback)
        def connect_group(accel_key, accel_mods, accel_flags, callback)
        def connect_by_path(accel_path, callback)
        def disconnect_key(accel_key, accel_mods)

    Functions

        def gtk.accelerator_valid(keyval, modifiers)
        def gtk.accelerator_parse(accelerator)
        def gtk.accelerator_name(accelerator_key, accelerator_mods)
        def gtk.accelerator_set_default_mod_mask(default_mod_mask)
        def gtk.accelerator_get_default_mod_mask()
        def gtk.accelerator_get_label(accelerator_key, accelerator_mods)
        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_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.AccelGroup

## gtk.AccelGroup Signal Prototypes

"accel-activate" | `def callback(`accelgroup`, `acceleratable`, `accel_key`, `accel_mods`, `user_param1`, `...`)`
"accel-changed" | `def callback(`accelgroup`, `accel_key`, `accel_mods`, `closure`, `user_param1`, `...`)`

## Description

A `gtk.AccelGroup` object groups all the accelerators for the associated window hierarchy (either `gtk.Window` (or a descendant) or `gtk.MenuShell` (or a descendant)). Once the `gtk.AccelGroup` is associated with a window or menu (using `gtk.Window.add_accel_group`() or `gtk.Menu.set_accel_group`()), accelerators can be added to the widget or one of its children by using `gtk.Widget.add_accelerator`() . Accelerators can also be added by using a `gtk.ItemFactory`.

Note that accelerators are different from mnemonics. Accelerators are shortcuts for activating a menu item; they appear alongside the menu item they're a shortcut for. For example Ctrl+Q might appear alongside the Files->Quit menu item. Mnemonics are shortcuts for GUI elements such as text entries or buttons; they appear as underlined characters. Of course, menu items can have both accelerators and mnemonics.

## Constructor

        gtk.AccelGroup()

Returns : | an AccelGroup object

Creates a new `gtk.AccelGroup` object.

## Methods

### gtk.AccelGroup.lock

        def lock()

The `lock`() method locks the accelerator group. preventing its accelerators from being changed during runtime. Refer to `gtk.accel_map_change_entry`() about runtime accelerator changes.

If called more than once, the accelerator group remains locked until `gtk.AccelGroup.unlock`() has been called an equivalent number of times.

### gtk.AccelGroup.unlock

        def unlock()

The `unlock`() method undoes the last call to `gtk.AccelGroup.lock`() for this accelerator group.

### gtk.AccelGroup.connect_group

        def connect(accel_key, accel_mods, accel_flags, callback)

`accel_key` : | key value of the accelerator
`accel_mods` : | modifier combination of the accelerator
`accel_flags` : | a flag mask to configure this accelerator
`callback` : | a function or method to be executed upon accelerator activation

### Note

This method is available in PyGTK 2.2 as `connect`() and was changed in PyGTK 2.4 and above to `connect_group`() to avoid conflict with the `gobject.GObject.connect`() method.

The `connect_group`() method installs an accelerator in the accelerator group. When the accelerator group is being activated, the function (or method) specified by `callback` will be invoked if the accelerator key and modifier key match those specified by `accel_key` and `accel_mods`.

The value of `modifier` is a combination of the GDK Modifier Constants. `accel_flags` is a combination of `gtk.ACCEL_VISIBLE` and `gtk.ACCEL_LOCKED`.

The `callback` function is defined as:

      def callback(accel_group, acceleratable, keyval, modifier)

where `accel_group` is the accelerator group, `acceleratable` is the object that the `accel_group` is attached to (e.g. a `gtk.Window`), `keyval` is the accelerator key and `modifier` is the key modifier. `callback` returns `TRUE` if the accelerator was handled by `callback`.

### Note

Due to implementation details, a single function or method can only be connected to one accelerator group.

### gtk.AccelGroup.connect_by_path

        def connect_by_path(accel_path, callback)

`accel_path` : | path used for determining key and modifiers.
`callback` : | function or method to be executed upon accelerator activation

### Note

This method is available in PyGTK 2.4 and above

The `connect_by_path`() method installs an accelerator in the accelerator group, using an accelerator path to look up the appropriate key and modifiers (see the function `gtk.accel_map_add_entry`()). When the accelerator group is being activated, the function (or method) specified by `callback` will be invoked if the `accel_key` and `accel_mods` that cause the activation match the key and modifiers for the accelerator path specified by `accel_path`.

The `callback` function is defined as:

      def callback(accel_group, acceleratable, keyval, modifier)

where `accel_group` is the accelerator group, `acceleratable` is the object that the `accel_group` is attached to (e.g. a `gtk.Window`), `keyval` is the accelerator key and `modifier` is the key modifier. `callback` returns `TRUE` if the accelerator was handled by `callback`.

### gtk.AccelGroup.disconnect_key

        def disconnect_key(accel_key, accel_mods)

`accel_key` : | key value of the accelerator
`accel_mods` : | modifier combination of the accelerator
Returns : | `TRUE` if there was an accelerator which was removed, `FALSE` otherwise

The `disconnect`() method removes a previously installed accelerator specified by `accel_key` and `accel_mods` from the accelerator group.

## Functions

### gtk.accelerator_valid

        def gtk.accelerator_valid(keyval, modifiers)

`keyval` : | a key value
`modifiers` : | a modifier mask
Returns : | `TRUE` if the accelerator is valid

The `gtk.accelerator_valid`() function returns `TRUE` if the specified `keyval` and `modifiers` constitute a valid keyboard accelerator. For example, the `ord('a')` keyval plus `gtk.gdk.CONTROL_MASK` is valid - this is a Control+a accelerator. The value of `modifiers` is a combination of the GDK Modifier Constants.

### gtk.accelerator_parse

        def gtk.accelerator_parse(accelerator)

`accelerator` : | a string representing an accelerator
Returns : | a 2-tuple containing the keyval and modifier mask of the accelerator

The `gtk.accelerator_parse`() function parses the specified `accelerator` string and returns a 2-tuple containing the keyval and modifier mask corresponding to `accelerator`. The format looks like "<Control>a" or "<Shift><Alt>F1" or "<Release>z" (the last one is for key release). The parser is fairly liberal and allows lower or upper case, and also abbreviations such as "<Ctl>" and "<Ctrl>". If the parse fails, the tuple values will both be 0 (zero). See the `gtk.accelerator_valid`() function for more details.

### gtk.accelerator_name

        def gtk.accelerator_name()

`accelerator_key` : | a key value
`accelerator_mods` : | a modifier mask
Returns : | a string representing the accelerator or `None` if not a valid accelerator

The `gtk.accelerator_name`() function converts the accelerator keyval and modifier mask (specified by `accelerator_key` and `accelerator_mods`) into a string parseable by the `gtk.accelerator_parse`() function. For example, if you pass in `ord('q')` and `gtk.gdk.CONTROL_MASK`, this function returns "<Control>q".

### gtk.accelerator_set_default_mod_mask

        def gtk.accelerator_set_default_mod_mask(default_mod_mask)

`default_mod_mask` : | the new default accelerator modifier mask

The `gtk.accelerator_set_default_mod_mask`() function sets the modifiers (specified by `default_mod_mask`) that will be considered significant for keyboard accelerators. The default mod mask is `gtk.gdk.CONTROL_MASK` | `gtk.gdk.SHIFT_MASK` | `gtk.gdk.MOD1_MASK`, that is, Control, Shift, and Alt. Other modifiers will by default be ignored by `gtk.AccelGroup`. You must include at least the three default modifiers in any value you pass to this function. The default mod mask should be changed on application startup, before using any accelerator groups. The value of `default_mod_mask` is a combination of the GDK Modifier Constants.

### gtk.accelerator_get_default_mod_mask

        def gtk.accelerator_get_default_mod_mask()

Returns : | the default accelerator modifier mask

The `gtk.accelerator_get_default_mod_mask`() function returns the default accelerator modifier mask as set by the `gtk.accelerator_set_default_mod_mask`() function. See the `gtk.accelerator_set_default_mod_mask`() function for more detail on modifier masks.

### gtk.accelerator_get_label

        def gtk.accelerator_get_label(accelerator_key, accelerator_mods)

`accelerator_key` : | a key value
`accelerator_mods` : | a modifier mask
Returns : | a string representing the accelerator

### Note

This function is available in PyGTK 2.6 and above.

The `gtk.accelerator_get_label`() function converts the accelerator keyval and modifier mask specified by `accelerator_key` and `accelerator_mods` respectively into a string which can be used to represent the accelerator to the user. The value of `accelerator_mods` is a combination of the GDK Modifier Constants.

### 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_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. 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.

### gtk.accel_groups_from_object

        def gtk.accel_groups_from_object(object)

`object` : | a GObject usually a `gtk.Window`

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.accel_groups_from_object`() function returns a list of all the `gtk.AccelGroup` objects attached to the object specified by `object`.

## Signals

### The "accel-activate" gtk.AccelGroup Signal

        def callback(accelgroup, acceleratable, accel_key, accel_mods, user_param1, ...)

`accelgroup` : | the accelgroup that received the signal
`acceleratable` : | the object that the accelerator is associated with
`accel_key` : | the accelerator key value
`accel_mods` : | the accelerator modifiers
`user_param1` : | the first user parameter (if any) specified with the `gobject.GObject.connect`() method
`...` : | additional user parameters (if any)
Returns : | `TRUE` if the accelerator was handled

The "accel-activate" signal is emitted when an accelerator is activated.

### The "accel-changed" gtk.AccelGroup Signal

        def callback(accelgroup, accel_key, accel_mods, closure, user_param1, ...)

`accelgroup` : | the accelgroup that received the signal
`accel_key` : | the key value of the accelerator
`accel_mods` : | the modifiers of the accelerator
`closure` : | the closure of the accelerator
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "accel-changed" signal is emitted when an accelerator is added or removed from an accelerator group.

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