Development/Tutorials/Using KActions (de)

Development/Tutorials/Using_KActions

Languages: عربي | Asturianu | Català | Česky | Kaszëbsczi | Dansk | Deutsch | English | Esperanto | Español | Eesti | فارسی | Suomi | Français | Galego | Italiano | 日本語 | 한국어 | Norwegian | Polski | Português Brasileiro | Română | Русский | Svenska | Slovenčina | Slovenščina | српски | Türkçe | Tiếng Việt | Українська | 简体中文 | 繁體中文

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

1. ifndef MAINWINDOW_H
2. define MAINWINDOW_H

1. include <KXmlGuiWindow>
2. include <KTextEdit>

class MainWindow : public KXmlGuiWindow {

 public:
   MainWindow(QWidget *parent=0);

 private:
   KTextEdit* textArea;
   void setupActions();

};

1. endif

mainwindow.cpp

1. include "mainwindow.h"

1. include <KApplication>
2. include <KAction>
3. include <KLocale>
4. include <KActionCollection>
5. 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

1. include <KApplication>
2. include <KAboutData>
3. include <KCmdLineArgs>

1. 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.

Writing your appnameui.rc File

Since the description of our UI is being defined with XML, the layout of the description must follow strict rules. We won't go through all the rules in this tutorial but for more information, see the _detailed_XmlGui_page_ (once we have a full explanation of XmlGui (or possibly liveui if that's done soon :)) on the wiki, I'll link it up).

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>

The <Toolbar> tag allows you to describe the toolbar. That is the bar across the top of the window with the icons. Here we give it a unique name mainToolBar, set it's user visible name Main Toolbar using the <text> tag and finally add our clear action to the toolbar using the <Action> tag. The name parameter in this tag relates to the string that was passed to the addAction() function in the C++ code.

As well as having our action in the toolbar, we can also add it to the menubar. Within the <MenuBar> tag, we say we want to add our action to the File menu and we add the action in the same way as for the toolbar.

Please note you can also add dynamic action list to your configuration file using a <ActionList> tag. For more information about this, see the plugActionList() method of the KXMLGUIClient documentation.

Change 'version' attribute of the gui tag if you changed .rc file since last install to force system cache update

CMake

Now that we're using XmlGui, we need to put the tutorial3ui.rc somewhere where KDE can find it. This means we need to install our project somewhere.

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 )

This file is almost identical to the one for tutorial2 but it has two extra lines at the end. These describe where the files are to be installed. Firstly, the tutorial3 target is installed to the BIN_INSTALL_DIR then the tutorial3ui.rc file that describes the layout of the user interface is installed to the application's data directory.

Make, Install And Run

If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.

To tell CMake where to install the program, set the DCMAKE_INSTALL_PREFIX switch. So to install the program to the KDE directory, do

cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3

Though, if you just want to install it somewhere local for testing (it's probably a bit silly to go to the effort of installing these tutorials to your KDE directory) you can do something like

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

which will create a KDE-like directory structure under ~/kdetmp and will install the executable to /home/kde-devel/kdetmp/bin/tutorial3.

Moving On

TODO