Difference between revisions of "Archive:Development/Tutorials/Using KActions (zh CN)"

Jump to: navigation, search
Line 15: Line 15:
  
 
==摘要==
 
==摘要==
在本讲中我们将介绍'''动作(action)'''的概念。动作是一种为用户提供程序交互接口的统一方法。
+
在本讲中我们将介绍动作(action)的概念。动作是一种为用户提供程序交互接口的统一方法。  
 
+
例如,假设我们要为[[Development/Tutorials/Using_KXmlGuiWindow (zh_CN)|教程2 - 创建主窗口]]的用户提供通过点击工具栏中的按钮,通过菜单中的一个菜单项,再或者是通过一个组合快捷键,来清除文本区内容的功能。通过一个{{class|KAction}}对象,就可以实现上述的全部功能。
例如,假设我们需要为用户提供一个清除文本输入框内全部文字的功能,并希望用户可以通过点击工具栏中的一个按钮,或者通过菜单中的一个菜单项,再或者是通过一个组合快捷键来执行该功能。在KDE中,我们只需要通过一个{{class|KAction}},就可以实现上述的全部功能。
+
  
 
[[image:introtokdetutorial3.png|frame|center]]
 
[[image:introtokdetutorial3.png|frame|center]]
  
 
==KAction==
 
==KAction==
{{class|KAction}}是一个包含着与某个动作有关的所有信息(如图标、快捷方式等)的对象。你可以将动作连接到实际执行工作的[http://doc.trolltech.com/latest/signalsandslots.html slot]上。
+
{{class|KAction}是一个包含着与某个动作有关的所有信息(如图标、快捷方式等)的对象。你可以将动作连接到实际执行工作的[http://doc.trolltech.com/latest/signalsandslots.html slot]上。
 +
 
 +
== 代码 ==
 +
 
 +
===main.cpp===
 +
<code cppqt n>
 +
#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();
 +
}
 +
</code>
 +
This time, very little has changed in <tt>main.cpp</tt>, only the KAboutData constructor has been updated to show that we are now on tutorial 3.
  
==代码==
 
 
===mainwindow.h===
 
===mainwindow.h===
 
<code cppqt n>
 
<code cppqt n>
Line 45: Line 70:
 
#endif
 
#endif
 
</code>
 
</code>
 +
Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions.
  
 
===mainwindow.cpp===
 
===mainwindow.cpp===
Line 70: Line 96:
 
   clearAction->setText(i18n("Clear"));
 
   clearAction->setText(i18n("Clear"));
 
   clearAction->setIcon(KIcon("document-new"));
 
   clearAction->setIcon(KIcon("document-new"));
   clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
+
   clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
 
   actionCollection()->addAction("clear", clearAction);
 
   actionCollection()->addAction("clear", clearAction);
 
   connect(clearAction, SIGNAL(triggered(bool)),
 
   connect(clearAction, SIGNAL(triggered(bool)),
Line 82: Line 108:
 
</code>
 
</code>
  
===main.cpp===
+
==Explanation==
<code cppqt n>
+
This builds upon the KXmlGuiWindow code from [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2]]. Most of the changes are to <tt>mainwindow.cpp</tt>, an important structural change being that the constructor for MainWindow now calls <tt>setupActions()</tt> instead of <tt>setupGUI()</tt>. <tt>setupActions()</tt> is where the new KAction code goes before finally calling <tt>setupGUI()</tt> itself.
#include <KApplication>
+
#include <KAboutData>
+
#include <KCmdLineArgs>
+
  
#include "mainwindow.h"
+
===Creating the KAction object===
 
+
The KAction is built up in a number of steps. The first is including the <tt>KAction</tt> library and then creating the KAction:
int main (int argc, char *argv[])
+
<code cppqt>
{
+
#include <KAction>
  KAboutData aboutData( "tutorial3", "tutorial3",
+
...
      ki18n("Tutorial 3"), "1.0",
+
KAction* clearAction = new KAction(this);
      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();
+
}
+
 
</code>
 
</code>
 +
This creates a new KAction called <tt>clearAction</tt>.
  
 
+
===Setting KAction Properties===
===创建你自己的动作===
+
====Text====
要创建一个动作,首先需要在你的<tt>.cpp</tt>文件中包含<tt>#include <KAction></tt> 。
+
Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>KAction</tt>'s icon in the toolbar.
=====创建对象=====
+
下面,我们将创建一个动作来清除文本区(见教程2)中的内容。
+
我们将通过一系列的步骤来创建这个动作。首先是创建KAction对象:
+
<code cppqt>KAction* clearAction = new KAction(this);</code>
+
上面这行代码创建了一个叫做<tt>clearAction</tt>的KAction对象。
+
=====文字=====
+
有了KAction对象之后,我们就可以来设置它的属性。
+
首先,我们要设置显示在菜单中和工具栏图标下的文字。
+
 
<code cppqt>clearAction->setText(i18n("Clear"));</code>
 
<code cppqt>clearAction->setText(i18n("Clear"));</code>
正如你所看到的那样,如果你希望你的用户界面能够被正确本地化(i18n),就要先用
+
Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]).
i18n()来处理要显示文字。
+
  
=====图标=====
+
====Icon====
如果你希望动作能显示在工具栏中,那么就需要给它指定一个图标。用<tt>setIcon()</tt> 函数即可实现该功能:
+
If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function:
 
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
 
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
这里我们设置使用标准KDE的<tt>document-new(新建文档)</tt>图标.
 
  
=====快捷键=====
+
====Keyboard Shortcut====
我们也需要给动作设置一个快捷键。只需要简单的通过代码
+
Setting a keyboard shortcut to perform our action is equally simple:
<code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
+
<code cppqt>clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</code>
来将Ctrl+W设置为快捷键。
+
This associates Ctrl+W with the KAction.
=====添加到集合中=====
+
 
为了让我们的动作能够被XmlGui架构访问,必须将它添加到程序的“动作集”中。通过<tt>actionCollection()</tt>函数来实现这一步:  
+
===Adding to the Collection===
 +
In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's ''action collection''. The action collection is accessed via the <tt>actionCollection()</tt> function like this:  
 
<code cppqt>
 
<code cppqt>
 
actionCollection()->addAction("clear", clearAction);
 
actionCollection()->addAction("clear", clearAction);
 
</code>
 
</code>
这里我们将KAction对象<tt>clearAction</tt>加入了动作集,并将其命名为“clear”。 XmlGui架构会使用这个名字来管理该对象。
+
Here, the <tt>clearAction</tt> KAction is added to the collection and given a name of ''clear''. This name (''clear'') is used by the XMLGUI framework to refer to the action.
=====连接到动作=====
+
 
完成对动作的设置之后,接下来我们需要将它连接到实际进行处理的部分。为此,我们将动作连接到textArea对象的<tt>clear()</tt>方法。
+
====Connecting the action====
 +
Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit)
 
<code cppqt>
 
<code cppqt>
 
connect( clearAction, SIGNAL( triggered(bool) ),  
 
connect( clearAction, SIGNAL( triggered(bool) ),  
 
         textArea, SLOT( clear() ) );
 
         textArea, SLOT( clear() ) );
 
</code>
 
</code>
这与Qt里的{{qt|QAction}}的用法是相同的。
+
This is the same as it would be done in Qt with a {{qt|QAction}}.
  
 
===KStandardAction===
 
===KStandardAction===
对于那些几乎在所有KDE程序中出现的动作,如“退出”,“保存”及“载入”等,KDE提供了一些预定义的KAction对象。可以通过{{class|KStandardAction}}来访问它们。
 
  
使用它们很简单。只要你在代码中包含了<tt>#include <KStandardAction></tt>, 你只需要简单的将你希望执行的方法和要加入的动作集提供给它即可。例如,
+
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 [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction].
 +
 
 +
They are very simple to use. Once the library has been included (<tt>#include <KStandardAction></tt>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example:
 
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
 
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
将会自动创建一个带有正确的图标、文本和快捷键的KAction对象,并自动加入文档菜单。
+
This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.
 +
 
 +
==Adding the action to menus and toolbars==
 +
At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.
  
 +
{{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.}}
  
==将动作放到菜单和工具栏中==
+
==XMLGUI==
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===
+
{{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.}}
+
  
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.
+
The <tt>setupGUI()</tt> function in {{class|KXmlGuiWindow}} depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.
  
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.
+
The rule for naming this XML file is <tt>appnameui.rc</tt>, where <tt>appname</tt> is the name you set in {{class|KAboutData}} (in this case, ''tutorial3''). So in our example, the file is called <tt>tutorial3ui.rc</tt>, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.
  
===编写你自己的''程序名''ui.rc文件===
+
==''appname''ui.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).
+
Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]] (here is an older tutorial: [http://developer.kde.org/documentation/tutorials/xmlui/preface.html]).
  
 
===tutorial3ui.rc===
 
===tutorial3ui.rc===
Line 170: Line 178:
 
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
 
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
 
<gui name="tutorial3" version="1">
 
<gui name="tutorial3" version="1">
 
 
   <ToolBar name="mainToolBar" >
 
   <ToolBar name="mainToolBar" >
 
     <text>Main Toolbar</text>
 
     <text>Main Toolbar</text>
 
     <Action name="clear" />
 
     <Action name="clear" />
    <ActionList name="dynamicActionlist" />
 
 
   </ToolBar>
 
   </ToolBar>
 
   <MenuBar>
 
   <MenuBar>
 
     <Menu name="file" >
 
     <Menu name="file" >
      <text>&amp;File</text>
 
 
       <Action name="clear" />
 
       <Action name="clear" />
 
     </Menu>
 
     </Menu>
Line 185: Line 190:
 
</code>
 
</code>
  
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.
+
The <tt><Toolbar></tt> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name ''mainToolBar'' and its user visible name set to ''Main Toolbar'' using the <tt><text></tt> tag. The clear action is added to the toolbar using the <tt><Action></tt> tag, the name parameter in this tag being the string that was passed to the KActionCollection with <tt>addAction()</tt> in <tt>mainwindow.cpp</tt>.
 
+
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.
+
  
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.
+
Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the ''File'' menu of the <tt>MenuBar</tt> the same way it was added to the toolbar.
  
Change 'version' attribute of the gui tag if you changed .rc file since last install to force system cache update
+
Change the 'version' attribute of the <tt><nowiki><gui></nowiki></tt> tag if you changed .rc file since the last install to force a system cache update.
  
 
==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.'''
+
Finally, the <tt>tutorial3ui.rc</tt> needs to go somewhere where KDE can find it (can't just leave it in the source directory!). '''This means the project needs to be installed somewhere.'''
 
===CMakeLists.txt===
 
===CMakeLists.txt===
<code>
+
<code ini n>
 
project(tutorial3)
 
project(tutorial3)
  
 
find_package(KDE4 REQUIRED)
 
find_package(KDE4 REQUIRED)
include_directories( ${KDE4_INCLUDES} )
+
include_directories(${KDE4_INCLUDES})
  
 
set(tutorial3_SRCS  
 
set(tutorial3_SRCS  
Line 212: Line 215:
  
 
install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
 
install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
install( FILES tutorial3ui.rc  
+
install(FILES tutorial3ui.rc  
        DESTINATION  ${DATA_INSTALL_DIR}/tutorial3 )
+
        DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)
 
</code>
 
</code>
  
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.
+
This file is almost identical to the one for tutorial2, but with two extra lines at the end that 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.
  
===Make, 安装和运行===
+
===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.
 
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 <tt>DCMAKE_INSTALL_PREFIX</tt> switch. So to install the program to the KDE directory, do
+
To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> switch. You probably 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), so the following might be appropriate:
  cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
+
mkdir build && cd build
 +
  cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
 
  make install
 
  make install
  tutorial3
+
  $HOME/bin/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
+
which will create a KDE-like directory structure in your user's home directory directory and will install the executable to {{path|$HOME/bin/tutorial3}}.
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}}.
+
  
==继续前进==
+
==Moving On==
TODO
+
Now you can move on to [[Development/Tutorials/Saving_and_loading|saving and loading]].
  
 
[[Category:C++]]
 
[[Category:C++]]

Revision as of 10:02, 30 May 2008

Template:I18n/Language Navigation Bar (zh CN)

使用KActions
Tutorial Series   初学者教程
Previous   教程2 - 创建主窗口, XML基础知识
What's Next   TODO (milliams)
Further Reading   None

Contents

摘要

在本讲中我们将介绍动作(action)的概念。动作是一种为用户提供程序交互接口的统一方法。 例如,假设我们要为教程2 - 创建主窗口的用户提供通过点击工具栏中的按钮,通过菜单中的一个菜单项,再或者是通过一个组合快捷键,来清除文本区内容的功能。通过一个KAction对象,就可以实现上述的全部功能。

Introtokdetutorial3.png

KAction

{{class|KAction}是一个包含着与某个动作有关的所有信息(如图标、快捷方式等)的对象。你可以将动作连接到实际执行工作的slot上。

代码

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();

} This time, very little has changed in main.cpp, only the KAboutData constructor has been updated to show that we are now on tutorial 3.

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

Only a function void setupActions() has been added which will do all the work setting up the KActions.

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();

}

Explanation

This builds upon the KXmlGuiWindow code from Tutorial 2. Most of the changes are to mainwindow.cpp, an important structural change being that the constructor for MainWindow now calls setupActions() instead of setupGUI(). setupActions() is where the new KAction code goes before finally calling setupGUI() itself.

Creating the KAction object

The KAction is built up in a number of steps. The first is including the KAction library and then creating the KAction:

  1. include <KAction>

... KAction* clearAction = new KAction(this); This creates a new KAction called clearAction.

Setting KAction Properties

Text

Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the KAction's icon in the toolbar. clearAction->setText(i18n("Clear")); Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the i18n tutorial).

Icon

If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE document-new icon through the use of the setIcon() function: clearAction->setIcon(KIcon("document-new"));

Keyboard Shortcut

Setting a keyboard shortcut to perform our action is equally simple: clearAction->setShortcut(Qt::CTRL + Qt::Key_W); This associates Ctrl+W with the KAction.

Adding to the Collection

In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's action collection. The action collection is accessed via the actionCollection() function like this: actionCollection()->addAction("clear", clearAction); Here, the clearAction KAction is added to the collection and given a name of clear. This name (clear) is used by the XMLGUI framework to refer to the action.

Connecting the action

Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the clear() action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit) connect( clearAction, SIGNAL( triggered(bool) ),

        textArea, SLOT( clear() ) );

This is the same as it would be done in Qt with a QAction.

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

They are very simple to use. Once the library has been included (#include <KStandardAction>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example: KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.

Adding the action to menus and toolbars

At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.

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

XMLGUI

The setupGUI() function in KXmlGuiWindow depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.

The rule for naming this XML file is appnameui.rc, where appname is the name you set in KAboutData (in this case, tutorial3). So in our example, the file is called tutorial3ui.rc, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.

appnameui.rc File

Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the detailed XMLGUI page (here is an older tutorial: [1]).

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" />
 </ToolBar>
 <MenuBar>
   <Menu name="file" >
     <Action name="clear" />
   </Menu>
 </MenuBar>

</gui>

The <Toolbar> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name mainToolBar and its user visible name set to Main Toolbar using the <text> tag. The clear action is added to the toolbar using the <Action> tag, the name parameter in this tag being the string that was passed to the KActionCollection with addAction() in mainwindow.cpp.

Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the File menu of the MenuBar the same way it was added to the toolbar.

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

CMake

Finally, the tutorial3ui.rc needs to go somewhere where KDE can find it (can't just leave it in the source directory!). This means the project needs to be installed 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 with two extra lines at the end that 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. You probably 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), so the following might be appropriate:

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial3

which will create a KDE-like directory structure in your user's home directory directory and will install the executable to $HOME/bin/tutorial3.

Moving On

Now you can move on to saving and loading.


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal