How to write the panel plugin - Razor-qt/razor-qt GitHub Wiki
This is a draft for new panel API!!!
Now panel has a different API, please see How-to-create-panel-plugin for more information.
##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 plugin that will remind us that it is time to have a cup of tea. The plugin will be called teatime. Create a directory razorqt-panel/plugin-teatime.
##CMake. Copy CMakeLists.txt from the "clock" plugin, and change it:
cmake_minimum_required(VERSION 2.6)
set(PLUGIN "teatime")
set(HEADERS
teatimeplugin.h
)
set(SOURCES
teatimeplugin.cpp
)
set(MOCS
teatimeplugin.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(TEATIME_PLUGIN Yes)
# *******************************************************************
...
if (TEATIME_PLUGIN)
set(ENABLED_PLUGINS ${ENABLED_PLUGINS} "Tea time")
add_subdirectory(plugin-teatime)
endif (TEATIME_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-teatime/resources and copy the desktop.in-file as teatime.desktop.in, and bring it to mind:
[Desktop Entry]
Type=Service
ServiceTypes=RazorPanel/Plugin
Name=Tea Time
Comment=A time to have a cup of tea reminder.
Code.
Finally it came to code. We must to wite 2 classes:
- Plugin proper, the class inherited from IRazorPanelPlugin
- It's loader - class inherited from IRazorPanelPluginLibrary.
This is a skeleton of our plugin, it's not large so I cite code completely. To make your own plugin, implement the functions themeId(), flags() and widget().
razorqt-panel/plugin-helloworld/teatimeplugin.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 <[email protected]>
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 TEATIMEPLUGIN_H
29 #define TEATIMEPLUGIN_H
30
31 #include "../panel/irazorpanelplugin.h"
32 #include <QtGui/QToolButton>
33
34 class TeaTimePlugin: public QObject, public IRazorPanelPlugin
35 {
36 Q_OBJECT
37 public:
38 TeaTimePlugin(const IRazorPanelPluginStartupInfo &startupInfo);
39
40 virtual QWidget *widget();
41 virtual QString themeId() const { return "TeaTime"; }
42 virtual IRazorPanelPlugin::Flags flags() const { return PreferRightAlignment; }
43
44 private:
45 QToolButton mButton;
46 };
47
48 class TeaTimePluginLibrary: public QObject, public IRazorPanelPluginLibrary
49 {
50 Q_OBJECT
51 Q_INTERFACES(IRazorPanelPluginLibrary)
52 public:
53 IRazorPanelPlugin *instance(const IRazorPanelPluginStartupInfo &startupInfo)
54 {
55 return new TeaTimePlugin(startupInfo);
56 }
57 };
58
59 #endif // TEATIMEPLUGIN_H
razorqt-panel/plugin-helloworld/teatimeplugin.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 <[email protected]>
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 "teatimeplugin.h"
29 #include <QtGui/QMessageBox>
30
31 Q_EXPORT_PLUGIN2(teatime, TeaTimePluginLibrary)
32
33 TeaTimePlugin::TeaTimePlugin(const IRazorPanelPluginStartupInfo &startupInfo):
34 QObject(),
35 IRazorPanelPlugin(startupInfo)
36 {
37 mButton.setText("Tea");
38 connect(&mButton, SIGNAL(clicked()), this, SLOT(showMessage()));
39 }
40
41 QWidget *TeaTimePlugin::widget()
42 {
43 return &mButton;
44 }
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 IRazorPanelPlugin.
Constructor (lines 38 in the .H and 33-35 in the .CPP) - you do not have to worry about the parameters, IRazorPanelPlugin process the parameters yourself.
From users point of view plugin is a some visual widget on the panel. The widget() method retuns pointer to it. In the our case it's a QToolButton (line 40 in the .H and 41-44 in the .CPP). This method called only once, so you are free to return pointer on class member, or create widget on the fly.
The themeId() (line 41 in the .H) returns the string that is used in the theme QSS file. Theme author may write something like #TeaTime { border: 1px solid red; } to set custom border for the TeaTime plugin.
An interesting function is flags() (42 .H), it returns a set of flags for your plugin, for now there are only 2 flags:
- PreferRightAlignment - when a user adds a plugin to the panel, it can be added on the left side or on the right. This flag is used only when the plugin is added to the panel. 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.
Every plugin must has the loader. Loader (48-54 .H) is very simple class with only one method instance(). You can copy-paste code, all you should to do is change the name of the created class (53 .H).
Now our plugin do nothing, but let's build 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 :)
To be continued...
These pages may be useful: