<appendix id="supportingadditionalfileformats">
<title
>Täiendavate failivormingute toetus</title>
<para
>Käesolev osa kirjeldab lisalugejate loomist toetuseta failivormingute tarbeks. Kui sa ei ole veel tutta andmeallikate kontseptsiooniga, loe palun osa <link linkend="supportingadditionalfileformatsdatasourceconcepts"
>Andmeallikate kontseptsioonid</link
>. </para>



<sect1 id="supportingadditionalfileformatscreatingdatasource">
<title
>Andmeallika lugeja loomine</title>

<para
>Kui soovid kasutada failivormingut, mida me praegu ei toeta, tuleks ise kirjutada ka vastav andmeallika lugeja. </para>
<para
>Kõik &kst; andmeallikate lugejad on tavalised &kde; pluginad. Nagu &kde; pluginatel ikka, peab igal andmeallika lugejal olema ühisobjekti fail ning <filename
>*.desktop</filename
>-fail. Enne lugeja kirjutamist peab kindlaks määrama plugina teegi nime. See peab olema C-keele korrektse muutuja nimi, sest seda kasutatakse ühisobjekti funktsiooninimedes. Nii on näiteks ASCII failide lugeja teegi nimi <quote
>ascii</quote
>. </para>
<note>
<para
>&kde; pluginad <emphasis
>ei ole</emphasis
> mitte needsamad, mida kasutab &kst; andmetega manipuleerimisel. Kõik viited pluginatele tähendavad käesolevas osas &kde; pluginaid. </para>
</note>

<sect2 id="supportingadditionalfileformatscreatingdatasourceobjectfile">
<title
>Ühisobjekt</title>
<para
>Andmeallika lugeja peab olema abstratse klassi <classname
>KstDataSource</classname
> alamklass. Kontrolli, et kaasaksid oma andmelugeja lähtekoodi <classname
>KstDataSource</classname
>'i päisefaili: <screen>
#include &lt;kstdatasource.h&gt;
</screen
> Andmeallika lugega peab vastama teatud nõuetele. Üks neist on seotud eksporditud C funktsioonide olemasoluga. Teine nõue tuleneb asjaolust, et andmeallika lugejad peavad olema <classname
>KstDataSource</classname
>'i järglased. Mõlemaid nõudeid koos mõningate soovituste ja selgitustega tutvustatakse allpool. </para>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexportedfxns">
<title
>Eksporditud C funktsioonid</title>
<para
>Allpool on ära toodud eksporditud C funktsioonid. Järgnevates näidetes tuleb <varname
>&lt;teeginimi&gt;</varname
> kõikjal asendada plugina teegi tegeliku nimega. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>KstDataSource *</returnvalue
>create_&lt;teeginimi&gt;(const QString&amp; <parameter
>failinimi</parameter
>, const QString&amp; <parameter
>tüüp</parameter
>)</function
></term>
<listitem>
<para
>See funktsioon loob uue andmeallika lugeja tüübiga <varname
>&lt;teeginimi&gt;</varname
>, kus <varname
>&lt;teeginimi&gt;</varname
> on plugina teegi nimi. Uuele klassile osutav viit tüübiga <classname
>KstDataSource</classname
> peab olema tagastatav. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>bool</returnvalue
> understands_&lt;teeginimi&gt;(const QString&amp; <parameter
>failinimi</parameter
>)</function
></term>
<listitem>
<para
>Funktsioon peab tagastama 'true', kui parameetriga <varname
>failinimi</varname
> määratud fail on antud lugeja toetusega tüübiga, vastasel juhul tagastatakse 'false'. Funktsioon peab kehtivuse leidmiseks kontrollima faili sisu, mitte toetuma ainult failinime laiendile. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>QStringList</returnvalue
> provides_&lt;teeginimi&gt;()</function
></term>
<listitem>
<para
>Funktsioon tagastab lugeja toetatud failitüüpide <classname
>QStringList</classname
>'i. Tagastatud stringid on suvalised, kuid peaks kirjeldama tegelikke failitüüpe. </para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilemembervars">
<title
>Kaitstud liikme muutujad</title>
<para
><classname
>KstDataSource</classname
> sisaldab mitmeid kaitstud liikme muutujaid, mida omaloodud andmeallika lugeja saab tarvitada. Muutujaid kirjeldatakse allpool. </para>

<variablelist>
<varlistentry>
<term
><varname
>bool _valid</varname
></term>
<listitem>
<para
>See muutuja on <literal
>true</literal
>, kui omaloodud andmeallika lugeja on sobilik. Üldiselt peakski see nii olema, kui ei ole just mingit viga (kui näiteks lugeja ei suuda siiski andmefaili lugeda). Muutujat kasutab <classname
>KstDataSource</classname
>'i funktsioon <function
>isValid()</function
>, mida tavaliselt ei teostata uuesti alamklassides. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>QStringList _fieldList</varname
></term>
<listitem>
<para
>See muutuja sisaldab andmeallika väljanimede loendit. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>QString _filename</varname
></term>
<listitem>
<para
>See muutuja sisaldab andmefaili nime, millega andmeallika lugeja on seostatud. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>QString _source</varname
></term>
<listitem>
<para
>See muutuja sisaldab allika tüübi nime. </para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilevirtualfxns">
<title
>Virtuaalsed funktsioonid</title>
<para
>Klass <classname
>KstDataSource</classname
> sisaldab mitmeid virtuaalseid funktsioone, mis tuleb omaloodud andmeallika lugejas uuesti defineerida. Need funktsioonid on mallifailid <filename
>template.h</filename
> ja <filename
>template.cpp</filename
>, mis on ära toodud <link linkend="supportingadditionalfileformatscreatingdatasourceobjectfileexample"
>näidismallide</link
> osas. Siinkohal toome ära funktsioonide kirjeldused. </para>

<variablelist>
<varlistentry>
<term
><function
>TemplateSource(const QString&amp;amp; <parameter
>failinimi</parameter
>, const QString&amp;amp; <parameter
>tüüp</parameter
>) </function
></term>
<listitem>
<para
>Andmeallika lugeja konstruktor. <varname
>failinimi</varname
> on selle faili nimi, millest andmed loetakse, <varname
>tüüp</varname
> failis sisalduvate andmete tüüp. Konstruktor peab üldjuhul välja kutsuma <classname
>KstDataSource</classname
>'i konstruktori konstruktori initsialiseerija loendis ning tõenäoliselt esitama liikme muutujate initsialiseerimiseks väljakutse allpool toodud funktsioonile <function
>update</function
>. Eriti tuleb silmas pidada muutuja <varname
>bool_valid</varname
> korrektset määramist. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual ~TemplateSource()</function
></term>
<listitem>
<para
>Andmeallika lugeja destruktor. Kogu dünaamiliselt eraldatud mälu vabastatakse. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>KstObject::UpdateType</returnvalue
> update(<parameter
>int = -1</parameter
>) </function
></term>
<listitem>
<para
>See funktsioon loeb andmefailist kõik uued andmed, mis on sinna lisandunud pärast viimast funktsiooni <function
>update</function
> väljakutset ning uuendab vastavalt liikme muutujaid. Funktsioon tagastab <varname
>KstObject::UPDATE</varname
>, kui failis on muudatusi, või <varname
>KstObject::NO_CHANGE</varname
>, kui neid ei ole. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> readField(double *<parameter
>v</parameter
>, const QString &amp;<parameter
>väli</parameter
>, int <parameter
>s</parameter
>, int <parameter
>n</parameter
>)</function
></term>
<listitem>
<para
>See funktsioon peab lugema andmetest <varname
>n</varname
> kaadrit, alustades kaadrist <varname
>s</varname
> väljal, mille määrab ära välja nimi <varname
>väli</varname
>, ning tagastama sisu massiivina <varname
>v</varname
>. Kui <varname
>n</varname
> on väiksem kui 0, peab funktsioon lugema 1 valimi alates kaadrist <varname
>s</varname
>. Tagastatakse loetud kaadrite arv. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>bool</returnvalue
> isValidField(const QString &amp;<parameter
>väli</parameter
>) const</function
></term>
<listitem>
<para
>See funktsioon peab tagastama 'true', kui väli, mille määrab välja nimi <varname
>väli</varname
>, on antud andmeallikas sobilik väli, või 'false', kui see ei ole sobilik väli. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> samplesPerFrame(const QString&amp; <parameter
>väli</parameter
>)</function
></term>
<listitem>
<para
>See funktsioon peab tagastama valimite arvu kaadri kohta väljal, mille määrab välja nimi <varname
>väli</varname
>. Andmeallikate puhul, mis sellist kontseptsiooni ei kasuta, määratakse valimite arvuks kaadri kohta <literal
>1</literal
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> frameCount() const</function
></term>
<listitem>
<para
>See funktsioon peab tagastama andmeallika kaadrite koguarvu, nagu see oli siis, kui viimati kutsuti välja <function
>update</function
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>QString</returnvalue
> fileType() const <parameter
></parameter
></function
></term>
<listitem>
<para
>See funktsioon peab tagastama parajasti kasutatava andmefaili failitüübi, mis tavaliselt on sama, mis konstruktorile edastatud parameeter <varname
>tüüp</varname
>. Vastasel juhul sisaldab see veateadet (mis näiteks annab teada, et tegemist ei ole sobiliku failiga). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>void</returnvalue
> save(QTextStream &amp;<parameter
>ts</parameter
>)</function
></term>
<listitem>
<para
>See funktsioon peaks salvestama failikirjelduse info <varname
>ts</varname
>-i. Enamasti peaks piisama <classname
>KstDataSource</classname
>'i pakutavast teostusest. </para>
</listitem>
</varlistentry>


</variablelist>

</sect3>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexample">
<title
>Näidismallid</title>
<para
>Üldiselt saab uute ühisobjekti failide loomiseks kasutada kaht allpool todud mallifaili. Muuda neis lihtsalt oma andmeallika vajadusi arvestades funktsioonide sisu. </para>
<informalexample>
<screen
>/***************************************************************************
                  template.h  -  data source plugin template
                             -------------------
    begin                : Fri Oct 17 2003
    copyright            : (C) 2003 The University of Toronto
    email                :
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef TEMPLATE_H
#define TEMPLATE_H

#include &amp;lt;kstdatasource.h&amp;gt;


class TemplateSource : public KstDataSource {
public:
  TemplateSource(const QString&amp; filename, const QString&amp; type);

  virtual ~TemplateSource();

  virtual KstObject::UpdateType update(int = -1);

  virtual int readField(double *v, const QString &amp;field, int s, int n);

  virtual bool isValidField(const QString &amp;field) const;

  virtual int samplesPerFrame(const QString &amp;field);

  virtual int frameCount() const;

  virtual QString fileType() const;

  virtual void save(QTextStream &amp;ts);
};


#endif
</screen>
</informalexample>
 
<informalexample>
<screen
>/***************************************************************************
                    template.cpp  -  data source template
                             -------------------
    begin                : Fri Oct 17 2003
    copyright            : (C) 2003 The University of Toronto
    email                :
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#include "template.h"


TemplateSource::TemplateSource(const QString&amp; filename, const QString&amp; type)
: KstDataSource(filename, type) {
}


TemplateSource::~TemplateSource() {
}


KstObject::UpdateType TemplateSource::update(int u) {
  Q_UNUSED(u)
  return KstObject::NO_CHANGE;
}


int TemplateSource::readField(double *v, const QString&amp; field, int s, int n) {
  Q_UNUSED(v)
  Q_UNUSED(field)
  Q_UNUSED(s)
  Q_UNUSED(n)
  return -1;
}


bool TemplateSource::isValidField(const QString&amp; field) const {
  Q_UNUSED(field)
  return false;
}


int TemplateSource::samplesPerFrame(const QString &amp;field) {
  Q_UNUSED(field)
  return 0;
}


int TemplateSource::frameCount() const {
  return 0;
}


QString TemplateSource::fileType() const {
  return QString::null;
}


void TemplateSource::save(QTextStream &amp;ts) {
  KstDataSource::save(ts);
}


extern "C" {
KstDataSource *create_template(const QString&amp; filename, const QString&amp; type) {
  return new TemplateSource(filename, type);
}

QStringList provides_template() {
  QStringList rc;
  // create the stringlist
  return rc;
}

bool understands_template(const QString&amp; filename) {
  // determine if it is an X file
  Q_UNUSED(filename)
  return false;
}

}
</screen>
</informalexample>
</sect3>

</sect2>

<sect2 id="supportingadditionalfileformatscreatingdatasourcedesktopfile">
<title
><filename
>.desktop</filename
>-fail</title>
<para
>Siin toome mallplugina <filename
>.desktop</filename
>-faili näite: </para>
<informalexample>
<screen
>[Desktop Entry]
Encoding=UTF-8
Type=Service
ServiceTypes=Kst Data Source
X-KDE-ModuleType=Plugin
X-Kst-Plugin-Library=template
X-Kst-Plugin-Author=The University of Toronto
Name=File Reader Template
Comment=Long description of the file reader template.
</screen>
</informalexample>

<para
>Väljadele 'Name' ja 'Comment' võib lisada tõlkeid mis tahes keelde, lisades täiendavalt samanimelised väljad, millele on lisatud sümbolid <literal
>[xx]</literal
>, kus <literal
>xx</literal
> kujutab endast vajaliku keele kahetähelist koodi, Näiteks eestikeelse tõlke lisamiseks tuleb lisada sellised read: </para>
<informalexample>
<screen
>Name[et]=Faililugeja mall
Comment[et]=Failidest andmete lugemise vahendi mall.
</screen>
</informalexample>
<para
>Väli <literal
>X-Kst-Plugin-Library</literal
> peab täpselt vastama plugina teegi nimele. </para>
</sect2>

<sect2 id="supportingadditionalfileformatscreatingdatasourcecompiling">
<title
>Kompileerimine ja kopeerimine</title>
<para
>Uue omaloodud andmeallika lugeja kompileerimiseks ja paigaldamiseks loo uus alamkataloog lähtepaketi kataloogis <filename
>kst/datasources</filename
>. Aseta uude kataloogi objekti lähtekoodifailid ning <filename
>.desktop</filename
>-fail. Seejärel muuda faili <filename
>kst/datasources/Makefile.am</filename
>, nii et <varname
>SUBDIRS</varname
> sisaldaks uue alamkataloogi nime. Kui näiteks uus alamkataloog kannab nime <filename
>template</filename
>, siis tuleks <varname
>SUBDIRS</varname
> muuta järgmiselt: <informalexample
> <screen
>SUBDIRS=ascii dirfile frame indirect template $(PIOLIB_SUBDIR) $(FITSIO_SUBDIR)
</screen>
</informalexample>
</para>


<para
>Pärast kõigi vajalike failide asetamist uude alamkataloogi, tuleb ka seal luua fail <filename
>Makefile.am</filename
>. Kasuta alltoodut näidisena, asendades kõik sõnad <quote
>template</quote
> enda teegi nimega kirjetes <varname
>kde_module_LTLIBRARIES</varname
>, <varname
>kstdata_template_la_SOURCES</varname
> ja <varname
>services_DATA</varname
>. </para>
<informalexample>
<screen
>INCLUDES=-I$(srcdir)/../.. $(all_includes)

kde_module_LTLIBRARIES=kstdata_template.la

kstdata_template_la_LDFLAGS=$(all_libraries) -module -avoid-version
kstdata_template_la_SOURCES=template.cpp

METASOURCES=AUTO

services_DATA=kstdata_template.desktop
servicesdir=$(kde_servicesdir)/kst
</screen>
</informalexample>

<para
>Kui see tehtud, võid &kst; muudetud lähteteksti kompileerida ja uuesti paigaldada või siis ka paigaldada ainult uued teegid, nagu näidatud allpool (seal on kasutatud alamkataloogi <quote
>template</quote
>). Esmalt liigu &kst; lähteteksti baaskataloogi ja seejärel: <screen
><userinput
><command
>./configure --prefix=`kde-config --prefix`</command>
<command
>cd ./kst/datasources/template</command>
<command
>make</command>
<command
>make install</command
></userinput
></screen>
</para>

<para
>Käivita &kst; uuesti ja uus andmeallika lugeja peaks olema laetud. </para>
</sect2>

</sect1>


</appendix>


<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "appendix")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->