===========================
How to use the control mode
===========================

.. important:: 
    
    The original :py:class:`ska_control_model.ControlMode` enum has been deprecated since ska-control-model 1.3.0 used in ska-tango-base 1.7.0. This guide explains how the new :py:class:`ska_control_model.future.ControlMode` should be used according to ADR-114.

The optional :py:class:`!controlMode` Tango attribute can be added to a device by using :py:func:`~ska_tango_base.future._base_interface.standard_control_mode`. This factory function returns a tuple of the private signal and public Tango attribute. The default write method of the attribute can then be overridden to implement the desired behaviour when the control mode is changed by a client. The following example shows how to implement the write method to connect to or disconnect from the underlying component depending on the control mode:

.. code:: python

    import ska_control_model as scm
    from ska_tango_base import future
    
    class MyDevice(future.BaseInterface):
        ...
        _control_mode, controlMode = future.standard_control_mode()

        @controlMode.write
        def write_controlMode(self, value: scm.future.ControlMode) -> None:
            if value == scm.future.ControlMode.NO_MONITOR_NO_CONTROL:
                self.component.disconnect()
                self.logger.info("Not monitoring or controlling the device")
            elif value == scm.future.ControlMode.MONITOR_NO_CONTROL:
                self.component.connect(mode=READ_ONLY)
                self.logger.info("Only monitoring the device")
            elif value == scm.future.ControlMode.MONITOR_AND_CONTROL:
                self.component.connect(mode=READ_WRITE)
                self.logger.info("Monitoring and controlling the device")
            self._control_mode = value