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

From KDE TechBase
Revision as of 15:49, 25 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.

Adding to the Collection

In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's action collection. The action collection is accessed via the actionCollection() function like this: actionCollection()->addAction("clear", clearAction); Here, the clearAction KAction is added to the collection and given a name of clear. This name (clear) is used by the XMLGUI framework to refer to the action, ergo, it should not be localized, since it is used internally only.

連接動作

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.

增加動作到選單和工具列

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.

See also developer.kde.org which still provides valid information for KDE4.

appnameui.rc 檔案

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

繼續前進

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

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