eye.helpers.actions module

Module for registering actions on widgets

This module helps in the creation of QAction objects. The actions module is to QAction`s what the :any:`eye.connector is to Qt signal and slots.

An action is registered with a name for a set of categories. The action can be triggered when a particular shortcut is pressed, which are registered with register_action_shortcut. When the action is triggered, in turn it can trigger a callback (with register_action) or a slot (with register_action_slot, but this one is optional), or a Scintilla editor action.

The use of categories lets the register be done once, not for every widget instance. Internally, QAction objects are created automatically by the module in each instance.

For example, an action print_console_file could be created for editor widgets and bound to Ctrl+P:

@register_action('editor', 'print_console_file')
def my_action_func(ed):
        print(ed.text())

register_action_shortcut('editor', 'print_console_file', 'Ctrl+P')

The same can be done in a single step:

@register_shortcut('editor', 'Ctrl+P')
def my_action_func(ed):
        print(ed.text())

This way is simpler but less re-usable because the action is unnamed. A plugin can register actions but should not bind keyboard shortcuts to it and let user configuration do it.

eye.helpers.actions.get_action(obj, action_name)

Return children QAction of obj named action_name.

eye.helpers.actions.register_action(categories, action_name=None, stackoffset=0)

Decorate a function to be registered as an action

The decorated function will be registered as action action_name for objects matching the categories

eye.helpers.actions.register_action_shortcut(categories, action_name, keyseq, context=<Mock object>)

Register a shortcut for an action

Parameters:

• categories – the categories of the widgets where to watch the shortcut

• action_name (str) – the name of the action to trigger when the shortcut is triggered

• keyseq (str, int or QKeySequence) – the shortcut description

• context – the context where to listen to the shortcut, relative to the widgets matching the categories

eye.helpers.actions.register_action_slot(categories, slot_name)

Register an action named slot_name, triggering slot slot_name

An action named slot_name is registered for categories. When the action is triggered, it will call the slot slot_name of the object where the action is triggered. So, objects matching categories should have a slot slot_name.

It’s not required to call this function: when a keyboard shortcut is triggered, and the shortcut was bound to an action (with register_action_shortcut) which had no callable registered (i.e. register_action or similar functions were never called), then it tries to call a slot named the same as the action name.

eye.helpers.actions.register_shortcut(categories, keyseq, context=<Mock object>, action_name=None)

Decorate a function to be called when a keyboard shortcut is typed

When the keyboard shortcut keyseq is pressed in any widget matching categories, the decorated function will be called, with the widget passed as first parameter.

Internally, when a widget matches the categories, a QAction is created for it and the shortcut is set. See build_action.

Parameters:

• categories (str or list) – the categories of the widgets where to watch the shortcut

• keyseq (str, int or QKeySequence) – the shortcut description

• context – the context where to listen to the shortcut, relative to the widgets matching the categories

eye.helpers.actions.unregister_action_shortcut(categories, keyseq, context=<Mock object>)

Unregister a keyboard shortcut previously registered

After this call, current widgets matching categories will not have the keyboard shortcut anymore, and it won’t be bound to new widgets matching categories.