Development/Tutorials/Using KActions (fi)

From KDE TechBase


Development/Tutorials/Using_KActions


Perehdytys 3 - KActions ja XMLGUI
Tutorial Series   Beginner Tutorial
Previous   Perehdytys 2 - Main-ikkunan luonti, XML perustietous
What's Next   Tutorial 4 - Saving and loading
Further Reading   None

Lyhyesti

Tämä perehdytys esittelee toiminnot. Toiminnot tarjoavat yhtenäisen tavan käyttäjälle vuorovaikuttaa ohjelman kanssa.

Jos esimerkiksi haluamme antaa perehdytyksessä 3 käyttäjlle mahdollisuuden tyhjentää tekstieditori hiiren näpäytyksellä työkaluriviltä, vaihtoehtoisesti Tiedosto-valikon kautta tai näppäinyhdistelmän avulla, voidaan tämä tehdä helposti käyttämällä KAction-luokkaa.

KAction

KAction on objekti joka sisältää kaiken tarvittavan tiedon ikonista ja näppäinyhdistelmistä jotka on yhdistetty joihinkin toimintoon. Toiminto taas on yhdistetty slot:n joka huolehtii toiminnon suorittamisesta.

Koodi

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

} Tällä kerralla muutokset tähän tiedostoon ovat hyvin vähäisiä. Ainoastaan "tutorial 2" on korjattu "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

Otsikkotiedostoon on lisätty void setupActions() jossa tehdään kaikki tarvittavat asettelut toimintoa varten.

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

}

Selvitys

Tämä perehdytys perustuu edelliseen perehdytykseen. Suurin osa koodi muutoksista on mainwindow.cpp tiedostossa. Muodostajassa kutsutaan nyt setupActions() setupGUI() sijaan. setupActions():ssa sijaitsee uusi KAction koodi joka lopuksi kutsuu setupGUI()-funktiota.

KAction objektin luominen

KActionin käyttöönotossa on muutamia vaiheita. Ensimmäinen on sisällyttää KAction-kirjasto ja luoda uusi KAction:

  1. include <KAction>

... KAction* clearAction = new KAction(this);

KAction:n ominaisuuksien asettelu

Teksti

Nyt meillä siis on KAction objekti, joten voimme alkaa muokkaamaan sen ominaisuuksia. Seuraava koodi asettaa tekstin joka näytetään valikossa sekä työkaluvalikossa olevan ikonin alapuolella. clearAction->setText(i18n("Clear")); Huomaa että teksti on syötetty i18n()-funktionin läpi. Tämä on pakollinen jotta käyttöliittymä on käännettävissä eri kielille. Lisätietoja lokalisoinnista löytyy i18n perehdytyksestä).

Ikoni

Jos toiminto on aikomus näyttää työkalurivillä, olisi hyvä jos sillä olisi toimintoa kuvaava ikoni. Seuraava koodi asettaa standardin KDE document-new(Uusi asiakirja) ikonin clearAction toiminnolle: clearAction->setIcon(KIcon("document-new"));

Pikanäppäinyhdistelmä

Pikanäppäinyhdistelmän asettaminen toiminnollemme on yhtälailla helppo. Seuraava koodi osoittaa yhdistelmän Ctrl+W clearAction toiminnolle: clearAction->setShortcut(Qt::CTRL + Qt::Key_W);

Kokoelmaan lisääminen

Jotta toimintoon olisi mahdollista päästä käsiksi XMLQUI-kehyksen(selitetty tarkemmin myöhemmin) läpi, se pitää lisätä ohjelman toiminto kokoelmaan. Toimintokokoelmaa käsitellään actionCollection()-funktion avulla seuraavasti: actionCollection()->addAction("clear", clearAction); Tässä clearAction KAction on lisätty kokoelmaan nimellä clear. Nimeä (clear) on käytetään XMLQUI-kehyksessä kuvaamaan tätä toimintoa.

Toiminnon yhdistäminen

Kun toiminto on asetettu kuntoon, si pitää yhdistää johonkin joka toteuttaa toiminnon. Tässä tapauksessa (koska haluamme tyhjentää tekstialueen), yhdistämme toiminnon KTextEdit:n kuuluvaan clear()-funktioon (joka tyhjentää tekstialueen) seuraavasti: connect( clearAction, SIGNAL( triggered(bool) ), 

        textArea, SLOT( clear() ) );

Tämä sama voidaan tehdä Qt:n kanssa käyttämällä QAction.

KStandardAction

Toimintoja varten jotka esiintyvät lähes jokaisessa KDE ohjelmassa kuten 'sulje', 'tallenna' ja 'avaa' on olemassa valmiiksi luotuja sopivia toimintoja jotka on käytettävissä KStandardAction:n avulla.

Nämä ovat erittäin helppoja ottaa käyttöön. Kun ensin on otettu kirjasto käyttöön (#include <KStandardAction>), tarvitsee vain ottaa haluttu toiminto käyttöön, esim: KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); Tämä luo Lopeta-toiminnon, oikean ikonin, tekstin ja pikanäppäinyhdistelmän kanssa sekä jopa lisää sen Tiedosto-valikkoon.

Adding the action to menus and toolbars

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.

appnameui.rc File

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.

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" />
 </ToolBar>
 <MenuBar>
   <Menu name="file" >
     <Action name="clear" />
   </Menu>
 </MenuBar>

</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.

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.

Moving On

Now you can move on to saving and loading.

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