Development/Tutorials/Using KXmlGuiWindow/KF5

How To Use KXmlGuiWindow

Tutorial Series	Beginner Tutorial
Previous	Tutorial 1 - Hello World
What's Next	Tutorial 3 - KActions and XMLGUI
Further Reading	KXmlGuiWindow

Abstract

This tutorial carries on from First Program Tutorial and will introduce the KXmlGuiWindow class.

In the previous tutorial, the program caused a dialog box to pop up but we're going to take steps towards a functioning application.

KXmlGuiWindow

Now found in the KF5::XmlGui framework

mainwindow.h

#ifndef MAINWINDOW_H
#define MAINWINDOW_H
 
#include <KXmlGuiWindow>

class KTextEdit;
 
class MainWindow : public KXmlGuiWindow
{
  public:
    MainWindow(QWidget *parent=0);
 
  private:
    KTextEdit* textArea;
};
 
#endif

Notes

• Use class forwarding instead of direct include.

mainwindow.cpp

#include <KTextEdit>

#include "mainwindow.h"

MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent)
{
  textArea = new KTextEdit();
  setCentralWidget(textArea);
  setupGUI();
}

Notes

• Include KTextEdit from here.

main.cpp

#include <cstdlib>
 
#include <QApplication>
#include <QCommandLineParser>

#include <KAboutData>
#include <KLocalizedString>

#include "mainwindow.h"
 
int main (int argc, char *argv[])
{
    // 1
    QApplication app(argc, argv);
    
    // 2
    KLocalizedString::setApplicationDomain("tutorial2");
    
    // 3
    KAboutData aboutData(
                         // The program name used internally. (componentName)
                         QStringLiteral("tutorial2"),
                         // A displayable program name string. (displayName)
                         // 4
                         i18n("Tutorial 2"),
                         // The program version string. (version)
                         QStringLiteral("1.0"),
                         // Short description of what the app does. (shortDescription)
                         i18n("A simple text area"),
                         // The license this code is released under
                         // 5
                         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"));
    
    // 6
    KAboutData::setApplicationData(aboutData);
 
    // 7
    QCommandLineParser parser;
    parser.addHelpOption();
    parser.addVersionOption();
    aboutData.setupCommandLine(&parser);
    parser.process(app);
    aboutData.processCommandLine(&parser);
    
    MainWindow* window = new MainWindow();
    window->show();
    
    return app.exec();
}

Notes

1. no more KApplication https://community.kde.org/Frameworks/Porting_Notes#Application
2. no more KAboutAdata catalogName https://community.kde.org/Frameworks/Porting_Notes#KAboutData
3. new KAboutData constructor http://api.kde.org/frameworks-api/frameworks5-apidocs/kcoreaddons/html/classKAboutData.html
4. use i18n for general and immediate cases, ki18n for special KF5 Cookbook https://books.kde.org/frameworks5/KDE-Frameworks-Cookbook.html#writing-messages
5. license keys http://api.kde.org/frameworks-api/frameworks5-apidocs/kcoreaddons/html/classKAboutLicense.html#a29386ce80267871552aedd21d9ce6bbb
6. Set about data https://mail.kde.org/pipermail/kde-frameworks-devel/2015-June/024983.html
7. new way to parse command line arguments https://community.kde.org/Frameworks/Porting_Notes#KCmdLineArgs

CMake

Add KXmlGui and KTextWidgets frameworks.

CMakeLists.txt

project (tutorial2)

#1
cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
set(QT_MIN_VERSION "5.3.0")
set(KF5_MIN_VERSION "5.2.0")

#2
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 
)

# Find KDE modules
find_package(KF5 ${KF5_MIN_VERSION} REQUIRED COMPONENTS
    CoreAddons      # KAboutData
    I18n            # KLocalizedString
    XmlGui          # KXmlGuiWindow
    TextWidgets     # KTextEdit
)
    

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)
    
set(tutorial2_SRCS main.cpp mainwindow.cpp)

# just plain add_executable
add_executable(tutorial2 ${tutorial2_SRCS})

# module-based linking
target_link_libraries(tutorial2
    Qt5::Widgets
    KF5::CoreAddons
    KF5::I18n
    KF5::XmlGui
    KF5::TextWidgets
)

install(TARGETS tutorial2  ${INSTALL_TARGETS_DEFAULT_ARGS})

Notes

1. KF5 Cookbook https://books.kde.org/frameworks5/KDE-Frameworks-Cookbook.html#adding-threadweaver-to-a-project---an-introduction-to-the-frameworks-5-build-system
2. https://community.kde.org/Frameworks/Porting_Notes#Build_System

TODO

warning: ‘virtual void KMainWindow::showAboutApplication()’ is deprecated [-Wdeprecated-declarations] /usr/include/KF5/KXmlGui/kmainwindow.h:604:37: note: declared here

    virtual KXMLGUI_DEPRECATED void showAboutApplication() {}