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

Development/Tutorials/Using_KActions

Languages: عربي | Asturianu | Català | Česky | Kaszëbsczi | Dansk | Deutsch | English | Esperanto | Español | Eesti | فارسی | Suomi | Français | Galego | Italiano | 日本語 | 한국어 | Norwegian | Polski | Português Brasileiro | Română | Русский | Svenska | Slovenčina | Slovenščina | српски | Türkçe | Tiếng Việt | Українська | 简体中文 | 繁體中文

Template:TutorialBrowser (zh TW)

摘要

在本教學中我們將介紹動作(action)的概念。動作是一種提供使用者互動程式的統一方法。

例如，假設我們要為教學 2的使用者提供清除文字區內容的功能，可以是點擊工具列中的按鈕、藉由檔案選單中的選項，或者是通過一個鍵盤快捷鍵。透通過一個KAction，就可以實現上述的全部功能。

KAction

KAction 是一個包含所有動作相關資訊的物件，如圖示、快捷鍵等。你可以將動作連接(connect)到實行運作的 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 建構子裡的參數更新成 tutorial 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()，它負責執行設定 KAction 的全部工作。

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 屬性

文字

Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the KAction's icon in the toolbar. clearAction->setText(i18n("Clear")); Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the i18n tutorial).

圖示

If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE document-new icon through the use of the setIcon() function: clearAction->setIcon(KIcon("document-new"));

鍵盤快捷鍵

Setting a keyboard shortcut to perform our action is equally simple: clearAction->setShortcut(Qt::CTRL + Qt::Key_W); This associates Ctrl+W with the KAction.

加入到動作集

為了讓我們的動作能夠被 XMLGUI 框架訪問(會在後面解釋)，必須將它加入到程式的動作集(action collectio)中。可以像下面這樣，經由actionCollection()函數來訪問動作集： actionCollection()->addAction("clear", clearAction); 這裡我們將KAction物件clearAction加入了動作集，並將其命名為clear。XMLGUI 框架會使用這個名稱(clear)來引用該動作，因此它不應該是區域的，因為它僅能在內部使用。

連接動作

Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the clear() action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit) 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 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.

增加動作到選單和工具列

現在，新的｢Clear｣動作已經創建，但還沒有聯結到任何選單或工具列。這需要使用一項叫做 XMLGUI 的 KDE技術來實現，它會為你實現很多很棒的功能諸如可移動的工具列之類。

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

KXmlGuiWindow 中的 setupGUI() 函數依賴 XMLGUI 系統來建構 GUI，XMLGUI 通過解析 XML 格式的介面描述檔來實現這一功能。

該 XML 檔的命名規範是 appnameui.rc，其中 appname 是你在KAboutData中設定的名稱(在本例中是tutorial3)。因此在我們的例子裡，該檔被命名為tutorial3ui.rc，並置於 build 目錄。這個檔案具體放在何處，是由 CMake 來處理的。

另見 developer.kde.org which still provides valid information for KDE4.

appnameui.rc 檔案

因為 UI 的描述是用 XML 來定義的，因此其排版必須嚴格遵守規範。本教學中不會深入討論這一主題，不過可以訪問詳細的 XMLGUI 頁面以獲取更多資訊(這裡還有一個舊的教學)。

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>

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. Be sure it is an integer, if you use a decimal value, it will not work, but will not notify that it didn't. Note: The version attribute must be an integer number, i.e. it may not contain dots or other non-digits like an application version number.

Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <text/> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.

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:

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.

繼續前進

現在你可以開始學習下一課： 儲存與載入。