Development/Tutorials/Using KActions: Difference between revisions

    From KDE TechBase
    m (Reflect the change from filenew -> document-new here also.)
    (third person now, reorganized, more concise)
    Line 15: Line 15:


    ==Abstract==
    ==Abstract==
    We're going to introduce the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.
    This tutorial introduces the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.


    Say, for example, we want to let the user clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut; we can provide all of those through one {{class|KAction}}.
    For example, if we wanted to let the user of [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 ]] clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut, it could all be done with one {{class|KAction}}.


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


    ==KAction==
    ==KAction==
    A {{class|KAction}} is an object which contains all the information about the icon and shortcuts you want associated to a certain action. You then connect the action to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.
    A {{class|KAction}} is an object which contains all the information about the icon and shortcuts that is associated with a certain action. The action is then connected to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.


    ===Creating Your Own===
    == The Code ==


    To create an action, you need to <tt>#include <KAction></tt> in your <tt>.cpp</tt> file.
    ===main.cpp===
    =====Creating the object=====
    <code cppqt n>
    We're going to create an action which will clear the text area (see Tutorial 2). The KAction is built up in a number of steps. The first is creating the KAction
    #include <KApplication>
    <code cppqt>KAction* clearAction = new KAction(this);</code>
    #include <KAboutData>
    This creates a KAction called <tt>clearAction</tt>.
    #include <KCmdLineArgs>
    =====Text=====
    Now we have our KAction object, we can start setting its properties. First, we'll set the text that will be displayed in the menu and under its icon in the toolbar.
    <code cppqt>clearAction->setText(i18n("Clear"));</code>
    As you can see, the text must be passed through the i18n() function if you want your UI to be translatable.


    =====Icon=====
    #include "mainwindow.h"
    If you're going to display the action in a toolbar, you're going to want to have an icon depicting the action. To set an icon we simply use the <tt>setIcon()</tt> function thus:
    <code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
    Here we're setting the icon to the standard KDE <tt>document-new</tt> icon.


    =====Shortcut=====
    int main (int argc, char *argv[])
    We can also set a shortcut that will perform our action. It's as simple as a
    {
    <code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
      KAboutData aboutData( "tutorial3", "tutorial3",
    to set Ctrl+W to be associated to this action.
          ki18n("Tutorial 3"), "1.0",
    =====Adding to the Collection=====
          ki18n("A simple text area using KAction etc."),
    In order for our action to be accessable by the XmlGui framework it must be added to the application's ''action collection''. It is accessed via the <tt>actionCollection()</tt> function thus:  
          KAboutData::License_GPL,
    <code cppqt>
          ki18n("Copyright (c) 2007 Developer") );
    actionCollection()->addAction("clear", clearAction);
      KCmdLineArgs::init( argc, argv, &aboutData );
    </code>
      KApplication app;
    Here we add the <tt>clearAction</tt> KAction to the collection and give it a name of ''clear''. This name is used by the XmlGui framework.
    =====Connecting the action=====
      MainWindow* window = new MainWindow();
    Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the <tt>clear()</tt> action belonging to a KTextArea.
      window->show();
    <code cppqt>
      return app.exec();
    connect( clearAction, SIGNAL( triggered(bool) ),
    }
            textArea, SLOT( clear() ) );
    </code>
    </code>
    This is the same as it would be done in Qt with a {{qt|QAction}}.
    ===KStandardAction===
    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 {{class|KStandardAction}}.
    They are very simple to use. Once you've done <tt>#include <KStandardAction></tt>, you simply need to supply it with what you want the function to do and which KActionCollection to add it to. For example,
    <code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
    Will Create a KAction with the correct icon, text and shortcut and will even add it to the File menu.


    ==The Code==
    ===mainwindow.h===
    ===mainwindow.h===
    <code cppqt n>
    <code cppqt n>
    Line 125: Line 107:
    </code>
    </code>


    ===main.cpp===
    ==Explanation==
    <code cppqt n>
    This builds upon the KXmlGuiWindow code from [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2]]. Most of the changes are to <tt>mainwindow.cpp</tt>, an important structural change being that the constructor for MainWindow now calls <tt>setupActions()</tt> instead of <tt>setupGUI()</tt>. <tt>setupActions()</tt> is where the new KAction code goes before finally calling <tt>setupGUI()</tt>.
    #include <KApplication>
     
    #include <KAboutData>
    ===Creating the KAction object===
    #include <KCmdLineArgs>
    The KAction is built up in a number of steps. The first is including the <tt>KAction</tt> library and then creating the KAction:
    <code cppqt>
    #include <KAction>
    ...
    KAction* clearAction = new KAction(this);
    </code>
    This creates a new KAction called <tt>clearAction</tt>.
     
    ===Setting KAction Properties===
    ====Text====
    Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>KAction</tt>'s icon in the toolbar.
    <code cppqt>clearAction->setText(i18n("Clear"));</code>
    Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable.
     
    ====Icon====
    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:
    <code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
     
    ====Keyboard Shortcut====
    Setting a keyboard shortcut to perform our action is equally simple:
    <code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code>
    This associates Ctrl+W with the KAction.


    #include "mainwindow.h"
    ===Adding to the Collection===
    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 thusly:
    <code cppqt>
    actionCollection()->addAction("clear", clearAction);
    </code>
    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.


    int main (int argc, char *argv[])
    ====Connecting the action====
    {
    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 KTextArea (which, unsurprisingly, clears the KTextArea).
      KAboutData aboutData( "tutorial3", "tutorial3",
    <code cppqt>
          ki18n("Tutorial 3"), "1.0",
    connect( clearAction, SIGNAL( triggered(bool) ),
          ki18n("A simple text area using KAction etc."),
            textArea, SLOT( clear() ) );
          KAboutData::License_GPL,
          ki18n("Copyright (c) 2007 Developer") );
      KCmdLineArgs::init( argc, argv, &aboutData );
      KApplication app;
      MainWindow* window = new MainWindow();
      window->show();
      return app.exec();
    }
    </code>
    </code>
    This is the same as it would be done in Qt with a {{qt|QAction}}.
    ===KStandardAction===
    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 {{class|KStandardAction}}.
    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:
    <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==
    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.


    ==Putting the actions in the menus and toolbars==
    Now, at the moment, we've only created our new "Clear" action. It won't yet show up in the menus or in the toolbars. To tell the program where to put our actions (and to allow the end-user to move them around) we use a KDE technology called XmlGui.
    ===XmlGui===
    {{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|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.}}


    When you call <tt>setupGUI()</tt> in your {{class|KXmlGuiWindow}} class, it calls the XmlGui system which reads an XML file description of your interface (which we will create in a minute) and creates the buttons and menus appropriately.
    ==XmlGui==
     
    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.


    Now obviously XmlGui needs to know which file is your description file, i.e. it needs to know its name and location. The rule for the naming is the file should be called <tt>appnameui.rc</tt> (where <tt>appname</tt> is the name you set in {{class|KAboutData}}), so in our example, the file will be called <tt>tutorial3ui.rc</tt>. Where the file will be located is handled by CMake.
    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.


    ===Writing your ''appname''ui.rc File===
    ===''appname''ui.rc File==


    Since the description of our UI is being defined with XML, the layout of the description must follow strict rules. We won't go through all the rules in this tutorial but for more information, see the _detailed_XmlGui_page_ (once we have a full explanation of XmlGui (or possibly liveui if that's done soon :)) on the wiki, I'll link it up).
    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_ (link pending).


    ===tutorial3ui.rc===
    ===tutorial3ui.rc====
    <code xml n>
    <code xml n>
    <?xml version="1.0" encoding="UTF-8"?>
    <?xml version="1.0" encoding="UTF-8"?>
    Line 182: Line 192:
    </code>
    </code>


    The <tt><Toolbar></tt> tag allows you to describe the toolbar. That is the bar across the top of the window with the icons. Here we give it a unique name ''mainToolBar'', set it's user visible name ''Main Toolbar'' using the <tt><text></tt> tag and finally add our clear action to the toolbar using the <tt><Action></tt> tag. The name parameter in this tag relates to the string that was passed to the <tt>addAction()</tt> function in the C++ code.
    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>.


    As well as having our action in the toolbar, we can also add it to the menubar. Within the <tt><MenuBar></tt> 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.
    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.


    Please note you can also add dynamic action list to your configuration file using a <tt><ActionList></tt> tag. For more information about this, see the <tt>plugActionList()</tt> method of the {{class|KXMLGUIClient}} documentation.
    Note that you can also add dynamic action lists to your configuration file using a <tt><ActionList></tt> tag. For more information about this, see the <tt>plugActionList()</tt> method of the {{class|KXMLGUIClient}} documentation.


    Change 'version' attribute of the gui tag if you changed .rc file since last install to force system cache update
    Change the 'version' attribute of the gui tag if you changed .rc file since the last install to force a system cache update.


    ==CMake==
    ==CMake==
    Now that we're using XmlGui, we need to put the <tt>tutorial3ui.rc</tt> somewhere where KDE can find it. '''This means we need to install our project somewhere.'''
    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.'''
    ===CMakeLists.txt===
    ===CMakeLists.txt===
    <code>
    <code>
    Line 213: Line 223:
    </code>
    </code>


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


    ===Make, Install And Run===
    ===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.
    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 <tt>DCMAKE_INSTALL_PREFIX</tt> switch. So to install the program to the KDE directory, do
    To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> switch. For example, to install the program to the KDE directory:
      cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
      cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
      make install
      make install
      tutorial3
      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
    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), the following might be more appropriate:
      cmake . -DCMAKE_INSTALL_PREFIX=/home/kde-devel/kdetmp
      cmake . -DCMAKE_INSTALL_PREFIX=$PWD
    which will create a KDE-like directory structure under ~/kdetmp and will install the executable to {{path|/home/kde-devel/kdetmp/bin/tutorial3}}.
    which will create a KDE-like directory structure under the current directory and will install the executable to {{path|$PWD/bin/tutorial3}}.


    ==Moving On==
    ==Moving On==

    Revision as of 02:32, 18 December 2007


    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

    This tutorial introduces the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.

    For example, if we wanted to let the user of Tutorial 2 clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut, it could all be done with one KAction.

    KAction

    A KAction is an object which contains all the information about the icon and shortcuts that is associated with a certain action. The action is then connected to a slot which carries out the work of your action.

    The Code

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

    }

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

    }

    Explanation

    This builds upon the KXmlGuiWindow code from Tutorial 2. Most of the changes are to mainwindow.cpp, an important structural change being that the constructor for MainWindow now calls setupActions() instead of setupGUI(). setupActions() is where the new KAction code goes before finally calling setupGUI().

    Creating the KAction object

    The KAction is built up in a number of steps. The first is including the KAction library and then creating the KAction:

    1. include <KAction>

    ... KAction* clearAction = new KAction(this); This creates a new KAction called clearAction.

    Setting KAction Properties

    Text

    Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the KAction's icon in the toolbar. clearAction->setText(i18n("Clear")); Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable.

    Icon

    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 document-new icon through the use of the setIcon() function: clearAction->setIcon(KIcon("document-new"));

    Keyboard Shortcut

    Setting a keyboard shortcut to perform our action is equally simple: clearAction->setShortcut(Qt::CTRL+Qt::Key_W); This associates Ctrl+W with the KAction.

    Adding to the Collection

    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 actionCollection() function thusly: actionCollection()->addAction("clear", clearAction); Here, the clearAction 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.

    Connecting the action

    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 clear() action belonging to a KTextArea (which, unsurprisingly, clears the KTextArea). connect( clearAction, SIGNAL( triggered(bool) ),

            textArea, SLOT( clear() ) );
    

    This is the same as it would be done in Qt with a QAction.

    KStandardAction

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

    They are very simple to use. Once the library has been included (#include <KStandardAction>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example: KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); 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

    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_ (link pending).

    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" />
       <ActionList name="dynamicActionlist" />
     </ToolBar>
     <MenuBar>
       <Menu name="file" >
         <text>&File</text>
         <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.

    Note that you can also add dynamic action lists to your configuration file using a <ActionList> tag. For more information about this, see the plugActionList() method of the KXMLGUIClient documentation.

    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. For example, to install the program to the KDE directory:

    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), the following might be more appropriate:

    cmake . -DCMAKE_INSTALL_PREFIX=$PWD
    

    which will create a KDE-like directory structure under the current directory and will install the executable to $PWD/bin/tutorial3.

    Moving On

    TODO