Adds change_slots event to notify UI of slot-modifying changes

Created by: stefanoborini

When the model contains options that might modify the resulting slots, a notification must be issued, so that the UI can take appropriate action.

Provides that mechanism, and documents it.

Fixes #74 (closed)

doc/source/plugin_development.rst

@@ -11,14 +11,31 @@ one of the above pluggable entities and its associated classes.
 To implement a new plugin, you must
 
 - define the entity you want to extend (e.g. ``MyOwnDataSource``) as a derived
-  class of the appropriate class (e.g. BaseDataSource), and reimplement
-  the appropriate methods.
-- Define the model that this DataSource needs, by extending
+  class of the appropriate class (e.g. ``BaseDataSource``), and reimplement
+  the appropriate methods:
+
+   - ``run()``: where the actual computation takes place, given the
+     configuration options specified in the model (which is received as an
+     argument). It is strongly advised that the ``run()`` method is stateless.
+   - ``slots()``: must return a 2-tuple of tuples. Each tuple contains instances
+     of the ``Slot`` class. Slots are the input and output entities of the
+     data source or KPI calculator. Given that this information depends on the
+     configuration options, ``slots()`` accepts the model and must return the
+     appropriate values according to the model options.
+
+- Define the model that this ``DataSource`` needs, by extending
   ``BaseDataSourceModel`` and adding, with traits, the appropriate data that
   are required by your data source to perform its task.
+  If a trait change in your model influences the input/output slots, you must
+  make sure that the event ``changes_slots`` is fired as a consequence of
+  those changes. This will notify the UI that the new slots need to be
+  recomputed and presented to the user. Failing to do so will have unexpected
+  consequences.
 - Define the Factory, by reimplementing BaseDataSourceFactory and reimplementing
   its ``create_*`` methods to return the above entities.
 - Define a ``Plugin`` by reimplementing ``BaseExtensionPlugin`` and
   reimplementing its initialization defaults methods to return your factory.
 - add the plugin class in the setup.py entry_point, under the namespace
   ``force.bdss.extensions``
+
+