View source for Development/Tutorials/Saving and loading (fa)

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Saving_and_loading}}

{{TutorialBrowser (fa)|

series=آموزش مقدماتی|

name=ذخیره و بازیابی|

pre=[[Development/Tutorials/Using_KActions_(fa)|آموزش ۳ - KActionها]]|

next=[[Development/Tutorials/KCmdLineArgs_(fa)|آموزش ۵ - استفاده از KCmdLineArgs]]| 

reading=KIO::[http://api.kde.org/classmapper.php?class=NetAccess&module=kdelibs&version=4.0 NetAccess] {{qt|QFile}}
}}

<div dir="rtl">
==چکیده==
حالا یک ویرایشگر متن ساده داریم، ولی هنوز کار به‌دردبخوری انجام نمی‌دهد. یک ویرایشگر متن باید حداقل بتواند فایل‌ها را از دیسک بخواند، فایل‌هایی که شما ساخته یا ویراسته‌اید را ذخیره کند و همین‌طور فایل جدید بسازد.

‏KDE برای کار با فایل‌ها کلاس‌هایی دارد که کار را برای برنامه‌نویسان بسیار آسان می‌سازد. کتاب‌خانه‌ی KIO به شما امکان می‌دهد به سادگی به فایل‌ها دسترسی پیدا کنید. هم‌چنین با کمک KIO می‌توانید از کادرهای استاندارد بازکردن و ذخیره‌سازی فایل‌ها در برنامه‌تان استفاده کنید.

[[image:introtokdetutorial4.png|frame|center]]

==کدهای منبع==
===main.cpp===
<div dir="ltr">
<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>
</div>
‏<tt>main.cpp</tt> نسبت به آموزش قبل هیچ تغییری نکرده فقط tutorial3ها به tutorial4 تغییر داده‌شده‌اند.

===mainwindow.h===
<div dir="ltr">
<code cppqt n>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
  Q_OBJECT

{
  public:
    MainWindow(QWidget *parent=0);

  private:
    KTextEdit* textArea;
    void setupActions();
	QString fileName; //new

  private slots:
	void newFile(); //new
	void openFile(); //new
	void saveFile(); //new
	void saveFileAs(); //new
	void saveFileAs(const QString &outputFileName); //new
};

#endif
</code>
</div>
از آنجایی که می‌خواهیم قابلیت‌های ذخیره و بازیابی فایل‌ها را به برنامه بیافزاییم، باید توابعی اضافه کنیم که این کارها را برایمان انجام دهند. چون این توابع از طریق مکانیزم [http://doc.trolltech.com/latest/signalsandslots.html signal/slot] مربوط به Qt فراخوانی می‌شوند، باید آن‌ها را به عنوان slot معرفی کنیم؛ که در سطر ۱۹ همین اتفاق می‌افتد. به علاوه، چون در این کلاس slot تعریف می‌کنیم، باید ماکروی [http://doc.trolltech.com/latest/qobject.html#Q_OBJECT <tt>Q_OBJECT</tt>] را به تعریف آن اضافه کنیم.

هم‌چنین در طول برنامه، باید نام فایلی که کاربر باز کرده‌است را بدانیم؛ بنابراین متغیر <tt>{qt|QString} fileName</tt> را اعلان می‌کنیم.

===mainwindow.cpp===
<div dir="ltr">
<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>
</div>

===tutorial4ui.rc===
<div dir="ltr">
<code xml n>
<?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>
</code>
</div>
این فایل هم دقیقا مشابه <tt>tutorial3ui.rc</tt> از آموزش ۳ است. تنها نام آن را به tutorial4 تغییر داده‌ایم. نیازی به هیچ‌گونه اطلاعات اضافی از <tt>KStandardAction</tt>ها در این فایل نیست. جای هر یک از گزینه‌ها در منوها را به طور خودکار KDE تنظیم می‌کند.

==شرح==
خوب. پس می‌خواهیم برنامه‌ای بنویسم که ذخیره و بازیابی انجام دهد. این کار در <tt>mainwindow.cpp</tt> اتفاق می‌افتد.

نخستین کاری که انجام می‌دهیم، اضافه‌کردن
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
fileName(QString())
</code>
</div>
به تعریف تابع سازنده‌ی <tt>MainWindow</tt> در سطر ۱۶ است. با این کار، اطمینان حاصل می‌کنیم که <tt>fileName</tt> از همان ابتدا تهی است.

===افزودن actionها===
در اینجا، ارائه‌ی یک رابط بیرونی به کاربران برنامه، اولین کاری خواهد بود که می‌خواهیم انجام دهیم. رابط کاربر برنامه به کاربران اجازه می‌دهد به برنامه بگویند فایل را باز کن، ذخیره کن یا فایل جدیدی بساز. به مانند گزینه‌ی <tt>quit</tt> در آموزش ۳، از <tt>KStandardAction</tt>ها استفاده می‌کنیم. در طول سطرهای ۳۷ تا ۴۷ actionهای جدید را به منو اضافه می‌کنیم و هر کدام را به slot مناسبی که در فایل سرایند تعریف کرده‌ایم، پیوند می‌دهیم.

===ساختن یک فایل جدید===

اولین تابعی که می‌نویسیم، تابع <tt>newFile()</tt> است.
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
void MainWindow::newFile()
{
  fileName.clear();
  textArea->clear();
}
</code>
</div>
‏<tt>fileName.clear()</tt> مقدار متغیر <tt>fileName</tt> را تهی قرار می‌دهد. این کار، نمودی از این حقیقت است که فایل هنوز بر روی دیسک وجود ندارد. آن‌گاه <tt>textArea->clear()</tt> کادر متنی وسط پنجره را خالی می‌کند. این همان تابعی است که به clearAction در آموزش ۳ پیوند زدیم.

===ذخیره‌کردن یک فایل===

====saveFileAs(QString)====

حالا می‌خواهیم اولین کدی که با فایل‌ها سر و کار دارد، بنویسیم. می‌خواهیم تابعی پیاده‌سازی کنیم که نوشته‌های درون کادر متن را در یک فایل، با نامی که به عنوان پارامتر رد می‌کنیم، ذخیره کند. KDE کلاسی در اختیار ما می‌گذارد که به کمک آن بتوانیم با اطمینان فایلی را ذخیره کنیم. این کلاس {{class|KSaveFile}} نام دارد و از کلاس {{qt|QFile}} متعلق به Qt مشتق شده است.

اعلان تابع به این صورت است:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
void MainWindow::saveFileAs(const QString &outputFileName)
</code>
</div>

سپس شیء <tt>KSaveFile</tt> خود را می‌سازیم و باز می‌کنیم:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
KSaveFile file(outputFileName);
file.open();
</code>
</div>

حالا که فایلمان باز شده و آماده‌ی نوشتن است، باید نوشته‌های درون کادر متنی را به قالبی درآوریم که بتوان آن را در فایل نوشت. برای این کار، یک {{qt|QByteArray}} می‌سازیم و آن را با متن ساده‌ی درون کادر متن پر می‌کنیم:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
QByteArray outputByteArray;
outputByteArray.append(textArea->toPlainText().toUtf8());
</code>
</div>
حالا با استفاده از تابع <tt>KSaveFile::write()</tt>، آرایه‌ی ساخته شده را در فایل می‌نویسیم. اگر از یک <tt>QFile</tt> استفاده می‌کردیم، تغییرات بلافاصله در فایل ذخیره می‌شدند. با این کار، اگر در میانه‌ی نوشتن مشکلی پیش بیاید، فایل خراب می‌شود. به همین دلیل، <tt>KSaveFile</tt> ابتدا در یک فایل موقتی می‌نویسد و سپس هنگامی که <tt>KSaveFile::finalize()</tt> را صدا می‌زنید، تغییرات در فایل واقعی اعمال می‌شوند.
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
file.write(outputByteArray);
file.finalize();
file.close();
</code>
</div>
در پایان، مقدار عضو داده‌ی <tt>fileName</tt> در کلاس <tt>MainWindow</tt> را به نام فایلی که نوشته‌ها را در آن ذخیره کردیم، تغییر می‌دهیم.
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
fileName = outputFileName;
</code>
</div>

====saveFileAs()====

این تابعی است که اسلات <tt>saveAs</tt> به آن پیوند خورده‌است. این تابع تنها تابع عمومی <tt>saveFileAs(QString)</tt> را با مقدار برگشتی تابع <tt>{{class|KFileDialog}}::[http://api.kde.org/4.0-api/kdelibs-apidocs/kio/html/classKFileDialog.html#8891356c249c5911e1ab15cc2739a89b getSaveFileName()]</tt> به عنوان آرگومان فرا می‌خواند.

<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
void MainWindow::saveFileAs()
{
  saveFileAs(KFileDialog::getSaveFileName());
}
</code>
</div>

این اولین استفاده‌ی واقعی ما از کتاب‌خانه‌ی KIO است. {{class|KFileDialog}} تعدادی تابع استاتیک در اختیار ما می‌گذارد تا بتوانیم کادرهای محاوره‌ای عمومی فایل (یعنی همان کادرهای Open/Save File) را نمایش دهیم. با فراخوانی <tt>KFileDialog::getSaveFileName()</tt>، پنجره‌ای باز می‌شود که از آن‌جا کاربر می‌تواند برای فایل خود نامی برگزیند. تابع نام کامل فایل (همراه با مسیر ذخیره‌سازی) برمی‌گرداند. این مقدار بازگشتی، سپس، به تابع <tt>saveFileAs(QString)</tt> رد می‌شود.

====saveFile()====

<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
void MainWindow::saveFile()
{
  if(!fileName.isEmpty())
  {
    saveFileAs(fileName);
  }
  else
  {
    saveFileAs();
  }
}
</code>
</div>

در این تابع چیز چندان جالب توجهی وجود ندارد؛ فقط منقطی که بر اساس آن تصمیم بگیریم پنجره‌ی ذخیره‌ی فایل را نمایش بدهیم یا نه. اگر <tt>fileName</tt> خالی نباشد، در این صورت فایل با همان نام <tt>fileName</tt> ذخیره خواهد شد. در غیر این صورت پنجره‌ی ذخیره‌ی فایل برای کاربر به نمایش در می‌آید تا بتواند نامی انتخاب کند.

===بازکردن یک فایل===

در پایان، باید به برنامه قابلیت بازیابی فایل‌ها بدهیم. همه‌ی کد این کار در تابع <tt>MainWindow::openFile()</tt> قرار گرفته است.

اول باید از کاربر بپرسیم نام فایلی که می‌خواهد باز کند چیست. این کار را با استفاده از تابع دیگری از <tt>KFileDialog</tt> انجام می‌دهیم؛ این بار <tt>getOpenFileName()</tt>:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
QString fileNameFromDialog = KFileDialog::getOpenFileName();
</code>
</div>

حالا از کتاب‌خانه‌ی KIO استفاده می‌کنیم تا فایل را دریافت کنیم. KIO به ما امکان می‌دهد فایل را به صورت یک QFile دریافت کنیم؛ حتی اگر فایل در یک ارتباط راه دور مانند یک FTP قرار داشته باشد. تابع <tt>download</tt> از {{class|NetAccess}} را به صورت زیر فرا می‌خوانیم:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
KIO::NetAccess::download(fileNameFromDialog, tmpFile, this)
</code>
</div>
اولین آرگومان، نام فایلی است که می‌خواهیم دریافت کنیم. دومی یک متغیر QString است که پس پایان دریافت، مکان کپی موقت فایل را در خود خواهد داشت. از این به بعد با همین <tt>tmpFile</tt> سر و کار خواهیم داشت.

خروجی تابع، بسته به موفقیت آمیز بودن یا نبودن عملیات، <tt>true</tt> یا <tt>false</tt> خواهد بود. اگر عملیات با شکست مواجه شد، پیامی حاوی خطای رخ داده نمایش می‌دهیم:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
KMessageBox::error(this, KIO::NetAccess::lastErrorString());
</code>
</div>

در غیر این صورت، به باز کردن فایل ادامه می‌دهیم.

یک QFile می‌سازیم و فایل موقتی که <tt>NetAccess::download()</tt> ساخته را به تابع سازنده‌اش رد می‌کنیم. هم‌چنین مشخص می‌کنیم که فایل به صورت «فقط خواندنی» باز شود.
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
QFile file(tmpFile);
file.open(QIODevice::ReadOnly);
</code>
</div>

برای نمایش محتویات فایل، باید از یک {{class|QTextStream}} استفاده کنیم. با رد کردن اشاره‌گر file به تابع سازنده‌ی <tt>QTextStream</tt> یک نمونه می‌سازیم و سپس تابع <tt>readAll()</tt> آن را فراخوانی می‌کنیم تا نوشته‌ها را از فایل بخوانیم. سپس آن را به تابع <tt>setPlainText()</tt> مربوط به کادر متنی رد می‌کنیم.

<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
textArea->setPlainText(QTextStream(&file).readAll());
</code>
</div>

سپس مسیر فایل بازشده را در <tt>fileName</tt> نگه‌داری می‌کنیم:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
fileName = fileNameFromDialog;
</code>
</div>

و نهایتا فایل موقتی که <tt>NetAccess::download()</tt> ساخته است را پاک می‌کنیم:
<div dir="ltr">
<syntaxhighlight lang="cpp-qt">
KIO::NetAccess::removeTempFile(tmpFile);
</code>
</div>

==ساخت، نصب و اجرا==

===CMakeLists.txt===
<div dir="ltr">
<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>
</div>

چون حالا از کتاب‌خانه‌ی KIO استفاده می‌کنیم، باید به CMake بگوییم آن را هم با برنامه‌مان لینک کند. این کار را با رد کردن <tt>${KDE4_KIO_LIBS}</tt> به تابع <tt>target_link_libraries()</tt> انجام می‌دهیم.

با این فایل، می‌توانید برنامه را درست مانند آموزش ۳ بسازید. برای اطلاعات بیشتر، به آموزش ۳ مراجعه کنید.

<div dir="ltr">
<code>
 mkdir build && cd build
 cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
 make install
 $HOME/bin/tutorial4
</code>
</div>

==به پیش==
حالا می‌توانید به سوی آموزش [[Development/Tutorials/KCmdLineArgs|KCmdLineArgs]] پیش بروید.
</div>
[[Category:C++]]