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

    继续进行

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