How to create panel plugin

Adys edited this page Jan 18, 2013 · 8 revisions

##Some theory

Plugin for the panel is a library written on C++. One more necessary thing is a .desktop file describing this plugin. The same may be additional files, like translations. Themselves plugins will be installed to /usr/local/lib/razor-panel or /usr/lib/razor-panel (dependent on cmake option -DCMAKE_INSTALL_PREFIX). Desktop files are installed to /usr/local/share/razor/razor-panel, translations to /usr/local/share/razor/razor-panel/PLUGIN_NAME.

To build, you need the source tree, the latest version can be downloaded from the GIT git clone git://github.com/Razor-qt/razor-qt.git or as an archive from here. Source plugins for the panel are located in the subdirectories of razorqt-panel.

Let's write a simple plugin - helloworld. Create a directory razorqt-panel/plugin-helloworld. Cmake project cannot have two sub-project with the same name, and one sub-project helloworld is already there, so we have to use weird "panelhelloworld".

##CMake. Copy CMakeLists.txt from the "clock" plugin, and change it:

cmake_minimum_required(VERSION 2.6)

set(PLUGIN "panelhelloworld")

set(HEADERS
    razorhelloworld.h
)

set(SOURCES
    razorhelloworld.cpp
)

set(MOCS
    razorhelloworld.h
)

set(UIS
)

#*******************************************
include ("../BuildPlugin.cmake")
BUILD_RAZOR_PLUGIN(${PLUGIN})

And add our plugin into the overall build system. To do this, add a few lines to the razorqt-panel/CMakeLists.txt

...
# *******************************************************************
# What plugins will be built, by default.
# You can enable/disable building of the plugin using cmake options.
#    cmake -DCLOCK_PLUGIN=Yes .. # Enable clock plugin
#    cmake -DCLOCK_PLUGIN=No ..  # Disable clock plugin

...
setByDefault(HELLOWORLD_PLUGIN Yes)
# *******************************************************************
...
if (HELLOWORLD_PLUGIN)
    set(ENABLED_PLUGINS ${ENABLED_PLUGINS}   "HelloWorld")
    add_subdirectory(plugin-helloworld)
endif (HELLOWORLD_PLUGIN)

##Desktop file. To display a list of available plugins, the panel need to know what plugins are installed and how they are called. To do this, each plugin provides the .desktop file with description. Again for a basis we take the file from the clock. We create a subdirectory of razorqt-panel/plugin-helloworld/resources and copy the desktop-file as panelhelloworld.desktop, and bring it to mind:

[Desktop Entry]
Type=Service
ServiceTypes=RazorPanel/Plugin
Name=Hello World
Comment=A "hello world" plugin.

Code.

Finally it came to code. Plugin - is class inherited from RazorPanelPlugin. Which inherited from QWidget. Create 2 files - razorhelloworld.h and razorhelloworld.cpp. They are not large so I cite them completely.

razorqt-panel/plugin-helloworld/razorhelloworld.h
    01 /* BEGIN_COMMON_COPYRIGHT_HEADER
    02  * (c)LGPL2+
    03  *
    04  * Razor - a lightweight, Qt based, desktop toolset
    05  * http://razor-qt.org
    06  *
    07  * Copyright: 2012 Razor team
    08  * Authors:
    09  *   Alexander Sokoloff <sokoloff.a@gmail.com>
    10  *
    11  * This program or library is free software; you can redistribute it
    12  * and/or modify it under the terms of the GNU Lesser General Public
    13  * License as published by the Free Software Foundation; either
    14  * version 2.1 of the License, or (at your option) any later version.
    15  *
    16  * This library is distributed in the hope that it will be useful,
    17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    19  * Lesser General Public License for more details.
    20  *
    21  * You should have received a copy of the GNU Lesser General
    22  * Public License along with this library; if not, write to the
    23  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    24  * Boston, MA 02110-1301 USA
    25  *
    26  * END_COMMON_COPYRIGHT_HEADER */
    27
    28 #ifndef RAZORHELLOWORLD_H
    29 #define RAZORHELLOWORLD_H
    30
    31 #include "../panel/razorpanelplugin.h"
    32 #include <QtGui/QPushButton>
    33
    34 class RazorHelloWorld : public RazorPanelPlugin
    35 {
    36    Q_OBJECT
    37 public:
    38     RazorHelloWorld(const RazorPanelPluginStartInfo* startInfo, QWidget* parent = 0);
    39     ~RazorHelloWorld();
    40
    41     virtual RazorPanelPlugin::Flags flags() const { return PreferRightAlignment; }
    42
    43 private slots:
    44     void showMessage();
    45 
    46 private:
    47     QPushButton mButton;
    48 };
    49
    50 EXPORT_RAZOR_PANEL_PLUGIN_H
    51
    52 #endif // RAZORHELLOWORLD_H
razorqt-panel/plugin-helloworld/razorhelloworld.cpp

    01 /* BEGIN_COMMON_COPYRIGHT_HEADER
    02  * (c)LGPL2+
    03  *
    04  * Razor - a lightweight, Qt based, desktop toolset
    05  * http://razor-qt.org
    06  *
    07  * Copyright: 2012 Razor team
    08  * Authors:
    09  *   Alexander Sokoloff <sokoloff.a@gmail.com>
    10  *
    11  * This program or library is free software; you can redistribute it
    12  * and/or modify it under the terms of the GNU Lesser General Public
    13  * License as published by the Free Software Foundation; either
    14  * version 2.1 of the License, or (at your option) any later version.
    15  *
    16  * This library is distributed in the hope that it will be useful,
    17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    19  * Lesser General Public License for more details.
    20  *
    21  * You should have received a copy of the GNU Lesser General
    22  * Public License along with this library; if not, write to the
    23  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    24  * Boston, MA 02110-1301 USA
    25  *
    26  * END_COMMON_COPYRIGHT_HEADER */
    27
    28 #include "razorhelloworld.h"
    29 #include <QtGui/QMessageBox>
    30 
    31 EXPORT_RAZOR_PANEL_PLUGIN_CPP(RazorHelloWorld)
    32 
    33 RazorHelloWorld::RazorHelloWorld(const RazorPanelPluginStartInfo* startInfo, QWidget* parent):
    34     RazorPanelPlugin(startInfo, parent)
    35 {
    36     setObjectName("HelloWorld");
    37 
    38     mButton.setText(tr("HW"));
    39     addWidget(&mButton);
    40     connect(&mButton, SIGNAL(clicked()), this, SLOT(showMessage()));
    41 }

    42 RazorHelloWorld::~RazorHelloWorld()
    43 {
    44 }

    45 void RazorHelloWorld::showMessage()
    46 {
    47     QMessageBox::information(0, tr("Panel"), tr("Hello, World!"));
    48 }

The first 26 lines - the license, it's preferable to use LGPL2+ as the most liberal of the GPL.

Line 31 in the .H file - Including a header file RazorPanelPlugin.

Constructor (lines 32 in the .H and 33-34 in the .CPP) - you do not have to worry about the parameters, RazorPanelPlugin process the parameters yourself.

Be sure to specify the ObjectName for the plugin (line 36 in the .CPP), it is used in the theme engine.

An interesting function is Flags (41 .H), it returns a set of flags for your plugin, now there are only 2 of the flag:

  • PreferRightAlignment - when a user adds a plugin to the panel, it can be added, or left or right. This flag is used only when the plugin is add to the pael. Later the user settings will be used. Most likely you need to set it.

  • HaveConfigDialog - plug-in has a settings dialog, in this tutorial we don't have it.

Building

At the root of the source tree we create a directory for building. Go into it and run cmake.

$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug ..

Run building and instalation:

$ make && sudo make install

You can check the plugin by running a new panel and specify a separate configuration file (the panel will automatically create it):

$ razor-panel testplugin

The panel will be empty and thin, do not overlook it. You can add the plugin via popup menu and enjoy :)


These pages may be useful: