<appendix id="supportingadditionalfileformats"> <title >Stöd för ytterligare filformat</title> <para >Det här avsnittet beskriver hur man skapar ytterligare läsare för filformat som inte stöds. Om du inte redan känner till begrepp relaterade till datakällor, läs då gärna <link linkend="supportingadditionalfileformatsdatasourceconcepts" >Begrepp för datakällor</link >. </para> <sect1 id="supportingadditionalfileformatscreatingdatasource"> <title >Skapa läsare av datakällor</title> <para >Om du vill använda ett annat filformat än de som för närvarande stöds, kan du välja att skriva egna läsare av datakällor. </para> <para >Alla läsare av datakällor i &kst; är vanliga &kde;-insticksprogram. Som alla &kde;-insticksprogram, måste varje läsare av datakällor ha en delad objektfil och en <filename >*.desktop</filename >-fil. Innan läsaren kodas, måste insticksprogrammets biblioteksnamn bestämmas. Namnet måste vara ett giltigt variabelnamn i C, eftersom det kommer att användas som funktionsnamn för det delade objektet. Biblioteksnamnet för läsaren av ASCII-filer är till exempel <quote >ascii</quote >. </para> <note> <para >&kde;-insticksprogram är <emphasis >inte</emphasis > samma som &kst;-insticksprogrammen som används för databehandling. Alla referenser till insticksprogram i det här avsnittet gäller &kde;-insticksprogram. </para> </note> <sect2 id="supportingadditionalfileformatscreatingdatasourceobjectfile"> <title >Det delade objektet</title> <para >En läsare av datakällor ska vara en delklass till den abstrakta klassen <classname >KstDataSource</classname >. Försäkra dig om att du inkluderar deklarationsfilen för <classname >KstDataSource</classname > i källkoden i din läsare av datakällor: <screen> #include <kstdatasource.h> </screen > Det finns vissa krav som en läsare av datakällor måste uppfylla. Ett krav gäller närvaron av exporterade C-funktioner. Andra krav är konsekvenser av det faktum att läsare av datakällor ärver <classname >KstDataSource</classname >. Båda uppsättningarna med krav, samt förslag och allmänna förklaringar, tillhandahålls i följande avsnitt. </para> <sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexportedfxns"> <title >Exporterade c-funktioner</title> <para >De exporterade C-funktionerna listas nedan. I följande exempel ska varje förekomst av <varname ><biblioteksnamn></varname > bytas ut mot insticksprogrammets verkliga biblioteksnamn. </para> <variablelist> <varlistentry> <term ><function ><returnvalue >KstDataSource *</returnvalue >create_<biblioteksnamn>(const QString& <parameter >filename</parameter >, const QString& <parameter >type</parameter >)</function ></term> <listitem> <para >Den här funktionen ska skapa en ny läsare av datakällor med typen <varname ><biblioteksnamn></varname >, där <varname ><biblioteksnamn></varname > är Insticksprogrammets biblioteksnamn. En pekare av typen <classname >KstDataSource</classname > till den nya läsaren ska returneras. </para> </listitem> </varlistentry> <varlistentry> <term ><function ><returnvalue >bool</returnvalue > understands_<biblioteksnamn>(const QString& <parameter >filename</parameter >)</function ></term> <listitem> <para >Den här funktionen ska returnera true om filen som anges av <varname >filename</varname > är av en giltig typ som stöds av den här läsaren, och false annars. Funktionen ska kontrollera att innehållet i filen är giltigt, och inte lita på filnamnsändelser. </para> </listitem> </varlistentry> <varlistentry> <term ><function ><returnvalue >QStringList</returnvalue > provides_<biblioteksnamn>()</function ></term> <listitem> <para >Den här funktionen ska returnera en <classname >QStringList</classname > med filtyperna som stöds av läsaren. Strängarna som returneras är godtyckliga, men bör vara beskrivande och passande för de verkliga filtyperna. </para> </listitem> </varlistentry> </variablelist> </sect3> <sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilemembervars"> <title >Skyddade medlemsvariabler</title> <para ><classname >KstDataSource</classname > innehåller diverse skyddade medlemsvariabler som den egna läsaren av datakällor kan använda. Dessa variabler beskrivs nedan. </para> <variablelist> <varlistentry> <term ><varname >bool _valid</varname ></term> <listitem> <para >Den här variabeln ska vara <literal >true</literal > om den egna läsaren av datakällor är giltig. Läsaren är troligen giltig, om inte ett feltillstånd har uppstått (som att datafilen inte kan läsas av läsaren). Variabeln används av funktionen <function >isValid()</function > i <classname >KstDataSource</classname >, vilken oftast inte implementeras om i delklasser. </para> </listitem> </varlistentry> <varlistentry> <term ><varname >QStringList _fieldList</varname ></term> <listitem> <para >Den här variabeln ska innehålla en lista med fältnamnen i datakällan. </para> </listitem> </varlistentry> <varlistentry> <term ><varname >QString _filename</varname ></term> <listitem> <para >Den här variabeln ska innehålla namnet på datafilen som den här läsaren av datakälla hör ihop med. </para> </listitem> </varlistentry> <varlistentry> <term ><varname >QString _source</varname ></term> <listitem> <para >Den här variabeln ska innehålla källans typnamn. </para> </listitem> </varlistentry> </variablelist> </sect3> <sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilevirtualfxns"> <title >Virtuella funktioner</title> <para >Klassen <classname >KstDataSource</classname > innehåller många virtuella funktioner som ska definieras om i den egna läsaren av datakällor. Dessa funktioner finns i mallfilerna <filename >template.h</filename > och <filename >template.cpp</filename >, som listas i avsnittet <link linkend="supportingadditionalfileformatscreatingdatasourceobjectfileexample" >Exempelmallar</link >. Beskrivningar av funktionerna följer. </para> <variablelist> <varlistentry> <term ><function >TemplateSource(const QString&amp; <parameter >filename</parameter >, const QString&amp; <parameter >type</parameter >) </function ></term> <listitem> <para >Konstruktor för läsaren av datakällor. <varname >filename</varname > är namnet på filen från vilken data ska läsas, och <varname >type</varname > är typ av data som filen innehåller. Konstruktorn ska troligen anropa konstruktorn <classname >KstDataSource</classname > i listan med konstruktorinitiering, och troligen anropa funktionen <function >update</function > som listas nedan för att initiera medlemsvariabler. I synnerhet ska variabeln <varname >bool _valid</varname > ges lämpligt värde. </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual ~TemplateSource()</function ></term> <listitem> <para >Destruktorn för läsaren av datakällor. Allt dynamiskt allokerat minne ska frigöras. </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual <returnvalue >KstObject::UpdateType</returnvalue > update(<parameter >int = -1</parameter >) </function ></term> <listitem> <para >Den här funktionen ska läsa eventuell ny data tillagd i funktionen sedan senaste gången <function >update</function > anropades, och uppdatera medlemsvariablerna på lämpligt sätt. Funktionen ska returnera <varname >KstObject::UPDATE</varname > om filen innehåller ändringar, eller annars <varname >KstObject::NO_CHANGE</varname >. </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual <returnvalue >int</returnvalue > readField(double *<parameter >v</parameter >, const QString &<parameter >field</parameter >, int <parameter >s</parameter >, int <parameter >n</parameter >)</function ></term> <listitem> <para >Den här funktionen ska läsa <varname >n</varname > dataposter, med start från post <varname >s</varname > från fältet som anges av fältnamnet <varname >field</varname >, och returnera innehållet i <varname >v</varname >. Om <varname >n</varname > är mindre än 0, ska funktionen istället läsa 1 sampling med början på post <varname >s</varname >. Antal poster som lästes ska returneras. </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual <returnvalue >bool</returnvalue > isValidField(const QString &<parameter >field</parameter >) const</function ></term> <listitem> <para >Funktionen ska returnera true om fältet som anges av fältnamnet <varname >field</varname > är ett giltigt fält i den aktuella datakällan, eller false om fältet inte är giltigt. </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual <returnvalue >int</returnvalue > samplesPerFrame(const QString& <parameter >field</parameter >)</function ></term> <listitem> <para >Den här funktionen ska returnera förhållandet samplingar per post för fältet som anges av fältnamnet <varname >field</varname >. För datakällor som inte använder begreppet, kan antal samplingar per post anges som <literal >1</literal >. </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual <returnvalue >int</returnvalue > frameCount() const</function ></term> <listitem> <para >Den här funktionen ska returnera totalt antal poster i datakällan, som fanns den senaste gången <function >update</function > anropades. </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual <returnvalue >QString</returnvalue > fileType() const <parameter ></parameter ></function ></term> <listitem> <para >Den här funktionen ska returnera filtypen för datafilen som för närvarande används, oftast samma sak som parametern <varname >type</varname > som skickades till konstruktorn. Som ett alternativ kan den returnera ett felmeddelande (för att till exempel ange att filen inte är giltig). </para> </listitem> </varlistentry> <varlistentry> <term ><function >virtual <returnvalue >void</returnvalue > save(QTextStream &<parameter >ts</parameter >)</function ></term> <listitem> <para >Den här funktionen ska spara filbeskrivningsinformation till <varname >ts</varname >. I de flesta fall bör implementeringen som tillhandahålls av <classname >KstDataSource</classname > vara tillräcklig. </para> </listitem> </varlistentry> </variablelist> </sect3> <sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexample"> <title >Exempelmallar</title> <para >I allmänhet kan de följande två mallfilerna användas för att skapa nya delade objektfiler. Ändra helt enkelt innehållet i funktionerna till vad som lämpar sig för din speciella datakälla. </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 >Filen <filename >.desktop</filename ></title> <para >Följande är ett exempel på en <filename >.desktop</filename >-fil för mallinsticksprogrammet: </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 >Du kan lägga till översättningar på ytterligare språk för fälten Name och Comments, genom att lägga till ytterligare fält för Name och Comments med <literal >[xx]</literal > tillagt i slutet på fältnamnen, där <literal >xx</literal > är språkkoden med två bokstäver. För att till exempel lägga till en svensk översättning, skulle följande rader behöva läggas till: </para> <informalexample> <screen >Name[sv]=Insticksprogram för filläsning Comment[sv]=Insticksprogram som fungerar som ett tillägg för filläsning. </screen> </informalexample> <para >Fältet <literal >X-Kst-Plugin-Library</literal > måste vara exakt samma som biblioteksnamnet som bestämts för insticksprogrammet. </para> </sect2> <sect2 id="supportingadditionalfileformatscreatingdatasourcecompiling"> <title >Kompilering och kopiering</title> <para >För att kompilera och installera den nya egna läsaren av datakällor, skapa en ny katalog under <filename >kst/datasources</filename > i källkodspaketet. Placera källkodsfilerna för objektet, tillsammans med <filename >.desktop</filename >-filen i den nya katalogen. Redigera därefter <filename >kst/datasources/Makefile.am</filename > så att <varname >SUBDIRS</varname > innehåller den nya underkatalogens namn. Om den nya underkatalogen till exempel heter <filename >template</filename >, kan <varname >SUBDIRS</varname > ändras till följande: <informalexample > <screen >SUBDIRS=ascii dirfile frame indirect template $(PIOLIB_SUBDIR) $(FITSIO_SUBDIR) </screen> </informalexample> </para> <para >När filerna som krävs finns i den nyskapade underkatalogen, måste filen <filename >Makefile.am</filename > också skapas där. Använd följande exempel som en mall, och ersätt alla förekomster av <quote >template</quote > med ditt eget biblioteksnamn i <varname >kde_module_LTLIBRARIES</varname >, <varname >kstdata_template_la_SOURCES</varname > och <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 >Så fort detta är klart, kan du kompilera och installera om &kst; från det ändrade källkodspaketet, eller som ett alternativ, bara installera de nya biblioteken på följande sätt (med underkatalogen <quote >template</quote > använd som exempel). Gå först till rotkatalogen i &kst;-källkodspaketet. Skriv därefter <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 >Starta om &kst; så ska den nya datakällans läsare laddas. </para> </sect2> </sect1> </appendix>