Saving and loading

Introduces the KIO library while adding loading and saving support to our application.

Introduction

Now that we have a basic text editor interface, it’s time to make it do something useful. At the most basic, a text editor needs to be able to load files from data storage, save files that you’ve created/edited, and create new files.

The KDE Frameworks provides a number of classes for working with files that make life a lot easier for developers. The KIO framework allows you to easily access files through network-transparent protocols. At the same time, Qt also provides standard file dialogs for opening and saving files.

The Code

main.cpp

We don’t need to change anything in here.

mainwindow.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
#ifndef MAINWINDOW_H
#define MAINWINDOW_H
 
#include <KXmlGuiWindow>

class KTextEdit;
class KJob;
 
class MainWindow : public KXmlGuiWindow
{
    Q_OBJECT
    
public:
    explicit MainWindow(QWidget *parent = nullptr);

private:
    void setupActions();
    void saveFileToDisk(const QString &outputFileName);

private Q_SLOTS:
    void newFile();
    void openFile();
    void saveFile();
    void saveFileAs();
    
    void downloadFinished(KJob *job);

private:
    KTextEdit *textArea;
    QString fileName;
};

#endif // MAINWINDOW_H

Since we want to add the ability to load and save files, we must add the functions which will do the work. Since the functions will be called through Qt’s signal/slot mechanism we must specify that these functions are slots. Since we are using slots in this header file, we must also add the Q_OBJECT macro.

We also want to keep track of the filename of the currently opened file so we declare a QString fileName.

mainwindow.cpp

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
#include <QApplication>
#include <QAction>
#include <QSaveFile>
#include <QFileDialog>
#include <QTextStream>
#include <QByteArray>

#include <KTextEdit>
#include <KLocalizedString>
#include <KActionCollection>
#include <KStandardAction>
#include <KMessageBox>
#include <KIO/Job>

#include "mainwindow.h"

MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent), fileName(QString())
{
  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, &QAction::triggered, textArea, &KTextEdit::clear);
    
    KStandardAction::quit(qApp, &QCoreApplication::quit, actionCollection());
    KStandardAction::open(this, &MainWindow::openFile, actionCollection());
    KStandardAction::save(this, &MainWindow::saveFile, actionCollection());
    KStandardAction::saveAs(this, &MainWindow::saveFileAs, actionCollection());
    KStandardAction::openNew(this, &MainWindow::newFile, actionCollection());

    setupGUI(Default, "texteditorui.rc");
}

void MainWindow::newFile()
{
    fileName.clear();
    textArea->clear();
}

void MainWindow::saveFileToDisk(const QString &outputFileName)
{
    if (!outputFileName.isNull()) {
        QSaveFile file(outputFileName);
        file.open(QIODevice::WriteOnly);
        
        QByteArray outputByteArray;
        outputByteArray.append(textArea->toPlainText().toUtf8());

        file.write(outputByteArray);
        file.commit();

        fileName = outputFileName;
    }
}

void MainWindow::saveFileAs()
{
    saveFileToDisk(QFileDialog::getSaveFileName(this, i18n("Save File As")));
}

void MainWindow::saveFile()
{
    if (!fileName.isEmpty()) {
        saveFileToDisk(fileName);
    } else {
        saveFileAs();
    }
}

void MainWindow::openFile()
{
    const QUrl fileNameFromDialog = QFileDialog::getOpenFileUrl(this, i18n("Open File"));
    
    if (!fileNameFromDialog.isEmpty()) {
        KIO::Job *job = KIO::storedGet(fileNameFromDialog);
        fileName = fileNameFromDialog.toLocalFile();

        connect(job, &KJob::result, this, &MainWindow::downloadFinished);
        
        job->exec();
    }
}

void MainWindow::downloadFinished(KJob *job)
{
    if (job->error()) {
        KMessageBox::error(this, job->errorString());
        fileName.clear();
        return;
    }
    
    const KIO::StoredTransferJob *storedJob = qobject_cast<KIO::StoredTransferJob *>(job);
    
    if (storedJob) {
        textArea->setPlainText(QTextStream(storedJob->data(), QIODevice::ReadOnly).readAll());
    }
}

We’ll get into the details of mainwindow.cpp in a while.

texteditorui.rc

This is identical to texteditorui.rc from the previous tutorial. We do not need to add any information about any of the KStandardAction since the placement of those actions is handled automatically by the XMLGUI system.

Explanation

Okay, now to implement the code that will do the loading and saving. This will all be happening in mainwindow.cpp.

MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent), fileName(QString())

The first thing we do is add fileName(QString()) to the MainWindow constructor list to make sure that fileName is empty right from the beginning.

Adding the actions

The first thing we are going to do is provide the outward interface for the user so they can tell the application to load and save. Like with the quit action in the previous tutorial, we will use KStandardAction . We add the actions in the same way we did for the quit action and, for each one, we connect it to the appropriate slot that we declared in the header file.

Creating a new document

The first function we create is the newFile() function.

void MainWindow::newFile()
{
  fileName.clear();
  textArea->clear();
}

fileName.clear() sets the fileName QString to be empty to reflect the fact that this document does not yet have a presence on storage. textArea->clear() then clears the central text area using the same function that we connected the ‘clear’ QAction to in the previous tutorial.

Warning

This example simply clears the text area without checking if the file has been saved first. It’s only meant as a demonstration of file I/O and is not an example of best programming practices.

Saving a file

Note

To make this tutorial simple, this example program can only save to local storage even though it can open any file from any location, even those from remote sources.

saveFileToDisk(const QString &)

Now we get onto our first file handling code. We’re going to implement a function which will save the contents of the text area to the file name given as a parameter. Qt provides a class for safely saving a file called QSaveFile.

The function’s prototype is:

void MainWindow::saveFileAs(const QString &outputFileName)

We then create our QSaveFile object and open it with:

QSaveFile file(outputFileName);
file.open(QIODevice::WriteOnly);

Now that we have our file to write to, we need to format the text in the text area to a format which can be written to file. For this, we create a QByteArray and fill it with the plain text version of whatever is in the text area:

QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText().toUtf8());

Now that we have our QByteArray, we use it to write to the file with QSaveFile::write(). If we were using a normal QFile, this would make the changes immediately. However, if a problem occurred partway through writing, the file would become corrupted. For this reason, QSaveFile works by first writing to a temporary file and then, when you call QSaveFile::commit() the changes are made to the actual file. commit() also closes the file.

file.write(outputByteArray);
file.commit();

Finally, we set MainWindows’s fileName member to point to the file name we just saved to.

fileName = outputFileName;

saveFileAs()

This is the function that the saveAs slot is connected to. It simply calls the generic saveFileAs(QString) function and passes the file name returned by QFileDialog ::getSaveFileName() .

void MainWindow::saveFileAs()
{
    saveFileAs(QFileDialog::getSaveFileName(this, i18n("Save File As")));
}

QFileDialog provides a number of static functions for displaying the common file dialog that is used by all KDE applications. Calling QFileDialog::getSaveFileName() will display a dialog where the user can select the name of the file to save to or choose a new name. The function returns the full file name, which we then pass to saveFileAs(QString).

saveFile()

void MainWindow::saveFile()
{
    if(!fileName.isEmpty()) {
        saveFileAs(fileName);
    } else {
        saveFileAs();
    }
}

There’s nothing exciting or new in this function, just the logic to decide whether or not to show the save dialog. If fileName is not empty, then the file is saved to fileName. But if it is, then the dialog is shown to allow the user to select a file name.

Loading a file

Finally, we get round to being able to load a file, from local storage or from a remote location like an FTP server. The code for this is all contained in MainWindow::openFile().

First we must ask the user for the name of the file they wish to open. We do this using another one of the QFileDialog functions, this time getOpenFileUrl():

const QUrl fileNameFromDialog = QFileDialog::getOpenFileUrl(this, i18n("Open File"));

Here we use the QUrl class to handle files from remote locations.

Then we use the KIO library to retrieve our file. This allows us to open the file normally even if it’s stored in a remote location like an FTP site. We make the following call to the KIO::storedGet function with an argument for the file you wish to open or download:

const KIO::Job *job = KIO::storedGet(fileNameFromDialog);

The function returns a handle to a KIO::Job , which we first connect to our downloadFinished() slot before “running” the job.

connect(job, &KJob::result, this, &KJob::downloadFinished);
job->exec();

The rest of the work happens in the downloadFinished() slot. First, the job is checked for errors. If it failed, we display a message box giving the error. We also make sure to clear the fileName, since the file wasn’t opened successfully:

KMessageBox::error(this, job->errorString());
fileName.clear();

Otherwise, we continue with opening the file.

The data that storedGet() successfully downloaded, in this case the contents of our text file, is stored in the data member of a KIO::StoredTransferJob class. But in order to display the contents of the file at text, we must use a QTextStream. We create one by passing the the data of the StoredTransferJob to its constructor and then call its readAll() function to get the text from the file. This is then passed to the setPlainText() function of our text area.

Note

Again, for simplicity’s sake, this tutorial only saves text files to local disk. When you open a remote file for viewing and try to save it, the program will behave as if you were calling Save As on a completely new file.

Make, Install, and Run

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
cmake_minimum_required(VERSION 3.0)

project(texteditor)

set(QT_MIN_VERSION "5.11.0")
set(KF5_MIN_VERSION "5.68.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 NO_POLICY_SCOPE)
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
    WidgetsAddons   # KMessageBox
    KIO             # KIO
)
    

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

add_executable(texteditor ${texteditor_SRCS})

target_link_libraries(texteditor
    Qt5::Widgets
    KF5::CoreAddons
    KF5::I18n
    KF5::XmlGui
    KF5::TextWidgets
    KF5::ConfigWidgets
    KF5::WidgetsAddons
    KF5::KIOCore
)

install(TARGETS texteditor ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
install(FILES texteditorui.rc DESTINATION ${KDE_INSTALL_KXMLGUI5DIR}/texteditor)

Since we are now using the KIO library, we must tell CMake to link against it. We do this by passing KIO to the find_package() function and KF5::KIOCore to target_link_libraries() function.

With this file, the tutorial can be built and run in the same way as the previous tutorial.

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/.local-kde
make install
source prefix.sh # located in the build directory
texteditor

Using Actions

Command Line Interface