Development/Tutorials/Using KActions: Difference between revisions

    From KDE TechBase
    m (Removed duplicated word.)
    m (Remove use of ECM_KDE_MODULE_DIR, part of ECM_MODULE_PATH)
    (15 intermediate revisions by 9 users not shown)
    Line 1: Line 1:
    {{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KActions}}


    {{TutorialBrowser|
    {{TutorialBrowser|
    Line 17: Line 16:
    This tutorial introduces 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.


    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}}.
    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 [http://doc.qt.io/qt-5/qaction.html QAction].


    [[image:introtokdetutorial3.png|frame|center]]
    [[image:tutorial3-kf5.png|frame|center]]


    ==KAction==
    ==QAction==
    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.


    == The Code ==
    A [http://doc.qt.io/qt-5/qaction.html QAction] 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.qt.io/qt-5/signalsandslots.html slot] which carries out the work of your action.
     
    ==The Code==


    ===main.cpp===
    ===main.cpp===
    <code cppqt>
    <syntaxhighlight lang="cpp-qt">
    #include <KApplication>
    #include <cstdlib>
    #include <QApplication>
    #include <QCommandLineParser>
     
    #include <KAboutData>
    #include <KAboutData>
    #include <KCmdLineArgs>
    #include <KLocalizedString>


    #include "mainwindow.h"
    #include "mainwindow.h"
     
    int main (int argc, char *argv[])
    int main (int argc, char *argv[])
    {
    {
      KAboutData aboutData( "tutorial3", "tutorial3",
        QApplication app(argc, argv);
          ki18n("Tutorial 3"), "1.0",
        KLocalizedString::setApplicationDomain("tutorial3");
          ki18n("A simple text area using KAction etc."),
       
          KAboutData::License_GPL,
        KAboutData aboutData(
          ki18n("Copyright (c) 2007 Developer") );
                            // The program name used internally. (componentName)
      KCmdLineArgs::init( argc, argv, &aboutData );
                            QStringLiteral("tutorial3"),
      KApplication app;
                            // A displayable program name string. (displayName)
                            i18n("Tutorial 3"),
                            // The program version string. (version)
                            QStringLiteral("1.0"),
                            // Short description of what the app does. (shortDescription)
                            i18n("A simple text area using KAction etc."),
                            // The license this code is released under
                            KAboutLicense::GPL,
                            // Copyright Statement (copyrightStatement = QString())
                            i18n("(c) 2015"),
                            // Optional text shown in the About box.
                            // Can contain any information desired. (otherText)
                            i18n("Some text..."),
                            // The program homepage string. (homePageAddress = QString())
                            QStringLiteral("http://example.com/"),
                            // The bug report email address
                            // (bugsEmailAddress = QLatin1String("[email protected]")
                            QStringLiteral("[email protected]"));
        aboutData.addAuthor(i18n("Name"), i18n("Task"), QStringLiteral("[email protected]"),
                            QStringLiteral("http://your.website.com"), QStringLiteral("OSC Username"));
        KAboutData::setApplicationData(aboutData);
       
       
      MainWindow* window = new MainWindow();
        QCommandLineParser parser;
      window->show();
        parser.addHelpOption();
      return app.exec();
        parser.addVersionOption();
        aboutData.setupCommandLine(&parser);
        parser.process(app);
        aboutData.processCommandLine(&parser);
       
        MainWindow* window = new MainWindow();
        window->show();
       
        return app.exec();
    }
    }
    </code>
    </syntaxhighlight>
    This time, very little has changed in <tt>main.cpp</tt>, only the KAboutData constructor has been updated to show that we are now on tutorial 3.
    This time, very little has changed in <tt>main.cpp</tt>, only the KAboutData constructor has been updated to show that we are now on tutorial 3.


    ===mainwindow.h===
    ===mainwindow.h===
    <code cppqt>
    <syntaxhighlight lang="cpp-qt">
    #ifndef MAINWINDOW_H
    #ifndef MAINWINDOW_H
    #define MAINWINDOW_H
    #define MAINWINDOW_H
     
    #include <KXmlGuiWindow>
    #include <KXmlGuiWindow>
    #include <KTextEdit>


    class KTextEdit;
    class MainWindow : public KXmlGuiWindow
    class MainWindow : public KXmlGuiWindow
    {
    {
       public:
       public:
         MainWindow(QWidget *parent=0);
         MainWindow(QWidget *parent=0);
       private:
       private:
         KTextEdit* textArea;
         KTextEdit* textArea;
         void setupActions();
         void setupActions();
    };
    };
     
    #endif
    #endif
    </code>
    </syntaxhighlight>
    Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions.
    Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the QActions.


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


    #include <KApplication>
    #include <KTextEdit>
    #include <KAction>
    #include <KLocalizedString>
    #include <KLocale>
    #include <KActionCollection>
    #include <KActionCollection>
    #include <KStandardAction>
    #include <KStandardAction>


    MainWindow::MainWindow(QWidget *parent)
    #include "mainwindow.h"
        : KXmlGuiWindow(parent)
     
    MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent)
    {
    {
       textArea = new KTextEdit;
       textArea = new KTextEdit();
       setCentralWidget(textArea);
       setCentralWidget(textArea);
     
     
       setupActions();
       setupActions();
    }
    }
    Line 94: Line 128:
    void MainWindow::setupActions()
    void MainWindow::setupActions()
    {
    {
      KAction* clearAction = new KAction(this);
        QAction* clearAction = new QAction(this);
      clearAction->setText(i18n("&Clear"));
        clearAction->setText(i18n("&Clear"));
      clearAction->setIcon(KIcon("document-new"));
        clearAction->setIcon(QIcon::fromTheme("document-new"));
      clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
        actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);
      actionCollection()->addAction("clear", clearAction);
        actionCollection()->addAction("clear", clearAction);
      connect(clearAction, SIGNAL(triggered(bool)),
        connect(clearAction, SIGNAL(triggered(bool)), textArea, SLOT(clear()));
              textArea, SLOT(clear()));
       
     
        KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
      KStandardAction::quit(kapp, SLOT(quit()),
       
                            actionCollection());
        setupGUI(Default, "tutorial3ui.rc");
     
      setupGUI(Default, "tutorial3ui.rc");
    }
    }
    </code>
    </syntaxhighlight>


    ==Explanation==
    ==Explanation==
    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> itself.


    ===Creating the KAction object===
    This builds upon the KXmlGuiWindow code from [[Development/Tutorials/Using_KXmlGuiWindow/KF5|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 QAction code goes before finally calling <tt>setupGUI()</tt> itself.
    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>
    ===Creating the QAction object===
    #include <KAction>
    The QAction is built up in a number of steps. The first is including the <tt>QAction</tt> header and then creating the QAction:
    <syntaxhighlight lang="cpp-qt">
    #include <QAction>
    ...
    ...
    KAction* clearAction = new KAction(this);
    QAction* clearAction = new QAction(this);
    </code>
    </syntaxhighlight>
    This creates a new KAction called <tt>clearAction</tt>.
    This creates a new QAction called <tt>clearAction</tt>.


    ===Setting KAction Properties===
    ===Setting QAction Properties===
    ====Text====
    ====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.
    Now that we have our QAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>QAction</tt>'s icon in the toolbar.
    <code cppqt>clearAction->setText(i18n("&Clear"));</code>
    <syntaxhighlight lang="cpp-qt">
    Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]).
    clearAction->setText(i18n("&Clear"));
    </syntaxhighlight>
    Note that the text is passed through the <tt>i18n()</tt> function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]).


    The text of the action should contain a <tt>&</tt> because that makes it easier to translate in non latin1 languages. In Japanese, the translation might be <tt>ソース(&S)</tt> and without the <tt>&</tt> in the english text the translators cannot know if they have to add a <tt>&</tt> or not.
    The text of the action should contain a <tt>&</tt> because that makes it easier to translate in non-latin1 languages. In Japanese, the translation might be <tt>ソース(&S)</tt> and without the <tt>&</tt> in the english text the translators cannot know if they have to add a <tt>&</tt> or not.


    ====Icon====
    ====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:
    If the action is going to be displayed in a toolbar, it is nice to have an icon depicting the action. The following code sets the icon to the standard the <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function:
    <code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
    <syntaxhighlight lang="cpp-qt">
    clearAction->setIcon(QIcon::fromTheme("document-new"));
    </syntaxhighlight>


    ====Keyboard Shortcut====
    ====Keyboard Shortcut====
    Setting a keyboard shortcut to perform our action is equally simple:
    Setting a keyboard shortcut to perform our action is equally simple:
    <code cppqt>clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</code>
    <syntaxhighlight lang="cpp-qt">
    This associates Ctrl+W with the KAction.
    actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);
    </syntaxhighlight>
    This associates Ctrl+W with the QAction.


    ===Adding to the Collection===
    ===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 like this:  
    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:  
    <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, ergo, it should not be localized, since it is used internally only.
    Here, the <tt>clearAction</tt> QAction 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, ergo, it should not be localized, since it is used internally only.


    ====Connecting 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 <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit)
    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)
    <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}}.


    ===KStandardAction===
    ===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 [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction].
    For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience QActions, accessed through {{kde|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 QActionCollection to add it to. For example:
    <syntaxhighlight lang="cpp-qt">
    KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
    </syntaxhighlight>
    Here we call the QApplicaton's [http://doc.qt.io/qt-5/qapplication.html#quit quit] method whenever the KStandardAction quit is triggered. We are able to access that QApplication method via the [http://doc.qt.io/qt-5/qapplication.html#qApp qApp] macro.


    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:
    In the end, this creates a QAction with the correct icon, text and shortcut and even adds it to the File menu.
    <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==
    ==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.
    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.}}


    ==Defining your own help menu==
    ==Defining your own help menu==
    The help menu is god-given, that is why all KDE help menus look the same. If you want to create your own help menu, go [http://websvn.kde.org/trunk/KDE/kdelibs/kdeui/widgets/khelpmenu.h?revision=1002779&view=markup here] and search for the explanation around showAboutApplication().
    The help menu is god-given, that is why all KDE help menus look the same. If you want to create your own help menu, search for the explanation around showAboutApplication() in from the {{class|KHelpMenu}} class in XMLGUI.


    ==XMLGUI==
    ==XMLGUI==
    Line 175: Line 215:
    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.
    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.


    ''See also'' [http://developer.kde.org/documentation/library/kdeqt/kde3arch/xmlgui.html developer.kde.org] which still provides valid information for KDE4.
    ==appnameui.rc file==


    ==''appname''ui.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 [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]].
     
    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]] (here is an older tutorial: [http://developer.kde.org/documentation/tutorials/xmlui/preface.html]).


    ===tutorial3ui.rc===
    ===tutorial3ui.rc===
    <code xml>
    <syntaxhighlight lang="xml">
    <?xml version="1.0" encoding="UTF-8"?>
    <?xml version="1.0" encoding="UTF-8"?>
    <gui name="tutorial3"
    <gui name="tutorial3"
    Line 190: Line 228:
         xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
         xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
                             http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >
                             http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >
     
       <MenuBar>
       <MenuBar>
         <Menu name="file" >
         <Menu name="file" >
           <Action name="clear" />
           <Action name="clear" />
         </Menu>
         </Menu>
        <Menu >
          <text>A&amp;nother Menu</text>
          <Action name="clear" />
        </Menu >
       </MenuBar>
       </MenuBar>
     
       <ToolBar name="mainToolBar" >
       <ToolBar name="mainToolBar" >
         <text>Main Toolbar</text>
         <text>Main Toolbar</text>
         <Action name="clear" />
         <Action name="clear" />
       </ToolBar>
       </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>.
    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>.
    Line 209: Line 251:
    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.
    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.


    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. Be sure it is an integer, if you use a decimal value, it will not work, but will not notify that it didn't. '''Note:''' The version attribute must be an integer number, i.e. it may not contain dots or other non-digits like an application version number.
    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. Be sure it is an integer, if you use a decimal value, it will not work, but will not notify that it didn't. '
     
    {{Warning|The version attribute must be an integer number, if you type in version<nowiki>=</nowiki>"1.2" it will dispose of your kittens  (but not eat them).}}


    Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <tt><nowiki><text/></nowiki></tt> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.
    Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <tt><nowiki><text/></nowiki></tt> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.


    ==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.'''
    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''', unlike in the previous tutorials.
     
    ===CMakeLists.txt===
    ===CMakeLists.txt===
    <code cmake>
    <syntaxhighlight lang="cmake">
    project(tutorial3)
    project (tutorial3)


    find_package(KDE4 REQUIRED)
    cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
    include_directories(${KDE4_INCLUDES})
    set(QT_MIN_VERSION "5.3.0")
    set(KF5_MIN_VERSION "5.2.0")


    set(tutorial3_SRCS
    find_package(ECM 1.0.0 REQUIRED NO_MODULE)
      main.cpp
    set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
      mainwindow.cpp
     
    include(KDEInstallDirs)
    include(KDECMakeSettings)
    include(KDECompilerSettings)
    include(FeatureSummary)
     
    find_package(Qt5 ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS
        Core    # QCommandLineParser, QStringLiteral
        Widgets # QApplication, QAction
    )
    )


    kde4_add_executable(tutorial3 ${tutorial3_SRCS})
    find_package(KF5 ${KF5_MIN_VERSION} REQUIRED COMPONENTS
        CoreAddons      # KAboutData
        I18n            # KLocalizedString
        XmlGui          # KXmlGuiWindow, KActionCollection
        TextWidgets    # KTextEdit
        ConfigWidgets  # KStandardActions
    )
       
     
    feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)
       
    set(tutorial3_SRCS main.cpp mainwindow.cpp)
     
    add_executable(tutorial3 ${tutorial3_SRCS})


    target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})
    target_link_libraries(tutorial3
        Qt5::Widgets
        KF5::CoreAddons
        KF5::I18n
        KF5::XmlGui
        KF5::TextWidgets
        KF5::ConfigWidgets
    )


    install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
    install(TARGETS tutorial3 ${INSTALL_TARGETS_DEFAULT_ARGS})
    install(FILES tutorial3ui.rc  
    install(FILES tutorial3ui.rc DESTINATION ${KXMLGUI_INSTALL_DIR}/tutorial3)
            DESTINATION ${DATA_INSTALL_DIR}/tutorial3)
    </syntaxhighlight>
    </code>


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


    ===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.
    This is probably the trickiest part. Where you install the files, especially <tt>tutorial3ui.rc</tt> is important. Normally, you'd want to install it where KDE software is installed by your distribution, which is usually under {{path|/usr}}. That, however, would require root/admin access and If you don't have that, 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. 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:
    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:
    mkdir build && cd build
    <syntaxhighlight lang="bash">
    cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
    mkdir build && cd build
    make install
    cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
    $HOME/bin/tutorial3
    make install
    which will create a KDE-like directory structure in your user's home directory and will install the executable to {{path|$HOME/bin/tutorial3}}.
    </syntaxhighlight>
    which will create a KDE-like directory structure in your user's home directory. Specifically, it will create the directories {{path|$HOME/bin/}} and {{path|$HOME/share/}} and will install the executable to {{path|$HOME/bin/tutorial3}} and the <tt>tutorial3ui.rc</tt> file to {{path|$HOME/share/kxmlgui/tutorial3/tutorial3ui.rc}}.
     
    However, to be able to run the program properly, you will need to let the system know where the XMLGUI file is. Since we installed it in a nonstandard location, we'll have to explicitly to do so every time. The following command would suffice:
    <syntaxhighlight lang="bash">
    XDG_DATA_DIRS=$HOME/share:$XDG_DATA_DIRS $HOME/bin/tutorial3
    </syntaxhighlight>
    This temporarily adds (prepends) the newly created "share" location to <tt>XDG_DATA_DIRS</tt>, the standard path for application data files.


    ==Moving On==
    ==Moving On==
    Now you can move on to [[Development/Tutorials/Saving_and_loading|saving and loading]].
    Now you can move on to [[Development/Tutorials/Saving_and_loading|saving and loading]].
    Or you can learn [[Development/Tutorial/Icons|how to add icons to your application]].
    Or you can learn [[Development/Tutorials/Desktop_File|how to place your application in the K-Menu using .desktop files]].
    {{Attention||The source code on this page applies only the current KDE Frameworks 5 ("KF5") version. For the older KDE Development Platform ("KDE4"), See [[Development/Tutorials/First_program/KDE4]]}}


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

    Revision as of 18:04, 18 April 2020

    How To Use KActions and XMLGUI
    Tutorial Series   Beginner Tutorial
    Previous   Tutorial 2 - KXmlGuiWindow, Basic XML knowledge
    What's Next   Tutorial 4 - Saving and loading
    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 QAction.

    QAction

    A QAction 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

    #include <cstdlib>
     
    #include <QApplication>
    #include <QCommandLineParser>
    
    #include <KAboutData>
    #include <KLocalizedString>
    
    #include "mainwindow.h"
     
    int main (int argc, char *argv[])
    {
        QApplication app(argc, argv);
        KLocalizedString::setApplicationDomain("tutorial3");
        
        KAboutData aboutData(
                             // The program name used internally. (componentName)
                             QStringLiteral("tutorial3"),
                             // A displayable program name string. (displayName)
                             i18n("Tutorial 3"),
                             // The program version string. (version)
                             QStringLiteral("1.0"),
                             // Short description of what the app does. (shortDescription)
                             i18n("A simple text area using KAction etc."),
                             // The license this code is released under
                             KAboutLicense::GPL,
                             // Copyright Statement (copyrightStatement = QString())
                             i18n("(c) 2015"),
                             // Optional text shown in the About box.
                             // Can contain any information desired. (otherText)
                             i18n("Some text..."),
                             // The program homepage string. (homePageAddress = QString())
                             QStringLiteral("http://example.com/"),
                             // The bug report email address
                             // (bugsEmailAddress = QLatin1String("[email protected]")
                             QStringLiteral("[email protected]"));
        aboutData.addAuthor(i18n("Name"), i18n("Task"), QStringLiteral("[email protected]"),
                            QStringLiteral("http://your.website.com"), QStringLiteral("OSC Username"));
        KAboutData::setApplicationData(aboutData);
     
        QCommandLineParser parser;
        parser.addHelpOption();
        parser.addVersionOption();
        aboutData.setupCommandLine(&parser);
        parser.process(app);
        aboutData.processCommandLine(&parser);
        
        MainWindow* window = new MainWindow();
        window->show();
        
        return app.exec();
    }
    

    This time, very little has changed in main.cpp, only the KAboutData constructor has been updated to show that we are now on tutorial 3.

    mainwindow.h

    #ifndef MAINWINDOW_H
    #define MAINWINDOW_H
     
    #include <KXmlGuiWindow>
    
    class KTextEdit;
     
    class MainWindow : public KXmlGuiWindow
    {
      public:
        MainWindow(QWidget *parent=0);
     
      private:
        KTextEdit* textArea;
        void setupActions();
    };
     
    #endif
    

    Only a function void setupActions() has been added which will do all the work setting up the QActions.

    mainwindow.cpp

    #include <QApplication>
    #include <QAction>
    
    #include <KTextEdit>
    #include <KLocalizedString>
    #include <KActionCollection>
    #include <KStandardAction>
    
    #include "mainwindow.h"
    
    MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent)
    {
      textArea = new KTextEdit();
      setCentralWidget(textArea);
      
      setupActions();
    }
    
    void MainWindow::setupActions()
    {
        QAction* clearAction = new QAction(this);
        clearAction->setText(i18n("&Clear"));
        clearAction->setIcon(QIcon::fromTheme("document-new"));
        actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);
        actionCollection()->addAction("clear", clearAction);
        connect(clearAction, SIGNAL(triggered(bool)), textArea, SLOT(clear()));
        
        KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
        
        setupGUI(Default, "tutorial3ui.rc");
    }
    

    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 QAction code goes before finally calling setupGUI() itself.

    Creating the QAction object

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

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

    This creates a new QAction called clearAction.

    Setting QAction Properties

    Text

    Now that we have our QAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the QAction'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 (more information on this can be found in the i18n tutorial).

    The text of the action should contain a & because that makes it easier to translate in non-latin1 languages. In Japanese, the translation might be ソース(&S) and without the & in the english text the translators cannot know if they have to add a & or not.

    Icon

    If the action is going to be displayed in a toolbar, it is nice to have an icon depicting the action. The following code sets the icon to the standard the document-new icon through the use of the setIcon() function:

    clearAction->setIcon(QIcon::fromTheme("document-new"));
    

    Keyboard Shortcut

    Setting a keyboard shortcut to perform our action is equally simple:

    actionCollection()->setDefaultShortcut(clearAction, Qt::CTRL + Qt::Key_W);
    

    This associates Ctrl+W with the QAction.

    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 like this:

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

    Here, the clearAction QAction 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, ergo, it should not be localized, since it is used internally only.

    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 KTextEdit (which, unsurprisingly, clears the KTextEdit)

    connect( clearAction, SIGNAL( triggered(bool) ), 
             textArea, SLOT( clear() ) );
    

    KStandardAction

    For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience QActions, accessed through Template:Kde.

    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 QActionCollection to add it to. For example:

    KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
    

    Here we call the QApplicaton's quit method whenever the KStandardAction quit is triggered. We are able to access that QApplication method via the qApp macro.

    In the end, this creates a QAction 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.

    Defining your own help menu

    The help menu is god-given, that is why all KDE help menus look the same. If you want to create your own help menu, search for the explanation around showAboutApplication() in from the KHelpMenu class in XMLGUI.

    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.

    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>
        <Menu >
          <text>A&amp;nother Menu</text>
          <Action name="clear" />
        </Menu >
      </MenuBar>
     
      <ToolBar name="mainToolBar" >
        <text>Main Toolbar</text>
        <Action name="clear" />
      </ToolBar>
     
    </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.

    Change the 'version' attribute of the <gui> tag if you changed .rc file since the last install to force a system cache update. Be sure it is an integer, if you use a decimal value, it will not work, but will not notify that it didn't. '

    Warning
    The version attribute must be an integer number, if you type in version="1.2" it will dispose of your kittens (but not eat them).


    Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <text/> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.

    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, unlike in the previous tutorials.

    CMakeLists.txt

    project (tutorial3)
    
    cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
    set(QT_MIN_VERSION "5.3.0")
    set(KF5_MIN_VERSION "5.2.0")
    
    find_package(ECM 1.0.0 REQUIRED NO_MODULE)
    set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
    
    include(KDEInstallDirs)
    include(KDECMakeSettings)
    include(KDECompilerSettings)
    include(FeatureSummary)
    
    find_package(Qt5 ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS 
        Core    # QCommandLineParser, QStringLiteral
        Widgets # QApplication, QAction
    )
    
    find_package(KF5 ${KF5_MIN_VERSION} REQUIRED COMPONENTS
        CoreAddons      # KAboutData
        I18n            # KLocalizedString
        XmlGui          # KXmlGuiWindow, KActionCollection
        TextWidgets     # KTextEdit
        ConfigWidgets   # KStandardActions
    )
        
    
    feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)
        
    set(tutorial3_SRCS main.cpp mainwindow.cpp)
    
    add_executable(tutorial3 ${tutorial3_SRCS})
    
    target_link_libraries(tutorial3
        Qt5::Widgets
        KF5::CoreAddons
        KF5::I18n
        KF5::XmlGui
        KF5::TextWidgets
        KF5::ConfigWidgets
    )
    
    install(TARGETS tutorial3  ${INSTALL_TARGETS_DEFAULT_ARGS})
    install(FILES tutorial3ui.rc DESTINATION ${KXMLGUI_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 INSTALL_TARGETS_DEFAULT_ARGS then the tutorial3ui.rc file that describes the layout of the user interface is installed to the application's data directory under KXMLGUI_INSTALL_DIR.

    Make, Install And Run

    This is probably the trickiest part. Where you install the files, especially tutorial3ui.rc is important. Normally, you'd want to install it where KDE software is installed by your distribution, which is usually under /usr. That, however, would require root/admin access and If you don't have that, 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. 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:

    mkdir build && cd build
    cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
    make install
    

    which will create a KDE-like directory structure in your user's home directory. Specifically, it will create the directories $HOME/bin/ and $HOME/share/ and will install the executable to $HOME/bin/tutorial3 and the tutorial3ui.rc file to $HOME/share/kxmlgui/tutorial3/tutorial3ui.rc.

    However, to be able to run the program properly, you will need to let the system know where the XMLGUI file is. Since we installed it in a nonstandard location, we'll have to explicitly to do so every time. The following command would suffice:

    XDG_DATA_DIRS=$HOME/share:$XDG_DATA_DIRS $HOME/bin/tutorial3
    

    This temporarily adds (prepends) the newly created "share" location to XDG_DATA_DIRS, the standard path for application data files.

    Moving On

    Now you can move on to saving and loading.

    Or you can learn how to add icons to your application.

    Or you can learn how to place your application in the K-Menu using .desktop files.

    The source code on this page applies only the current KDE Frameworks 5 ("KF5") version. For the older KDE Development Platform ("KDE4"), See Development/Tutorials/First_program/KDE4