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.