apptools.selection.selection_service module

class apptools.selection.selection_service.SelectionService[source]

Bases: HasTraits

The selection service connects selection providers and listeners.

The selection service is a register of selection providers, i.e., objects that publish their current selection.

Selections can be requested actively, by explicitly requesting the current selection in a provider (get_selection(id)()), or passively by connecting selection listeners.

add_selection_provider(provider)[source]

Add a selection provider.

The provider is identified by its ID. If a provider with the same ID has been already registered, an IDConflictError is raised.

Parameters

ISelectionProvider (provider --) – The selection provider added to the internal registry.

connect_selection_listener(provider_id, func)[source]

Connect a listener to selection events from a specific provider.

The signature if the listener callback is func(i_selection). The listener is called:

  1. When a provider with the given ID is registered, with its initial selection as argument, or

  2. whenever the provider fires a selection event.

It is perfectly valid to connect a listener before a provider with the given ID is registered. The listener will remain connected even if the provider is repeatedly connected and disconnected.

Parameters

  • str (provider_id --) – The selection provider ID.

  • callable (func --) – A callable object that is notified when the selection changes.

disconnect_selection_listener(provider_id, func)[source]

Disconnect a listener from a specific provider.

Parameters

  • str (provider_id --) – The selection provider ID.

  • callable (func --) – A callable object that is notified when the selection changes.

get_selection(provider_id)[source]

Return the current selection of the provider with the given ID.

If a provider with that ID has not been registered, a ProviderNotRegisteredError is raised.

Parameters

str (provider_id --) – The selection provider ID.

Returns

selection – ISelection

The current selection of the provider.

has_selection_provider(provider_id)[source]

Has a provider with the given ID been registered?

remove_selection_provider(provider)[source]

Remove a selection provider.

If the provider has not been registered, a ProviderNotRegisteredError is raised.

Parameters

ISelectionProvider (provider --) – The selection provider added to the internal registry.

set_selection(provider_id, items, ignore_missing=False)[source]

Set the current selection in a provider to the given items.

If a provider with the given ID has not been registered, a ProviderNotRegisteredError is raised.

If ignore_missing is True, items that are not available in the selection provider are silently ignored. If it is False (default), a ValueError should be raised.

Parameters

  • str (provider_id --) – The selection provider ID.

  • list (items --) – List of items to be selected.

  • bool (ignore_missing --) – If False (default), the provider raises an exception if any of the items in items is not available to be selected. Otherwise, missing elements are silently ignored, and the rest is selected.