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.FunctionType or types.MethodType) – The function to be called when the action is triggered.

Raises

TypeError – If the given callback is not a function or 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, data=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.MethodType 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.MethodType or None) – The function to be called when the associated keyboard shortcut is released, or None to not call a function in that event.
data (object or None) – Custom data to pass to the callbacks when calling them. (Optional)

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 or None

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, or None if no such action ID is registered.

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.

__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, data=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.MethodType 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.MethodType 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.
data (object or None) – Custom data to pass to the callbacks when calling them. (Optional)

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 KeyboardShortcutItem objects 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.

Managing Keyboard Shortcuts¶

KeyboardShortcutManager¶

`KeyboardShortcutManager`¶