eye.helpers.intent module

Action intents

Intents are generic actions triggered by plugins that are delegated to user configuration and other plugins.

An example is the “open_editor” intent. It be triggered by an “Open” dialog (eye.widgets.filechooser module) when a file is selected by the user or by a eye.widgets.locationlist.LocationList when a location is clicked. Configuration scripts can register multiple intent callbacks for this intent type. They will be called in turn, until one of the callbacks handles the intent, for example by opening a new tab (see eye.helpers.buffers module). When the intent has been handled, callback processing for this intent stops.

Internally, intents are events and intent listeners are event filters.

class eye.helpers.intent.IntentEvent(intent_type, **kwargs)[source]

Bases: QEvent

Intent

Type = <Mock object>
accept(result=None)[source]

Accept the intent

When an intent listener handles an IntentEvent, it should return True to avoid the intent being handled multiple times. Optionally, when the intent is handled, it can also be marked as accepted, with a result value. This result can then be retrieved by the object which sent the intent. The result is set in the result attribute of the IntentEvent.

For example, there could be an intent for querying user input, an object needing input would send the intent and would get back the input that one of the listeners produced, in the result attribute. Or there could be an intent for creating a new tab, and a handler would create a different widget than the normal eye.widgets.editor.Editor, and return it through this result.

info = <Mock object>

Extra info about the intent

This info is filled when the intent is sent (send_intent).

Type:

eye.structs.PropDict

intent_type = <Mock object>

Type of the intent

An intent has a type, which is a simple string, for example “open_editor” for the intent to open an editor with a particular file displayed.

Type:

str

result = <Mock object>

Result of the intent (if applicable)

Optionally set by a handler with accept.

source = <Mock object>

Object that sent the intent

Type:

QObject

eye.helpers.intent.default_open_editor(source, ev)[source]
eye.helpers.intent.dummy_listener(source, intent)[source]

Sample intent listener

Intent listeners (see register_intent_listener) should follow this function prototype.

The function can handle intent and perform appropriate action if desired.

If the function handled the intent, it should return True to mark the intent has having been already processed. Consequently, no more callbacks are called for this intent, to avoid it being handled multiple times.

If the function handled the intent and returned a “truthy” value, but it did not call Intent.accept, the Intent is automatically accepted and the value returned by the function is considered to be the Intent result (Intent.result).

If the function didn’t handle the intent, it should return False, so other callbacks have a chance to handle it.

Parameters:
Returns:

True if the listener handled the intent, else False

Return type:

bool

eye.helpers.intent.register_intent_listener(intent_type, categories=None, stackoffset=0)[source]

Decorate a callback to be registered as an intent listener

See dummy_listener for documentation of how the callback should be.

Parameters:

  • intent_type (str) – the type of the intent to listen to

  • categories – If None, listen to intents from any object. Else, listen to intent emitted by objects matching the categories.

eye.helpers.intent.send_intent(source, intent_type, **kwargs)[source]

Send an intent

If the intent was handled by a listener, it can have a result, see IntentEvent.result.

Parameters:

  • source – object sending the intent

  • intent_type (str) – type of the intent

  • kwargs – extra info about the intent

Returns:

the result of the intent, if any