===================
Developing Examples
===================

This section describes different examples of how to develop functionalities and add them to the taurus_pyqtgraph package.
The way of adding follows the same development guidelines as the rest of the taurus packages, so you can check the `Taurus development guidelines`_ for more information.

How to add a new action to the context menu of Plot/Trend
---------------------------------------------------------
We will see here how to add a new action to the context menu of Plot/Trend, this action will be called "Dummy Action" and will just print console message and pop up a dialog when it is clicked.

1 - First of all, you need to create a new file in the `taurus_pyqtgraph` package, for example, `dummy_feature.py`, the correct place to put it is in the `taurus_pyqtgraph` module/directory.

2 - In this file, you will need to import all the necessarry things to create your desired action.
    .. code-block:: python

        from taurus.external.qt import Qt
3 - Define a new class that will inherit from `QDialog` and implement the desired functionality. For example, you can create a dialog that will show a message when the action is clicked.

    .. code-block:: python

        class DummyTool(Qt.QAction):
            """
            This tool inserts an action in the menu of the :class:`pyqtgraph.PlotItem`.
            It pops up a dialog saying "This is a dummy feature. It does nothing."
            and it prints the same message to the console.
            """

            def __init__(self, parent=None, itemClass=None):
                super().__init__("Dummy Action", parent)
                self.parent = parent
                self.triggered.connect(self._onTriggered)
                self.plotItem = None

            def attachToPlotItem(self, plot_item, parentWidget=None):
                """
                Use this method to add this tool to a plot.

                :param plot_item: (PlotItem)
                """
                self.plotItem = plot_item
                if self.plotItem.legend is not None:
                    self.legend = self.plotItem.legend

                menu = self.plotItem.getViewBox().menu
                menu.addAction(self)
                self.setParent(parentWidget or menu)

4 - As you can see the _onTriggered methos is not implemented yet, and to implement it now we will encapsulate the logic
of the dialog on a separated class in charge of the view part. To keep it simple we will use a static method to display the dialog.
    .. code-block:: python

        class DummyToolDlg(Qt.QDialog):
        """
        Dialog to display the dummy feature message.
        This can be a complete class with more customization, but for the
        example it will be used as a static method to display the message.
        """

        @staticmethod
        def display(parent=None, data_items=None):
            dlg = DummyToolDlg(parent)
            dlg.setWindowTitle("Dummy Feature")
            dlg.setModal(True)
            dlg.resize(300, 100)
            layout = Qt.QVBoxLayout(dlg)
            label = Qt.QLabel("This is a dummy feature. It does nothing.", dlg)
            layout.addWidget(label)
            button = Qt.QPushButton("OK", dlg)
            button.clicked.connect(dlg.accept)
            layout.addWidget(button)
            dlg.setLayout(layout)
            dlg.exec_()
            print("This is a dummy feature. It does nothing.")

5 - Now we can implement the _onTriggered method to show the dialog when the action is clicked.
    .. code-block:: python

        def _onTriggered(self):
            """
            This method is called when the action is triggered.
            It will show the dialog and print a message to the console.
            """
            DummyToolDlg.display(self.parent, self.plotItem)

6 - Finally, you need to register this new action in the `__init__.py` file of the `taurus_pyqtgraph` packages so it can be loaded when the package is imported.
In this case the feature will be registered for the Plot and Trend items, so you will need to modify both files.
    .. code-block:: python

        from .dummy_feature import DummyTool

        def __init__():
            ....................
            # Register the new action
            dummy_tool = DummyTool(self)
            dummy_tool.attachToPlotItem(self.getPlotItem())
            ....................

You can see here on the following picture the result of this new action in the context menu of a PlotItem, but for the trend it will be the same.:
 .. image:: imgs/dummy_action.png
    :alt: Dummy feature action in the context menu of a PlotItem, for the trend it will be the same.



.. _Taurus development guidelines: https://taurus-scada.org/devel/coding_guide.html
