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

    From KDE TechBase
    No edit summary
     
    (28 intermediate revisions by 4 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|Tutorial 4 - Saving and loading]]|  
    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ällä kerralla muutokset tähän tiedostoon ovat hyvin vähäisiä. 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ätty <tt>void setupActions()</tt> joka tekee kaiken tarvittavan asettelun KActions:a 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ämä 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äyttöönotossa on muutamia vaiheita. Ensimmäinen on sisällyttää <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ä siis on KAction objekti, ja voi mme alkaa muokkaamaan sen ominaisuuksia. Seuraava koodi asettaa tekstin joka näytetään valikossa sekä työ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ä 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 [[Development/Tutorials/Localization/i18n|i18n perehdytyksestä]]).
    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====
    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 <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function:
    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>


    ====Näppäinyhdistelmä====
    ====Pikan&auml;pp&auml;inyhdistelm&auml;====
    Setting a keyboard shortcut to perform our action is equally simple:
    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>
    This associates Ctrl+W with the KAction.


    ===Adding to the Collection===
    ===Kokoelmaan lisääminen===
    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 <tt>actionCollection()</tt> function like this:  
    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>
    Here, the <tt>clearAction</tt> 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.
    Tässä <tt>clearAction</tt> KAction on lisätty kokoelmaan nimellä ''clear''. Nimeä (''clear'') käytetään XMLGUI-kehyksessä kuvaamaan tätä toimintoa.


    ====Connecting the action====
    ====Toiminnon yhdistäminen====
    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 <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit)
    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>
    This is the same as it would be done in Qt with a {{qt|QAction}}.
    Tämä sama voidaan tehdä Qt:n kanssa käyttämällä {{qt|QAction}}.


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


    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 [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction].
    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:  
     
    <syntaxhighlight lang="cpp-qt">KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</syntaxhighlight>
    They are very simple to use. Once the library has been included (<tt>#include <KStandardAction></tt>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example:
    Tämä luo ''Lopeta''-toiminnon, oikean kuvakkeen, tekstin ja pikanäppäinyhdistelmän kanssa. Toiminto myös lisätään Tiedosto-valikkoon.
    <code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
    This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.


    ==Adding the action to menus and toolbars==
    ==Toiminnon lisääminen valikoihin ja työkaluriville==
    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.
    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|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.}}
    {{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.


    The <tt>setupGUI()</tt> function in {{class|KXmlGuiWindow}} depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.
    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'').
     
    The rule for naming this XML file is <tt>appnameui.rc</tt>, where <tt>appname</tt> is the name you set in {{class|KAboutData}} (in this case, ''tutorial3''). So in our example, the file is called <tt>tutorial3ui.rc</tt>, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.


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


    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 [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]].
    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 189: Line 187:
         </Menu>
         </Menu>
       </MenuBar>
       </MenuBar>
      <ToolBar name="mainToolBar" >
        <text>Main Toolbar</text>
        <Action name="clear" />
      </ToolBar>
    </gui>
    </gui>
    </code>
    </syntaxhighlight>


    The <tt><Toolbar></tt> 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 <tt><text></tt> tag. The clear action is added to the toolbar using the <tt><Action></tt> tag, the name parameter in this tag being the string that was passed to the KActionCollection with <tt>addAction()</tt> in <tt>mainwindow.cpp</tt>.
    <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.


    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 <tt>MenuBar</tt> the same way it was added to the toolbar.
    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.


    Change the 'version' attribute of the <tt><nowiki><gui></nowiki></tt> tag if you changed .rc file since the last install to force a system cache update.
    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==
    Finally, the <tt>tutorial3ui.rc</tt> 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.'''
    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 219: Line 224:
    install(FILES tutorial3ui.rc  
    install(FILES tutorial3ui.rc  
             DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)
             DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)
    </code>
    </syntaxhighlight>


    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 <tt>tutorial3</tt> target is installed to the <tt>BIN_INSTALL_DIR</tt> then the <tt>tutorial3ui.rc</tt> file that describes the layout of the user interface is installed to the application's data directory.
    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.


    ===Make, Install And Run===
    ===Käännä, Asenna ja Suorita===
    If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.
    Jos sinulla ei ole kirjoitusoikeutta KDE4:n asennushakemistoon, voit asentaa ohjelmasi myös kotikansiossa olevaan hakemistoon.


    To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> 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:
    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:
    mkdir build && cd build
    <syntaxhighlight lang="text">
    cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
    mkdir build && cd build
    make install
    cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/kde4_harjoittelu
    $HOME/bin/tutorial3
    make install
    which will create a KDE-like directory structure in your user's home directory directory and will install the executable to {{path|$HOME/bin/tutorial3}}.
    $HOME/kde4_harjoittelu/bin/tutorial3
    </syntaxhighlight>
    Ylläoleva luo KDE-hakemistorakenteen kotihakemistosi kde_harjoittelu-hakemiston alle, sekä asentaa ohjelman sinne oikeille paikoilleen.


    ==Moving On==
    ==Seuraavaksi==
    Now you can move on to [[Development/Tutorials/Saving_and_loading|saving and loading]].
    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.