How to create your own gui plugin

Every plugin consits of:

• a subclass of ArmarXGuiPlugin
• a subclass of ArmarXComponentWidgetController (with Ice functionality) or ArmarXWidgetController (without Ice functionality)
• a Qt .ui file containing the Gui layout
• an optional .ui file containing a configuration dialog

All required files should be generated using the armarx-package tool in the following way (execute this command in the toplevel directory of your package):

    armarx-package add gui-plugin MyGuiPlugin

This is an exemplary header file (MyGuiPlugin.h) for a custom ArmarXGuiPlugin subclass :

#ifndef ARMARX_MY_GUI_PLUGIN_H
#define ARMARX_MY_GUI_PLUGIN_H
 
#include "MyWidgetController.h"
 
#include <Gui/libraries/ArmarXGuiBase/ArmarXGuiPlugin.h>
 
namespace armarx
{
    // The plugin definition
    class MyGuiPlugin :
        public ArmarXGuiPlugin
    {
    public:
        // add all widget controllers contained in the plugin in the constructor
        // each entry will appear as a separate widget in the 'Add Widget' menu of ArmarXGui
        MyGuiPlugin()
        {
            addWidget<MyWidgetController>();
        }
 
        // return the name of the plugin
        // this has to be a unique name amongst all plugins
        QString getPluginName()
        {
            return "MyGuiPlugin";
        }
    };
}
 
// ****
// IMPORTANT: Use this QT macro to register your plugin
// ****
Q_EXPORT_PLUGIN2(armarx_gui_MyGuiPlugin, MyGuiPlugin)
 
#endif

This is an exemplary header file (MyGuiPluginWidgetController.h)for a custom ArmarXComponentWidgetController subclass :

#ifndef _ARMARX_MYPACKAGE_MyGuiPlugin_WidgetController_H
#define _ARMARX_MYPACKAGE_MyGuiPlugin_WidgetController_H
 
// This file is created from your custom Qt-widget UI file that you have built with Qt-Designer or Qt-Creator
// this file is generated from MyGuiPlugin.ui
// .ui files are created using QtDesigner or QtCreator and describe the layout of a widget
#include "ui_MyGuiPluginWidget.h"
// This is an optional config dialog, which can be omitted
#include "ui_MyConfigDialog.h"
 
#include <Gui/libraries/ArmarXGuiBase/ArmarXGuiPlugin.h>
#include <Gui/libraries/ArmarXGuiBase/ArmarXComponentWidgetController.h>
 
#include <QtGui/QMainWindow>
#include <memory>
 
// Only needed if you intend to offer 3D visualization data
#include <Inventor/nodes/SoNode.h>
 
 
// use a different namespace here depending on the armarx package the plugin belongs to
// such as memoryx or visionx
namespace armarx
{
    // The widget controller
    class MyGuiPluginWidgetController :
        public armarx::ArmarXComponentWidgetController
    {
        Q_OBJECT
    public:
        explicit MyGuiPluginWidgetController();
        virtual ~MyGuiPluginWidgetController() {}
 
        // inherited from armarx::Component
        // implement you custom startup, connect and exit code here
        virtual void onInitComponent();
        virtual void onConnectComponent();
        virtual void onExitComponent();
 
        // inherited of ArmarXWidget
        virtual QString getWidgetName() const
        {
            return "MyWidgetController";
        }
 
        // You may want to offer GUI save/load functionality.
        // If not, you can leave these methods empty.
        virtual void loadSettings(QSettings * settings);
        virtual void saveSettings(QSettings * settings);
 
        // Each Gui widget can be configured when it is instantiated.
        // A custom initialization dialog can be implemented here.
        // Have a look at existing plugins on how to realize a config dialog.
        // If no custom implementation is provided by your widget, a standard config dialog is offered by ArmarXGui.
        virtual QPointer<QDialog> getConfigDialog(QWidget* parent = 0);
 
        // This method is called by the framework when your custom config dialog is closed with OK.
        // Now you can read the parameters from your custom dialog.
        virtual void configured();
 
        // If this widget offers a 3D model you have to implement this method and
        // return the SoNode containing the 3D model.
        virtual SoNode* getScene();
 
    signals:
 
        // you may want to specify custom Qt signal methods here
        // void updateData();
 
 
    public slots:
 
        // you may want to specify custom Qt slots methods here
        // don't forget to connect them in onConnectComponent()
        // e.g.  connect(ui.myButton, SIGNAL(clicked()), this, SLOT(myButtonPressed()));
        // void myButtonPressed();
 
    private:
 
        // the ui object comes from your Qt-UI widget "ui_MyGuiPluginWidget.h"
        // PLEASE NOTE: the toplevel widget in this file needs to be named MyGuiPluginWidget
        // otherwise this line will fail to compile
        Ui::MyGuiPluginWidget widget;
 
        // optional config dialog
        QPointer<MyConfigDialog> dialog;
 
        const std::string DEFAULT_SETTINGS_PLUGIN_NAME;
        const std::string DEFAULT_SETTINGS_CUSTOM_TEXT;
    };
}
 
#endif

The corresponding cpp file (MyGuiPluginWidgetController.cpp) :

#include "MyGuiPluginWidgetController.h"
 
// Qt and other includes are skipped here
 
namespace armarx
{
 
    MyGuiPluginWidgetController::MyWidgetController() :
        DEFAULT_SETTINGS_PLUGIN_NAME("MyGuiPlugin"),
        DEFAULT_SETTINGS_CUSTOM_TEXT("custom text")
    {
        // init gui
        // getWidget() returns a container into which this widget is embedded
        widget.setupUi(getWidget());
        ARMARX_INFO << " setup of ui finished" << flush;
    }
 
    void MyGuiPluginWidgetController::onInitComponent()
    {
        ARMARX_INFO << "Init MyWidgetController " << flush;
 
        // if you want to use proxies you can specify them here
        //usingProxy(myProxyName);
    }
 
    void MyGuiPluginWidgetController::onConnectComponent()
    {
        // if you have a button named myButton in your widget you have to connect it here
        //connect(ui.myButton, SIGNAL(clicked()), this, SLOT(myButtonPressed()));
 
        // if you want to listen on topics you can specify them here
        //usingTopic(myTopicName);
    }
 
    void MyGuiPluginWidgetController::onExitComponent()
    {
        // implement cleanup
    }
 
    QPointer<QDialog> MyGuiPluginWidgetController::getConfigDialog(QWidget* parent)
    {
        if (!dialog)
        {
            dialog = new MyConfigDialog(parent);
            // set standard values (we assume here that the two Qt QLineEdits editMyGuiName and editCustomText are defined in config widget)
            dialog->ui->editMyGuiName->setText(QString::fromStdString(DEFAULT_SETTINGS_PLUGIN_NAME));
            dialog->ui->editCustomText->setText(QString::fromStdString(DEFAULT_SETTINGS_CUSTOM_TEXT));
        }
        return qobject_cast<MyConfigDialog*>(dialog);
    }
 
    void MyGuiPluginWidgetController::configured()
    {
        ARMARX_VERBOSE << "MyWidgetController::configured()";
 
        // read user data from config dialog
        // assumes that the ui of the dialog contains two fields with the name
        // editCustomText and editMyGuiName
        std::string customText = dialog->ui->editCustomText->text().toStdString();
        this->setInstanceName(dialog->ui->editMyGuiName->text());
    }
 
 
    void MyGuiPluginWidgetController::loadSettings(QSettings* settings)
    {
        // Qt-based settings loading
        std::string customText = settings->value("CustomText", QString::fromStdString(myCustomTextVariable)).toString().toStdString();
    }
 
    void MyGuiPluginWidgetController::saveSettings(QSettings* settings)
    {
        // Qt-based settings saving
        settings->setValue("CustomText", QString::fromStdString(myCustomTextVariable));
    }
 
 
    SoNode* MyGuiPluginWidgetController::getScene()
    {
        // if widgte offers a 3d model it has to be returned here, otherwise this method shouldn't be implemented
        return myOpenInventorModel;
    }
 
    void MyGuiPluginWidgetController::myButtonPressed()
    {
        ARMARX_INFO << "Button pressed" << flush;
    }
}

A CMakeLists.txt file to compile this gui plugin:

armarx_set_target("MyGuiPlugin")
 
# Qt
find_package(Qt4 COMPONENTS QtCore QtGui QtOpenGL QUIET)
 
# Eigen
find_package(Eigen3 QUIET)
 
# VirtualRobot (adds dependencies to Coin3D and SoQt)
find_package(Simox 2.1.5 QUIET)
 
armarx_build_if(ArmarXGui_FOUND "ArmarXGui not available")
armarx_build_if(QT_FOUND "Qt not available")
armarx_build_if(QT_QTOPENGL_FOUND "QtOpenGL not available")
armarx_build_if(Eigen3_FOUND "Eigen3 not available")
armarx_build_if(Simox_FOUND "VirtualRobot not available")
 
if (QT_FOUND AND Eigen3_FOUND AND Simox_FOUND)
    include(${QT_USE_FILE})
 
    include_directories(
        ${Eigen3_INCLUDE_DIRS}
        ${Simox_INCLUDE_DIRS})
endif()
 
# MyConfigDialog.cpp is optional
set(SOURCES
    MyGuiPluginWidgetController.cpp
    MyConfigDialog.cpp
)
 
# MyConfigDialog.h is optional
set(HEADERS
    MyGuiPlugin.h
    MyGuiPluginWidgetController.h
    MyConfigDialog.h
)
 
# MyConfigDialog.h is optional
set(GUI_MOC_HDRS
    MyGuiPlugin.h
    MyGuiPluginWidgetController.h
    MyConfigDialog.h
)
 
# generates ui_MyGuiPlugin.h
# MyConfigDialog.ui is optional
set(GUI_UIS
    MyGuiPluginWidget.ui
    MyConfigDialog.ui
)
 
# You may want to add more libraries here
set(COMPONENT_LIBS ArmarXInterfaces ArmarXGuiBase ArmarXCore ${QT_LIBRARIES} ${Simox_LIBRARIES})
 
set(LIB_VERSION    0.1.0)
set(LIB_SOVERSION  0)
 
# The armarx_gui_library function builds your plugin
# It is made available by adding 'depends_on_armarx_package(ArmarXGui)' in the toplevel CMakeLists.txt
if (ArmarXGui_FOUND)
    armarx_gui_library(MyGuiPlugin "${SOURCES}" "${GUI_MOC_HDRS}" "${GUI_UIS}" "" "${COMPONENT_LIBS}" "${LIB_VERSION}" "${LIB_SOVERSION}")
endif()

To add proper documentation for your gui plugin, create a doxygen page in your MyGuiPluginWidgetController.h:

namespace armarx
{
    /**
    * \page ${PACKAGENAME}-GuiPlugins-MyGuiPlugin MyGuiPlugin
    * \brief The MyGuiPlugin allows you to ...
    *
    * \image html MyGuiPlugin.png
    *
    * This is a detailled description of the MyGuiPlugin
    * gui plugin. It is very awesome.
    *
    * \see MyGuiPluginGuiPlugin
    */
...
}

and add it as subpage to ${PACKAGENAME}/etc/doxygen/pages/GuiPlugins.dox:

\subpage ${PACKAGENAME}-GuiPlugins-MyGuiPlugin "MyGuiPlugin"

Images (e.g. a screenshot of the widget) go to ${PACKAGENAME}/etc/doxygen/images/.

Note

All network calls (e.g. with Ice) should be in a seperate thread like armarx::RunningTask, armarx::PeriodicTask or QThread since they can take a long time to complete and block the complete GUI if executed in the qt main-event-loop. QTimer or timerEvent(QTimerEvent) are running in the same thread as the main application loop, so they are not suitable for network calls. Especially periodic network calls like updating data should be in a seperate thread.