Development/Tutorials/Using KActions (se)

How To Use KActions and XmlGui

Tutorial Series	Beginner Tutorial
Previous	Tutorial 2 - KXmlGuiWindow, Basic XML knowledge
What's Next	TODO (milliams)
Further Reading	None

Abstract

Vi ska här introducera konceptet "actions". "Actions" är en enhetlig metod att förse användaren med ett sätt att interagera med ditt program.

Säg, att vi t.e.x. vill låta användaren rensa text arean genom att klicka på en knapp i "toolbaren", från ett alternativ i filmenyn eller genom en tangentbordsgenväg; vi kan göra allt detta med hjälp av en KAction.

KAction

En KAction är ett objekt som innehåller all information om ikonen och genvägen du vill ha associerad till en viss "action". Du kopplar sedan "actionen" till en slot som utför din "actions" arbete.

Skapa din egen

För att skapa en "action", så behöver du #include <KAction> i din .cpp fil.

Skapa objektet

Vi ska skapa en "action" som rensar textarean (se Guide 2). En KAction är uppbyggd i flera steg. Det första är att skapa KAction'en

KAction* clearAction = new KAction(this);

Det här skapar en KAction vid namn clearAction.

Text

Nu när vi har vårt KAction objekt, så kan vi börja med att sätta dess "properties". First sätter vi texten som ska visas i menyn och under ikonen i toolbaren.

clearAction->setText(i18n("Clear"));

Som du kan se, så måste texten gå igenom i18n() funktione om du vill att ditt UI ska vara översättningsbart.

Icon

Om du ska visa din "action" i toolbaren, så lär du vilja ha en ikon för att visa den. För att sätta en ikon så använder vi oss helt enkelt av setIcon() funktionen:

clearAction->setIcon(KIcon("document-new"));

Här sätter vi ikonen till KDE's standard document-new ikon.

Genväg

Vi kan också sätta en genväg som utför våran "action". Det är så enkelt som

clearAction->setShortcut(Qt::CTRL+Qt::Key_W);

för att associera Ctrl+W som genväg till denna "action".

Lägga till i samlingen

För att våran "action" ska vara åtkomlig av XmlGui ramverket så måste det läggas in i applikationens action collection. Det görs via actionCollection() funktionen:

actionCollection()->addAction("clear", clearAction);

Här lägger vi till clearAction KAction till samlingen och ger den namnet clear. Det här namnet används av XmlGui ramverket.

Connecting the action

Nu är vår "action" iordninggjord för använding, och vi måste nu koppla ihop den med något användningsbart. Vi ska koppla vår "action" till clear() "actionen" som tillhör KTextArea.

connect( clearAction, SIGNAL( triggered(bool) ), 
         textArea, SLOT( clear() ) );

Det här är samma som det skulle gjorts i Qt med en QAction.

KStandardAction

För "actions" som med största sannolikhet uppträder i nästan alla KDE-applikationer, som t.e.x. 'quit', 'save', och 'load' finns det för-skapade KActions, i KStandardAction.

Dem är väldigt enkla att använda. Efter att du har gjort #include <KStandardAction>, så behöver du bara ange vad funktionen ska göra, och till vilken KActionCollection den ska läggas till. T.e.x.,

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

kommer att skapa en KAction med rätt ikon, text och genväg och kommer t.o.m. lägga in den i filmenyn.

The Code

mainwindow.h

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
  public:
    MainWindow(QWidget *parent=0);
	
  private:
    KTextEdit* textArea;
    void setupActions();
};

#endif

mainwindow.cpp

#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#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

#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

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

Putting the actions in the menus and toolbars

Än så länge har vi bara skapat vår nya "Clear" action. Den kommer inte att synas i menyerna eller i toolbaren. För att tala om för programmet var våra actions ska användas (och tillåta slutanvändaren att flytta runt dem) så använder vi en KDE teknologi som kallas XmlGui.

XmlGui

Note

I senare versioner av KDE4, kan XmlGui komma att ersättas av ett nytt framework, vid namn "liveui". Just nu, så är dock XmlGui det enda rätta sättet att sätta upp ett UI.

När du anropar setupGUI() i din KXmlGuiWindow klass, anropas XmlGui systemet som läser en XML-filsrepresentation av ditt interface (som vi kommer skapa alldeles strax) och skapar knapparna och menyerna.

XmlGui behöver givetvis veta vilken fil som beskriver interfacet, dvs, den behöver veta dess namn och var den kan hittas någonstans. Regeln för namngivningen är att filen ska heta appnameui.rc (där appname är namnet du satte i KAboutData), så i vårt exempel heter filen tutorial3ui.rc. Var filen finns någonstans hanteras av CMake.

Writing your appnameui.rc File

Eftersom beskrivningen av vårat UI är definierad i XML så måste vissa strikta regler följas.Vi kommer inte att gå igenom all regler i den här guiden, men för mer information se the _detailed_XmlGui_page_ (så fort vi har en fullständig förklaring av XmlGui (eller möjligtvis liveui om det händer någongång snart :)) på wiki, så länkar jag till det).

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" >
      <text>&amp;File</text>
      <Action name="clear" />
    </Menu>
  </MenuBar>

  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
    <ActionList name="dynamicActionlist" />
  </ToolBar>

</gui>

<Toolbar> taggen tillåter dig att beskriva toolbaren. Det är raden på andra sidan av det övre fönstret, med ikonerna. Här ger vi det ett unikt namn 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, 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. 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.

Moving On

TODO