<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 &lt;kstdatasource.h&gt;
</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
>&lt;biblioteksnamn&gt;</varname
> bytas ut mot insticksprogrammets verkliga biblioteksnamn. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>KstDataSource *</returnvalue
>create_&lt;biblioteksnamn&gt;(const QString&amp; <parameter
>filename</parameter
>, const QString&amp; <parameter
>type</parameter
>)</function
></term>
<listitem>
<para
>Den här funktionen ska skapa en ny läsare av datakällor med typen <varname
>&lt;biblioteksnamn&gt;</varname
>, där <varname
>&lt;biblioteksnamn&gt;</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_&lt;biblioteksnamn&gt;(const QString&amp; <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_&lt;biblioteksnamn&gt;()</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;amp; <parameter
>filename</parameter
>, const QString&amp;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 &amp;<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 &amp;<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&amp; <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 &amp;<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 &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
>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>
