User:Mxttie: Difference between revisions

Latest revision as of 20:37, 8 May 2011

Developing my first plasmoid

These are my personal findings in creating my first plasmoid. I plan on integrating these bits in the appropiate pages.

Learn by example

Existing plasmoids can be found in the following places:

Plasma widgets which you can use to build your plasmoid UI:

http://projects.kde.org/projects/kde/kdelibs/repository/revisions/master/show/plasma/widgets

Other intesting plasma sources:

http://projects.kde.org/projects/kde/kdebase/kde-runtime/repository

When using OpenSSL

You have to remove the FindOpenSSL cmake module supplied by KDE libs which is superseded now by the Cmake provided one. The KDE one does not link against the crypto lib.

Adding custom SVG content to your plasmoid

Normally, relative paths are used to point to items from the current desktop theme. When you have custom content that's not part of any theme yet, you can supply it with your plasmoid by installing it in the default desktop theme.

In Cmake language this translates to: install(FILES "analog_telemeter.svgz"

  DESTINATION ${DATA_INSTALL_DIR}/desktoptheme/default/widgets/ )

I discovered this by looking at the cmake files of desktop themes. Desktop themes are found in KDE/kdeartwork/desktopthemes , except for oxygen, which can be found at KDE/kdebase/runtime/desktoptheme/oxygen. DATA_INSTALL_DIR translates for example to /usr/share/kde4/apps.

A desktop theme can support your plasmoid by supplying a file with the same name. If it is not found, there is a fallback to the default theme.

Adding configuration

//todo tell something about setConfigurationRequired

The Applet class has a config() method which returns a KConfigGroup. There is a tutorial explaining the KConfig basics but here we'll explain the basics needed to persist your plasmoid settings.

Config dialog

The easiest thing to do, is create your gui using the gui designer. Add this form to your build file: kde4_add_ui_files(telemeter_SRCS telemeterConfig.ui)

Override the createConfigurationInterface(KConfigDialog *parent) method where you initialise your gui fields with the in-memory values (normally previously read from disk). You'll also want to map the accepted() signal from the KConfigDialog parent to some local slot which persists the new settings. In the end, add your form to the KConfigDialog: parent->addPage(uiConfig, i18n("General"), icon());

Enable the config gui by setHasConfigurationInterface(true) during construction.

Writing settings

KConfigGroup cfg = config(); config.writeEntry("login", m_login); Don't forget to emit configNeedsSaving() as it hints to the corona to persist your settings. This may not happen immediately but definitely at destruction time. It can also compress config changed events to minimize disk I/O hence battery drain. Never call sync() yourself!

Reading settings

KConfigGroup config = config(); m_login = config.readEntry("login", ""); Settings should not be read in the constructor, but in the init() method.

Adding an icon

This icon will be used to identify your plasmoid in the widget browser.

Read this blog post on the naming convention which are to be used for icons and how to add them to your cmake build file. Don't forget to use the correct cmake install prefix or the icons will not show up!

Taking security constraints into account

Excerpt from KDE/kdebase/workspace/plasma/design/security:

Each plasmoid's .desktop file must list what features the plasmoid requires, and be kept up to date with the code. X-Plasma-Requires-<feature> can be set to Required, Unused, or Optional. Example: X-Plasma-Requires-FileDialog=Required

Internationalization

You can read anything your heart desires to know about i18n in this section

Packaging and deploying

//todo [02:09] <aseigo> look in kdesdk/scripts/createtarball .. it has everythign you need :)

@@ Line 1: / Line 1: @@
 == Developing my first plasmoid ==
+These are my personal findings in creating my first plasmoid. I plan on integrating these bits in the appropiate pages.
 === Learn by example ===
 Existing plasmoids can be found in the following places:
-* http://websvn.kde.org/trunk/KDE/kdebase/workspace/plasma/
+* https://projects.kde.org/projects/kde/kdebase/kde-workspace/repository/revisions/master/show/plasma
-* http://websvn.kde.org/trunk/KDE/kdeexamples/plasma/
+* http://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma
-* http://websvn.kde.org/trunk/KDE/kdebase/apps/plasma/
+* https://projects.kde.org/projects/kde/kdebase/kde-baseapps/repository/revisions/master/show/plasma/applets
+* http://projects.kde.org/projects/kde/kdeplasma-addons/repository/revisions/master/show/applets
 Plasma widgets which you can use to build your plasmoid UI:
-* http://websvn.kde.org/trunk/KDE/kdelibs/plasma/widgets/
+* http://projects.kde.org/projects/kde/kdelibs/repository/revisions/master/show/plasma/widgets
 Other intesting plasma sources:
-* http://websvn.kde.org/trunk/KDE/kdebase/runtime/plasma/
+* http://projects.kde.org/projects/kde/kdebase/kde-runtime/repository
 === When using OpenSSL ===
@@ Line 31: / Line 34: @@
 === Adding configuration ===
-The Applet class has a '''config()''' method which returns a '''KConfigGroup'''. There is a [http://techbase.kde.org/Development/Tutorials/KConfig tutorial] explaining the KConfig basics but here we explain the plasma KConfig basics. :)
+//todo tell something about setConfigurationRequired
+The Applet class has a '''config()''' method which returns a '''KConfigGroup'''. There is a [http://techbase.kde.org/Development/Tutorials/KConfig tutorial] explaining the KConfig basics but here we'll explain the basics needed to persist your plasmoid settings.
+==== Config dialog ====
 The easiest thing to do, is create your gui using the gui designer. Add this form to your build file:
 <code bash>kde4_add_ui_files(telemeter_SRCS telemeterConfig.ui)</code>
@@ Line 42: / Line 49: @@
 </code>
-Writing settings is as easy as:
+Enable the config gui by '''setHasConfigurationInterface(true)''' during construction.
+==== Writing settings ====
 <code cppqt>
-KConfigGroup config = this->config();
+KConfigGroup cfg = config();
 config.writeEntry("login", m_login);
 </code>
+Don't forget to
+<code cppqt>
+emit configNeedsSaving()
+</code>
+as it hints to the corona to persist your settings. This may not happen immediately but definitely at destruction time. It can also compress config changed events to minimize disk I/O hence battery drain. Never call <tt>sync()</tt> yourself!
-Reading:
+==== Reading settings ====
 <code cppqt>
-KConfigGroup config = this->config();
+KConfigGroup config = config();
 m_login = config.readEntry("login", "");
 </code>
+Settings should not be read in the constructor, but in the <tt>init()</tt> method.
-Enable your plasma config gui by '''setHasConfigurationInterface(true)''' during construction.
+=== Adding an icon ===
+This icon will be used to identify your plasmoid in the widget browser.
+Read [http://blog.urbylog.info/2010/01/plasma-applet-development-adding-icons.html this blog post] on the naming convention which are to be used for icons and how to add them to your cmake build file. Don't forget to use the correct cmake install prefix or the icons will not show up!
+=== Taking security constraints into account ===
+Excerpt from <tt>[http://websvn.kde.org/trunk/KDE/kdebase/workspace/plasma/design/security?view=markup KDE/kdebase/workspace/plasma/design/security]</tt>:
+Each plasmoid's .desktop file must list what features the plasmoid requires, and be kept up to date with the code. X-Plasma-Requires-<feature> can be set to Required, Unused, or Optional. Example: X-Plasma-Requires-FileDialog=Required
 === Internationalization ===
@@ Line 60: / Line 83: @@
 === Packaging and deploying ===
+//todo
 [02:09] <aseigo> look in kdesdk/scripts/createtarball .. it has everythign you need :)