Development/Tutorials/Using KActions (fi): Difference between revisions

From KDE TechBase
mNo edit summary
No edit summary
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KActions}}
 


{{TutorialBrowser|
{{TutorialBrowser|
Line 5: Line 5:
series=Beginner Tutorial|
series=Beginner Tutorial|


name=Perehdytys 3 - KActions ja XMLGUI|
name=Opas 3 - KActions ja XMLGUI|


pre=[[Development/Tutorials/Using_KXmlGuiWindow (fi)|Perehdytys 2 - Main-ikkunan luonti]], XML perustietous|
pre=[[Development/Tutorials/Using_KXmlGuiWindow (fi)|Opas 2 - main-ikkunan luonti]], XML-perustietous|


next=[[Development/Tutorials/Saving_and_loading (fi)|Perehdytys 4 - Tallettaminen ja Avaaminen]]|  
next=[[Development/Tutorials/Saving_and_loading (fi)|Opas 4 - tallentaminen ja avaaminen]]|  


reading=None
reading=None
Line 15: Line 15:


==Lyhyesti==
==Lyhyesti==
Tämä perehdytys esittelee toiminnot. Toiminnot tarjoavat yhtenäisen tavan käyttäjälle vuorovaikuttaa ohjelman kanssa.
Tämä opas esittelee toiminnot, engl. ''actions''. Toiminnot tarjoavat yhtenäisen tavan vuorovaikuttaa ohjelman kanssa.


Jos esimerkiksi haluamme antaa [[Development/Tutorials/Using_KXmlGuiWindow (fi)|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ä {{class|KAction}}-luokkaa.
Jos esimerkiksi haluamme antaa [[Development/Tutorials/Using_KXmlGuiWindow (fi)|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ä {{class|KAction}}-luokkaa.


[[image:introtokdetutorial3.png|frame|center]]
[[image:introtokdetutorial3.png|frame|center]]


==KAction==
==KAction==
{{class|KAction}} on objekti joka sisältää kaiken tarvittavan tiedon ikonista ja näppäinyhdistelmistä jotka on yhdistetty joihinkin toimintoon. Toiminto taas on yhdistetty [http://doc.trolltech.com/latest/signalsandslots.html slot]:n joka huolehtii toiminnon suorittamisesta.
{{class|KAction}} on objekti joka sisältää kaiken tarvittavan tiedon kuvakkeesta ja näppäinyhdistelmistä, jotka on liitetty johonkin toimintoon. Toiminto taas on yhdistetty [http://doc.trolltech.com/latest/signalsandslots.html slot]iin, joka huolehtii toiminnon suorittamisesta.


== Koodi ==
== Koodi ==


===main.cpp===
===main.cpp===
<code cppqt n>
<syntaxhighlight lang="cpp-qt" line>
#include <KApplication>
#include <KApplication>
#include <KAboutData>
#include <KAboutData>
Line 48: Line 48:
   return app.exec();
   return app.exec();
}
}
</code>
</syntaxhighlight>
T&auml;ll&auml; kerralla muutokset t&auml;h&auml;n tiedostoon ovat hyvin v&auml;h&auml;isi&auml;. Ainoastaan "tutorial 2" on korjattu "tutorial 3".
T&auml;ll&auml; kerralla muutokset t&auml;h&auml;n tiedostoon ovat hyvin v&auml;h&auml;isi&auml;. Ainoastaan "tutorial 2" on korjattu "tutorial 3".


===mainwindow.h===
===mainwindow.h===
<code cppqt n>
<syntaxhighlight lang="cpp-qt" line>
#ifndef MAINWINDOW_H
#ifndef MAINWINDOW_H
#define MAINWINDOW_H
#define MAINWINDOW_H
Line 70: Line 70:


#endif
#endif
</code>
</syntaxhighlight>
Otsikkotiedostoon on lis&auml;tty <tt>void setupActions()</tt> jossa tehdään kaikki tarvittavat asettelut toimintoa varten.
Otsikkotiedostoon on lis&auml;tty <tt>void setupActions()</tt>, jossa tehdään kaikki tarvittavat asettelut toimintoa varten.


===mainwindow.cpp===
===mainwindow.cpp===
<code cppqt n>
<syntaxhighlight lang="cpp-qt" line>
#include "mainwindow.h"
#include "mainwindow.h"


Line 107: Line 107:
   setupGUI();
   setupGUI();
}
}
</code>
</syntaxhighlight>


==Selvitys==
==Selvitys==
T&auml;m&auml; perehdytys perustuu [[Development/Tutorials/Using_KXmlGuiWindow (fi)|edelliseen perehdytykseen]]. Suurin osa koodi muutoksista on <tt>mainwindow.cpp</tt> tiedostossa.  Muodostajassa kutsutaan nyt <tt>setupActions()</tt> <tt>setupGUI()</tt> sijaan. <tt>setupActions()</tt>:ssa sijaitsee uusi KAction koodi joka lopuksi kutsuu <tt>setupGUI()</tt>-funktiota.
T&auml;m&auml; perehdytys perustuu [[Development/Tutorials/Using_KXmlGuiWindow (fi)|edelliseen perehdytykseen]]. Suurin osa koodimuutoksista on <tt>mainwindow.cpp</tt> tiedostossa.  Muodostajassa kutsutaan nyt <tt>setupActions()</tt> <tt>setupGUI()</tt> sijaan. <tt>setupActions()</tt>:ssa sijaitsee uusi KAction-koodi, joka lopuksi kutsuu <tt>setupGUI()</tt>-funktiota.


===KAction objektin luominen===
===KAction objektin luominen===
KActionin k&auml;ytt&ouml;&ouml;notossa on muutamia vaiheita. Ensimm&auml;inen on sis&auml;llytt&auml;&auml; <tt>KAction</tt>-kirjasto ja luoda uusi <tt>KAction</tt>:
KActionin k&auml;ytt&ouml;&ouml;notossa on muutamia vaiheita. Ensimm&auml;inen on sis&auml;llytt&auml;&auml; <tt>KAction</tt>-kirjasto ja luoda uusi <tt>KAction</tt>:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
#include <KAction>
#include <KAction>
...
...
KAction* clearAction = new KAction(this);
KAction* clearAction = new KAction(this);
</code>
</syntaxhighlight>


===KAction:n ominaisuuksien asettelu===
===KAction:n ominaisuuksien asettelu===
====Teksti====
====Teksti====
Nyt meill&auml; siis on KAction objekti, joten voimme alkaa muokkaamaan sen ominaisuuksia. Seuraava koodi asettaa tekstin joka n&auml;ytet&auml;&auml;n valikossa sek&auml; ty&ouml;kaluvalikossa olevan ikonin alapuolella.
Nyt meill&auml; siis on KAction objekti, joten voimme alkaa muokkaamaan sen ominaisuuksia. Seuraava koodi asettaa tekstin, joka n&auml;ytet&auml;&auml;n valikossa sek&auml; ty&ouml;kaluvalikossa olevan kuvakkeen alapuolella.
<code cppqt>
<syntaxhighlight lang="cpp-qt">
clearAction->setText(i18n("Clear"));
clearAction->setText(i18n("Clear"));
</code>
</syntaxhighlight>
Huomaa ett&auml; teksti on sy&ouml;tetty i18n()-funktionin l&auml;pi. T&auml;m&auml; on pakollinen jotta k&auml;ytt&ouml;liittym&auml; on k&auml;&auml;nnett&auml;viss&auml; eri kielille. Lis&auml;tietoja lokalisoinnista l&ouml;ytyy [[Development/Tutorials/Localization/i18n|i18n perehdytyksest&auml;]]).
Huomaa ett&auml; teksti on sy&ouml;tetty i18n()-funktion l&auml;pi. T&auml;m&auml; on välttämätöntä jotta k&auml;ytt&ouml;liittym&auml; on k&auml;&auml;nnett&auml;viss&auml; eri kielille. Lis&auml;tietoja lokalisoinnista l&ouml;ytyy [[Development/Tutorials/Localization/i18n|i18n perehdytyksest&auml;]]).


====Ikoni====
====Ikoni====
Jos toiminto on aikomus n&auml;ytt&auml;&auml; työkalurivill&auml;, olisi hyv&auml; jos sill&auml; olisi toimintoa kuvaava ikoni. Seuraava koodi asettaa standardin KDE <tt>document-new</tt>(Uusi asiakirja) ikonin clearAction toiminnolle:
Jos toiminto on tarkoitus n&auml;ytt&auml;&auml; työkalurivill&auml;, olisi hyv&auml; jos sill&auml; olisi toimintoa kuvaava ikoni. Seuraava koodi asettaa standardin KDE <tt>document-new</tt>(Uusi asiakirja) -kuvakkeen clearAction toiminnolle:
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
<syntaxhighlight lang="cpp-qt">clearAction->setIcon(KIcon("document-new"));</syntaxhighlight>


====Pikan&auml;pp&auml;inyhdistelm&auml;====
====Pikan&auml;pp&auml;inyhdistelm&auml;====
Pikan&auml;pp&auml;inyhdistelm&auml;n asettaminen toiminnollemme on yht&auml;lailla helppo. Seuraava koodi osoittaa yhdistelm&auml;n Ctrl+W clearAction toiminnolle:
Pikan&auml;pp&auml;inyhdistelm&auml;n asettaminen toiminnollemme on yht&auml;lailla helppo. Seuraava koodi osoittaa yhdistelm&auml;n Ctrl+W clearAction toiminnolle:
<code cppqt>clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</code>
<syntaxhighlight lang="cpp-qt">clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</syntaxhighlight>


===Kokoelmaan lisääminen===
===Kokoelmaan lisääminen===
Jotta toimintoon olisi mahdollista päästä käsiksi XMLGUI-kehyksen(selitetty tarkemmin myöhemmin) läpi, se pitää lisätä ohjelman ''toiminto kokoelmaan''. Toimintokokoelmaa käsitellään <tt>actionCollection()</tt>-funktion avulla seuraavasti:
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 <tt>actionCollection()</tt>-funktion avulla seuraavasti:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
actionCollection()->addAction("clear", clearAction);
actionCollection()->addAction("clear", clearAction);
</code>
</syntaxhighlight>
Tässä <tt>clearAction</tt> KAction on lisätty kokoelmaan nimellä ''clear''. Nimeä (''clear'') on käytetään XMLGUI-kehyksessä kuvaamaan tätä toimintoa.
Tässä <tt>clearAction</tt> KAction on lisätty kokoelmaan nimellä ''clear''. Nimeä (''clear'') käytetään XMLGUI-kehyksessä kuvaamaan tätä toimintoa.


====Toiminnon yhdistäminen====
====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 <tt>clear()</tt>-funktioon (joka tyhjentää tekstialueen) seuraavasti:
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 <tt>clear()</tt>-funktioon (joka tyhjentää tekstialueen) seuraavasti:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
connect( clearAction, SIGNAL( triggered(bool) ),  
connect( clearAction, SIGNAL( triggered(bool) ),  
         textArea, SLOT( clear() ) );
         textArea, SLOT( clear() ) );
</code>
</syntaxhighlight>
Tämä sama voidaan tehdä Qt:n kanssa käyttämällä {{qt|QAction}}.
Tämä sama voidaan tehdä Qt:n kanssa käyttämällä {{qt|QAction}}.


===KStandardAction===
===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ä [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction]:n avulla.
Lähes jokaisessa KDE-ohjelmassa esiintyviä toimintoja varten (esim. 'sulje', 'tallenna' ja 'avaa') on olemassa valmiita toimintoja, jotka ovat käytettävissä [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction]:n avulla.


Nämä ovat erittäin helppoja ottaa käyttöön. Kun ensin on otettu kirjasto käyttöön (<tt>#include <KStandardAction></tt>), tarvitsee vain ottaa haluttu toiminto käyttöön, esim:  
Nämä ovat erittäin helppoja ottaa käyttöön. Kun ensin on otettu kirjasto käyttöön (<tt>#include <KStandardAction></tt>), tarvitsee vain ottaa haluttu toiminto käyttöön, esim:  
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
<syntaxhighlight lang="cpp-qt">KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</syntaxhighlight>
Tämä luo ''Lopeta''-toiminnon, oikean ikonin, tekstin ja pikanäppäinyhdistelmän kanssa sekä jopa lisää sen Tiedosto-valikkoon.
Tämä luo ''Lopeta''-toiminnon, oikean kuvakkeen, tekstin ja pikanäppäinyhdistelmän kanssa. Toiminto myös lisätään Tiedosto-valikkoon.


==Toiminnon lisääminen valikoihin ja työkaluriville==
==Toiminnon lisääminen valikoihin ja työkaluriville==
Tällä hetkellä, uusi "Tyhjennä" toiminto on luotu, mutta sitä ei ole vielä yhdistetty yhteenkään valikkoon tai työkaluriviin. Tähän tarkoitukseen käytämme KDE tekniikkaa nimeltään XMLGUI, jonka avulla voidaan toteuttaa mm. siirrettävät työkalurivit.
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ä}}
{{note|Myöhemmissä KDE4 versioisssa XMLGUI-kehys saatetaan vaihtaa liveui-kehykseen, mutta tällä hetkellä XMLGUI on ainoa oikea tapa asettaa käyttöliittymä}}


==XMLGUI==
==XMLGUI==
{{class|KXmlGuiWindow}}:n <tt>setupGUI()</tt>-funktion käyttöliittymän muodostus on riippuvainen XMLGUI-järjestelmästä joka hakee XML-tiedostosta käyttöliittymän muodostuksessa tarvittavat tiedot.
{{class|KXmlGuiWindow}}:n <tt>setupGUI()</tt>-funktion käyttöliittymän muodostus on riippuvainen XMLGUI-järjestelmästä, joka hakee XML-tiedostosta käyttöliittymän muodostuksessa tarvittavat tiedot.


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


==''ohjelmannimi''ui.rc - tiedosto==
==''ohjelmannimi''ui.rc - tiedosto==


Koska käyttöliittymä on määritelty XML-tiedoston avulla, ulkoasun täytyy noudattaa tiettyjä sääntöjä. Tämä perehdytys ei paneudu kovin syvällisesti tähän aiheeseen. Lisätietoja: [[Development/Architecture/KDE4/XMLGUI_Technology|XMLGUI - Tekniikka]](tulossa ?).
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: [[Development/Architecture/KDE4/XMLGUI_Technology|XMLGUI - Tekniikka]](tulossa ?).


===tutorial3ui.rc===
===tutorial3ui.rc===
<code xml n>
<syntaxhighlight lang="xml" line>
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial3"
<gui name="tutorial3" version="1">
    version="1"
  <ToolBar name="mainToolBar" >
    xmlns="http://www.kde.org/standards/kxmlgui/1.0"
    <text>Main Toolbar</text>
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    <Action name="clear" />
    xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
  </ToolBar>
                        http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >
 
   <MenuBar>
   <MenuBar>
     <Menu name="file" >
     <Menu name="file" >
Line 186: Line 187:
     </Menu>
     </Menu>
   </MenuBar>
   </MenuBar>
  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
  </ToolBar>
</gui>
</gui>
</code>
</syntaxhighlight>


<tt><Toolbar></tt>-kohdassa kuvaillaan ikkunan yläosassa, yleensä ikonein 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 <tt><text></tt>-merkinnällä ''Main Toolbar'':ksi. Tyhjennä-toiminto on asetettu työkaluriville <tt><Action></tt>-merkinnän avulla. Toiminnon nimi on sama joka aikasemmin lisättiin <tt>addAction()</tt>-funktion avulla toimintokokoelmaan <tt>mainwindow.cpp</tt>-tiedostossa.
<tt><Toolbar></tt>-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 <tt><text></tt>-merkinnällä ''Main Toolbar'':ksi. Tyhjennä-toiminto on asetettu työkaluriville <tt><Action></tt>-merkinnän avulla. Toiminnon nimi on sama, kuin mikä aikaisemmin lisättiin <tt>addAction()</tt>-funktion avulla toimintokokoelmaan <tt>mainwindow.cpp</tt>-tiedostossa.


Toiminto on mahdollista lisätä myös valikkoriville. Tässä tapauksessa ''Tyhjennä'' toiminto on lisätty ''Tiedosto''(File) valikkoon, samalla tavalla kuin se lisättiin työkalurivillekkin.
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) <tt><nowiki><gui></nowiki></tt>-merkinnästä jos muutat .rc-tiedostoa saattaaksesi viimeisimmän asennuksen mukaisen version järjestelmänvälmuistiin.
Muista vaihtaa 'version'-määrite(versionumero) <tt><nowiki><gui></nowiki></tt>-merkinnästä jos muutat .rc-tiedostoa saattaaksesi viimeisimmän asennuksen mukaisen version järjestelmän välimuistiin.


==CMake==
==CMake==
Lopuksi <tt>tutorial3ui.rc</tt>-tiedosto täytyy sijoittaa jonnekkin mistä KDE voi sen löytää (sitä ei voi pelkästään jättää lähdehakemistoon). '''Tämä tarkoittaa että tämä projekti tarvitsee asentaa jonnekkin.'''
Lopuksi <tt>tutorial3ui.rc</tt>-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.'''
 
===CMakeLists.txt===
===CMakeLists.txt===
<code ini n>
<syntaxhighlight lang="ini" line>
project(tutorial3)
project(tutorial3)


Line 216: Line 224:
install(FILES tutorial3ui.rc  
install(FILES tutorial3ui.rc  
         DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)
         DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)
</code>
</syntaxhighlight>


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. <tt>tutorial3</tt>(suoritettava binääri, ohjelma) asennetaan hakemistoon joka on määritelty <tt>BIN_INSTALL_DIR</tt>-muttujassa ja <tt>tutorial3ui.rc</tt>-tiedosto joka siis määrittelee ohjelman ulkoasun, asennetaan ohjelman data-hakemistoon.
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. <tt>tutorial3</tt>(suoritettava binääri, ohjelma) asennetaan hakemistoon, joka on määritelty <tt>BIN_INSTALL_DIR</tt>-muuttujassa ja <tt>tutorial3ui.rc</tt>-tiedosto, joka siis määrittelee ohjelman ulkoasun, asennetaan ohjelman data-hakemistoon.


===Käännä, Asenna ja Suorita===
===Käännä, Asenna ja Suorita===
Jos sinulla ei ole kirjoitusoikeutta KDE4:n asennushakemistoon, voit asentaa ohjelmasi myös kotikansiossa olevaan hakemistoon.
Jos sinulla ei ole kirjoitusoikeutta KDE4:n asennushakemistoon, voit asentaa ohjelmasi myös kotikansiossa olevaan hakemistoon.


Kertoaksesi CMakelle, minne ohjelma tulee asentaa, tarvitsee käyttää <tt>DCMAKE_INSTALL_PREFIX</tt>-kytkintä. Luultavasti haluat asentaa nämä perehdytykset kotihakemistoosi (KDE asennushakemisto on oletuksena asennushakemisto) joten ehdotan seuraavaa:
Kertoaksesi CMakelle, minne ohjelma asennetaan, tarvitsee käyttää <tt>DCMAKE_INSTALL_PREFIX</tt> -valitsinta. Luultavasti haluat asentaa nämä tiedostot kotihakemistoosi (KDE-asennushakemisto on oletuksena asennushakemisto), joten ehdotan seuraavaa:
<code>
<syntaxhighlight lang="text">
mkdir build && cd build
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/kde4_harjoittelu
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/kde4_harjoittelu
make install
make install
$HOME/kde4_harjoittelu/bin/tutorial3
$HOME/kde4_harjoittelu/bin/tutorial3
</code>
</syntaxhighlight>
Ylläoleva luo KDE-hakemistorakenteen kotihakemistosi kde_harjoittelu-hakemiston alle sekä asentaa ohjelman sinne oikeille paikoilleen.
Ylläoleva luo KDE-hakemistorakenteen kotihakemistosi kde_harjoittelu-hakemiston alle, sekä asentaa ohjelman sinne oikeille paikoilleen.


==Seuraavaksi==
==Seuraavaksi==
Nyt olet valmis siirtymään eteenpäin [[Development/Tutorials/Saving_and_loading (fi)|Perehdytys 4 - Tallettaminen ja Avaaminen]]-kohtaan.
Nyt olet valmis siirtymään eteenpäin [[Development/Tutorials/Saving_and_loading (fi)|Perehdytys 4 - Tallentaminen ja Avaaminen]]-kohtaan.


[[Category:C++]]
[[Category:C++]]

Latest revision as of 09:44, 15 July 2012


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

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.

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.

Koodi

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

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.

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

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.

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

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 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ä).

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

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

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.

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.

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ä


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

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

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.

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.

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.

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.

Seuraavaksi

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