Development/Tutorials/Using KActions (de): Difference between revisions

From KDE TechBase
(→‎KAction: weitere Übersetzung)
No edit summary
 
(29 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KActions}}
 
 
{{TutorialBrowser (de)|
 
series=Anleitungen für Anfänger|
 
name=KActions benutzen|
 
pre=[[Development/Tutorials/Using_KXmlGuiWindow (de)|Anleitung 2 - KXmlGuiWindow]]|
 
next=[[Development/Tutorials/Saving_and_loading (de)|Anleitung 4 - Laden und Speichern von Dateien]]|
 
reading=Keine
}}


==Zusammenfassung==
==Zusammenfassung==
Line 9: Line 22:


==KAction==
==KAction==
Eine {{class|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 einem[http://doc.trolltech.com/latest/signalsandslots.html slot] verbinden, welcher dann bestimmte Arbeiten ausführt, die bei dieser Aktion vorgesehen sind.  
Eine {{class|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 einem [http://doc.trolltech.com/latest/signalsandslots.html slot] verbinden, welcher dann bestimmte Arbeiten ausführt, die bei dieser Aktion vorgesehen sind.  


===Eine eigene Aktion erzeugen===
===Eine eigene Aktion erzeugen===
Line 16: Line 29:
=====Das Objekt erzeugen=====
=====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:
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:
<code cppqt>KAction* clearAction = new KAction(this);</code>
<syntaxhighlight lang="cpp-qt">KAction* clearAction = new KAction(this);</syntaxhighlight>
Das erzeugt ein KAction-Objekt welches <tt>clearAction</tt> heißt.
Das erzeugt ein KAction-Objekt welches <tt>clearAction</tt> heißt.


=====Text=====
=====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:
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:
<code cppqt>clearAction->setText(i18n("Clear"));</code>
<syntaxhighlight lang="cpp-qt">clearAction->setText(i18n("Clear"));</syntaxhighlight>
Wie man sieht, muss dieser Text durch die <tt>i18n()</tt> Funktion geleitet werden, wenn man das Benutzerinterface später übersetzen möchte.  
Wie man sieht, muss dieser Text durch die <tt>i18n()</tt> Funktion geleitet werden, wenn man das Benutzerinterface später übersetzen möchte.  


=====Icon=====
=====Icon=====
If you're going to display the action in a toolbar, you're going to want to have an icon depicting the action. To set an icon we simply use the <tt>setIcon()</tt> function thus:
Soll in der Werkzeugleiste die Aktion angezeigt werden, muss man ein Icon verknüpfen, welches die Aktion bildlich beschreibt. Um das zu bewerkstelligen, benutzen wir die <tt>setIcon()</tt> Funktion:
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
<syntaxhighlight lang="cpp-qt">clearAction->setIcon(KIcon("document-new"));</syntaxhighlight>
Here we're setting the icon to the standard KDE <tt>document-new</tt> icon.
Hier wird das Standardicon <tt>document-new</tt> von KDE benutzt.


=====Shortcut=====
=====Shortcut=====
We can also set a shortcut that will perform our action. It's as simple as a
Wir können auch einen Tastaturshortcut definieren, welcher die Aktion ausführt.. Das wird ganz einfach durch <syntaxhighlight lang="cpp-qt">clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</syntaxhighlight> bewekstelligt. In diesem Fall wird Ctrl+W mit der Aktion verknüpft.
<code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
 
to set Ctrl+W to be associated to this action.
=====Zur Sammlung hinzufügen=====
=====Adding to the Collection=====
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 <tt>actionCollection()</tt> Funktion zugegriffen:  
In order for our action to be accessable by the XmlGui framework it must be added to the application's ''action collection''. It is accessed via the <tt>actionCollection()</tt> function thus:  
<syntaxhighlight lang="cpp-qt">
<code cppqt>
actionCollection()->addAction("clear", clearAction);
actionCollection()->addAction("clear", clearAction);
</code>
</syntaxhighlight>
Here we add the <tt>clearAction</tt> KAction to the collection and give it a name of ''clear''. This name is used by the XmlGui framework.
Dieser Code fügt die <tt>clearAction</tt> KAction in die Sammlung ein und gibt ihr den Namen ''clear''. Dieser Name wird vom XmlGui Framework benutzt.
=====Connecting the action=====
 
Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the <tt>clear()</tt> action belonging to a KTextArea.
=====Die Aktion verbinden=====
<code cppqt>
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 <tt>clear()</tt> Slot, der zu einem KTextArea Objekt gehört, verknüpfen:
<syntaxhighlight lang="cpp-qt">
connect( clearAction, SIGNAL( triggered(bool) ),  
connect( clearAction, SIGNAL( triggered(bool) ),  
         textArea, SLOT( clear() ) );
         textArea, SLOT( clear() ) );
</code>
</syntaxhighlight>
This is the same as it would be done in Qt with a {{qt|QAction}}.
Das gleiche würden wir in Qt mit einer {{qt|QAction}} machen


===KStandardAction===
===KStandardAction===


For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience KActions, accessed through {{class|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 {{class|KStandardAction}} zugegriffen wird.
 
Diese sind sehr einfach zu benutzen. Sobald man <tt>#include <KStandardAction></tt> im Quellcode eingefügt hat, muss man nur noch festlegen, welche Funktion bei Auslösung aufgerufen werden soll und zu welcher <tt>KActionCollection</tt> die Aktion hinzugefügt werden soll. Beispiel:


They are very simple to use. Once you've done <tt>#include <KStandardAction></tt>, you simply need to supply it with what you want the function to do and which KActionCollection to add it to. For example,
<syntaxhighlight lang="cpp-qt">KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</syntaxhighlight>
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
Dieser Code erzeugt ein KAction Objekt mit dem entsprechenden Icon, Text und Shortcut und fügt dieses sogar zum Datei-Menü hinzu.
Will Create a KAction with the correct icon, text and shortcut and will even add it to the File menu.


==The Code==
==Der Code==
===mainwindow.h===
===mainwindow.h===
<code cppqt n>
<syntaxhighlight lang="cpp-qt" line>
#ifndef MAINWINDOW_H
#ifndef MAINWINDOW_H
#define MAINWINDOW_H
#define MAINWINDOW_H
Line 75: Line 89:


#endif
#endif
</code>
</syntaxhighlight>


===mainwindow.cpp===
===mainwindow.cpp===
<code cppqt n>
<syntaxhighlight lang="cpp-qt" line>
#include "mainwindow.h"
#include "mainwindow.h"


Line 111: Line 125:
   setupGUI();
   setupGUI();
}
}
</code>
</syntaxhighlight>


===main.cpp===
===main.cpp===
<code cppqt n>
<syntaxhighlight lang="cpp-qt" line>
#include <KApplication>
#include <KApplication>
#include <KAboutData>
#include <KAboutData>
Line 135: Line 149:
   return app.exec();
   return app.exec();
}
}
</code>
</syntaxhighlight>
 
==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.


==Putting the actions in the menus and toolbars==
Now, at the moment, we've only created our new "Clear" action. It won't yet show up in the menus or in the toolbars. To tell the program where to put our actions (and to allow the end-user to move them around) we use a KDE technology called XmlGui.
===XmlGui===
===XmlGui===
{{note|In a later version of KDE4, XmlGui may be replaced with a new framework called liveui. For now, XmlGui is the only and correct way to set up the UI.}}
{{note (de)|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.}}


When you call <tt>setupGUI()</tt> in your {{class|KXmlGuiWindow}} class, it calls the XmlGui system which reads an XML file description of your interface (which we will create in a minute) and creates the buttons and menus appropriately.
Ruft man <tt>setupGUI()</tt> in der {{class|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.


Now obviously XmlGui needs to know which file is your description file, i.e. it needs to know its name and location. The rule for the naming is the file should be called <tt>appnameui.rc</tt> (where <tt>appname</tt> is the name you set in {{class|KAboutData}}), so in our example, the file will be called <tt>tutorial3ui.rc</tt>. Where the file will be located is handled by CMake.
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 <tt>appnameui.rc</tt> genannt werden(<tt>appname</tt> ist dabei der Name, der in {{class|KAboutData}}) gesetzt wurde). In unserem Beispiel wird die Datei also <tt>tutorial3ui.rc</tt> heißen. Wo die Datei zu finden ist, wird von CMake erledigt.


===Writing your ''appname''ui.rc File===
===Die ''appname''ui.rc Datei schreiben===


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).
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===
===tutorial3ui.rc===
<code xml n>
<syntaxhighlight lang="xml" line>
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial3"
<gui name="tutorial3" version="1">
    version="1"
    xmlns="http://www.kde.org/standards/kxmlgui/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
                        http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >


  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
    <ActionList name="dynamicActionlist" />
  </ToolBar>
   <MenuBar>
   <MenuBar>
     <Menu name="file" >
     <Menu name="file" >
Line 167: Line 181:
     </Menu>
     </Menu>
   </MenuBar>
   </MenuBar>
  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
    <ActionList name="dynamicActionlist" />
  </ToolBar>
</gui>
</gui>
</code>
</syntaxhighlight>


The <tt><Toolbar></tt> 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 <tt><text></tt> tag and finally add our clear action to the toolbar using the <tt><Action></tt> tag. The name parameter in this tag relates to the string that was passed to the <tt>addAction()</tt> function in the C++ code.
Das <tt><Toolbar></tt> 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 <tt><text></tt> Tag anwenden und fügen letztlich unsere Clear-Aktion in die Werkzeugleiste ein, indem wir das <tt><Action></tt> Tag benutzen. Der Parameter "name" dieses Tags ist die gleiche Zeichenkette, die der <tt>addAction()</tt> Funktion im C++ Code übergeben wurde.  


As well as having our action in the toolbar, we can also add it to the menubar. Within the <tt><MenuBar></tt> 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.
Neben der Werkzeugleiste können wir die Aktion auch in das Hauptmenü einfügen. Dieses erfolgt über das <tt><MenuBar></tt> 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.  


Please note you can also add dynamic action list to your configuration file using a <tt><ActionList></tt> tag. For more information about this, see the <tt>plugActionList()</tt> method of the {{class|KXMLGUIClient}} documentation.
Bitte beachten Sie, dass sie auch eine dynamische Aktionsliste in die Konfigurationsdatei einfügen können, wenn Sie das <tt><ActionList></tt> Tag benutzen. Mehr Informationen darüber finden Sie in der Methodenbeschreibung <tt>plugActionList()</tt> der {{class|KXMLGUIClient}} Dokumentation.


Change 'version' attribute of the gui tag if you changed .rc file since last install to force system cache update
Ändern Sie jedesmal das "version" Attribut des Gui-Tags wenn Sie die .rc Datei geändert haben, damit eine Auffrischung des Systemcaches erfolgt.


==CMake==
==CMake==
Now that we're using XmlGui, we need to put the <tt>tutorial3ui.rc</tt> somewhere where KDE can find it. '''This means we need to install our project somewhere.'''
Da wir jetzt XmlGui benutzen, muß die <tt>tutorial3ui.rc</tt> Datei irgendwo hin kopiert werden, wo KDE sie finden kann. '''Aus diesem Grund muss unser Programm irgendwo hin installiert werden.'''
 
===CMakeLists.txt===
===CMakeLists.txt===
<code>
<syntaxhighlight lang="text">
project(tutorial3)
project(tutorial3)


Line 199: Line 221:
install( FILES tutorial3ui.rc  
install( FILES tutorial3ui.rc  
         DESTINATION  ${DATA_INSTALL_DIR}/tutorial3 )
         DESTINATION  ${DATA_INSTALL_DIR}/tutorial3 )
</code>
</syntaxhighlight>


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 <tt>tutorial3</tt> target is installed to the <tt>BIN_INSTALL_DIR</tt> then the <tt>tutorial3ui.rc</tt> file that describes the layout of the user interface is installed to the application's data directory.
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 <tt>tutorial3</tt> Ziel in das Verzeichnis <tt>BIN_INSTALL_DIR</tt> Verzeichnis installiert und anschließend die <tt>tutorial3ui.rc</tt> Datei, die das Layout unseres Userinterfaces beschreibt in das Datenverzeichnis unserer Applikation.  


===Make, Install And Run===
===Erzeugen, Installieren und Ausführen===
If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.
Wenn Sie keinen Schreibzugriff auf das KDE4 Installationsverzeichnis haben, können Sie das Programm auch in ein Verzeichnis innerhalb Ihres Heimatverzeichnissen installieren.  


To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> switch. So to install the program to the KDE directory, do
Um CMake mitzuteilen, wohin das Programm installiert werden soll, setzen Sie den <tt>DCMAKE_INSTALL_PREFIX</tt> Schalter. Um also das Programm in das KDE Verzeichnis zu installieren, rufen Sie
  cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
  cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
  make install
  make install
  tutorial3
  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
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
  cmake . -DCMAKE_INSTALL_PREFIX=/home/kde-devel/kdetmp
which will create a KDE-like directory structure under ~/kdetmp and will install the executable to {{path|/home/kde-devel/kdetmp/bin/tutorial3}}.
eine KDE-artige Verzeichnisstruktur innerhalb des ~/kdetmp Verzeichnissen angelegt und die Applikation in das {{path|/home/kde-devel/kdetmp/bin/tutorial3}} Verzeichnis kopiert.


==Moving On==
==Weiter geht's==
TODO
Jetzt können sie mit dem Kapitel [[Development/Tutorials/Saving_and_loading (de)| Laden und Speichern von Dateien]] fortfahren.


[[Category:C++]]
[[Category:C++]]

Latest revision as of 14:27, 14 July 2012


KActions benutzen
Anleitungsserie   Anleitungen für Anfänger
Voriges Kapitel   Anleitung 2 - KXmlGuiWindow
Nächstes Kapitel   Anleitung 4 - Laden und Speichern von Dateien
Weiterführende Texte   Keine
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 einem slot 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 bewerkstelligen, 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

noframe
noframe
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.
Anmerkung


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"?>
<gui name="tutorial3"
     version="1"
     xmlns="http://www.kde.org/standards/kxmlgui/1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
                         http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >

  <MenuBar>
    <Menu name="file" >
      <text>&amp;File</text>
      <Action name="clear" />
    </Menu>
  </MenuBar>

  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
    <ActionList name="dynamicActionlist" />
  </ToolBar>

</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 eine Auffrischung 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

Jetzt können sie mit dem Kapitel Laden und Speichern von Dateien fortfahren.