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

使用KActions

Tutorial Series	初学者教程
Previous	教程2 - 创建主窗口, XML基础知识
What's Next	TODO (milliams)
Further Reading	None

摘要

在本讲中我们将介绍动作(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()函数。

Creating the KAction object

我们将通过一系列的步骤来创建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对象，并自动加入文档菜单。

They are very simple to use. Once the library has been included (#include <KStandardAction>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example: KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.

Adding the action to menus and toolbars

At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.

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.

XMLGUI

The setupGUI() function in KXmlGuiWindow depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.

The rule for naming this XML file is appnameui.rc, where appname is the name you set in KAboutData (in this case, tutorial3). So in our example, the file is called tutorial3ui.rc, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.

appnameui.rc File

Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the detailed XMLGUI page (here is an older tutorial: [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>

The <Toolbar> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name mainToolBar and its user visible name set to Main Toolbar using the <text> tag. The clear action is added to the toolbar using the <Action> tag, the name parameter in this tag being the string that was passed to the KActionCollection with addAction() in mainwindow.cpp.

Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the File menu of the MenuBar the same way it was added to the toolbar.

Change the 'version' attribute of the <gui> tag if you changed .rc file since the last install to force a system cache update.

CMake

Finally, the tutorial3ui.rc needs to go somewhere where KDE can find it (can't just leave it in the source directory!). This means the project needs to be installed somewhere.

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}) 将会自动创建一个带有正确的图标、文本和快捷键的KAction对象，并自动加入文档菜单。

They are very simple to use. Once the library has been included (#include <KStandardAction>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example: KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.

Adding the action to menus and toolbars

At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.

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.

XMLGUI

The setupGUI() function in KXmlGuiWindow depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.

The rule for naming this XML file is appnameui.rc, where appname is the name you set in KAboutData (in this case, tutorial3). So in our example, the file is called tutorial3ui.rc, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.

appnameui.rc File

Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the detailed XMLGUI page (here is an older tutorial: [2]).

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>

The <Toolbar> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name mainToolBar and its user visible name set to Main Toolbar using the <text> tag. The clear action is added to the toolbar using the <Action> tag, the name parameter in this tag being the string that was passed to the KActionCollection with addAction() in mainwindow.cpp.

Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the File menu of the MenuBar the same way it was added to the toolbar.

Change the 'version' attribute of the <gui> tag if you changed .rc file since the last install to force a system cache update.

CMake

Finally, the tutorial3ui.rc needs to go somewhere where KDE can find it (can't just leave it in the source directory!). This means the project needs to be installed somewhere.

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)

This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the tutorial3 target is installed to the BIN_INSTALL_DIR then the tutorial3ui.rc file that describes the layout of the user interface is installed to the application's data directory.

Make, Install And Run

If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.

To tell CMake where to install the program, set the DCMAKE_INSTALL_PREFIX switch. You probably 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), so the following might be appropriate:

mkd

target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR}) install(FILES tutorial3ui.rc

       DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)

This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the tutorial3 target is installed to the BIN_INSTALL_DIR then the tutorial3ui.rc file that describes the layout of the user interface is installed to the application's data directory.

Make, Install And Run

If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.

To tell CMake where to install the program, set the DCMAKE_INSTALL_PREFIX switch. You probably 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), so the following might be appropriate:

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

which will create a KDE-like directory structure in your user's home directory directory and will install the executable to $HOME/bin/tutorial3.

Moving On

Now you can move on to saving and loading.