Development/Tutorials/Using KActions/KF5: Difference between revisions

    From KDE TechBase
    Line 211: Line 211:
    ==XMLGUI==
    ==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.
    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.


    ==appnameui.rc file==
    ==appnameui.rc file==

    Revision as of 03:39, 16 January 2016

    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.

    KAction

    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

    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>
    

    CMake

    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} ${ECM_KDE_MODULE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
    
    include(KDEInstallDirs)
    include(KDECMakeSettings)
    include(KDECompilerSettings)
    include(FeatureSummary)
    
    # Find Qt modules
    find_package(Qt5 ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS 
        Core    # QCommandLineParser, QStringLiteral
        Widgets # QApplication, QAction
    )
    
    # Find KDE modules
    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)
    
    # just plain add_executable
    add_executable(tutorial3 ${tutorial3_SRCS})
    
    # module-based linking
    target_link_libraries(tutorial3
        Qt5::Widgets
        KF5::CoreAddons
        KF5::I18n
        KF5::XmlGui
        KF5::TextWidgets
        KF5::ConfigWidgets
    )
    
    install(TARGETS tutorial3  ${INSTALL_TARGETS_DEFAULT_ARGS})
    # 1
    install(FILES tutorial3ui.rc DESTINATION ${KXMLGUI_INSTALL_DIR}/tutorial3)
    

    Notes

    1. .ui files now installed to {KXMLGUI_INSTALL_DIR - https://community.kde.org/Frameworks/Porting_Notes#General

    Moving On