Development/Tutorials/Using KActions (fi)

< Development | Tutorials

Opas 3 - KActions ja XMLGUI

Tutorial Series	Beginner Tutorial
Prerequisites	Opas 2 - main-ikkunan luonti, XML-perustietous
What's Next	Opas 4 - tallentaminen ja avaaminen
Further Reading	None

[edit] Lyhyesti

Tämä opas esittelee toiminnot, engl. actions. Toiminnot tarjoavat yhtenäisen tavan vuorovaikuttaa ohjelman kanssa.

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

[edit] KAction

KAction on objekti joka sisältää kaiken tarvittavan tiedon kuvakkeesta ja näppäinyhdistelmistä, jotka on liitetty johonkin toimintoon. Toiminto taas on yhdistetty slotiin, joka huolehtii toiminnon suorittamisesta.

[edit] Koodi

[edit] 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();
}

Tällä kerralla muutokset tähän tiedostoon ovat hyvin vähäisiä. Ainoastaan "tutorial 2" on korjattu "tutorial 3".

[edit] 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

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

[edit] 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();
}

[edit] Selvitys

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

[edit] KAction objektin luominen

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

#include <KAction>
...
KAction* clearAction = new KAction(this);

[edit] KAction:n ominaisuuksien asettelu

[edit] 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 kuvakkeen alapuolella.

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

Huomaa että teksti on syötetty i18n()-funktion läpi. Tämä on välttämätöntä jotta käyttöliittymä on käännettävissä eri kielille. Lisätietoja lokalisoinnista löytyy i18n perehdytyksestä).

[edit] Ikoni

Jos toiminto on tarkoitus näyttää työkalurivillä, olisi hyvä jos sillä olisi toimintoa kuvaava ikoni. Seuraava koodi asettaa standardin KDE document-new(Uusi asiakirja) -kuvakkeen clearAction toiminnolle:

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

[edit] 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);

[edit] Kokoelmaan lisääminen

Jotta toimintoon olisi mahdollista päästä käsiksi XMLGUI-kehyksen (selitetään tarkemmin myöhemmin) kautta, se pitää lisätä ohjelman toimintokokoelmaan. Toimintokokoelmaa käsitellään actionCollection()-funktion avulla seuraavasti:

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

Tässä clearAction KAction on lisätty kokoelmaan nimellä clear. Nimeä (clear) käytetään XMLGUI-kehyksessä kuvaamaan tätä toimintoa.

[edit] Toiminnon yhdistäminen

Kun toiminto on asetettu kuntoon, se 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.

[edit] KStandardAction

Lähes jokaisessa KDE-ohjelmassa esiintyviä toimintoja varten (esim. 'sulje', 'tallenna' ja 'avaa') on olemassa valmiita toimintoja, jotka ovat 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 kuvakkeen, tekstin ja pikanäppäinyhdistelmän kanssa. Toiminto myös lisätään Tiedosto-valikkoon.

[edit] Toiminnon lisääminen valikoihin ja työkaluriville

Tällä hetkellä uusi "Tyhjennä" toiminto on luotu. Sitä ei kuitenkaan ole vielä yhdistetty yhteenkään valikkoon tai työkaluriviin. Tähän tarkoitukseen käytämme XMLGUI-nimistä KDE-tekniikkaa. Sen avulla voidaan toteuttaa esimerkiksi siirrettävät työkalurivit.

Note

Myöhemmissä KDE4 versioisssa XMLGUI-kehys saatetaan vaihtaa liveui-kehykseen, mutta tällä hetkellä XMLGUI on ainoa oikea tapa asettaa käyttöliittymä

[edit] XMLGUI

KXmlGuiWindow:n setupGUI()-funktion käyttöliittymän muodostus on riippuvainen XMLGUI-järjestelmästä, joka hakee XML-tiedostosta käyttöliittymän muodostuksessa tarvittavat tiedot.

XML-tiedoston nimeämissäännöt ovat riippuvaisia ohjelmannimestä, joka on asetettu KAboutData:ssa (tässä tapauksessa tutorial3) siten että XML-tiedostonimi muodostuu: ohjelmannimi + ui.rc (tässä tapauksessa siis tutorial3ui.rc).

[edit] ohjelmannimiui.rc - tiedosto

Koska käyttöliittymä on määritelty XML-tiedoston avulla, ulkoasun täytyy noudattaa tiettyjä sääntöjä. Tämä opas ei paneudu kovin syvällisesti tähän aiheeseen. Lisätietoja: XMLGUI - Tekniikka(tulossa ?).

[edit] 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>-kohdassa kuvaillaan ikkunan yläosassa, yleensä kuvakkein varusteltu, vaakasuuntainen laidasta laitaan sijaitseva työkalurivi. Tässä tapauksessa työkaluriville on annettu yksilöllinen nimi mainToolBar ja sen näkyvä nimi on asetettu <text>-merkinnällä Main Toolbar:ksi. Tyhjennä-toiminto on asetettu työkaluriville <Action>-merkinnän avulla. Toiminnon nimi on sama, kuin mikä aikaisemmin lisättiin addAction()-funktion avulla toimintokokoelmaan mainwindow.cpp-tiedostossa.

Toiminto on mahdollista lisätä myös valikkoriville. Tässä tapauksessa toiminto Tyhjennä on lisätty Tiedosto(File)-valikkoon, samalla tavalla kuin se lisättiin työkaluriville.

Muista vaihtaa 'version'-määrite(versionumero) <gui>-merkinnästä jos muutat .rc-tiedostoa saattaaksesi viimeisimmän asennuksen mukaisen version järjestelmän välimuistiin.

[edit] CMake

Lopuksi tutorial3ui.rc-tiedosto täytyy sijoittaa paikkaan, josta KDE voi sen löytää (tiedostoa ei siis voi pelkästään jättää lähdehakemistoon). Tämä tarkoittaa että tämä projekti on asennettava johonkin.

[edit] 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)

Tämä tiedosto on lähes identtinen Perehdytys 2:n vastaavan kanssa. Ainoastaan tiedoston loppuun on lisätty kaksi uutta riviä, jotka kertovat minne tiedostot tulee asentaa. tutorial3(suoritettava binääri, ohjelma) asennetaan hakemistoon, joka on määritelty BIN_INSTALL_DIR-muuttujassa ja tutorial3ui.rc-tiedosto, joka siis määrittelee ohjelman ulkoasun, asennetaan ohjelman data-hakemistoon.

[edit] Käännä, Asenna ja Suorita

Jos sinulla ei ole kirjoitusoikeutta KDE4:n asennushakemistoon, voit asentaa ohjelmasi myös kotikansiossa olevaan hakemistoon.

Kertoaksesi CMakelle, minne ohjelma asennetaan, tarvitsee käyttää DCMAKE_INSTALL_PREFIX -valitsinta. Luultavasti haluat asentaa nämä tiedostot kotihakemistoosi (KDE-asennushakemisto on oletuksena asennushakemisto), joten ehdotan seuraavaa:

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

Ylläoleva luo KDE-hakemistorakenteen kotihakemistosi kde_harjoittelu-hakemiston alle, sekä asentaa ohjelman sinne oikeille paikoilleen.

[edit] Seuraavaksi

Nyt olet valmis siirtymään eteenpäin Perehdytys 4 - Tallentaminen ja Avaaminen-kohtaan.