Archive:Development/Tutorials/Using KActions (zh CN)

From KDE TechBase

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

继续进行

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