.. meta::
    :description: Infrastructure Callbacks event

.. _callbacks:

Callbacks
=========

Similarly to :ref:`interests <pluginElementsInterests>`, callbacks is a notification mechanism used to keep the whole application coherent.
It works by specifying a function to be called when a specific event occurs.

These callbacks are set/removed by calling the methods defined in :class:`OrsEvent.eventCallback.EventCallback`.

.. note::
    When callbacks associated to a model object instance should not be triggered, call the method
    :meth:`ORSModel.ors.Managed.setCallbacksEnabled` on that instance.
    This is used when such a model object instance is created to perform a given task and is then deleted
    in the same method.

Syntax for adding a callback (for example, using an instance callback)::

    # Callback function to be called
    # Using a weak reference of the plugin so that it can be deleted
    weakSelf = self.getWeakRef()  # "self" is the plugin instance

    def aCallbackFunction(eventData):
        mySelf = weakSelf()
        if mySelf is None:
            return
        mySelf.aPluginMethod()  # "aPluginMethod" is an instance method of the plugin

    # Creating a unique ID for this callback
    callbackId = 'DemoPlugin_{}_{}_{}'.format('ObjectDeleted', anObject.getGUID(), repr(id(self)))

    # Setting the callback
    # The returned object of EventCallback should be kept in order to keep the callback alive
    self._objectDeletedEventCallback = EventCallback.addCallbackObjectDeletedEvent(anObject, callbackId,
                                                                                   aCallbackFunction)

The callback will exist as long as the object returned by the method of *EventCallback* is referenced.
To delete the callback, remove all references of that callback object. For example::

    # Removing the callback
    self._objectDeletedEventCallback = None

**Instance callbacks**

These callbacks are set on specific instances of the model. For example, it can be to react to a specific *Channel*
instance.

The available methods are those of :class:`OrsEvent.eventCallback.EventCallback` starting with *addCallback*.

.. _sourcecodeexample_plugin_DemoInstanceCallbacks_56a0eba8addf11e7baff448a5b5d70c0:

Source code example:

#. Download the :download:`compressed file </Documentation/Zipped/DemoInstanceCallbacks_56a0eba8addf11e7baff448a5b5d70c0.zip>`;
#. Extract these files into a :ref:`plugin extension folder <filesLocationPluginExtension>`;
#. Start the application;
#. Open the top level menu *Demos* to see the menu item named *Demo: instance callbacks*;
#. By clicking on the menu item, an instance of the plugin will be created
   and his mainform will be displayed.
   When initialized, this plugin instance will create and publish a ROI named *ROI with callback set on delete*,
   for which a callback is set on the deletion of this object that will close the plugin instance.
   At the plugin initialization, another ROI named *A common ROI* is also created and published,
   for which no specific callback is set;
#. Select the ROI *A common ROI*. Delete this ROI (use the button *Delete* next to the list of objects).
   Note that the plugin is still open and responsive;
#. Select the ROI *ROI with callback set on delete*. Delete this ROI.
   The plugin is closed due to the callback on the deletion of that specific object.

**Class callbacks**

These callbacks are set for any instances of the model. For example, it can be to react to the changes to any *Channel*
instance.

The available methods are those of :class:`OrsEvent.eventCallback.EventCallback` starting with *addClassCallback*.

.. _sourcecodeexample_plugin_DemoClassCallbacks_d335ec40aded11e7b38f448a5b5d70c0:

Source code example:

#. Download the :download:`compressed file </Documentation/Zipped/DemoClassCallbacks_d335ec40aded11e7b38f448a5b5d70c0.zip>`;
#. Extract these files into a :ref:`plugin extension folder <filesLocationPluginExtension>`;
#. Start the application;
#. Open the top level menu *Demos* to see the menu item named *Demo: class callbacks*;
#. By clicking on the menu item, an instance of the plugin will be created
   and his mainform will be displayed.
   When initialized, this plugin instance will set 2 class callbacks on the class *StructuredGrid*:
   one for the publish and one for the deletion. With this, any model object instance of that class that is getting
   published or deleted will trigger this callback, that will be used to update the plugin UI;
#. Create/import/delete some datasets, ROIs and MultiROIs to see the plugin UI being updated
   with the count of these objects.

**Global callbacks**

These callbacks are not specific to any model object, but to more general events.

The available methods are those of :class:`OrsEvent.eventCallback.EventCallback` starting with *addGlobalCallback*.

.. _sourcecodeexample_plugin_DemoGlobalCallbacks_ea5008a6adf911e7a36a448a5b5d70c0:

Source code example:

#. Download the :download:`compressed file </Documentation/Zipped/DemoGlobalCallbacks_ea5008a6adf911e7a36a448a5b5d70c0.zip>`;
#. Extract these files into a :ref:`plugin extension folder <filesLocationPluginExtension>`;
#. Start the application;
#. Open the top level menu *Demos* to see the menu item named *Demo: global callbacks*;
#. By clicking on the menu item, an instance of the plugin will be created
   and his mainform will be displayed.
   When initialized, this plugin instance will set a global callback on the view mode change;
#. Set the view mode of the current view to be in 3D. The pushbutton of the plugin UI will be disabled;
#. Set the view mode of the current view to be in any 2D view. The pushbutton of the plugin is re-enabled.