<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 för närvarande inte stöds. Om du inte redan känner till begrepp relaterade till datakällor, läs då gärna <link linkend="data-sources-concepts"
>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 en egen 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 class="extension"
>.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 <quote
>C</quote
>-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 <quote
>C</quote
>-funktioner</title>
<para
>De exporterade <quote
>C</quote
>-funktionerna listas nedan. I följande exempel ska varje förekomst av <replaceable
>biblioteksnamn</replaceable
> bytas ut mot insticksprogrammets verkliga biblioteksnamn. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>KstDataSource *</returnvalue
>create_<replaceable
>biblioteksnamn</replaceable
>(KConfig* <parameter
>cfg</parameter
>, 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 <replaceable
>biblioteksnamn</replaceable
>, där <replaceable
>biblioteksnamn</replaceable
> är insticksprogrammets biblioteksnamn. En pekare av typen <classname
>KstDataSource</classname
> till den nya läsaren ska returneras. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>[valfri] <function
><returnvalue
>KstDataSource *</returnvalue
>load_<replaceable
>biblioteksnamn</replaceable
>( KConfig* <parameter
>cfg</parameter
>, const QString& <parameter
>filename</parameter
>, const QString& <parameter
>type</parameter
>, const QDomElement& <parameter
>e</parameter
> )</function
></term>
<listitem>
<para
>Den här funktionen ska skapa en ny läsare av datakällor med typen <replaceable
>biblioteksnamn</replaceable
>, där <replaceable
>biblioteksnamn</replaceable
> är insticksprogrammets biblioteksnamn. En pekare av typen <classname
>KstDataSource</classname
> till den nya läsaren ska returneras. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
><returnvalue
>int</returnvalue
> understands_<replaceable
>biblioteksnamn</replaceable
>(const QString& <parameter
>filename</parameter
>)</function
></term>
<listitem>
<para
>Den här funktionen ska returnera ett heltal från 0 till 100. Värdet 0 anger att datakällan fullständigt saknar möjlighet att läsa filen som anges av <varname
>filename</varname
>, medan värdet 100 anger att datakällan är helt övertygad om att den har bäst möjlighet att förstå filen som anges av <varname
>filename</varname
>. Funktionen ska kontrollera att innehållet i filen är giltigt, och inte helt enkelt lita på filnamnsändelser. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>[valfri] <function
><returnvalue
>QStringList</returnvalue
> fieldList_<replaceable
>biblioteksnamn</replaceable
>( KConfig* <parameter
>cfg</parameter
>, const QString& <parameter
>filename</parameter
>, const QString& <parameter
>type</parameter
>, QString* <parameter
>typeSuggestion</parameter
>, bool* <parameter
>complete</parameter
> )</function
></term>
<listitem>
<para
>Funktionen ska returnera en lista med fält som hittas i filen, om den kan förstå filen som anges av <varname
>filename</varname
>, annars ska den returnera en tom <classname
>QStringList</classname
>. Värdet av <varname
>typeSuggestion</varname
> ska sättas till filtypen och värdet av <varname
>complete</varname
> ska sättas till falskt om inga fält hittas, annars ska det sättas till sant. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>[valfri] <function
><returnvalue
>QStringList</returnvalue
> matrixList_<replaceable
>biblioteksnamn</replaceable
>( KConfig* <parameter
>cfg</parameter
>, const QString& <parameter
>filename</parameter
>, const QString& <parameter
>type</parameter
>, QString* <parameter
>typeSuggestion</parameter
>, bool* <parameter
>complete</parameter
> )</function
></term>
<listitem>
<para
>Funktionen ska returnera en lista med matriser som hittas i filen, om den kan förstå filen som anges av <varname
>filename</varname
>, annars ska den returnera en tom <classname
>QStringList</classname
>. Värdet av <varname
>typeSuggestion</varname
> ska sättas till filtypen och värdet av <varname
>complete</varname
> ska sättas till falskt om inga matriser hittas, annars ska det sättas till sant. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>[valfri] <function
><returnvalue
>QWidget*</returnvalue
> widget_<replaceable
>biblioteksnamn</replaceable
>( )</function
></term>
<listitem>
<para
>Om datakällan vill tillhandahålla en egen inställningsdialogruta, ska den implementera funktionen och returnera den nyskapade klassen härledd från <classname
>QWidget</classname
> här. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
><returnvalue
>QStringList</returnvalue
> provides_<replaceable
>biblioteksnamn</replaceable
>( )</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>
<varlistentry>
<term
>[valfri] <function
><returnvalue
>bool</returnvalue
> supportsHierarchy_<replaceable
>biblioteksnamn</replaceable
>( )</function
></term>
<listitem>
<para
>Funktionen ska returnera sant om datakällan stöder hierarkiska fältnamn. Hierarkin anges av tecknet <quote
><literal
>/</literal
></quote
>. </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. Det är bara nödvändigt att överskrida funktionerna när den fördefinierade implementeringen inte är tillräcklig. 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
>_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 fältet <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
> readMatrix( KstMatrixData *<parameter
>data</parameter
>, const QString &<parameter
>matrix</parameter
>, int <parameter
>xStart</parameter
>, int <parameter
>yStart</parameter
>, int <parameter
>xNumSteps</parameter
>, int <parameter
>yNumSteps</parameter
> )</function
></term>
<listitem>
<para
>Funktionen ska läsa angiven del av matrisen, genom att läsa <varname
>xNumSteps</varname
> med början på <varname
>xStart</varname
> och <varname
>yNumSteps</varname
> med början på <varname
>yStart</varname
> från matrisen som anges av matrisnamnet <varname
>matrix</varname
>, och returnera innehållet i <classname
>KstMatrixData</classname
> <varname
>data</varname
>. Om <varname
>xNumSteps</varname
> är mindre än 0, ska funktionen istället läsa 1 sampling med början på <varname
>xStart</varname
>. Om <varname
>yNumSteps</varname
> är minder än 0, ska funktionen istället läsa 1 sampling med början på <varname
>yStart</varname
>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>bool</returnvalue
> isValidMatrix(const QString &<parameter
>matrix</parameter
>) const</function
></term>
<listitem>
<para
>Funktionen ska returnera true om matrisen som anges av matrisnamnet <varname
>matrix</varname
> är en giltig matris i den aktuella datakällan, eller false om matrisen inte är giltigt. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>bool</returnvalue
> matrixDimensions( const QString &<parameter
>matrix</parameter
>, int* <parameter
>xDim</parameter
>, int* <parameter
>yDim</parameter
> )</function
></term>
<listitem>
<para
>Funktionen ska returnera sant om matrisen som anges av matrisnamnet <varname
>matrix</varname
> är en giltig matris i den aktuellla datakällan, eller falskt om matrisen inte är en giltig matris. Om matrisen är en giltig matris ska värdet av <varname
>xDim</varname
> och <varname
>yDim</varname
> sättas till matrisens respektive X-dimension och Y-dimension. </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 <kstdatasource.h>
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 class="extension"
>.desktop</filename
></title>
<para
>Följande är ett exempel på en <filename class="extension"
>.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 British Columbia
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
></userinput>
<userinput
><command
>cd ./kst/datasources/template</command
></userinput>
<userinput
><command
>make</command
></userinput>
<userinput
><command
>make install</command
></userinput
>
</screen>
</para>
<para
>Starta om &kst; så ska den nya datakällans läsare automatiskt laddas. </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:
-->
