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

使用KActions

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

摘要

在本讲中我们将介绍动作(action)的概念。动作是一种为用户提供程序交互接口的统一方法。

例如，假设我们需要为用户提供一个清除文本输入框内全部文字的功能，并希望用户可以通过点击工具栏中的一个按钮，或者通过菜单中的一个菜单项，再或者是通过一个组合快捷键来执行该功能。在KDE中，我们只需要通过一个KAction，就可以实现上述的全部功能。

KAction

KAction是一个包含着与某个动作有关的所有信息（如图标、快捷方式等）的对象。你可以将动作连接到实际执行工作的slot上。

创建你自己的动作

要创建一个动作，首先需要在你的.cpp文件中包含#include <KAction> 。

创建对象

下面，我们将创建一个动作来清除文本区（见教程2）中的内容。 我们将通过一系列的步骤来创建这个动作。首先是创建KAction对象： KAction* clearAction = new KAction(this); 上面这行代码创建了一个叫做clearAction的KAction对象。

文字

有了KAction对象之后，我们就可以来设置它的属性。 首先，我们要设置显示在菜单中和工具栏图标下的文字。 clearAction->setText(i18n("Clear")); 正如你所看到的那样，如果你希望你的用户界面能够被正确本地化（i18n），就要先用 i18n()来处理要显示文字。

图标

如果你希望动作能显示在工具栏中，那么就需要给它指定一个图标。用setIcon() 函数即可实现该功能: clearAction->setIcon(KIcon("document-new")); 这里我们设置使用标准KDE的document-new（新建文档）图标.

快捷键

我们也需要给动作设置一个快捷键。只需要简单的通过代码 clearAction->setShortcut(Qt::CTRL+Qt::Key_W); 来将Ctrl+W设置为快捷键。

添加到集合中

In order for our action to be accessable by the XmlGui framework it must be added to the application's action collection. It is accessed via the actionCollection() function thus: actionCollection()->addAction("clear", clearAction); Here we add the clearAction KAction to the collection and give it a name of clear. This name is used by the XmlGui framework.

连接到动作

Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the clear() action belonging to a KTextArea. connect( clearAction, SIGNAL( triggered(bool) ),

        textArea, SLOT( clear() ) );

This is the same as it would be done in Qt with a QAction.

KStandardAction

For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience KActions, accessed through KStandardAction.

They are very simple to use. Once you've done #include <KStandardAction>, you simply need to 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()); Will Create a KAction with the correct icon, text and shortcut and will even add it to the File menu.

代码

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

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

}

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

}

将动作放到菜单和工具栏中

Now, at the moment, we've only created our new "Clear" action. It won't yet show up in the menus or in the toolbars. To tell the program where to put our actions (and to allow the end-user to move them around) we use a KDE technology called XmlGui.

XmlGui

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.

When you call setupGUI() in your KXmlGuiWindow class, it calls the XmlGui system which reads an XML file description of your interface (which we will create in a minute) and creates the buttons and menus appropriately.

Now obviously XmlGui needs to know which file is your description file, i.e. it needs to know its name and location. The rule for the naming is the file should be called appnameui.rc (where appname is the name you set in KAboutData), so in our example, the file will be called tutorial3ui.rc. Where the file will be located is handled by CMake.

编写你自己的程序名ui.rc文件

Since the description of our UI is being defined with XML, the layout of the description must follow strict rules. We won't go through all the rules in this tutorial but for more information, see the _detailed_XmlGui_page_ (once we have a full explanation of XmlGui (or possibly liveui if that's done soon :)) on the wiki, I'll link it up).

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" />
   <ActionList name="dynamicActionlist" />
 </ToolBar>
 <MenuBar>
   <Menu name="file" >
     <text>&File</text>
     <Action name="clear" />
   </Menu>
 </MenuBar>

</gui>

The <Toolbar> tag allows you to describe the toolbar. That is the bar across the top of the window with the icons. Here we give it a unique name mainToolBar, set it's user visible name Main Toolbar using the <text> tag and finally add our clear action to the toolbar using the <Action> tag. The name parameter in this tag relates to the string that was passed to the addAction() function in the C++ code.

As well as having our action in the toolbar, we can also add it to the menubar. Within the <MenuBar> tag, we say we want to add our action to the File menu and we add the action in the same way as for the toolbar.

Please note you can also add dynamic action list to your configuration file using a <ActionList> tag. For more information about this, see the plugActionList() method of the KXMLGUIClient documentation.

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

CMake

Now that we're using XmlGui, we need to put the tutorial3ui.rc somewhere where KDE can find it. This means we need to install our project 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 it has two extra lines at the end. These 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, 安装和运行

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. So to install the program to the KDE directory, do

cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3

Though, if you 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) you can do something like

cmake . -DCMAKE_INSTALL_PREFIX=/home/kde-devel/kdetmp

which will create a KDE-like directory structure under ~/kdetmp and will install the executable to /home/kde-devel/kdetmp/bin/tutorial3.

继续前进

TODO