Development/Tutorials/Using KActions (se)

    From KDE TechBase
    Revision as of 11:21, 15 February 2009 by Urwald (talk | contribs) (Using xsd instead of dtd (not state of the art) / MenuBar tag _before_ ToolBar tag as requested by xsd)


    Development/Tutorials/Using_KActions


    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'enKAction* 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

    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

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

    }

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

    }

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