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

    From KDE TechBase
    Revision as of 15:58, 30 May 2008 by Roy (talk | contribs)

    Template:I18n/Language Navigation Bar (zh CN)

    Template:TutorialBrowser (zh CN)

    摘要

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

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

    } 这次,main.cpp中的代码几乎没有什么改动, 只是KAboutData构造器里的说明性参数改成了教程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

    只增加了函数void setupActions(),它负责执行设置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();
    

    }

    解释

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

    创建KAction对象

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

    1. 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"?> <!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>

    <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

    继续进行

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