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

From KDE TechBase
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar (zh_CN)|Development/Tutorials/Using_KActions}}
{{Template:I18n/Language Navigation Bar (zh_CN)|Development/Tutorials/Using_KActions}}


{{TutorialBrowser|
{{TutorialBrowser (zh_CN)|


series=初学者教程|
series=初学者教程|
Line 9: Line 9:
pre=[[Development/Tutorials/Using_KXmlGuiWindow (zh_CN)|教程2 - 创建主窗口]], XML基础知识|
pre=[[Development/Tutorials/Using_KXmlGuiWindow (zh_CN)|教程2 - 创建主窗口]], XML基础知识|


next=TODO (milliams)|  
next=[[Development/Tutorials/Saving_and_loading (zh_CN)|教程4 - 保存与装载]]|  


reading=None
reading=None
}}
}}


==摘要==
== 摘要 ==
在本讲中我们将介绍'''动作(action)'''的概念。动作是一种为用户提供程序交互接口的统一方法。
在本讲中我们将介绍动作(action)的概念。动作是一种为用户提供程序交互接口的统一方法。  
 
例如,假设我们要为[[Development/Tutorials/Using_KXmlGuiWindow (zh_CN)|教程2 - 创建主窗口]]的用户提供通过点击工具栏中的按钮,通过菜单中的一个菜单项,再或者是通过一个组合快捷键,来清除文本区内容的功能。通过一个{{class|KAction}}对象,就可以实现上述的全部功能。
例如,我们需要为用户提供一个清除文本输入框内全部文字的功能,该功能可以通过点击工具栏中的一个按钮,或者通过菜单中的一个菜单项,再或者是通过一个组合快捷键来访问。只需要通过一个{{class|KAction}},我们就可以全部实现上面这些功能。


[[image:introtokdetutorial3.png|frame|center]]
[[image:introtokdetutorial3.png|frame|center]]


==KAction==
== KAction ==
A {{class|KAction}} is an object which contains all the information about the icon and shortcuts you want associated to a certain action. You then connect the action to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.
{{class|KAction}是一个包含着与某个动作有关的所有信息(如图标、快捷方式等)的对象。你可以将动作连接到实际执行工作的[http://doc.trolltech.com/latest/signalsandslots.html slot]上。


===创建你自己的动作(Action)===
== 代码 ==


To create an action, you need to <tt>#include <KAction></tt> in your <tt>.cpp</tt> file.
===main.cpp===
=====创建对象=====
<syntaxhighlight lang="cpp-qt" line>
We're going to create an action which will clear the text area (see Tutorial 2). The KAction is built up in a number of steps. The first is creating the KAction
#include <KApplication>
<code cppqt>KAction* clearAction = new KAction(this);</code>
#include <KAboutData>
This creates a KAction called <tt>clearAction</tt>.
#include <KCmdLineArgs>
=====文字=====
Now we have our KAction object, we can start setting its properties. First, we'll set the text that will be displayed in the menu and under its icon in the toolbar.
<code cppqt>clearAction->setText(i18n("Clear"));</code>
As you can see, the text must be passed through the i18n() function if you want your UI to be translatable.


=====图标=====
#include "mainwindow.h"
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:
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
Here we're setting the icon to the standard KDE <tt>document-new</tt> icon.


=====快捷键=====
int main (int argc, char *argv[])
We can also set a shortcut that will perform our action. It's as simple as a
{
<code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
  KAboutData aboutData( "tutorial3", "tutorial3",
to set Ctrl+W to be associated to this action.
      ki18n("Tutorial 3"), "1.0",
=====添加到集合中=====
      ki18n("A simple text area using KAction etc."),
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:
      KAboutData::License_GPL,
<code cppqt>
      ki18n("Copyright (c) 2007 Developer") );
actionCollection()->addAction("clear", clearAction);
  KCmdLineArgs::init( argc, argv, &aboutData );
</code>
  KApplication app;
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.
=====连接到动作=====
  MainWindow* window = new MainWindow();
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.
  window->show();
<code cppqt>
  return app.exec();
connect( clearAction, SIGNAL( triggered(bool) ),
}
        textArea, SLOT( clear() ) );
</syntaxhighlight>
</code>
这次,<tt>main.cpp</tt>中的代码几乎没有什么改动, 只是KAboutData构造器里的说明性参数改成了教程3。
This is the same as it would be done in Qt with a {{qt|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 {{class|KStandardAction}}.
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,
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
Will Create a KAction with the correct icon, text and shortcut and will even add it to the File menu.
==代码==
===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 87: Line 69:


#endif
#endif
</code>
</syntaxhighlight>
只增加了函数<tt>void setupActions()</tt>,它负责执行设置KActions的全部工作。


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


Line 113: 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 123: Line 106:
   setupGUI();
   setupGUI();
}
}
</code>
</syntaxhighlight>
 
== 解释 ==
本教程的代码基于 [[Development/Tutorials/Using_KXmlGuiWindow (zh_CN)|教程2 - 创建主窗口]] 中的KXmlGuiWindow代码。大部分改动都发生在<tt>mainwindow.cpp</tt>里,其中一个重要的结构变化是,MainWindow的构造函数现在调用<tt>setupActions()</tt>而不再调用<tt>setupGUI()</tt>。在<tt>setupActions()</tt>函数中包含了新的KAction相关代码,并最终自行调用了<tt>setupGUI()</tt>函数。
 
===创建KAction对象===
我们将通过一系列的步骤来创建KAction对象。首先,在代码中包含对<tt>KAction</tt> 库的声明名并创建KAction对象:
<syntaxhighlight lang="cpp-qt">
#include <KAction>
...
KAction* clearAction = new KAction(this);
</syntaxhighlight>
上面这行代码创建了一个叫做<tt>clearAction</tt>的对象。
 
===设置KAction对象属性===
====文字====
有了KAction对象之后,我们就可以来设置它的属性。下面这段代码设置了显示在菜单中和工具栏图标下的文字。
<syntaxhighlight lang="cpp-qt">clearAction->setText(i18n("Clear"));</syntaxhighlight>
注意,文字首先被i18n()函数所处理。这是翻译用户界面所必须的(更多信息,可参考[[Development/Tutorials/Localization/i18n (zh_CN)|i18n教程]])。
 
====图标====
如果你希望动作能显示在工具栏中,那么就需要给它指定一个图标。下面的代码使用<tt>setIcon()</tt>函数,将标准KDE的<tt>document-new</tt>图标设置为动作的图标:
<syntaxhighlight lang="cpp-qt">clearAction->setIcon(KIcon("document-new"));</syntaxhighlight>
 
====快捷键====
设定我们的动作所对象的快捷键很简单:
<syntaxhighlight lang="cpp-qt">clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</syntaxhighlight>
这将Ctrl+W关联到我们的KAction对象。
 
===添加到动作集===
为了让我们的动作能够被XmlGui架构访问(会在后面解释) ,必须将它添加到程序的“动作集”中。可以像下面这样,使用<tt>actionCollection()</tt>函数来访问动作集:
<syntaxhighlight lang="cpp-qt">
actionCollection()->addAction("clear", clearAction);
</syntaxhighlight>
这里我们将KAction对象<tt>clearAction</tt>加入了动作集,并将其命名为“clear”。 XmlGui架构会使用这个名字来引用该动作。


===main.cpp===
====连接到动作====
<code cppqt n>
完成对动作的设置之后,接下来我们需要将它连接到实际进行处理的部分。在这里(因为我们希望清除文件区中的内容),我们将动作连接到KTextEdit对象的<tt>clear()</tt>方法。
#include <KApplication>
<syntaxhighlight lang="cpp-qt">
#include <KAboutData>
connect( clearAction, SIGNAL( triggered(bool) ),
#include <KCmdLineArgs>
        textArea, SLOT( clear() ) );
</syntaxhighlight>
这与Qt里的{{qt|QAction}}的用法是相同的。
 
===KStandardAction===
对于那些几乎在所有KDE程序中出现的动作,如“退出”,“保存”及“载入”等,KDE提供了一些预定义的KAction对象。可以通过[http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction]来访问它们。
 
使用它们很简单。只要在代码中包含了有关的库(#include <KStandardAction>), 你只需要简单的将你希望执行的方法和要加入的KActionCollection动作集提供给它即可。例如,
<syntaxhighlight lang="cpp-qt">KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</syntaxhighlight>
将会自动创建一个带有正确的图标、文本和快捷键的KAction对象,并自动加入文档菜单。


#include "mainwindow.h"
==将动作添加到菜单和工具栏==
现在,新的“Clear”动作已经创建,但还没有与任何菜单或工具栏相关联。这需要通过一项叫做XMLGUI的KDE技术来实现,它会自动为你实现诸如可移动的工具栏之类的功能。


int main (int argc, char *argv[])
{{note|在以后的KDE4版本中, XMLGUI, 可能会被叫做liveui的新架构所替代。不过,目前XMLGUI还仍是唯一正确的设置用户界面的方法。}}
{
  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>


==将动作放到菜单和工具栏中==
==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.
{{class|KXmlGuiWindow}}中的<tt>setupGUI()</tt>函数依赖XMLGUI系统来创建图形用户界面。XMLGUI通过解析XML格式的界面描述文件来实现这一功能。


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.
该XML文件的命名规范是<tt>appnameui.rc</tt>, 其中<tt>appname</tt>是你在{{class|KAboutData}}中设置的程序名 (在本例中是“tutorial3”)。因此在我们的例子里,该文件被命名为<tt>tutorial3ui.rc</tt>, 位于build目录。这个文件具体放在何处,是由CMake来处理的。


===编写你自己的''程序名''ui.rc文件===
==''appname''ui.rc 文件==


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).
因为用户界面的描述是用XML来定义的,因此其布局必须严格遵守规范。在本教程中将不会深入讨论这一主题,不过可以访问 [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]] 以获取更多信息。(这里还有一个旧的教程: [http://developer.kde.org/documentation/tutorials/xmlui/preface.html])


===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" >
      <text>&amp;File</text>
       <Action name="clear" />
       <Action name="clear" />
     </Menu>
     </Menu>
   </MenuBar>
   </MenuBar>
  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
  </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.


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.
<tt><Toolbar></tt>标签允许你定义工具栏,即窗口上部包含图标的长条。这里,它被赋予了一个唯一的名字“mainToolBar”,并用<tt><text></tt>将它的用户可见名称设成了“Main Toolbar”。通过<tt><Action></tt>标签,“clear”动作被添加到了工具栏中。注意,该标签的“name”参数应该是在<tt>mainwindow.cpp</tt>中用<tt>addAction()</tt>传递给KActionCollection的那个名字。


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.
除了在工具栏中添加该工作外,它也可以被添加到菜单栏中。这里,用与工具栏添加同样的方法,将该工作添加到了<tt>工具栏(MenuBar)</tt>里的“File”菜单中。


Change 'version' attribute of the gui tag if you changed .rc file since last install to force system cache update
如果你在上次安装后又对.rc文件作了更新,那么需要修改<tt><nowiki><gui></nowiki></tt>标签中的“version”属性,以强制更新系统缓存。


==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.'''
最后, 需要将<tt>tutorial3ui.rc</tt>文件放到KDE系统可以找到的地方(不可以仅将它放到源目录中!). '''这意味着需要将项目安装到某个地方。'''
===CMakeLists.txt===
===CMakeLists.txt===
<code>
<syntaxhighlight lang="ini" line>
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 209: Line 221:


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>
</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.
这个文件几乎与教程二里的相同,除了最后多出两行来描述文件将被安装到何处。首先, <tt>tutorial3</tt>目标被安装到<tt>BIN_INSTALL_DIR</tt>;然后描述用户界面布局的<tt>tutorial3ui.rc</tt>文件被安装到了应用程序数据目录。


===Make, 安装和运行===
===编译, 安装与运行===
If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.
如果你没有KDE4安装目录的写权限,可以将它安装到你的主目录下的某个文件夹里。


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
通过<tt>DCMAKE_INSTALL_PREFIX</tt>开关项,可以告诉CMake将程序安装到何处。也许你正希望将它安装到本地的某处进行测试(直接将这些教程安装到你的KDE目录里可能有点傻),因此下面的做法可能比较合适:
  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
这将会在你的用户主目录下创建一个结构类似于KDE目录的目录,并将可执行文件安装到 {{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}}.


==继续前进==
==继续进行==
TODO
现在,你可以继续学习下一教程:[[Development/Tutorials/Saving_and_loading (zh_CN)|保存与载入]].


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

Latest revision as of 12:34, 23 June 2013

Template:I18n/Language Navigation Bar (zh CN)

Template:TutorialBrowser (zh CN)

摘要

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

KAction

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

代码

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

这次,main.cpp中的代码几乎没有什么改动, 只是KAboutData构造器里的说明性参数改成了教程3。

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

只增加了函数void setupActions(),它负责执行设置KActions的全部工作。

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

解释

本教程的代码基于 教程2 - 创建主窗口 中的KXmlGuiWindow代码。大部分改动都发生在mainwindow.cpp里,其中一个重要的结构变化是,MainWindow的构造函数现在调用setupActions()而不再调用setupGUI()。在setupActions()函数中包含了新的KAction相关代码,并最终自行调用了setupGUI()函数。

创建KAction对象

我们将通过一系列的步骤来创建KAction对象。首先,在代码中包含对KAction 库的声明名并创建KAction对象:

#include <KAction>
...
KAction* clearAction = new KAction(this);

上面这行代码创建了一个叫做clearAction的对象。

设置KAction对象属性

文字

有了KAction对象之后,我们就可以来设置它的属性。下面这段代码设置了显示在菜单中和工具栏图标下的文字。

clearAction->setText(i18n("Clear"));

注意,文字首先被i18n()函数所处理。这是翻译用户界面所必须的(更多信息,可参考i18n教程)。

图标

如果你希望动作能显示在工具栏中,那么就需要给它指定一个图标。下面的代码使用setIcon()函数,将标准KDE的document-new图标设置为动作的图标:

clearAction->setIcon(KIcon("document-new"));

快捷键

设定我们的动作所对象的快捷键很简单:

clearAction->setShortcut(Qt::CTRL + Qt::Key_W);

这将Ctrl+W关联到我们的KAction对象。

添加到动作集

为了让我们的动作能够被XmlGui架构访问(会在后面解释) ,必须将它添加到程序的“动作集”中。可以像下面这样,使用actionCollection()函数来访问动作集:

actionCollection()->addAction("clear", clearAction);

这里我们将KAction对象clearAction加入了动作集,并将其命名为“clear”。 XmlGui架构会使用这个名字来引用该动作。

连接到动作

完成对动作的设置之后,接下来我们需要将它连接到实际进行处理的部分。在这里(因为我们希望清除文件区中的内容),我们将动作连接到KTextEdit对象的clear()方法。

connect( clearAction, SIGNAL( triggered(bool) ), 
         textArea, SLOT( clear() ) );

这与Qt里的QAction的用法是相同的。

KStandardAction

对于那些几乎在所有KDE程序中出现的动作,如“退出”,“保存”及“载入”等,KDE提供了一些预定义的KAction对象。可以通过KStandardAction来访问它们。

使用它们很简单。只要在代码中包含了有关的库(#include <KStandardAction>), 你只需要简单的将你希望执行的方法和要加入的KActionCollection动作集提供给它即可。例如,

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

将会自动创建一个带有正确的图标、文本和快捷键的KAction对象,并自动加入文档菜单。

将动作添加到菜单和工具栏

现在,新的“Clear”动作已经创建,但还没有与任何菜单或工具栏相关联。这需要通过一项叫做XMLGUI的KDE技术来实现,它会自动为你实现诸如可移动的工具栏之类的功能。

Note
在以后的KDE4版本中, XMLGUI, 可能会被叫做liveui的新架构所替代。不过,目前XMLGUI还仍是唯一正确的设置用户界面的方法。


XMLGUI

KXmlGuiWindow中的setupGUI()函数依赖XMLGUI系统来创建图形用户界面。XMLGUI通过解析XML格式的界面描述文件来实现这一功能。

该XML文件的命名规范是appnameui.rc, 其中appname是你在KAboutData中设置的程序名 (在本例中是“tutorial3”)。因此在我们的例子里,该文件被命名为tutorial3ui.rc, 位于build目录。这个文件具体放在何处,是由CMake来处理的。

appnameui.rc 文件

因为用户界面的描述是用XML来定义的,因此其布局必须严格遵守规范。在本教程中将不会深入讨论这一主题,不过可以访问 detailed XMLGUI page 以获取更多信息。(这里还有一个旧的教程: [1])。

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

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

</gui>

<Toolbar>标签允许你定义工具栏,即窗口上部包含图标的长条。这里,它被赋予了一个唯一的名字“mainToolBar”,并用<text>将它的用户可见名称设成了“Main Toolbar”。通过<Action>标签,“clear”动作被添加到了工具栏中。注意,该标签的“name”参数应该是在mainwindow.cpp中用addAction()传递给KActionCollection的那个名字。

除了在工具栏中添加该工作外,它也可以被添加到菜单栏中。这里,用与工具栏添加同样的方法,将该工作添加到了工具栏(MenuBar)里的“File”菜单中。

如果你在上次安装后又对.rc文件作了更新,那么需要修改<gui>标签中的“version”属性,以强制更新系统缓存。

CMake

最后, 需要将tutorial3ui.rc文件放到KDE系统可以找到的地方(不可以仅将它放到源目录中!). 这意味着需要将项目安装到某个地方。

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)

这个文件几乎与教程二里的相同,除了最后多出两行来描述文件将被安装到何处。首先, tutorial3目标被安装到BIN_INSTALL_DIR;然后描述用户界面布局的tutorial3ui.rc文件被安装到了应用程序数据目录。

编译, 安装与运行

如果你没有KDE4安装目录的写权限,可以将它安装到你的主目录下的某个文件夹里。

通过DCMAKE_INSTALL_PREFIX开关项,可以告诉CMake将程序安装到何处。也许你正希望将它安装到本地的某处进行测试(直接将这些教程安装到你的KDE目录里可能有点傻),因此下面的做法可能比较合适:

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

这将会在你的用户主目录下创建一个结构类似于KDE目录的目录,并将可执行文件安装到 $HOME/bin/tutorial3

继续进行

现在,你可以继续学习下一教程:保存与载入.