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

From KDE TechBase
Revision as of 02:26, 26 September 2009 by Alisha (talk | contribs)


Development/Tutorials/Using_KActions


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

對於那些幾乎在所有KDE程式中出現的動作，如「離開」(quit)、「儲存」(save)及「載入」(load)等，KDE提供了一些預定義的KAction。可以透過KStandardAction 來訪問它們。

使用它們很簡單。只要含入有關的函式庫（#include <KStandardAction>)），簡單的將你希望執行的函數和要加入的 KActionCollection 提供給它即可。例如：

KStandardAction::quit(kapp, SLOT(quit()), actionCollection());

這會創建一個帶有正確的圖示、文字和快捷鍵的KAction，並加入檔案選單。

增加動作到選單和工具列

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

Note
在 KDE4 之後的版本中，XMLGUI 可能會被叫做 liveui 的新框架所取代。不過,目前 XMLGUI 還仍是唯一正確設定 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>

<Toolbar> 標籤讓你可以描述工具列(toolbar)，即視窗上部包含圖示的長條。這裡它被賦予了一個唯一的名字 mainToolBar ，並用 <text> 標籤將它的用戶可見名稱設成了 Main Toolbar 。使用 <Action> 標籤，加入 clear 動作到了工具列中。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.

除了在工具列中加入動作外，它也可以被加入到選單列(menubar)中。這裡用與加入工具列同樣的方法，將該動作增加到 MenuBar 裡的 File 選單中。

如果你在上次安裝後又對.rc 檔作了更新，那麼需要修改<gui>標籤中的 'version' 屬性，以強制更新系統快取。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

最後,需要將 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)

這個檔案幾乎與教學2裡的相同，除了最後多出兩行來描述檔案將被安裝到何處。首先, tutorial3 目標被安裝到 BIN_INSTALL_DIR；然後描述用戶界面排版的 tutorial3ui.rc 檔被安裝到了應用程式的 data 目錄。

編譯、安裝與運行

如果你沒有 KDE4 安裝目錄的寫入權限，可以將它安裝到你的家目錄下的某個資料夾裡。

設定 DCMAKE_INSTALL_PREFIX 開關項，可以告訴 CMake 將程式安裝到何處。也許你只希望將它安裝到本地的某處進行測試(直接將這些教程安裝到你的KDE目錄裡可能有點傻)，因此下面的做法可能比較合適： 

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

這將會在你的使用者家目錄下創建一個結構類似於KDE目錄的目錄，並將可執行檔安裝到$HOME/bin/tutorial3 。

繼續前進

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

Retrieved from "https://techbase.kde.org/index.php?title=Archive:Development/Tutorials/Using_KActions_(zh_TW)&oldid=44998"