*********
SCADA API
*********
**Module:** ``typhoon.api.scada``

SCADA API is collections of functions/methods that can be used for changing widget parameters.
To use SCADA API to change widgets’ parameters, you must first load the HIL SCADA Panel file.

.. note::
    In case you try to use any other function then ``load_panel()`` before Panel file is loaded,
    ``ScadaAPIException`` will be raised. The same exception will be raised in case any error occurs in any SCADA API function.

Example::

    from typhoon.api.scada import panel

    # load a Panel file
    panel.load_panel(r"C:\scada_file.cus")

After the Panel whose widgets you want to change is loaded, you can access a particular widget by using the Widget ID.

.. note::
    To get the Widget ID open the Panel file in HIL SCADA, right-click on the desired widget and choose ``Copy Widget ID`` action.

Example::

    from typhoon.api.scada import panel

    # load a Panel file
    panel.load_panel(r"C:\scada_file.cus")

    # get the widget handle
    widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

Once the desired widget is acquired, its properties can be changed.

.. note::
    Not all widget properties can be changed by SCADA API. For detailed information witch properties can be changed for a specific widget, please consult the :doc:`Available Widget Properties </widget_prop>` section.

Example::

    from typhoon.api.scada import panel
    import typhoon.api.scada.const as api_const
    from typhoon.api.scada.exception import ScadaAPIException

    # load a Panel file
    panel.load_panel(r"C:\scada_file.cus")

    # get the widget handle
    widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

    # change the widget name
    panel.set_property_value(widget_handle,
                             api_const.PROP_NAME,
                             "New widget name")

    # in case we try to change an unsupported property or a new property
    # value is not valid ``ScadaAPIException`` will be raised
    try:
        # the new property value is invalid
        panel.set_property_value(widget_handle,
                                 api_const.PROP_NAME,
                                 [56, 28, 89])
    except ScadaAPIException as ex:
        print(ex)

After you finish modifying the Panel and the Panel’s widget, the loaded Panel can be saved to an existing Panel file or as a new Panel file.

Complete example::

    from typhoon.api.scada import panel
    import typhoon.api.scada.const as api_const
    from typhoon.api.scada.exception import ScadaAPIException

    # load a Panel file
    panel.load_panel(r"C:\scada_file.cus")

    # get the widget handle whose properties you want to change
    widget_handle = panel.get_widget_by_id("e18c3fe582d011e9bac3e0d55e6b2045")

    # change the widget name
    panel.set_property_value(widget_handle,
                             api_const.PROP_NAME,
                             "New widget name")

    # in case we try to change an unsupported property or a new property
    # value is not valid ``ScadaAPIException`` will be raised
    try:
        # the new property value is invalid
        panel.set_property_value(widget_handle,
                                 api_const.PROP_NAME,
                                 [56, 28, 89])
    except ScadaAPIException as ex:
        print(ex)

    # save changes to the existing Panel file...
    panel.save_panel()

    # ...or save changes to a new Panel file
    panel.save_panel_as(r"C:\new_scada_file.cus")

.. _api_constants:

SCADA API constants
-------------------
**Module:** ``typhoon.api.scada.const``

Various SCADA API methods expect predefined constants for some of their parameters.

Below is a listing (Python module) of all constants which are used
in SCADA API methods.

.. literalinclude:: ../../../typhoon/api/scada/const.py
   :language: python
   :lines: 26-

SCADA API in HIL SCADA
----------------------

HIL SCADA supports a subset of SCADA API functions, mainly for changing Panel widget properties and executing actions which are near identical as the manual GUI actions.

The following functions are available:

* get_widget_by_id()
* set_property_value()
* get_property_value()
* execute_action()

.. note::
    The functions listed above can be used in all handlers (Action Widgets) and Expression scripts (Monitoring Widgets), including
    the Panel and the local namespace (group-like widgets) initialization scripts.

.. note::
    SCADA API is imported into the HIL SCADA namespace as ``panel``

.. note::
    It is not recommended to change widget's parameters from multiple places (handlers, expression scripts...) at the same time.

.. note::
    The number of widgets which have support for the execute_action() function is currently limited. More information can be found in the :doc:`Available Widget Actions </widget_actions>` documentation.

    The function expects two mandatory arguments - widget_handle and action_name.

    It can also receive other optional keyword arguments (arg_name=arg_value) - this depends on the implementation by each widget.


Below you can find an example of changing the widget's name and executing an action::

    # store the widget id
    w_id = "484d3a86ffcf11e9956de0d55e6b2045"

    # get the widget that needs to be changed (in this case the Capture/Scope widget)
    wh = panel.get_widget_by_id(w_id)

    # change the widget's properties
    panel.set_property_value(wh,
                             prop_name=api_const.PROP_NAME,
                             prop_value="New name")


    # executing the "force_trigger" action (api_const.ACT_CS_FORCE_TRIGGER)
    panel.execute_action(widget_handle=wh,
                         action_name=api_const.ACT_CS_FORCE_TRIGGER)


`API references`_
-----------------

.. autoclass:: typhoon.api.scada.ScadaAPI
    :members:
    :member-order: bysource