Difference between revisions of "Development/Tutorials/Saving and loading"

m (Remove use of ECM_KDE_MODULE_DIR, part of ECM_MODULE_PATH)
(Replaced content with "This page was moved [https://develop.kde.org/docs/getting-started/saving_and_loading/ here].")
Tag: Replaced
 
Line 1: Line 1:
<languages/>
+
This page was moved [https://develop.kde.org/docs/getting-started/saving_and_loading/ here].
<translate>
 
<!--T:1-->
 
{{TutorialBrowser|
 
series=Beginner Tutorial|
 
name=Loading and saving files|
 
pre=[[Development/Tutorials/Using_Actions|Tutorial 3 - Actions]]|
 
next=[[Development/Tutorials/CommandLineArguments|Tutorial 5 - Using Command Line Arguments]]|
 
reading=[[Development/Tutorials/KIO Slaves/Using KIO Slaves in your Program|Tutorial: Using KIO Slaves in your Program]] KIO::{{class|NetAccess}} {{qt|QFile}}
 
}}
 
 
 
==Abstract== <!--T:2-->
 
 
 
<!--T:3-->
 
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.
 
 
 
<!--T:4-->
 
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.
 
 
 
<!--T:5-->
 
[[image:tutorial4-kf5.png|frame|center]]
 
 
 
== The Code == <!--T:6-->
 
 
 
===main.cpp=== <!--T:7-->
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
#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("tutorial4");
 
   
 
    KAboutData aboutData(
 
                        // The program name used internally. (componentName)
 
                        QStringLiteral("tutorial4"),
 
                        // A displayable program name string. (displayName)
 
                        i18n("Tutorial 4"),
 
                        // The program version string. (version)
 
                        QStringLiteral("1.0"),
 
                        // Short description of what the app does. (shortDescription)
 
                        i18n("A simple text area which can load and save."),
 
                        // 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;
 
    aboutData.setupCommandLine(&parser);
 
    parser.process(app);
 
    aboutData.processCommandLine(&parser);
 
   
 
    MainWindow* window = new MainWindow();
 
    window->show();
 
   
 
    return app.exec();
 
}
 
</syntaxhighlight>
 
<translate>
 
<!--T:8-->
 
<tt>main.cpp</tt> hasn't changed from tutorial 3 except to change any reference from tutorial 3 to tutorial 4.
 
 
 
===mainwindow.h=== <!--T:9-->
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
#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();
 
 
  private slots:
 
    void newFile();
 
    void openFile();
 
    void saveFile();
 
    void saveFileAs();
 
    void saveFileAs(const QString &outputFileName);
 
   
 
    void downloadFinished(KJob* job);
 
 
 
  private:
 
    KTextEdit* textArea;
 
    QString fileName;
 
};
 
 
#endif
 
</syntaxhighlight>
 
<translate>
 
<!--T:10-->
 
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 [http://doc.qt.io/qt-5/signalsandslots.html 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 [http://doc.qt.io/qt-5/qobject.html#Q_OBJECT <tt>Q_OBJECT</tt>] macro.
 
 
 
<!--T:11-->
 
We also want to keep track of the filename of the currently opened file so we declare a <tt>[http://doc.qt.io/qt-5/qstring.html QString] fileName</tt>.
 
 
 
===mainwindow.cpp=== <!--T:12-->
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
#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, SIGNAL(triggered(bool)), textArea, SLOT(clear()));
 
   
 
    KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
 
   
 
    KStandardAction::open(this, SLOT(openFile()), actionCollection());
 
 
    KStandardAction::save(this, SLOT(saveFile()), actionCollection());
 
 
    KStandardAction::saveAs(this, SLOT(saveFileAs()), actionCollection());
 
 
    KStandardAction::openNew(this, SLOT(newFile()), actionCollection());
 
   
 
    setupGUI(Default, "tutorial4ui.rc");
 
}
 
 
 
void MainWindow::newFile()
 
{
 
    fileName.clear();
 
    textArea->clear();
 
}
 
 
 
void MainWindow::saveFileAs(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()
 
{
 
    saveFileAs(QFileDialog::getSaveFileName(this, i18n("Save File As")));
 
}
 
 
 
void MainWindow::saveFile()
 
{
 
    if (!fileName.isEmpty())
 
    {
 
        saveFileAs(fileName);
 
    }
 
    else
 
    {
 
        saveFileAs();
 
    }
 
}
 
 
 
 
 
void MainWindow::openFile()
 
{
 
    QUrl fileNameFromDialog = QFileDialog::getOpenFileUrl(this, i18n("Open File"));
 
   
 
    if (!fileNameFromDialog.isEmpty())
 
    {
 
        KIO::Job* job = KIO::storedGet(fileNameFromDialog);
 
        fileName = fileNameFromDialog.toLocalFile();
 
 
 
        connect(job, SIGNAL(result(KJob*)), this, SLOT(downloadFinished(KJob*)));
 
       
 
        job->exec();
 
    }
 
}
 
 
 
void MainWindow::downloadFinished(KJob* job)
 
{
 
    if (job->error())
 
    {
 
        KMessageBox::error(this, job->errorString());
 
        fileName.clear();
 
        return;
 
    }
 
   
 
    KIO::StoredTransferJob* storedJob = (KIO::StoredTransferJob*)job;
 
    textArea->setPlainText(QTextStream(storedJob->data(), QIODevice::ReadOnly).readAll());
 
}
 
</syntaxhighlight>
 
<translate>
 
<!--T:13-->
 
We'll get into the details of <tt>mainwindow.cpp</tt> in a while.
 
 
 
===tutorial4ui.rc=== <!--T:14-->
 
</translate>
 
<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<gui name="tutorial4"
 
    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>
 
  </MenuBar>
 
 
  <ToolBar name="mainToolBar" >
 
    <text>Main Toolbar</text>
 
    <Action name="clear" />
 
  </ToolBar>
 
 
</gui>
 
</syntaxhighlight>
 
<translate>
 
<!--T:15-->
 
This is identical to <tt>tutorial3ui.rc</tt> from tutorial 3 except the <tt>name</tt> has changed to 'tutorial4'. We do not need to add any information about any of the <tt>KStandardAction</tt>s since the placement of those actions is handled automatically by KDE.
 
 
 
==Explanation== <!--T:16-->
 
 
 
<!--T:17-->
 
Okay, now to implement the code that will do the loading and saving. This will all be happening in <tt>mainwindow.cpp</tt>
 
 
 
<!--T:18-->
 
The first thing we do is add <tt>fileName(QString())</tt> to the <tt>MainWindow</tt> constructor list to make sure that <tt>fileName</tt> is empty right from the beginning.
 
 
 
===Adding the actions=== <!--T:19-->
 
 
 
<!--T:20-->
 
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 <tt>quit</tt> action in tutorial 3, we will use <tt>KStandardActions</tt>. We add the actions in the same way as for the <tt>quit</tt> action and, for each one, we connect it to the appropriate slot that we declared in the header file.
 
 
 
===Creating a new document=== <!--T:21-->
 
 
 
<!--T:22-->
 
The first function we create is the <tt>newFile()</tt> function.
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
void MainWindow::newFile()
 
{
 
  fileName.clear();
 
  textArea->clear();
 
}
 
</syntaxhighlight>
 
<translate>
 
<!--T:23-->
 
<tt>fileName.clear()</tt> sets the <tt>fileName</tt> QString to be empty to reflect the fact that this document does not yet have a presence on storage. <tt>textArea->clear()</tt> then clears the central text area using the same function that we connected the <tt>clear</tt> <tt>KQction</tt> to in tutorial 3.
 
 
 
<!--T:24-->
 
{{Warning|This simple 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 not as an example of best programming practices.}}
 
 
 
===Saving a file=== <!--T:25-->
 
 
 
<!--T:26-->
 
{{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.}}
 
 
 
====saveFileAs(QString)==== <!--T:27-->
 
 
 
<!--T:28-->
 
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 [http://doc.qt.io/qt-5/qsavefile.html QSaveFile].
 
 
 
<!--T:29-->
 
The function's prototype is
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
void MainWindow::saveFileAs(const QString &outputFileName)
 
</syntaxhighlight>
 
<translate>
 
<!--T:30-->
 
We then create our <tt>QSaveFile</tt> object and open it with
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
QSaveFile file(outputFileName);
 
file.open(QIODevice::WriteOnly);
 
</syntaxhighlight>
 
<translate>
 
<!--T:31-->
 
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 [http://doc.qt.io/qt-5/qbytearray.html QByteArray] and fill it with the plain text version of whatever is in the text area:
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
QByteArray outputByteArray;
 
outputByteArray.append(textArea->toPlainText().toUtf8());
 
</syntaxhighlight>
 
<translate>
 
<!--T:32-->
 
Now that we have our <tt>QByteArray</tt>, we use it to write to the file with <tt>QSaveFile::write()</tt>. If we were using a normal <tt>QFile</tt>, this would make the changes immediately. However, if a problem occurred partway through writing, the file would become corrupted. For this reason, <tt>QSaveFile</tt> works by first writing to a temporary file and then, when you call <tt>QSaveFile::commit()</tt> the changes are made to the actual file. <tt>commit()</tt> also closes the file.
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
file.write(outputByteArray);
 
file.commit();
 
</syntaxhighlight>
 
<translate>
 
<!--T:33-->
 
Finally, we set <tt>MainWindows</tt>'s <tt>fileName</tt> member to point to the file name we just saved to.
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
fileName = outputFileName;
 
</syntaxhighlight>
 
<translate>
 
 
 
====saveFileAs()==== <!--T:34-->
 
 
 
<!--T:35-->
 
This is the function that the <tt>saveAs</tt> slot is connected to. It simply calls the generic <tt>saveFileAs(QString)</tt> function and passes the file name returned by <tt>[http://doc.qt.io/qt-5/qfiledialog.html QFileDialog]::[http://doc.qt.io/qt-5/qfiledialog.html#getSaveFileName getSaveFileName()]</tt>.
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
void MainWindow::saveFileAs()
 
{
 
  saveFileAs(QFileDialog::getSaveFileName(this, i18n("Save File As")));
 
}
 
</syntaxhighlight>
 
<translate>
 
 
 
<!--T:36-->
 
[http://doc.qt.io/qt-5/qfiledialog.html QFileDialog] provides a number of static functions for displaying the common file dialog that is used by all KDE applications. Calling <tt>QFileDialog::getSaveFileName()</tt> 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 <tt>saveFileAs(QString)</tt>.
 
 
 
====saveFile()==== <!--T:37-->
 
 
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
void MainWindow::saveFile()
 
{
 
  if(!fileName.isEmpty())
 
  {
 
    saveFileAs(fileName);
 
  }
 
  else
 
  {
 
    saveFileAs();
 
  }
 
}
 
</syntaxhighlight>
 
<translate>
 
 
 
<!--T:38-->
 
There's nothing exciting or new in this function, just the logic to decide whether or not to show the save dialog. If <tt>fileName</tt> is not empty, then the file is saved to <tt>fileName</tt>. But if it is, then the dialog is shown to allow the user to select a file name.
 
 
 
===Loading a file=== <!--T:39-->
 
 
 
<!--T:40-->
 
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 <tt>MainWindow::openFile()</tt>.
 
 
 
<!--T:41-->
 
First we must ask the user for the name of the file they wish to open. We do this using another one of the <tt>QFileDialog</tt> functions, this time <tt>getOpenFileName()</tt>:
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
QUrl fileNameFromDialog = QFileDialog::getOpenFileUrl(this, i18n("Open File"));
 
</syntaxhighlight>
 
<translate>
 
<!--T:42-->
 
Here we use the QUrl class to handle files from remote locations.
 
 
 
<!--T:43-->
 
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 <tt>[http://api.kde.org/frameworks-api/frameworks5-apidocs/kio/html/namespaceKIO.html#a17631774b47cddb0127d8a3c1fc2315c KIO::storedGet()]</tt> function with an argument for the file you wish to open or download:
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
KIO::Job* job = KIO::storedGet(fileNameFromDialog);
 
</syntaxhighlight>
 
<translate>
 
 
 
<!--T:44-->
 
The function returns a handle to a <tt>KIO::Job</tt>, which we first connect to our <tt>downloadFinished()</tt> slot before "running" the job.
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
connect(job, SIGNAL(result(KJob*)), this, SLOT(downloadFinished(KJob*)));
 
 
 
job->exec();
 
</syntaxhighlight>
 
<translate>
 
 
 
<!--T:45-->
 
The rest of the work happens in the <tt>downloadFinished()</tt> 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:
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
KMessageBox::error(this, job->errorString());
 
fileName.clear();
 
</syntaxhighlight>
 
<translate>
 
<!--T:46-->
 
Otherwise, we continue with opening the file.
 
 
 
<!--T:47-->
 
The data that <tt>storedGet()</tt> successfully downloaded, in this case the contents of our text file, is stored in the <tt>data</tt> member of a <tt>[http://api.kde.org/frameworks-api/frameworks5-apidocs/kio/html/classKIO_1_1StoredTransferJob.html KIO::StoredTransferJob]</tt> class. But in order to display the contents of the file at text, we must use a [http://doc.qt.io/qt-5/qtextstream.html QTextStream]. We create one by passing the the data of the <tt>StoredTransferJob</tt> to its constructor and then call its <tt>readAll()</tt> function to get the text from the file. This is then passed to the <tt>setPlainText()</tt> function of our text area.
 
</translate>
 
<syntaxhighlight lang="cpp-qt">
 
KIO::StoredTransferJob* storedJob = (KIO::StoredTransferJob*)job;
 
textArea->setPlainText(QTextStream(storedJob->data(), QIODevice::ReadOnly).readAll());
 
</syntaxhighlight>
 
<translate>
 
<!--T:48-->
 
{{{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== <!--T:49-->
 
 
 
===CMakeLists.txt=== <!--T:50-->
 
</translate>
 
<syntaxhighlight lang="cmake">
 
cmake_minimum_required(VERSION 3.0)
 
 
 
project (tutorial4)
 
 
 
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 NO_POLICY_SCOPE)
 
include(FeatureSummary)
 
 
 
find_package(Qt5 ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS
 
    Core    # QCommandLineParser, QStringLiteral, QSaveFile, QTextStream, QByteArray
 
    Widgets # QApplication, QAction, QFileDialog
 
)
 
 
 
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(tutorial4_SRCS main.cpp mainwindow.cpp)
 
 
 
add_executable(tutorial4 ${tutorial4_SRCS})
 
 
 
target_link_libraries(tutorial4
 
    Qt5::Widgets
 
    KF5::CoreAddons
 
    KF5::I18n
 
    KF5::XmlGui
 
    KF5::TextWidgets
 
    KF5::ConfigWidgets
 
    KF5::WidgetsAddons
 
    KF5::KIOCore
 
)
 
 
 
install(TARGETS tutorial4  ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
 
 
 
install(FILES tutorial4ui.rc DESTINATION ${KDE_INSTALL_KXMLGUI5DIR}/tutorial4)
 
</syntaxhighlight>
 
<translate>
 
<!--T:51-->
 
Since we are now using the KIO library, we must tell CMake to link against it. We do this by passing <tt>KIO</tt> to the <tt>find_package()</tt> function and <tt>KF5::KIOCore</tt> to <tt>target_link_libraries()</tt> function.
 
 
 
<!--T:52-->
 
With this file, the tutorial can be built and run in the same way as tutorial 3. For more information, see tutorial 3.
 
</translate>
 
<syntaxhighlight lang="bash">
 
mkdir build && cd build
 
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
 
make install
 
XDG_DATA_DIRS=$HOME/share:$XDG_DATA_DIRS $HOME/bin/tutorial4
 
</syntaxhighlight>
 
<translate>
 
 
 
==Moving On== <!--T:53-->
 
 
 
<!--T:54-->
 
Now you can move on to the [[Development/Tutorials/CommandLineArguments|command line arguments]] tutorial.
 
 
 
<!--T:55-->
 
[[Category:C++]]
 
</translate>
 

Latest revision as of 14:34, 8 September 2020

This page was moved here.


This page was last edited on 8 September 2020, at 14:34. Content is available under Creative Commons License SA 4.0 unless otherwise noted.