KF5 Tutorial 2 - How To Use KXmlGuiWindow

In first tutorial, we learned how to write our first KF5 program. In this 2nd tutorial, we will learn how to create a main window program. Again, this is example 2 from KDE4 - Development series available here. Credit for code goes to original writer of the code on  KDE techbase site. I will be making changes in that code so that it can be compiled and run using KDE Frameworks 5 libraries. With that said, you can use code in this post for learning development with KF5 libraries.

I will not explain each line of code like it is explained in KDE4 tutorial, however you will find short comments within code which will give you some idea about what's being done. I plan to add explanation for code at later time. Also, I am not pointing out changes that are made for porting purpose because I am planning to do it in near future.

Before we begin, I assume that you have development environment setup and you have completed the first tutorial. You need at least following software installed.

• Qt 5.3
• KDE Frameworks 5(KF5)
• cmake
• extra-cmake-modules(ECM)

So, let's begin with creating a project folder named 'MainWindow' inside KF5 folder. I assume that you still have 'KF5' folder we created in first tutorial. We will have folders organized as below.

KF5
|
|--- MainWindow


Edit: Code updated to remove deprecated classes KLocale, KAction and KIcon. Also removed use of KDELibs4Support and made it true port to KF5.

Now, first thing we need to do is to create a "mainwindow.h" file. This file will contain class definition for our MainWindow class. Create a new file inside MainWindow folder with below code and save it as "mainwindow.h" without quotes in name and put below code in it.

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

// including KF5 classes
#include <KXmlGuiWindow>
#include <KTextEdit>

// MainWindow class definition - It inherits the KXmlGuiWindow class
class MainWindow : public KXmlGuiWindow
{
  public:
      MainWindow(QWidget* parent = 0); // Constructor for our class

  private:
      KTextEdit* textArea;  // We will put a text area widget on our main window.
 
};

#endif

Now, our project should look like below.

KF5
|
|--- MainWindow
      |
      |--- mainwindow.h


We have our class defined now. Next, we need to implement the constructor in our implementation file. Create a "mainwindow.cpp" file in MainWindow folder. Put below code in it.

// Include our class definition for MainWindow class
#include "mainwindow.h"


// Implementation of our constructor
// We pass argument to KXmlGuiWindow class' constructor
MainWindow::MainWindow(QWidget* parent): KXmlGuiWindow(parent)
{
  // Create a new KTextEdit widget.
  textArea = new KTextEdit();

  // Set caption to be displayed in title bar.
  setCaption("My Editor");
  
  // Make KTextEdit widget a central widget of our main window.
  setCentralWidget(textArea);
  
  // Set the GUI for main window. Create Menu bar, status bar etc.
  setupGUI();
  
}

Now, our project should look like below.

KF5
|
|--- MainWindow
      |
      |--- mainwindow.h
      |--- mainwindow.cpp



We have finished implementing our main window. Now, we need to create a "main.cpp" file, which will create an application and show our main window.
Create "main.cpp" with below code.

// Include Qt classes
#include <QApplication>

// Include KF5 classes
#include <KAboutData>
#include <KLocalizedString>

// Include our MainWindow class
#include "mainwindow.h"


int main(int argc, char* argv[])
{
  // Configure data about our application. Data like display name, version, license etc.
  KAboutData about("editor", i18n("My Editor"), "0.1",
     i18n("A Simple Text Editor"),
     KAboutLicense::LGPL,
     i18n("Copyright (C) 2014 Arpan P")
  );
  
  // Add application author with role and email address.
  about.addAuthor(i18n("Arpan P"), i18n("Developer"), i18n("arpan@example.com"), QString());
  
  // Now, set above configured data to our application.
  KAboutData::setApplicationData(about);
  
  // Create an application, we use QApplication instead of KApplication
  QApplication app(argc, argv);

  // Set application's name to be displayed in title bar
  QApplication::setApplicationDisplayName(i18n("Simple Text Editor"));
  
  // Create our main window using our MainWindow class.
  MainWindow* window = new MainWindow();

  // Show our window on screen.
  window->show();
  
  // Wait until application closes and return status.
  return app.exec();
}

Now, our project should look like below.

KF5
|
|--- MainWindow
      |
      |--- mainwindow.h
      |--- mainwindow.cpp
      |--- main.cpp


Last thing we need to is compile and build our code. We will do it same way as we did it in first tutorial using cmake.

Create a file called "CMakeLists.txt" without quotes in name inside our MainWindow folder. Put below contents in it.

# Set minimum required version of cmake.
cmake_minimum_required(VERSION 2.8.12)

# Set project name.
project(mainwindow) 

# Locate extra-cmake-modules version 0.0.11 and make it a required package
find_package(ECM 0.0.11 REQUIRED NO_MODULE)

# Set value of CMAKE_MODULE_PATH variable where cmake will search for modules
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR})

# include KF5 directories
include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings)

# Locate Qt5, make it required package and use QtWidgets and QtCore modules
find_package(Qt5 REQUIRED COMPONENTS Widgets Core)

# Locate KF5, make it required package and use KF5CoreAddons, KI18n, KXmlGUI
# and KTextWidgets modules
find_package(KF5 REQUIRED COMPONENTS CoreAddons I18n XmlGui TextWidgets)

# Name of the exe file and source files from which exe will be generated.
add_executable(mainwindow main.cpp mainwindow.cpp)

# Link our exe with KF5 libraries we used in our code.
target_link_libraries(mainwindow KF5::CoreAddons KF5::I18n KF5::XmlGui KF5::TextWidgets)

We will also need a "build" directory to keep our code files separate from cmake generated files. So let's create "build" folder inside MainWindow folder. Run following command in command prompt.

mkdir build

Now, our project should look like below.

KF5
|
|--- MainWindow
     |
     |--- mainwindow.h
     |--- mainwindow.cpp
     |--- main.cpp
     |--- CMakeLists.txt
     |
     |--- build


Now, we want all files to be created inside this "build" folder so let's first change to it. Run below command.

cd build

Next step is to compile the code and generate a makefile using cmake. Run below command. This will use our CMakeLists.txt file for creating the makefile.

cmake ..

After, our code is compiled successfully and make file is generated, let's build the exe file using makefile. Run below command.

make

This will create exe file named "mainwindow" inside build folder. To execute it, run below command.

./mainwindow

Your application should look like this when running.

Main Window

About dialog

Author tab or About dialog

That's it. This is the end of porting KDE tutorial 2 to KF5. Hope this was helpful to you.

If you come across any error while following this example, post it in comment.

In next tutorial we will add some more menus and relative actions to our Text Editor.