Graphical panels
================

Overview
--------

The support of SCADE Display or SCADE Rapid Prototyper is possible and is
partially automated: the SCADE Display DLLs are built and loaded at run time,
and the DLL exports all the required functions to access the displays.
However, the Python ``ctype`` structures corresponding to the layers' contexts
must be written manually for now.

.. Note::

    The graphical panels are accessed independently from Python and thus,
    existing mappings between SCADE Suite and SCADE Display are not considered.

    Rationale: Although the proxy considers a single instance of each
    graphical panel, the current design allows several instances of SCADE
    root operators. The mapping cannot be applied.

Usage
-----

The wrapper generates the file ``sdy_xxx.py`` where ``xxx`` is the name of the
module generated for SCADE Suite. This file defines one global variable
``sdy_yyy`` per graphical panel ``Yyy`` with the following members:

* ``reset()``: Reset the graphical panel, automatically called when the Python
  module is imported
* ``draw()``: Render the image
* ``lockio()``: Lock the contexts before accessing any I/O
* ``unlockio()``: Release the lock on the contexts
* ``cancelled() -> bool``: Return ``True`` when the window is closed
* One member per layer in the graphical panels, corresponding to the contexts:
  The name of the variable is the name of the layer.

The type of these contexts **must be written manually** in a file called
``usr_xxx.py``.
The class defining these contexts must inherit from ``SdyLayer``, defined in
the ``sdyproxy.py`` resource file and must be named ``XxxLayer``, where ``Xxx``
is the name of the corresponding layer.

Example
-------

Consider a SCADE Suite project ``application.etp`` containing a
SCADE Display project with a graphical specification ``Panel.sgfx`` defining
a layer ``Symbology`` with the following interface:

.. vale off

======== ====
Variable Type
======== ====
active   bool
speed    float64
======== ====

.. vale on

SCADE KCG Display generates the following C context:

.. code:: c

   /* Context type */
   typedef struct SDY1_Panel_typ_Symbology_ {
     /* ------------------------- inputs --------------------------- */
     SGLbool active;
     SGLdouble speed;
   } SDY1_Panel_typ_Symbology;

You must provide the corresponding Python structure in ``usr_application.py``:

.. code::

   import ctypes
   from sdyproxy import SdyLayer
   class SymbologyLayer(SdyLayer):
       _fields_ = [
           ('active', ctypes.c_uint8),  # provide the C type corresponding to SGLbool
           ('speed', ctypes.c_double),
       ]

.. Note::

   No consistency check is performed between the structure you define and the
   one generated by SCADE Display KCG.

The Python code to access the graphical panel is rather straightforward:

.. code::

   from sdy_application import sdy_panel
   ...
   # run until the window is closed
   while not sdy_panel.cancelled():
       ...
       active = True
       speed = 42
       ...
       # update the display
       sdy_panel.lockio()
       sdy_panel.Symbology.active = active
       sdy_panel.Symbology.speed = speed
       sdy_panel.unlockio()
       sdy_panel.draw()
       ...