Development/Tutorials/Using KActions (de)

Development/Tutorials/Using_KActions

KActions benutzen

Anleitungsserie	Anleitungen für Anfänger
Voriges Kapitel	Anleitung 2 - KXmlGuiWindow
Nächstes Kapitel	Todo
Weiterführende Texte	none
Navigation	Deutsche Startseite

Zusammenfassung

In diesem Kapitel wird das Konzept der Aktionen eingeführt. Aktionen sind ein vereinheitlichter Weg, dem Benutzer eine Interaktion mit Ihrem Programm zu ermöglichen

Soll zum Beispiel durch das Klicken eines Buttons, einem Eintrag im Dateimenü oder einem Tastaturshortcut das Textfeld geleert werden, wird dies alles durch eine KAction bewerkstelligt.

KAction

Eine KAction ist ein Objekt, welches alle Informationen über das Icon und Shortcuts enthält, welche mit einer bestimmten Aktion assoziiert sind. Diese Aktion läßt sich mit einemslot verbinden, welcher dann bestimmte Arbeiten ausführt, die bei dieser Aktion vorgesehen sind.

Eine eigene Aktion erzeugen

Um eine Aktion zu erzeugen, muss #include <KAction> in die .cpp Datei eingefügt werden.

Das Objekt erzeugen

Wir werden hier eine Aktion erzeugen, welche die Applikation aus Kapitel 2 dahingehend erweitert, dass durch sie das Textfeld geleert wird. Die KAction wird in einer Reihe einzelner Schritte zusammengestellt. Zunächst wird das Objekt selber erzeugt: KAction* clearAction = new KAction(this); Das erzeugt ein KAction-Objekt welches clearAction heißt.

Text

Bei dem jetzt erzeugten KAction Objekt können jetzt die Eigenschaften gesetzt werden. Zunächst setzen wir einen Text der im Menü und unter seinem Icon in der Werkzeugleiste angezeigt wird: clearAction->setText(i18n("Clear")); Wie man sieht, muss dieser Text durch die i18n() Funktion geleitet werden, wenn man das Benutzerinterface später übersetzen möchte.

Icon

Soll in der Werkzeugleiste die Aktion angezeigt werden, muss man ein Icon verknüpfen, welches die Aktion bildlich beschreibt. Um das zu bewekstelligen, benutzen wir die setIcon() Funktion: clearAction->setIcon(KIcon("document-new")); Hier wird das Standardicon document-new von KDE benutzt.

Shortcut

Wir können auch einen Tastaturshortcut definieren, welcher die Aktion ausführt.. Das wird ganz einfach durch clearAction->setShortcut(Qt::CTRL+Qt::Key_W); bewekstelligt. In diesem Fall wird Ctrl+W mit der Aktion verknüpft.

Zur Sammlung hinzufügen

Damit das XmlGui Framework auf unsere Aktion zugreifen kann, muss diese in die action collection (Sammlung der Aktionen) der Applikation eingefügt werden. Auf diese wird über die actionCollection() Funktion zugegriffen: actionCollection()->addAction("clear", clearAction); Dieser Code fügt die clearAction KAction in die Sammlung ein und gibt ihr den Namen clear. Dieser Name wird vom XmlGui Framework benutzt.

Die Aktion verbinden

Jetzt ist unsere Aktion vollständig aufgesetzt und sie muss nun noch verknüpft werden, damit sie etwas sinnvolles macht. Wir werden unsere Aktion mit dem clear() Slot, der zu einem KTextArea Objekt gehört, verknüpfen: connect( clearAction, SIGNAL( triggered(bool) ),

        textArea, SLOT( clear() ) );

Das gleiche würden wir in Qt mit einer QAction machen

KStandardAction

Manche Aktionen, wie zum Beispiel 'beenden', 'speichern' und 'laden', benötigt fast jede KDE Applikation. Daher gibt es zur Vereinfachung vorgefertigte KActions, auf welche über KStandardAction zugegriffen wird.

Diese sind sehr einfach zu benutzen. Sobald man #include <KStandardAction> im Quellcode eingefügt hat, muss man nur noch festlegen, welche Funktion bei Auslösung aufgerufen werden soll und zu welcher KActionCollection die Aktion hinzugefügt werden soll. Beispiel:

KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); Dieser Code erzeugt ein KAction Objekt mit dem entsprechenden Icon, Text und Shortcut und fügt dieses sogar zum Datei-Menü hinzu.

Der Code

mainwindow.h

ifndef MAINWINDOW_H
define MAINWINDOW_H

include <KXmlGuiWindow>
include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{

 public:
   MainWindow(QWidget *parent=0);

 private:
   KTextEdit* textArea;
   void setupActions();

};

endif

mainwindow.cpp

include "mainwindow.h"

include <KApplication>
include <KAction>
include <KLocale>
include <KActionCollection>
include <KStandardAction>

MainWindow::MainWindow(QWidget *parent)

   : KXmlGuiWindow(parent)

 textArea = new KTextEdit;
 setCentralWidget(textArea);

 setupActions();

}
void MainWindow::setupActions()
{

 KAction* clearAction = new KAction(this);
 clearAction->setText(i18n("Clear"));
 clearAction->setIcon(KIcon("document-new"));
 clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
 actionCollection()->addAction("clear", clearAction);
 connect(clearAction, SIGNAL(triggered(bool)),
         textArea, SLOT(clear()));

 KStandardAction::quit(kapp, SLOT(quit()),
                       actionCollection());

 setupGUI();

}

main.cpp

include <KApplication>
include <KAboutData>
include <KCmdLineArgs>

include "mainwindow.h"

int main (int argc, char *argv[])
{

 KAboutData aboutData( "tutorial3", "tutorial3",
     ki18n("Tutorial 3"), "1.0",
     ki18n("A simple text area using KAction etc."),
     KAboutData::License_GPL,
     ki18n("Copyright (c) 2007 Developer") );
 KCmdLineArgs::init( argc, argv, &aboutData );
 KApplication app;

 MainWindow* window = new MainWindow();
 window->show();
 return app.exec();

}

Die Aktionen mit den Menüs und Werkzeugleisten verknüpfen

Zur Zeit haben wir nur unsere neue "Clear" Aktion erzeugt. Zum jetzigen Zeitpunkt würde diese weder in den Menüs noch in den Werkzeugleisten erscheinen. Um der Applikation mitzuteilen wo die Aktion eingefügt werden soll (und dem Benutzer zu ermöglichen, diese dann beliebig umherzuschieben) wird die KDE-Technik namens XmlGui genutzt.

XmlGui

Note

In einer späteren Version von KDE4 könnte XmlGui durch ein neues Framework namens liveui ersetzt werden. Doch zum jetzigen Zeitpunkt ist XmlGui die einzige und korrekte Art, das UI aufzusetzen.

Ruft man setupGUI() in der KXmlGuiWindow Klasse auf, wird das XmlGui System aufgerufen, welche eine XML Datei einliest, welche das entsprechende interface beschreibt und die Buttons und Menüeinträge entsprechend erzeugt. Diese Datei wird im nächsten Schritt für unsere Applikation erzeugt.

Natürlich muss das XmlGui System wissen, welche Beschreibungs-Datei zu der jeweiligen Applikation gehört. Es muss also dem Namen und den Pfad dieser Datei kennen. Standardmäßig soll die Datei appnameui.rc genannt werden(appname ist dabei der Name, der in KAboutData) gesetzt wurde). In unserem Beispiel wird die Datei also tutorial3ui.rc heißen. Wo die Datei zu finden ist, wird von CMake erledigt.

Die appnameui.rc Datei schreiben

Da die Beschreibung unseres UI mit XML definiert wird, muss der Inhalt der Beschreibung strengen Regeln folgen. Wir werden hier nicht alle Regeln auflisten. Darüber wird es eine gesonderte und detailierte Seite geben (die aber noch nicht fertig ist).

tutorial3ui.rc

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> <gui name="tutorial3" version="1">

 <ToolBar name="mainToolBar" >
   <text>Main Toolbar</text>
   <Action name="clear" />
   <ActionList name="dynamicActionlist" />
 </ToolBar>
 <MenuBar>
   <Menu name="file" >
     <text>&File</text>
     <Action name="clear" />
   </Menu>
 </MenuBar>

</gui>

Das <Toolbar> Tag beschreibt die Werkzeugleiste (der Balken mit Icons am oberen Rand des Fensters). Wir geben dieser hier den eindeutigen Namen mainToolBar, setzen den Namen, der für den Benutzer sichtbar ist, auf Main Toolbar, indem wir das <text> Tag anwenden und fügen letztlich unsere Clear-Aktion in die Werkzeugleiste ein, indem wir das <Action> Tag benutzen. Der Parameter "name" dieses Tags ist die gleiche Zeichenkette, die der addAction() Funktion im C++ Code übergeben wurde.

Neben der Werkzeugleiste können wir die Aktion auch in das Hauptmenü einfügen. Dieses erfolgt über das <MenuBar> Tag. Hier wird festgelegt, dass die Aktion in das File Menü eingefügt werden soll. Die Aktion selber wird auf die gleiche Art und Weise eingefügt wie bereits in der der Werkzeugleiste beschrieben.

Bitte beachten Sie, dass sie auch eine dynamische Aktionsliste in die Konfigurationsdatei einfügen können, wenn Sie das <ActionList> Tag benutzen. Mehr Informationen darüber finden Sie in der Methodenbeschreibung plugActionList() der KXMLGUIClient Dokumentation.

Ändern Sie jedesmal das "version" Attribut des Gui-Tags wenn Sie die .rc Datei geändert haben, damit ein Auffrisches des Systemcaches erfolgt.

CMake

Da wir jetzt XmlGui benutzen, muß die tutorial3ui.rc Datei irgendwo hin kopiert werden, wo KDE sie finden kann. Aus diesem Grund muss unser Programm irgendwo hin installiert werden.

CMakeLists.txt

project(tutorial3)

find_package(KDE4 REQUIRED) include_directories( ${KDE4_INCLUDES} )

set(tutorial3_SRCS

 main.cpp
 mainwindow.cpp

)
kde4_add_executable(tutorial3 ${tutorial3_SRCS})
target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})
install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
install( FILES tutorial3ui.rc

        DESTINATION  ${DATA_INSTALL_DIR}/tutorial3 )

Diese Datei sieht fast genau so aus wie diejenige für Kapitel2, hat aber zwei extra Zeilen am Ende. Diese beschreiben, wohin die Dateien installiert werden sollen. Zunächst wird das tutorial3 Ziel in das Verzeichnis BIN_INSTALL_DIR Verzeichnis installiert und anschließend die tutorial3ui.rc Datei, die das Layout unseres Userinterfaces beschreibt in das Datenverzeichnis unserer Applikation.

Erzeugen, Installieren und Ausführen

Wenn Sie keinen Schreibzugriff auf das KDE4 Installationsverzeichnis haben, können Sie das Programm auch in ein Verzeichnis innerhalb Ihres Heimatverzeichnissen installieren.

Um CMake mitzuteilen, wohin das Programm installiert werden soll, setzen Sie den DCMAKE_INSTALL_PREFIX Schalter. Um also das Programm in das KDE Verzeichnis zu installieren, rufen Sie

cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3

auf.

Wenn man hingegen das Programm irgendwo lokal zu Testzwecken installieren will (bei der zurzeit etwas eingeschränkten Funktionalität unsere Applikation ist es vielleicht nicht unbedingt sinnvoll diese in das KDE Hauptverzeichnis zu installieren), wird mit dem Befehl

cmake . -DCMAKE_INSTALL_PREFIX=/home/kde-devel/kdetmp

eine KDE-artige Verzeichnisstruktur innerhalb des ~/kdetmp Verzeichnissen angelegt und die Applikation in das /home/kde-devel/kdetmp/bin/tutorial3 Verzeichnis kopiert.

Weiter geht's

TODO