<appendix id="supportingadditionalfileformats">
<title
>Täiendavate failivormingute toetus</title>
<para
>Hetkel &kst;...toetab... See osa kirjeldab andmeallikate kontseptsioone ning seda, kuidas luua lisalugejaid toetamata failivormingutele. </para>

<sect1 id="supportingadditionalfileformatsdatasourceconcepts">
<title
>Andmeallikate kontseptsioonid</title>
<para
>Järgnevad kontseptsioonid on äärmiselt olulised mõistmaks, kuidas &kst; kasutab erinevaid andmeallikaid, ning aitavad täiendavate andmeallikate lugejate kirjutamisel. Toome siin ära ka mõnevõrra terminite seletusi. </para>

<sect2 id="supportingadditionalfileformatsdatasourceconceptssamples">
<title
>Valimid</title>
<para
>Andmefailide mõttes on valim fundamentaalne ühik. Valim vastab tavaliselt &kst; vektori ühele väärtusele. </para>
</sect2>

<sect2 id="supportingadditionalfileformatsdatasourceconceptsframes">
<title
>Raamid</title>
<para
>Raam tähistab teatud hulka valimeid. Igal andmefaili väljal võib olla erinev raamidesse kaasatud valimite hulk. Andmefaili suurust mõõdetakse selles sisalduvate raamide arvuga. Enamasti on valimeid raamis ainult üks, kuid mõnikord võib raamis olla ka märksa rohkem valimeid. </para>
</sect2>

<sect2 id="supportingadditionalfileformatsdatasourceconceptsfields">
<title
>Väljad</title>
<para
>Väli tähistab &kst;-s tavaliselt üht vektorit. Näiteks ASCII andmefaili veergu peetakse üheks väljaks. Igal väljal võib olla vaikimisi eeldatud või ka otseselt antud nimi. Andmeallika lugejad sisaldavad funktsioone väljade ja nende nimede lugemiseks ja hankimiseks. </para>
</sect2>

</sect1>

<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
> raami, alustades raamist <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 raamist <varname
>s</varname
>. Tagastatakse loetud raamide 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 raami kohta väljal, mille määrab välja nimi <varname
>väli</varname
>. Andmeallikate puhul, mis sellist kontseptsiooni ei kasuta, määratakse valimite arvuks raami 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 raamide 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>
