<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 <kstdatasource.h> </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 ><teeginimi></varname > kõikjal asendada plugina teegi tegeliku nimega. </para> <variablelist> <varlistentry> <term ><function ><returnvalue >KstDataSource *</returnvalue >create_<teeginimi>(const QString& <parameter >failinimi</parameter >, const QString& <parameter >tüüp</parameter >)</function ></term> <listitem> <para >See funktsioon loob uue andmeallika lugeja tüübiga <varname ><teeginimi></varname >, kus <varname ><teeginimi></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_<teeginimi>(const QString& <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_<teeginimi>()</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; <parameter >failinimi</parameter >, const QString&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 &<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 &<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& <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 &<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 &lt;kstdatasource.h&gt; class TemplateSource : public KstDataSource { public: TemplateSource(const QString& filename, const QString& type); virtual ~TemplateSource(); virtual KstObject::UpdateType update(int = -1); virtual int readField(double *v, const QString &field, int s, int n); virtual bool isValidField(const QString &field) const; virtual int samplesPerFrame(const QString &field); virtual int frameCount() const; virtual QString fileType() const; virtual void save(QTextStream &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& filename, const QString& 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& field, int s, int n) { Q_UNUSED(v) Q_UNUSED(field) Q_UNUSED(s) Q_UNUSED(n) return -1; } bool TemplateSource::isValidField(const QString& field) const { Q_UNUSED(field) return false; } int TemplateSource::samplesPerFrame(const QString &field) { Q_UNUSED(field) return 0; } int TemplateSource::frameCount() const { return 0; } QString TemplateSource::fileType() const { return QString::null; } void TemplateSource::save(QTextStream &ts) { KstDataSource::save(ts); } extern "C" { KstDataSource *create_template(const QString& filename, const QString& type) { return new TemplateSource(filename, type); } QStringList provides_template() { QStringList rc; // create the stringlist return rc; } bool understands_template(const QString& 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>