Development/Tutorials/Saving and loading: Difference between revisions

From KDE TechBase
m (Another tiny grammer fix)
(Replaced content with "This page was moved [https://develop.kde.org/docs/getting-started/saving_and_loading/ here].")
Tag: Replaced
 
(27 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Saving_and_loading}}
This page was moved [https://develop.kde.org/docs/getting-started/saving_and_loading/ here].
 
{{TutorialBrowser|
 
series=Beginner Tutorial|
 
name=Loading and saving files|
 
pre=[[Development/Tutorials/Using_KActions|Tutorial 3 - KActions]]|
 
next=[[Development/Tutorials/KCmdLineArgs|Tutorial 5 - Using KCmdLineArgs]]|
 
reading=KIO::{{class|NetAccess}} {{qt|QFile}}
}}
 
==Abstract==
 
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 disc, save files that you've created/edited and create new files.
 
KDE provides a number of classes for working with files which make life a lot easier for developers. The KIO library allows you to easily access files through network-transparent protocols as well as providing standard file dialogs.
 
[[image:introtokdetutorial4.png|frame|center]]
 
== The Code ==
 
===main.cpp===
<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include "mainwindow.h"
int main (int argc, char *argv[])
{
  KAboutData aboutData( "tutorial4", "tutorial4",
      ki18n("Tutorial 4"), "1.0",
      ki18n("A simple text area which can load and save."),
      KAboutData::License_GPL,
      ki18n("Copyright (c) 2007 Developer") );
  KCmdLineArgs::init( argc, argv, &aboutData );
  KApplication app;
  MainWindow* window = new MainWindow();
  window->show();
  return app.exec();
}
</code>
<tt>main.cpp</tt> hasn't changed from tutorial 3 except to change any reference to tutorial 3 to tutorial 4.
 
===mainwindow.h===
<code cppqt n>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H
 
#include <KXmlGuiWindow>
#include <KTextEdit>
 
class MainWindow : public KXmlGuiWindow
{
  Q_OBJECT //new from tutorial3
 
  public:
    MainWindow(QWidget *parent=0);
 
  private:
    KTextEdit* textArea;
    void setupActions();
    QString fileName; //new
 
  private slots: //new
    void newFile(); //new
    void openFile(); //new
    void saveFile(); //new
    void saveFileAs(); //new
    void saveFileAs(const QString &outputFileName); //new
};
 
#endif
</code>
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.trolltech.com/latest/signalsandslots.html signal/slot] mechanism we must specify that these functions are slots as we do on line 19. Since we are using slots in this header file, we must also add the [http://doc.trolltech.com/latest/qobject.html#Q_OBJECT <tt>Q_OBJECT</tt>] macro.
 
We also want to keep track of the filename of the currently opened file so we declare a <tt>{{qt|QString}} fileName</tt>.
 
===mainwindow.cpp===
<code cppqt n>
#include "mainwindow.h"
 
#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>
#include <KFileDialog> //new
#include <KMessageBox> //new
#include <KIO/NetAccess> //new
#include <KSaveFile> //new
#include <QTextStream> //new
MainWindow::MainWindow(QWidget *parent)
    : KXmlGuiWindow(parent),
      fileName(QString()) //new
{
  textArea = new KTextEdit;
  setCentralWidget(textArea);
  setupActions();
}
void MainWindow::setupActions()
{
  KAction* clearAction = new KAction(this);
  clearAction->setText(i18n("Clear"));
  clearAction->setIcon(KIcon("document-new"));
  clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
  actionCollection()->addAction("clear", clearAction);
  connect(clearAction, SIGNAL(triggered(bool)),
          textArea, SLOT(clear()));
  KStandardAction::quit(kapp, SLOT(quit()),
                        actionCollection());
  KStandardAction::open(this, SLOT(openFile()),
                        actionCollection()); //new
  KStandardAction::save(this, SLOT(saveFile()),
                        actionCollection()); //new
  KStandardAction::saveAs(this, SLOT(saveFileAs()),
                        actionCollection()); //new
  KStandardAction::openNew(this, SLOT(newFile()),
                        actionCollection()); //new
  setupGUI();
}
 
//New from here on
 
void MainWindow::newFile()
{
  fileName.clear();
  textArea->clear();
}
 
void MainWindow::saveFileAs(const QString &outputFileName)
{
  KSaveFile file(outputFileName);
  file.open();
 
  QByteArray outputByteArray;
  outputByteArray.append(textArea->toPlainText().toUtf8());
  file.write(outputByteArray);
  file.finalize();
  file.close();
 
  fileName = outputFileName;
}
 
void MainWindow::saveFileAs()
{
  saveFileAs(KFileDialog::getSaveFileName());
}
 
void MainWindow::saveFile()
{
  if(!fileName.isEmpty())
  {
    saveFileAs(fileName);
  }
  else
  {
    saveFileAs();
  }
}
 
void MainWindow::openFile()
{
  QString fileNameFromDialog = KFileDialog::getOpenFileName();
 
  QString tmpFile;
  if(KIO::NetAccess::download(fileNameFromDialog, tmpFile,
        this))
  {
    QFile file(tmpFile);
    file.open(QIODevice::ReadOnly);
    textArea->setPlainText(QTextStream(&file).readAll());
    fileName = fileNameFromDialog;
 
    KIO::NetAccess::removeTempFile(tmpFile);
  }
  else
  {
    KMessageBox::error(this,
        KIO::NetAccess::lastErrorString());
  }
}
</code>
 
===tutorial4ui.rc===
<code xml n>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial4" version="1">
  <ToolBar name="mainToolBar" >
    <text>Main Toolbar</text>
    <Action name="clear" />
  </ToolBar>
  <MenuBar>
    <Menu name="file" >
      <Action name="clear" />
    </Menu>
  </MenuBar>
</gui>
</code>
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==
 
Okay, now to implement the code that will do the loading and saving. This will all be happening in <tt>mainwindow.cpp</tt>
 
The first thing we do is add
<code cppqt>
fileName(QString())
</code>
to the <tt>MainWindow</tt> constructor list on line 16. This makes sure that <tt>fileName</tt> 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 <tt>quit</tt> action in tutorial 3, we will use <tt>KStandardActions</tt>. On lines 37 to 47 we add the actions in the same way as for the <tt>quit</tt> action. 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 <tt>newFile()</tt> function.
<code cppqt>
void MainWindow::newFile()
{
  fileName.clear();
  textArea->clear();
}
</code>
<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 disc. <tt>textArea->clear()</tt> then clears the central text area using the same function that we connected the <tt>clear</tt> <tt>KAction</tt> to in tutorial 3.
 
===Saving a file===
 
====saveFileAs(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. KDE provides a class for safely saving a file called {{class|KSaveFile}} which is derived from Qt's {{qt|QFile}}.
 
The function's prototype is
<code cppqt>
void MainWindow::saveFileAs(const QString &outputFileName)
</code>
 
We then create our <tt>KSaveFile</tt> object and open it with
<code cppqt>
KSaveFile file(outputFileName);
file.open();
</code>
 
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 {{qt|QByteArray}} and fill it with the plain text version of whatever is in the text area:
<code cppqt>
QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText().toUtf8());
</code>
Now that we have our <tt>QByteArray</tt>, we use it to write to the file with <tt>KSaveFile::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>KSaveFile</tt> works by first writing to a temporary file and then, when you call <tt>KSaveFile::finalize()</tt> the changes are made to the actual file.
<code cppqt>
file.write(outputByteArray);
file.finalize();
file.close();
</code>
Finally, we set <tt>MainWindows</tt>'s <tt>fileName</tt> member to point to the file name we just saved to.
<code cppqt>
fileName = outputFileName;
</code>
 
====saveFileAs()====
 
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>{{class|KFileDialog}}::[http://api.kde.org/4.0-api/kdelibs-apidocs/kio/html/classKFileDialog.html#8891356c249c5911e1ab15cc2739a89b getSaveFileName()]</tt>.
 
<code cppqt>
void MainWindow::saveFileAs()
{
  saveFileAs(KFileDialog::getSaveFileName());
}
</code>
 
This is our first actual use of the KIO library. {{class|KFileDialog}} provides a number of static functions for displaying the common file dialog that is used by all KDE applications. Calling <tt>KFileDialog::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()====
 
<code cppqt>
void MainWindow::saveFile()
{
  if(!fileName.isEmpty())
  {
    saveFileAs(fileName);
  }
  else
  {
    saveFileAs();
  }
}
</code>
 
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===
 
Finally, we get round to being able to load a file from disc. The code for this is all contained in <tt>MainWindow::openFile()</tt>.
 
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>KFileDialog</tt> functions, this time <tt>getOpenFileName()</tt>:
<code cppqt>
QString fileNameFromDialog = KFileDialog::getOpenFileName();
</code>
 
Then we use the KIO library to retrieve our file. This allows us to open the file with QFile even if it's stored in a remote location like an FTP site. We make the following call to {{class|NetAccess}}'s <tt>download()</tt> function
<code cppqt>
KIO::NetAccess::download(fileNameFromDialog, tmpFile, this)
</code>
The first argument is the name of the file you wish to download. The second is a QString which, after the download is complete, will contain the location of the temporary copy of the file. It is this <tt>tmpFile</tt> we will work with from now on.
 
The function returns <tt>true</tt> or <tt>false</tt> depending on whether the transfer was successful. If it failed, we display a message box giving the error:
<code cppqt>
KMessageBox::error(this, KIO::NetAccess::lastErrorString());
</code>
 
Otherwise, we continue with opening the file.
 
We create a QFile by passing the temporary file created by <tt>NetAccess::download()</tt> to its constructor and then open it in read-only mode
<code cppqt>
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
</code>
 
In order to display the contents of the file, we must use a {{class|QTextStream}}. We create one by passing the contents of our file to its constructor and then call QFile's <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.
 
<code cppqt>
textArea->setPlainText(QTextStream(&file).readAll());
</code>
 
We then store the path of the file we just opened:
<code cppqt>
fileName = fileNameFromDialog;
</code>
and finally, we remove the temporary file that was created by <tt>NetAccess::download()</tt>:
<code cppqt>
KIO::NetAccess::removeTempFile(tmpFile);
</code>
 
==Make, Install And Run==
 
===CMakeLists.txt===
<code ini n>
project(tutorial4)
find_package(KDE4 REQUIRED)
include_directories(${KDE4_INCLUDES})
set(tutorial4_SRCS
  main.cpp
  mainwindow.cpp
)
kde4_add_executable(tutorial4 ${tutorial4_SRCS})
target_link_libraries(tutorial4 ${KDE4_KDEUI_LIBS}
                                ${KDE4_KIO_LIBS})
install(TARGETS tutorial4 DESTINATION ${BIN_INSTALL_DIR})
install(FILES tutorial4ui.rc
        DESTINATION ${DATA_INSTALL_DIR}/tutorial4)
</code>
Since we are now using the KIO library, we must tell CMake to link against it. We do this by passing <tt>${KDE4_KIO_LIBS}</tt> to the <tt>target_link_libraries()</tt> function.
 
With this file, the tutorial can be built and run in the same way as tutorial 3. For more information, see tutorial 3.
 
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial4
 
==Moving On==
Now you can move on to the [[Development/Tutorials/KCmdLineArgs|KCmdLineArgs]] tutorial.
 
[[Category:C++]]

Latest revision as of 14:34, 8 September 2020

This page was moved here.

Retrieved from "https://techbase.kde.org/index.php?title=Development/Tutorials/Saving_and_loading&oldid=106714"