Aufmacher

Fortgeschrittenes Basteln

Plasmoiden für KDE 4 programmieren

01.10.2008 Plasmoiden erweitern den KDE-4-Desktop um sinnvolle Anwendungen. KDE-Entwickler Sebastian Kügler erklärt, wie Sie die kleinen Helfer programmieren.

In der letzten Ausgabe von LinuxUser haben Sie gelesen, was Plasmoiden sind, aus welchen Komponenten sie bestehen [1] und wie Sie eine Entwicklungsumgebung für KDE 4 aufsetzen [2]. Diesmal gehts ans Eingemachte: Sie lernen, wie Sie den KDE-Desktop um eigene Widgets bereichern. Der Artikel zeigt zunächst, aus welchen Komponenten Sie ein neues Plasmoid entwickeln und wie Sie es dann fachgerecht in KDE 4 einbetten. Der Desktop befindet sich allerdings weiterhin in der Entwicklung, so dass sich die API und das Build-System mitunter ändern. Bei Fehlermeldungen hilft unter anderem die KDE-Devel-Mailingliste [3] weiter.

Schritt für Schritt zum Plasmoid

Zur Illustration dient das Beispiel-Plasmoid "Dr. Ade", dessen Quellcode Sie auf der Heft-DVD sowie unserer Website finden [4]. Es zeigt einen Monitor, der sich einschaltet, sobald Sie einen USB-Stick einstöpseln (Abbildung 1). In einem Tooltip erscheinen weitere Informationen zum eingesteckten Stick. Sie platzieren "Dr. Ade" auf dem Desktop oder in der Fußleiste, indem Sie das Plasmoid vom Appletbrowser per Drag & Drop dorthin ziehen.

Abbildung 1

Abbildung 1: Sobald Sie einen USB-Stick in den passenden Port schieben, meldet sich das Plasmoid "Dr. Ade".

"Dr. Ade" demonstriert, wie Sie SVG-Grafiken einbinden und darin einzelne Elemente separat wiedergeben und animieren. Sie lesen zudem, wie Sie einen Konfigurationsdialog für das Plasmoid erstellen und die Konfiguration speichern.

Im Beispiel implementieren Sie das Widget in der Programmiersprache C++. Plasma unterstützt aber auch Plasmoiden in anderen Programmiersprachen wie Javascript, Ruby und Python.

Buildsystem und Co.

Beim Übersetzen und Installieren des Plasmoids spielen zwei Dateien eine Hauptrolle: plasma-drade-default.desktop und CMakeLists.txt.

Die Datei plasma-drade-default.desktop (Abbildung 2) enthält Metainformationen über das Widget. Hier tragen Sie Ihren Namen als Programmierer ein, bestimmen ein Icon für das Applet, die Lizenz sowie einige weitere Parameter. Über die installierte .desktop-Datei findet Plasma das Plasmoid später und stellt es den Anwendern über den Appletbrowser zur Verfügung.

Abbildung 2

Abbildung 2: Die "Desktop"-Datei des Plasmoids enthält die wichtigsten Eckdaten zu "Dr. Ade".

Aus der Datei CMakeLists.txt (Listing 1) erfährt das Build-System CMake, mit dem Sie den Code übersetzen, welche Dateien es kompilieren soll und in welches Verzeichnis diese jeweils gehören. Am einfachsten ist es, eine existierende Datei entsprechend anzupassen. Um sie etwa mit dem Benutzerinterface von "Dr. Ade" (dradeConfig.ui) zu übersetzen, verwenden Sie das CMake-Makro kde4_add_ui_files() aus Zeile 3. Um weitere Bibliotheken einzubinden, ergänzen Sie das Makro target_link_libraries() in der Zeile 5.

project(plasma-drade)
set(drade_SRCS drade.cpp)
kde4_add_ui_files(drade_SRCS dradeConfig.ui)
kde4_add_plugin(plasma_applet_drade ${drade_SRCS})
target_link_libraries(plasma_applet_drade plasma ${KDE4_KIO_LIBS}${KDE4_SOLID_LIBS})
install(TARGETS plasma_applet_drade DESTINATION ${PLUGIN_INSTALL_DIR})
install(FILES plasma-drade-default.desktop DESTINATION ${SERVICES_INSTALL_DIR})
install(FILES television.svg DESTINATION ${DATA_INSTALL_DIR}/desktoptheme/default/widgets/)

TIPP

Haben Sie nur Kleinigkeiten in der CPP-Datei geändert, überspringt CMake das Überprüfen der Abhängigkeiten, wenn Sie zum erneuten Übersetzen make -j3 install/fast verwenden.

Das CMake-Makro install kümmert sich um die Installation des übersetzten Applets, der .desktop-Datei und eventuell vorhandener SVG-Grafiken.

Letztere landen typischerweise im Verzeichnis mit dem Standard-Theme von KDE 4, das sie überlagern. Bringt das Plasmoid keine passende SVG-Datei mit, wählt Plasma automatisch die aus dem Default-Theme.

TIPP

Wählen Sie beim Erstellen des Applets Farben aus der Klasse Plasma::Theme, da andernfalls eventuell Kontrastprobleme auftreten. Dank dieser Funktion integriert sich Ihr Applet visuell gut in den Desktop, auch wenn neue Plasma-Themes eigene Farbpaletten mitbringen.

Vorbereiten und Laden der Grafik

Inkscape eignet sich hervorragend, um die Vektorgrafik zu bearbeiten – werfen Sie einen Blick auf die Beispielgrafik. Dazu öffnen Sie die Datei television.svg mit Inkscape und betrachten Sie dann im eingebauten XML-Editor, den Sie über Bearbeiten | XML-Editor öffnen (Abbildung 3). Sie sehen, dass einige Elemente über lesbare id-Felder verfügen, die Sie später aus dem Code heraus ansprechen. Sie passen also existierende SVG-Dateien recht einfach an Ihre Bedürfnisse an, indem Sie die Elemente neu anordnen und dem id-Feld des betreffenden Elements einen sinnvollen Namen verpassen.

Abbildung 3

Abbildung 3: In Inkscape bearbeiten Sie Vektorgrafiken im SVG-Format weiter.

Drade.cpp unter der Lupe

Das Laden der SVG-Datei besorgt im Applet die Methode init() (Listing 2). Dank des Codes lädt Plasma die Vektorgrafik. Da Sie in der Datei CMakeLists.txt angegeben haben, dass diese in das Verzeichnis desktoptheme/default/widgets/ gehört, können Sie sie im Applet-Code über widgets/television wiederfinden und ansprechen. Wie der vordere Teil der Adresse aussieht, hängt vom voreingestellten Pfad der Umgebungsvariable $KDEHOME ab. Weil hinter television die Dateiendung fehlt, lädt Plasma auch komprimierte Vektorgrafiken (.svgz), ohne dass Sie das Applet neu übersetzen müssen.

// drade.cpp, Zeilen 76 bis 80
m_svg = new Plasma::Svg(this);
m_svg->setImagePath("widgets/television");
m_svg->setContainsMultipleImages(false);
m_svg->resize(contentsRect().size());

Im nächsten Schritt bestimmen Sie den Inhaltstyp ("ContentType") für das m_svg-Objekt. Dabei geben Sie zunächst an, dass es sich bei der Grafik um ein einzelnes Bild handelt und nicht um eine Reihe von Bildern (Listing 2, Zeile 4). Über den resize-Parameter (Zeile 5) passen Sie die Grafik der Größe des Inhaltes an.

Das rechenintensive Übersetzen der Vektorgrafik in eine Bitmapgrafik sollten Sie nicht über paintInterface() erledigen, sondern in der Methode init() und über die Funktion constraintsEvent() (Zeilen 93 bis 98 in drade.cpp). Letztere ruft Plasma auf, wenn sich die Größe des Applets ändert. Das passiert, wenn der Benutzer die Größe des Plasmoids über die Applet-Anfasser oder das Panel verändert. Rufen Sie resize() nicht auf, gerät die Grafik körnig oder ungenau.

Die Elemente in der SVG-Datei sprechen Sie mit den Zeilen aus Listing 3 an. Hier zeichnet Plasma ein Element – und damit alle unterliegenden Elemente – ins Applet. Dies geschieht innerhalb der Methode paintInterface(), die den Teil der Grafik in ein vorgegebenes Rechteck zeichnet. Dessen Größe hängt vom darin befindlichen Inhalt ab, was Sie in der Methode resize über contentsRect definiert haben. Um das Positionieren der SVG-Grafiken zu erleichtern, empfiehlt es sich, den darin enthaltenen Elementen gleich große Rechtecke zuzuweisen.

// drade.cpp, Zeilen 229 bis 233
if (m_svg->hasElement("Box")) {
    m_svg->paint(p, contentsRect, "Box");
        } else {
            kDebug() << "Box SVG element is not there. …";
        }

Einbinden von dynamischen Daten

Plasma trennt Darstellungen und Daten/Inhalte streng voneinander. Die Applets übernehmen die Darstellung, ihre Daten beziehen sie aus einer der bestehenden DataEngines [1].

Mehrere Plasmoiden können sich eine DataEngine teilen, die Plasma bei Bedarf lädt. Benötigt kein Plasmoid mehr den Datenmotor, entlädt Plasma ihn wieder, so dass er keine Ressourcen konsumiert. Dies alles regelt Plasma selbständig, als Entwickler müssen Sie sich nicht darum kümmern.

Ein Motor ist die Hotplug-DataEngine. Sie gibt ein Signal, wenn Sie ein neues Gerät mit dem Computer verbinden. Für "Dr. Ade" soll sie einen eingesteckten USB-Stick erkennen. Dazu verbinden Sie das Signal sourceAdded(const QString&) der DataEngine mit dem Slot onSourceAdded(const QString&) (Listing 4, Zeile 2). In Zeile 3 gibt hotplug ein Signal, sobald Sie das Gerät wieder entfernen.

// drade.cpp, Zeilen 83 und 84
connect(dataEngine("hotplug"), SIGNAL(sourceAdded(const QString&)), this, SLOT(onSourceAdded(const QString&)));
connect(dataEngine("hotplug"), SIGNAL(sourceRemoved(const QString&)), this, SLOT(onSourceRemoved(const QString&)));

Als Ergebnis liefern die Signal/Slot-Konstruktionen eine QString-Variable in den Methoden onSourceAdded() sowie onSourceRemoved() zurück. Die erste Methode benutzen Sie, um mit Hilfe von Solid – der Hardwarebibliothek von KDE 4 – herauszufinden, um was für ein Gerät es sich handelt (Listing 5). Im Beispiel soll der Produktname genügen (Solid::Device(name);, Zeile 6). Die Daten, die Solid liefert, zeichnet die Methode paintInferface() dann in das Plasmoid (Zeilen 222 bis 243 in drade.cpp).

// drade.cpp, Zeilen 124 bis 131
void DrAde::onSourceAdded(const QString &name)
{
    m_isPlugged = true;
    showScreen(true);
    Solid::Device m_device = Solid::Device(name);
    kDebug() << "Solid: vendor, product, icon" << m_device.vendor() << m_device.product() << m_device.icon();
    m_volumeName = m_device.product();
}

Die Funktion showScreen() startet die Animation der SVG-Grafik – dazu später mehr. Sie benutzen zunächst den Parameter &name, um über Solid ein neues Gerät anzumelden (Solid::Device), das Sie dann der Member-Variable m_device übergeben, auf die auch die paintInterface()- Funktion zugreifen kann.

Konfiguration und Einstellungen

Sie können Applets auch mit Konfigurationsdialogen ausstatten. Die Dialoge erstellen Sie recht einfach mit dem Qt-Designer. Das Beispiel zeigt, wie Sie eine Checkbox, eine Spinbox und ein Slider-Element einsetzen. Die Userinterface-Datei (.ui) koppelt dabei Slider und Spinbox aneinander, indem sie die Signale valueChanged() und die Slots setValue() der jeweiligen Elemente verbindet.

Abbildung 4

Abbildung 4: Im Qt-Designer entwerfen Sie die grafische Oberfläche für das Konfigurationsmenü des Plasmoids.

Den Konfigurationsdialog binden Sie in drei Schritten ein (Listing 6): Die Methode init() liest die gespeicherten Einstellungen aus einem KConfigGroup-Objekt, das Plasma über eine Funktion in der Applet-Klasse zur Verfügung stellt (config()). Dann liest das Programm über cg.readEntry die Werte der Schlüssel animate und animDuration aus. Der zweite Parameter in der Klammer (Zeilen 3 und 4) diktiert jeweils die Voreinstellung.

// drade.cpp, Zeilen 70 bis 72
KConfigGroup cg = config();
m_animDuration = cg.readEntry("animDuration", 200);
m_animate = cg.readEntry("animate", true);

Über die Member-Variablen m_animate und m_animDuration bestimmen Sie, ob Sie das Applet animieren wollen und wie lange die Animation dauert.

In der Methode createConfigurationInterface() (Listing 7) erstellen Sie den Konfigurationsdialog. Plasma führt die Methode aus, sobald der Benutzer den Konfigurationsdialog öffnet. Sie lädt das Interface der UI-Datei und ergänzt Knöpfe wie OK, Anwenden und Abbrechen automatisch.

In den Zeilen 7 und 8 übergeben Sie der Methode die Werte, die Sie vorher aus dem KConfig-Objekt ausgelesen haben. Schließen Sie den Konfigurationsdialog, muss das Applet davon erfahren. Dazu verbinden Sie die Signale applyClicked() und okClicked() mit dem Slot configAccepted() – einer Methode des Applets (Zeilen 10 und 11). Abschließend ergänzen Sie das Widget in Zeile 12 um den Konfigurationsdialog, wobei ein Pointer zum Einsatz kommt.

// drade.cpp, Zeilen 141 bis 159
void DrAde::createConfigurationInterface(KConfigDialog *parent)
{
    QWidget *widget = new QWidget;
    ui.setupUi(widget);
    parent->setButtons( KDialog::Ok | KDialog::Cancel | KDialog::Apply );
    ui.speedSlider->setValue(m_animDuration);
    ui.speedSpin->setValue(m_animDuration);
[…]
    connect( m_dialog, SIGNAL(applyClicked()), this, SLOT(configAccepted()) );
    connect( m_dialog, SIGNAL(okClicked()), this, SLOT(configAccepted()) );
    parent->addPage(widget, parent->windowTitle(), "drade");
}

Die Methode configureAccepted() (Listing 8) gibt ein Signal, sobald der Anwender im Konfigurationsbereich die Buttons OK oder Anwenden drückt. Die Methode gleicht die Daten des Applets mit jenen des Benutzers ab und schreibt sie meist auch direkt in die Konfiguration. Zum Speichern dient hier KConfig, KDEs Konfigurationssystem, das auch dafür sorgt, dass Sie die Daten einfach wieder auslesen können. Da KConfig viele Qt-Typen unterstützt, brauchen Sie sich kaum Gedanken über das Format zu machen, oder wie Sie verschiedene Datentypen speichern und einlesen. Es genügt, abstrakte Daten – wie zum Beispiel eine QColor-Farbe – in einen Konfigurationseintrag zu schreiben und sie später wieder auszulesen.

In der Methode von Listing 8 lesen Sie die Werte aus dem UI-Objekt. Dann schreiben Sie sie in die Konfigurationsdatei sowie in die Member-Variable, um bei Bedarf einfach auf die Daten zuzugreifen. Da sich möglicherweise interne Daten geändert haben, erneuern Sie die Verbindung mit der DataEngine (update()).

// drade.cpp, Zeilen 161 bis 172
void DrAde::configAccepted()
{
    m_animDuration = ui.speedSlider->value();
    m_animate = ui.Animate->isChecked();
    config().writeEntry("animate", m_animate);
    config().writeEntry("animDuration", m_animDuration);
    update();
    emit configNeedsSaving();
}

Indem Sie update() aufrufen, malt Plasma das Applet neu. Zugleich geben Sie auf diese Weise an, dass sich die Konfiguration geändert hat. Plasma kümmert sich in der Folge darum, dass die Konfigurationsdaten "in Kürze" auf der Festplatte landen. Es speichert die Daten nicht direkt: Bringen bestimmte Einstellungen den KDE-4-Desktop zum Absturz, soll er bei einem Neustart nicht gleich wieder den Geist aufgeben. Zugleich bündeln Sie durch die Verzögerung die Schreibzugriffe auf die Festplatte, was Energie spart.

In Bewegung

Plasma bietet dem Anwender im Idealfall ein organisches Benutzer-Interface an, auf dem sich Objekte so verhalten, wie der Benutzer es erwartet und wie sein Gehirn es aus der Natur kennt. Animationen sollen ihm dabei visuelle Hinweise geben, denn das menschliche Gehirn kommt mit kurzen Bewegungen besser klar, als mit abrupten Änderungen. Um die Benutzer nicht abzulenken, sollten sich Plasmoiden daher ruhig verhalten, solange sie nicht den Fokus besitzen.

Animationen in Plasma benutzen die Klasse Plasma::Animator. Diese stellt eine Zeitachse bereit, indem sie in bestimmten Abständen eine definierte Funktion aufruft und das Plasmoid neu zeichnet. Das Beispiel benutzt diese Phase, um den gezeichneten Bildschirm des Plasmoids zur Mitte hin zu verkleinern. Das erzeugt einen Ausschalteffekt, wie bei einem alten Fernseher. Genügt der Platz auf dem Desktop, blendet das Plasmoid zugleich den Namen des USB-Sticks weich ein.

Sobald ein Anwender einen USB-Stick einsteckt, startet das Applet über die Methode showScreen() die Animation, die in regelmäßigen Abständen die Methode animationUpdate() des Applets aufruft. Dabei speichert es die ID, um sie im weiteren Verlauf zu kontrollieren. (Listing 9)

// drade.cpp, Zeile 148
m_animId = Plasma::Animator::self()->customAnimation(40 / (1000 / m_animDuration), m_animDuration, Plasma::Animator::EaseInCurve, this, "animationUpdate");

Als Parameter übergeben Sie Plasma::Animator die Anzahl der Bilder, die Länge der Animation, die Kurvenform, das Empfänger-Widget für die Updates und die aufzurufende Methode. Die Zahl der Bilder errechnen Sie, indem Sie von 25 Bildern pro Sekunde ausgehen, was einem Bild pro 40 Millisekunden entspricht. Die Dauer der Animation wählen Sie zwischen 150 und 300 Millisekunden – länger andauernde Animationen empfinden Benutzer mitunter als störend. Als Kurvenform kommt die EaseInCurve zum Einsatz, die dafür sorgt, dass sich die Geschwindigkeit am Anfang schnell erhöht und danach langsam abbremst. Lineare Kurven wie LinearCurve fühlen sich häufig hölzern und statisch an.

Die Methode animationUpdate() bekommt dann wiederum eine Variable vom Typ Qreal namens progress mit auf den Weg (Listing 10), die verrät, wie weit die Animation fortgeschritten ist. Anhand der Boolschen Member-Variable m_fadeIn merkt sich Plasma, ob es die zu animierende Grafik gerade ein- oder ausblendet.

// drade.cpp, Zeilen 209 bis 220
void DrAde::animationUpdate(qreal progress)
{
    if (progress == 1) {
        m_animId = -1;
    }
    if (!m_fadeIn) {
        m_animProgress = 1 - progress;
    } else {
        m_animProgress = progress;
    }
    update();
}

Die Variable progress pendelt dabei immer zwischen 0 (am Anfang der Animation) und 1 (am Ende). Für den Ausblendeffekt invertieren Sie den Wert einfach, sodass er kleiner wird. Die Member-Variable m_animProgress speichert den Status der Animation im Plasmoid und sorgt dafür, dass Plasma es mit Unterstützung der Methode paintInterface() neu zeichnet (drade.cpp, Zeile 235), was dann so aussieht:

m_svg->paint(p, scaleRectF(m_animProgress, contentsRect), "Screen");

Durch diesen Aufruf zeichnet Plasma das SVG-Element Screen in der durch die Animation vorgegebenen Größe. Die Funktion scaleRectF() kommt dabei zur Hilfe: Sie rechnet Position und Größe innerhalb des Plasmoids aus. Verfügt das über eine bestimmte Mindestbreite, sorgt paintLabel() dafür, dass Plasma den Namen des USB-Sticks in einem Rechteck mit abgerundeten Ecken abbildet.

Geben Sie den Farben, mit denen Sie malen, einen bestimmten Alpha-Wert mit, blendet die Methode den Text im Takt mit der Animation des Screen-Elements weich ein. Der Wert hängt dabei vom Fortschritt der Animation ab. Die folgenden zwei Zeilen (drade.cpp, Zeile 262 und 263) erledigen dies:

boxColor.setAlphaF(0.3*m_animProgress);
textColor.setAlphaF(0.8*m_animProgress);

Damit ist "Dr. Ade" nun fertig. Es fehlt noch ein letzter Schritt: Sie müssen das Applet kompilieren und so in die KDE-Trunk-Version einbinden.

Dr. Ade aktivieren

Melden Sie sich über sux - kde-devel als KDE-Entwicklungshelfer an. Wechseln Sie in das Verzeichnis /home/kde-devel/KDE/kdeplasma-addons/applets und legen Sie ein neues Verzeichnis namens drade an. Kopieren Sie sämtliche Dateien von der LinuxUser-DVD, die zu "Dr. Ade" gehören, in den neuen Ordner. Wechseln Sie ins übergeordnete Verzeichnis, öffnen Sie die Datei CMakeLists.txt mit einem Texteditor und ergänzen Sie die Zeile add_subdirectory(drade). Nach dem Speichern der Datei übersetzen Sie aus dem Verzeichnis applets heraus das Plasmoid über den Befehl cmakekde. Im Drade-Verzeichnis sollte nun ein Makefile erscheinen, das Sie mit make und make install installieren. Nach einem Neustart von KDE steht Ihnen "Dr. Ade" zu Diensten.

[1] Über Plasma: Sebastian Kügler, "Plasmische Chirurgie", LinuxUser 09/2008, S. 82, http://www.linux-user.de/ausgabe/2008/09/082/

[2] Entwicklungsumgebung für KDE 4 einrichten: Kristian Kißling, "Bleeding Edge", LinuxUser 09/2008, S. 86, http://www.linux-user.de/ausgabe/2008/09/086/

[3] Mailingliste der KDE-Anwendungsentwickler: https://mail.kde.org/mailman/listinfo/kde-devel

[4] Quellcode für "Dr. Ade": http://www.linux-user.de/Downloads/2008/10/

Tip a friend    Druckansicht beenden Bookmark and Share
Kommentare