Archive:Development/Tutorials/Using KActions (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。

继续进行

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