eye.connector module

Connector for signals and slots of categories.

Connector

In Qt, a signal of an object can be connected to the slot of another object, so when the signal of this object is emitted, the slot of that object is called. However, the connections are individual: even though a signal exists for a whole class of object, it’s not possible to connect the signal of all objects of a class to one slot.

In EYE, the connector allows to connect a signal of all existing objects matching a category (see Categories) as well as future objects matching this category, to a function.

Categories

A category is a string tag attached to an object. An object can have multiple categories. Categories can be added to/removed from an object dynamically, though often the categories will be set when the object is created. Since the connector (see Connector) allows automatic connection of many objects to a function, categories allow finer grained control of what objects should be connected than if the class of the objects was the only criterion of connection.

Example

All objects of the class eye.widgets.Editor have by default the category "editor" and that class has the file_saved = Signal(str) signal, where the first argument is the path of the saved file. When configuring EYE (see Configuration), it’s possible to add this code:

from eye.connector import register_signal

@register_signal('editor', 'file_saved')
def foo(editor_obj, path):
        print('file %s was saved' % path)

We connect the file_saved signal all objects having the category "editor" to the foo callback, which will receive multiple arguments, first the object which sent the signal, and then the arguments of the file_saved signal. When a new Editor widget will be created, it will automatically be connected to our callback, so when any editor will be saved, foo will be called.

Module contents

class eye.connector.CategoryMixin(**kwargs)

Bases: object

Mixin class to support object categories.

This class should be inherited by classes of objects which should have categories.

add_category(c)

Add a category to the object.

categories()

Return categories of the object.

remove_category(c)

Remove a category from an object.

eye.connector.category_objects(categories, ancestor=None)

Return objects matching all specified categories.

Parameters:

• categories (list or str) – matching object should match _all_ these categories

• ancestor – if not None, only objects that are children of ancestor are returned

eye.connector.default_editor_config(x)

Decorate a function that should be called for every editor.

This decorator is intended for functions to configure editor widgets. See also register_setup.

eye.connector.default_lexer_config(x)

Decorate a function that should be called when a lexer is set for an editor.

This decorator is intended for functions to configure lexers.

eye.connector.default_window_config(x)

Decorate a function that should be called for every EYE window.

This decorator is intended for functions to configure EYE windows. See also register_setup.

eye.connector.delete_created_by(caller)

Unregister listeners registered by script caller.

If caller script file had registered any listeners (as with register_signal), this method unregisters them.

This can be useful to unregister all listeners from a script to re-run the script afterwards, to avoid listeners be registered (and listening) twice.

Parameters:

caller (str) – path of the script that registered listeners

eye.connector.disabled(func)

Disable a function previously decorated with a listener like register_signal.

If the decorated function (func) has been decorated with register_signal, registerEventFilter or some other kind of listener decorator, the decorated function will not be called anymore when a matching signal is emitted or a event has to pass in a filter, until it is enabled again.

This decorator simply sets an enabled attribute on the decorated function to False. To re-enable the disabled function, just set the enabled attribute to True.

When the function is re-enabled, missed signals and events will not cause the decorated function to be called, but upcoming signals/events will trigger the decorated function.

Since functions decorated with registerSetup can be triggered only when an object _starts_ matching categories, re-enabling such a function will not catch-up the setup of an object.

eye.connector.register_event_filter(categories, event_types, stackoffset=0)

Decorate a function that should be run when an event is sent to an object.

When a PyQt5.QtCore.QEvent object of a type in event_types is sent to an object matching categories, the decorated function will be called.

The decorated function must take 2 parameters: the destination object to which the event is sent and the event itself.

If the value returned by the decorated function is True, the sent event will be filtered: it will not reach the destination object, and it will not be processed by any other event-filters, registered by standard Qt functions or by registerEventFilter.

If the value returned by the decorated function is False or is omitted (it is None then), the event will continue its route through other event-filters and to the destination object.

See also PyQt5.QtCore.QObject.eventFilter and PyQt5.QtCore.QObject.installEventFilter.

Example:

@register_event_filter('window', [QEvent.Close])
def on_win_close(window, event):
        print('the %s window was closed' % window)

Parameters:

• categories (list or str) – the categories to match

• event_types (list of ints) – list of accepted QEvent.type() the sent event should match

Return type:

bool

eye.connector.register_setup(categories, stackoffset=0)

Decorate a function that should be run for all objects matching categories.

When an object is created that matches categories or an object is being added new categories and they match the specified categories, the decorated function will be called. Also, when the function is decorated, it is called for all existing objects matching categories.

The decorated function will received the matching object as only argument.

Parameters:

categories (list or str) – the categories to match

Example:

@register_setup('editor')
def foo(editor_obj):
        print('an editor has been created')

eye.connector.register_signal(categories, signal, stackoffset=0)

Decorate a function that should be run when a signal is emitted.

When the signal of all existing and future objects matching all specified categories is emitted, the decorated function will be called.

When called, the decorated function will received the target object as first argument, then the signal arguments as next arguments.

Parameters:

categories (list or str) – the categories to match

Example:

@register_signal('editor', 'file_saved')
def foo(editor_obj, path):
        print('file %s has been saved', path)

eye.connector.register_teardown(categories, stackoffset=0)