Managing Keyboard Shortcuts¶

Certain actions and key events in the UI can be defined with custom keyboard shortcuts using a configuration file stored in a user’s Katana folder: $HOME/.katana/shortcuts.xml.

Not all keyboard shortcuts can be customized. A list of modifiable keyboard shortcuts can be viewed in the Keyboard Shortcuts tab, along with their default assignments. Keyboard shortcuts can be customized in tabs that make use of the Keyboard Shortcuts Manager, including new custom tabs.

The configuration file can be used to override the default keyboard shortcuts of actions and key events that are registered with Katana’s Keyboard Shortcut Manager, for example:

<shortcuts>
    <shortcut id="430f81d33d338680a0c64ae9ea311cd7"
              name="SceneGraphView.ExpandBranchesToAssembly"
              shortcut="A"></shortcut>
</shortcuts>

The ID of a keyboard shortcut element is assigned by the user that registers the action or key event. It is a hash based on the original name of the action or key event. While the name of an action or key event may change, the ID remains the same for future versions of Katana. This ensures that the correspondence of custom keyboard shortcuts to the respective actions or key events remain the same, even if names change.

From the Keyboard Shortcuts tab, you can copy an XML representation of an item in the keyboard shortcuts tree to the clipboard by right-clicking the item and choosing Copy as XML. Pasting such an XML representation into the shortcuts.xml file allows you to override the default assigned keyboard shortcut.

Note

The name attribute of a shortcut XML element only appears for readability, making it easy to identify the action or key event to which the shortcut has been assigned. The names in the shortcuts.xml file are not updated automatically when names of actions or key events are changed in the application.

KeyboardShortcutManager¶

The UI4.App.KeyboardShortcutManager Python module can be used to register action callbacks to which keyboard shortcuts can be assigned.

It covers the following areas of the UI:

The buttons next to the main menu in Katana’s main application window:
- Shelf Scripts
- Flush Caches
- Toggle Scene Graph Implicit Resolvers
- Render Only Selected Objects
- Auto-key All
The Scene Graph tab
The table of objects in GafferThree nodes that are edited in the Parameters tab
Custom tab plug-ins that derive from UI4.Tabs.BaseTab

Module providing functions to register and handle keyboard shortcuts for actions and key events.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.LoadShortcuts()¶: Loads user’s keyboard shortcuts definition file.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.RegisterActions(contextName, actions)¶

Registers multiple actions as defined by the data of the given actions dictionary under the given keyboard shortcuts context.

Parameters:	contextName (`str`) – The name of the keyboard shortcuts context under which to register the actions. actions (`dict`) – A dictionary with names of actions as keys and tuples of action data as values. Each value must be a tuple of 3 values: `action ID: str, keyboard shortcut: str or None, callback: callable`
Raises:	TypeError – If one of the arguments has an invalid type. ValueError – If a value in the given `actions` dictionary is not a 3-tuple of a string, a string or None, and a callable object.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.RegisterAction(actionID, name, shortcut, callback)¶

Registers an action with the specified ID, name, shortcut and callback.

Registered actions are bound to an actual widget using the BindActions function.

Parameters:

actionID (str) – The unique identifier to be associated to the action.
name (str) – The name of the action to be registered, including the name of its keyboard shortcuts context.
shortcut (str or None) – The default keyboard shortcut to be assigned to the action, or None to not assign a default keyboard shortcut.
callback (types.UnboundMethodType) – The function to be called when the action is triggered.

Raises:

TypeError – If the given callback is not an unbound method.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.UnregisterAction(actionID)¶

Removes the action with the given ID from the registry of actions, deleting any ManagedAction instances that may be bound against widgets for it.

Parameters:	actionID (`str`) – The unique identifier of the action to unregister.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.RegisterKeyEvent(className, keyEventID, name, shortcut, pressCallback=None, releaseCallback=None)¶

Registers a key event with the specified keyEventID.

Parameters:

className (str) – The name of the widget’s class we want to associate the key event with.
keyEventID (str) – The unique identifier to be associated to the key event.
name (str) – The name of the key event to be registered.
shortcut (str) – The keyboard shortcut to be associated to the key event.
pressCallback (types.UnboundMethodType or None) – The function to be called when the associated keyboard shortcut is pressed, or None to not call a function in that event.
releaseCallback (types.UnboundMethodType or None) – The function to be called when the associated keyboard shortcut is released, or None to not call a function in that event.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.UnregisterKeyEvent(keyEventID)¶

Unregisters a key event

Parameters:	keyEventID (`str`) – The unique identifier to be associated to the key event.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.UpdateAction(managedAction)¶

Updates the database of actions modifying the keyboard shortcut for the given managed action.

Parameters:	managedAction (`ManagedAction`) – The action to be updated.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GetActionID(contextName, actionName)¶

Return type:	`str` or `None`
Parameters:	contextName (`str`) – The name of the keyboard shortcuts context under which the action has been registered whose action ID to return. actionName (`str`) – The relative name of the action under the keyboard shortcuts context with the given name whose action ID to return.
Returns:	The ID of the action corresponding to the given keyboard shortcuts context name and action name, or `None` if no such action is registered.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GetFullActionName(actionID)¶

Return type:	`str` or `None`
Parameters:	actionID (`str`) – The ID of the action for which to return the full name.
Returns:	The full name of the action (including the context under which it was registered) which was registered for the given ID, or `None` if no registered action could be found for the given ID.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GetShortcutForAction(actionNameOrID)¶

Return type:	`str` or `None`
Parameters:	actionNameOrID (`str`) – The name or ID of a registered action for which the shortcut should be returned.
Returns:	A string representing the registered shortcut for the given action name or ID, or `None` if no such shortcut could be found.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GetKeyEventID(contextName, keyEventName)¶

Return type:	`str` or `None`
Parameters:	contextName (`str`) – The name of the keyboard shortcuts context under which the key event has been registered whose key event ID to return. keyEventName (`str`) – The relative name of the key event under the keyboard shortcuts context with the given name whose key event ID to return.
Returns:	The ID of the key event corresponding to the given keyboard shortcuts context name and key event name, or `None` if no such key event is registered.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GetFullKeyEventName(keyEventID)¶

Return type:	`str` or `None`
Parameters:	keyEventID (`str`) – The ID of the key event for which to return the full name.
Returns:	The full name of the key event (including the context under which it was registered) which was registered for the given ID, or `None` if no registered key event could be found for the given ID.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GetKeyEventNameForShortcut(contextName, shortcut)¶

Gets the KeyEventName for the shortcut

Return type:	`str`
Parameters:	contextName (`str`) – The name of the widget’s class we want to associate the key event with. shortcut (`str`) – The keyboard shortcut to be associated to the key event.
Returns:	Name of the keyevent

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GetShortcutForKeyEvent(keyEventID)¶

Return type:	`str` or `None`
Parameters:	keyEventID (`str`) – The ID of a registered key event for which the shortcut should be returned.
Returns:	A string representing the registered shortcut for the given key event ID, or `None` if no such shortcut could be found.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.BindActions(contextName, widget, callbackInstance=None)¶

Binds actions to the given widget for the specified context.

Parameters:	contextName (`str`) – The name of the keyboard shortcuts context used to look up actions. widget (`QtWidgets.QWidget`) – The widget to bind actions to. callbackInstance (`object` or `None`) – An instance to bind registered action callbacks to, or `None` to bind registered action callbacks to the given widget.
Raises:	TypeError – If the given widget is not an instance of a class derived from `QtWidgets.QWidget`.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.CreateAction(actionID, widget, icon=None, text=None, enabled=True)¶

Creates an action for use in a menu or toolbar based on the registered action with the given ID. The registered action’s icon and text can be overridden with the given icon and text. The given enabled state controls whether the resulting action is enabled or disabled.

Return type:	`QtWidgets.QAction`
Parameters:	actionID (`str`) – The ID of the registered action to return a `QtWidgets.QAction` for. widget (`QtWidgets.QWidget`) – The widget to which the action has been bound. icon (`QtGui.QIcon` or `None`) – An icon to use for the resulting action, or `None` to use the icon of the registered action. text (`str` or `None`) – Text to use for the resulting action, or `None` to use the name of the registered action for its text. enabled (`bool`) – The enabled state to use for the resulting action.
Returns:	An action for use in a UI corresponding to the registered action with the given ID.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.BuildShortcutModel()¶: Builds a model from the actions dictionary and returns it.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.HandleKeyEvent(widget, keyEvent)¶

Handles the given key press or key release event for the given widget by calling a callback that has been registered for the pressed or released keyboard shortcut, if available.

Return type:	`bool`
Parameters:	widget (`QtWidgets.QWidget`) – The widget in which the key event originated. keyEvent (`QtGui.QKeyEvent`) – The key event to handle
Returns:	`True` if a key event callback has successfully been called or if the given key event is the result of a key being held down, or `False` if the given key event has already been accepted, if no callback is available for the given key event, or if calling a callback has failed.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.IsShortcutRegisteredForClass(className, shortcut)¶

Check if the same shortcut is used for this tab already. Linear walk but it should be short anyway.

Return type:	`bool`
Parameters:	className (`str`) – The name of the widget’s class we want to associate the key event with. shortcut (`str`) – The keyboard shortcut to be associated to the key event.
Returns:	True if the shortcut is already being used.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.IsShortcutRegisteredForAction(actionContext, shortcut)¶

Check if the shortcut is already in used by an action.

Return type:	`bool`
Parameters:	actionContext (`str`) – The context of the action. shortcut (`str`) – The keyboard shortcut to be associated to the action.
Returns:	True if the shortcut is already being used.

UI4.App.KeyboardShortcutManager.KeyboardShortcutManager.GenerateActionID(name)¶

Return type:	`str`
Parameters:	name (`str`) – The name of the action to generate an action ID for.
Returns:	An ID that can be used as an action ID for the action with the given name.

class UI4.App.KeyboardShortcutManager.KeyboardShortcutItem.KeyboardShortcutItem(name, data, parent=None)¶

Bases: object

Represents a shortcut bound to an action or a key event. Shortcut items are stored in a tree-like structure built upon item names.

__init__(name, data, parent=None)¶

Initializes the current item with the provided data and sets the parent item.

Parameters:	name (`str`) – The name of the keyboard shortcut item that will appear as a leaf in the keyboard shortcuts tree. data (`dict`) – Data associated with the keyboard shortcut. By default this should include the ‘defaultShortcut’ and ‘currentShortcut’ keys. parent (`KeyboardShortcutItem` or `None`) – The parent keyboard shortcut item.

appendChild(child)¶

Appends a child item to the current item.

Parameters:	child (`KeyboardShortcutItem` or `None`) – The item to be added as a child for the keyboard shortcut item.

getChildByRow(row)¶

Return type:	`KeyboardShortcutItem` or `None`
Parameters:	row (`int`) – The row index for the requested child.
Returns:	The item’s child for the specified row. If the item doesn’t have any child, `None` will be returned.

getCurrentShortcut()¶

Return type:	`str`
Returns:	The current keyboard shortcut associated with the keyboard shortcut item.

getDefaultShortcut()¶

Return type:	`str`
Returns:	The default keyboard shortcut associated with the keyboard shortcut item.

getID()¶

Return type:	`str`
Returns:	The ID of the keyboard shortcut item.

getName()¶

Return type:	`str`
Returns:	The name of the keyboard shortcut item.

getParent()¶

Return type:	`KeyboardShortcutItem`
Returns:	The parent of the keyboard shortcut item.

getRowOfChild(child)¶

Return type:	`int`
Parameters:	child (`KeyboardShortcutItem`) – The keyboard shortcut item to get the row index from.
Returns:	The row index for the specified child. If the specified item is not an item’s child, -1 will be returned.

sort()¶: Sorts the current item sub-tree by name.

class UI4.App.KeyboardShortcutManager.KeyboardShortcutManagerMixin.KeyboardShortcutManagerMixin(*args, **kwargs)¶

Bases: object

Base class for UI widgets which need to provide keyboard shortcut handling for themselves and their child widgets.

Provides handling of custom callbacks for keyboard shortcuts that are associated with user-defined keyboard shortcuts.

Classes should inherit from this class as well as a QWidget -derived class. Place QWidget classes first where possible.

Every class that extends KeyboardShortcutManagerMixin should set its __metaclass__ class member to KeyboardShortcutManagerMixinMetaclass.

__init__(*args, **kwargs)¶: Initializes an instance of the class.

eventFilter(obj, event)¶

Filter events delivered to this widget or to its child widgets.

Return type:	`bool`
Parameters:	obj (`QObject`) – The target object for which the incoming event was intended. event (`QEvent`) – The incoming event to be filtered.
Returns:	`True` to prevent further processing of this event, or `False` to allow the original target object to receive the event.

classmethod getShortcutsContextName()¶

Return type:	`str`
Returns:	The name under which keyboard shortcuts are registered for the widget implemented by the given class.

classmethod registerKeyboardShortcut(shortcutID, name, shortcut, keyPressCallback=None, keyReleaseCallback=None)¶

Convenience function to register keyboard shortcuts callbacks.

Parameters:

shortcutID (str) – The unique string identifying the keyboard shortcut.
name (str) – The name of the key event to be registered.
shortcut (str) – The keyboard shortcut assigned to the key event.
keyPressCallback (types.UnboundMethodType or None) – The callback function assigned to the key event to be called when the matching keyboard shortcut is pressed, None to not assign a callback function for the key press event.
keyReleaseCallback (types.UnboundMethodType or None) – The callback function assigned to the key event to be called when the matching keyboard shortcut is released, or None to not assign a callback function for the key release event.

classmethod setShortcutsContextName(name)¶

Sets the name under which keyboard shortcuts are registered for the widget implemented by the given class.

Parameters:	name (`str`) – The keyboard shortcuts context name to be assigned for the given class.

class UI4.App.KeyboardShortcutManager.KeyboardShortcutModel.KeyboardShortcutModel(data, parent=None)¶

Bases: PyQt5.QtCore.QAbstractItemModel

Builds a Qt model for shortcut items to be displayed in a QTreeView.

__init__(data, parent=None)¶

Initializes the model from the provided data.

Parameters:	data (`dict`) – The dictionary containing actions and key events data to be used to generate the tree model. parent (`QObject`) – The object owning the model.

columnCount(parent)¶

Return type:	`int`
Parameters:	parent (`QtCore.QModelIndex`) – The parent item for which to return the number columns.
Returns:	The number of columns for this model.

data(index, role)¶

Return type:	`QtCore.QVariant`
Parameters:	index (`QtCore.QModelIndex`) – The index for which to return the item’s data. role (`int`) – The type of data requested by the view.
Returns:	The data token associated with the current item for the specified index and role.

headerData(section, orientation, role)¶

Return type:	`QtCore.QVariant`
Parameters:	section (`int`) – The index of the headers list to be returned. orientation (`QtCore.Qt.Orientation`) – The requesting view’s orientation. role (`int`) – The type of data requested by the view.
Returns:	The header data for this model.

index(row, column, parent)¶

Return type:	`QtCore.QModelIndex`
Parameters:	row (`int`) – The row for which to return an item index. column (`int`) – The column for which to return an item index. parent (`QtCore.QModelIndex`) – The parent item index.
Returns:	The index of the element in the tree specified by the given row, column and parent.

parent(child)¶

Return type:	`QtCore.QModelIndex`
Parameters:	child (`QtCore.QModelIndex`) – The item for which to return the parent item.
Returns:	The parent index for the given child.

rowCount(parent)¶

Return type:	`int`
Parameters:	parent (`QtCore.QModelIndex`) – The parent item for which to return the number of children.
Returns:	The number of rows for the given parent index.

setupModelData(data)¶

Builds a tree of KeyboardShortcutItems based on the provided data.

Parameters:	data (`dict`) – The dictionary used to generate the tree model.

class UI4.App.KeyboardShortcutManager.ManagedAction.ManagedAction(actionID, text, parent, icon=None)¶

Bases: PyQt5.QtWidgets.QAction

Defines an extended QtWidgets.QAction handling the 'changed' signal to update keyboard shortcuts stored by the KeyboardShortcutManager.

__init__(actionID, text, parent, icon=None)¶

Initializes an instance of the class.

Parameters:	actionID (`str`) – The unique ID of the action. text (`str`) – The default text to use for actions created from this managed action for a UI. parent (`QtCore.QObject`) – The parent to use for the action. icon (`QtGui.QIcon` or `None`) – An icon to use for actions created from this managed action for a UI.

getActionID()¶

Return type:	`str`
Returns:	The unique ID of the action.