KaptureControlGui/KCG/Documentation/source/Dev/widgets.rst

New Widgets
===========

KCG is written in Python using PyQt4. Therefore all Widgets are and have to be written in Python with PyQt4 for the
Gui toolkit.

Creating Widgets
----------------

The following things are mandatory:

    * A widget has to be defined in it's own class in it's own seperate module (file).
    * The class for the widget has to be derived from base.kcgwidget.KCGWidgets.
    * The __init__ method has to set self.par from `parent` parameter and self.id from `unique_id` parameter. It also has to call the KCGWidgets __init__ method. See :ref:`here <exampleInit>`.
    * The module has to contain the variable __widget_id__ that is initially set to `None`
    * The module has to contain a function to add the widget to the MultiWidget area as described :ref:`here <add_widget_function>`.
    * The class has to override the method closeEvent(...). See :ref:`here <closeEvent>`.
    * The module has to ``import base.kcgwidget as kcgw``


.. note:: To activate a widget it has to be placed into the widget subfolder and the module name has to be added to the __all__
    variable in the file ``__init__.py`` in the widget folder.


To register a widget this line is needed:

.. code:: python

    kcgw.register_widget(QtGui.QIcon("path/to/icon"), "Name of Widget", addWidgetFunction, "Ctrl+e")

Substitute ``"path/to/icon"``, ``"Name of Widget"``, ``addWidgetFunction`` (see :ref:`add_widget_function`) and ``"Ctrl+e"`` with
appropriate values. For ``kcgw.register_widget()`` refer to the :ref:`kcgwidget module <kcgwidget_register_widget>`.

.. note:: Collision of keyboard shortcuts is not handled by the gui.

If a widget is activated and registered it will automatically be imported and the correct steps to integrate the widget are performed.


.. hint:: Because every widget is derived from base.kcgwidget.KCGWidgets the helper methods defined :ref:`here <kcgwidgets_helper_methods>`
    can be used.


.. _exampleInit:

Minimal __init__
~~~~~~~~~~~~~~~~

Assume: Widget class is called `ExampleWidget`

.. code:: python

    def __init__(self, unique_id, parent):
        super(ExampleWidget, self).__init__()
        self.id = unique_id
        self.par = parent

.. _add_widget_function:

Function to add a widget
~~~~~~~~~~~~~~~~~~~~~~~~

Assume: base.kcgwiget is imported as kcgw

.. code:: python

    def addNewWidget():
        global __widget_id__
        if __widget_id__:
            kcgw.area.widgets[__widget_id__].setFocus()
        else:
            nid = kcgw.idg.genid()
            __widget_id__ = nid
            w = acquireSettings(nid, kcgw.area)
            kcgw.area.newWidget(w, "NewWidgetName", nid, widget_type=NewWidgetType_as_int, minSize=True)


.. note:: It is highly recommended to use this function as is (with adjustments to the function name, ``NewWidgetName``
 and ``NewWidgetType_as_int``). For ``newWidget(..)`` see :ref:`here <newWidget>`.

.. _closeEvent:

closeEvent method
~~~~~~~~~~~~~~~~~

.. code:: python

    def closeEvent(self, event):
        global __widget_id__
        __widget_id__ = None
        del self.par.widgets[self.id]

This is a minimal construct that has to be present in a widget class.

Interface to the GUI
--------------------

Sometimes elements (e.g. Buttons) have to be disabled at certain points. To group elements you can make use of the
groupelements module.

See :ref:`groupedelements`.

Following is a list of used groups that will be activated and disabled at certain points in runtime:

    * **after_start**: Elements in this group get enabled after board is started
    * **continuous_read**: Elements in this group get enabled when a continuous read is possible
    * **synchronize**: Elements in this group get enabled when the board is calibrated
    * **set_defaults**: Elements in this group get enabled when the board is synchronized
    * **timing**: Elements in this group get enabled when defaults are set

.. caution:: Be careful when using one of this groups, as the names may mislead their point of activation.


Interface to the board
----------------------

It is recommended to use the :ref:`backendinterface` to interface with the board

Example Widget
--------------

This is a minimal example implementation of a widget.

.. code:: python

    from PyQt4 import QtGui

    import base.kcgwidget as kcgw

    __widget_id__ = None

    class exampleWidget(kcgw.KCGWidgets):
        def __init__(self, unique_id, parent):
            super(exampleWidget, self).__init__()

            self.id = unique_id
            self.par = parent

            self.layout = QtGui.QHBoxLayout()
            self.setLayout(self.layout)

            self.button1 = self.createButton("Button 1", connect=self.pressed)
            self.button2 = self.createButton("Button 2", connect=self.pressed)

            self.layout.addWidget(self.button1)
            self.layout.addWidget(self.button2)

            self.setWindowTitle("Example Widget")

        def pressed(self):
            print 'Pressed'

        def closeEvent(self, event):
            global __widget_id__
            __widget_id__ = None
            del self.par.widgets[self.id]

    def addExampleWidget():
        global __widget_id__
        if __widget_id__:
            kcgw.area.widgets[__widget_id__].setFocus()
        else:
            nid = kcgw.idg.genid()
            __widget_id__ = nid
            w = exampleWidget(nid, kcgw.area)
            kcgw.area.newWidget(w, "Example Widget", nid, widget_type=4)

    kcgw.register_widget(QtGui.QIcon("icons/project.svg"), "Example Widget", addExampleWidget, "Ctrl+e")

Screenshot:

.. image:: _static/example_widget.png

.. caution:: Be careful when refering to this as this is a screenshot made with kde5 and PyQt4.
        The design of the actual widget may vary between different desktop environments.