<appendix id="supportingadditionalfileformats">
<title
>Ondersteuning van extra bestandstypen</title>
<para
>In deze sectie wordt beschreven hoe u extra leesprogramma's kunt maken voor bestandstypen die niet worden ondersteund. Als u het idee achter de gegevensbronnen nog niet kent, moet u <link linkend="supportingadditionalfileformatsdatasourceconcepts"
>Concepten gegevensbronnen</link
> eerst even lezen. </para>



<sect1 id="supportingadditionalfileformatscreatingdatasource">
<title
>Het maken van leesprogramma's voor gegevensbronnen</title>

<para
>Als u een bestandsformaat wilt gebruiken dat nog niet wordt ondersteund, kunt u er voor kiezen zelf een programma te maken dat dit bestandsformaat kan lezen. </para>
<para
>Alle leesprogramma's voor gegevensbronnen in &kst; zijn gewone plugins voor &kde;. Zoals alle plugins van &kde; moet elk leesprogramma voor gegevensbronnen een "shared object file" hebben en een <filename
>*.desktop</filename
>-bestand. Voordat u met het schrijven van het leesprogramma begint moet u de plugin een bibliotheeknaam geven. Deze naam moet een geldige naam zijn in (de programmeertaal) C, omdat die in de functienamen zal worden gebruikt van het "shared object" (gedeelde object). Bijvoorbeeld: de bibliotheeknaam van het leesprogramma voor ASCII-bestanden is <quote
>ascii</quote
>. </para>
<note>
<para
>De plugins van &kde; zijn <emphasis
>niet</emphasis
> het zelfde als die die in &kst; worden gebruikt voor het verwerken van gegevens. Alle verwijzingen naar plugins in deze sectie betreffen &kde;-plugins. </para>
</note>

<sect2 id="supportingadditionalfileformatscreatingdatasourceobjectfile">
<title
>Het "Shared Object" (gedeelde object)</title>
<para
>Een leesprogramma voor een gegevensbron moet een "subclass" zijn van de abstracte "class" <classname
>KstDataSource</classname
>. Zorg ervoor dat u in de broncode van uw leesprogramma het "header"- bestand opneemt voor <classname
>KstDataSource</classname
>:
<screen>
#include &lt;kstdatasource.h&gt;
</screen>
Er zijn bepaalde eisen waaraan een leesprogramma voor een gegevensbron moet voldoen. Een ervan betreft de aanwezigheid van geëxporteerde C-functies. Andere eisen volgen uit het feit dat leesprogramma's voor gegevensbronnen erven ("inherit") van <classname
>KstDataSource</classname
>. Beide soorten eisen, samen met suggesties en algemene uitleg, vindt u in de volgende secties terug. </para>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexportedfxns">
<title
>Geëxporteerde C- functies</title>
<para
>Hieronder volgt een lijst van geëxporteerde C- functies. In al deze voorbeelden moet <varname
>&lt;biebnaam&gt;</varname
> worden vervangen door de werkelijke bibliotheeknaam van de plugin. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>KstDataSource *</returnvalue
>create_&lt;biebnaam&gt;(const QString&amp; <parameter
>bestandsnaam</parameter
>, const QString&amp; <parameter
>type</parameter
>)</function
></term>
<listitem>
<para
>Deze functie moet een nieuw leesprogramma voor gegevensbronnen maken van het type <varname
>&lt;biebnaam&gt;</varname
>, waarin <varname
>&lt;biebnaam&gt;</varname
> de bibliotheeknaam is van de plugin. De functie moet een "pointer" van het type <classname
>KstDataSource</classname
> naar het nieuwe leesprogramma retourneren. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>bool</returnvalue
> understands_&lt;biebnaam&gt;(const QString&amp; <parameter
>bestandsnaam</parameter
>)</function
></term>
<listitem>
<para
>Deze functie moet de waarde "true" (waar) retourneren als het type van het bestand <varname
>bestandsnaam</varname
> door dit leesprogramma wordt ondersteund, en anders "false" (onwaar). De functie moet de inhoud van het bestand controleren, en niet afgaan op extensies in de bestandsnaam. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>QStringList</returnvalue
> provides_&lt;biebnaam&gt;()</function
></term>
<listitem>
<para
>Deze functie moet een <classname
>QStringList</classname
> van bestandstypen retourneren die door dit leesprogramma worden ondersteund. De geretourneerde "strings" (karakterrijen) kunnen van alles zijn, maar moeten de werkelijke bestandstypen beschrijven en er bij passen. </para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilemembervars">
<title
>"Protected Member Variables" (beschermde lidvariabelen)</title>
<para
><classname
>KstDataSource</classname
> kent diverse beschermde lidvariabelen voor gebruik in het leesprogramma voor gegevensbronnen. Hieronder volgt een beschrijving. </para>

<variablelist>
<varlistentry>
<term
><varname
>bool _valid</varname
></term>
<listitem>
<para
>Deze variabele moet de waarde <literal
>true</literal
> (waar) hebben als het zelf gemaakte leesprogramma voor gegevensbronnen in orde is. Hoogstwaarschijnlijk is dat wel het geval, behalve als er een fout optreedt (zoals het onleesbaar zijn van het gegevensbestand door het leesprogramma). Deze variabele wordt gebruikt in de functie <function
>isValid()</function
> van <classname
>KstDataSource</classname
>, die in de "subclasses" gewoonlijk niet opnieuw wordt geïmplementeerd. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>QStringList _fieldList</varname
></term>
<listitem>
<para
>Deze variabele moet een lijst bevatten van de veldnamen in de gegevensbron. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>QString _filename</varname
></term>
<listitem>
<para
>Deze variabele moet de naam bevatten van het gegevensbestand die behoort bij deze gegevensbron. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><varname
>QString _source</varname
></term>
<listitem>
<para
>Deze variabele moet de typenaam bevatten van de bron </para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilevirtualfxns">
<title
>Virtuele functies</title>
<para
>De "class" <classname
>KstDataSource</classname
> bevat vele virtuele functies die in het eigen leesprogramma voor gegevensbronnen opnieuw moeten worden gedefinieerd. Deze functies vindt u in de "template"bestanden (sjabloonbestanden) <filename
>template.h</filename
> en <filename
>template.cpp</filename
>, opgenomen in de sectie <link linkend="supportingadditionalfileformatscreatingdatasourceobjectfileexample"
>Voorbeeldsjablonen</link
>. Een beschrijving van deze functies volgt. </para>

<variablelist>
<varlistentry>
<term
><function
>TemplateSource(const QString&amp;amp; <parameter
>bestandsnaam</parameter
>, const QString&amp;amp; <parameter
>type</parameter
>) </function
></term>
<listitem>
<para
>De "constructor" voor het leesprogramma voor gegevensbronnen. <varname
>bestandsnaam</varname
> is de naam van het bestand waaruit gegevens moeten worden gelezen en <varname
>type</varname
> is het type van de gegevens in het bestand. Deze constructor zal hoogstwaarschijnlijk de constructor van de <classname
>KstDataSource</classname
> aanroepen in de lijst van te initialiseren constructors, en waarschijnlijk de functie <function
>update</function
> (zie hier onder) aanroepen om lidvariabelen (member variables) te initialiseren. In het bijzonder moet de variabele <varname
>bool _valid</varname
> de juiste waarde hebben. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual ~TemplateSource()</function
></term>
<listitem>
<para
>De "destructor" voor het leesprogramma voor gegevensbronnen. Al het dynamisch toegewezen (allocated) geheugen moet weer worden vrijgegeven. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>KstObject::UpdateType</returnvalue
> update(<parameter
>int = -1</parameter
>) </function
></term>
<listitem>
<para
>Deze functie moet alle nieuwe gegevens in het gegevensbestand, sinds de laatste keer dat de functie <function
>update</function
> werd aangeroepen, inlezen en de lidvariabelen dienovereenkomstig aanpassen. De functie moet <varname
>KstObject::UPDATE</varname
> retourneren als het bestand is gewijzigd en anders <varname
>KstObject::NO_CHANGE</varname
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> readField(double *<parameter
>v</parameter
>, const QString &amp;<parameter
>veld</parameter
>, int <parameter
>s</parameter
>, int <parameter
>n</parameter
>)</function
></term>
<listitem>
<para
>Deze functie moet <varname
>n</varname
> "frames" van gegevens inlezen, te beginnen met frame <varname
>s</varname
> vanaf het veld met de naam <varname
>veld</varname
>, en dit in het "array" <varname
>v</varname
> retourneren. Als <varname
>n</varname
> kleiner is dan 0 moet de functie 1 monster (sample) lezen vanaf frame <varname
>s</varname
>. Het aantal ingelezen frames moet worden geretourneerd. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>bool</returnvalue
> isValidField(const QString &amp;<parameter
>veld</parameter
>) const</function
></term>
<listitem>
<para
>Deze functie moet "true" (waar) retourneren als het veld met de naam <varname
>veld</varname
> een geldig veld is in de huidige gegevensbron, en "false" (onwaar) als het niet geldig is. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> samplesPerFrame(const QString&amp; <parameter
>veld</parameter
>)</function
></term>
<listitem>
<para
>Deze functie moet het aantal monsters per frame retourneren voor het veld met de naam <varname
>veld</varname
>. Voor gegevensbronnen die hier geen gebruik van maken kan het aantal monsters per frame op <literal
>1</literal
> worden gesteld. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> frameCount() const</function
></term>
<listitem>
<para
>Deze functie moet het totale aantal frames in de gegevensbron retourneren tijdens de laatste keer dat de functie <function
>update</function
> werd aangeroepen. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>QString</returnvalue
> fileType() const <parameter
></parameter
></function
></term>
<listitem>
<para
>Deze functie moet het bestandstype retourneren van het gegevensbestand dat nu in gebruik is, dit is gewoonlijk hetzelfde als de <varname
>type</varname
>-parameter die aan de "constructor" werd meegegeven. Ook kan die een foutmelding bevatten (om aan te geven, bijvoorbeeld, dat het bestandstype niet goed is). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
>virtual <returnvalue
>void</returnvalue
> save(QTextStream &amp;<parameter
>ts</parameter
>)</function
></term>
<listitem>
<para
>Deze functie moet de beschrijving van het bestand opslaan in <varname
>ts</varname
>. In de meeste gevallen is de implementatie die beschikbaar is in <classname
>KstDataSource</classname
> voldoende. </para>
</listitem>
</varlistentry>


</variablelist>

</sect3>

<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexample">
<title
>Voorbeelden van templates (sjablonen)</title>
<para
>In het algemeen kunnen de volgende twee "template"bestanden worden gebruikt voor het maken van nieuwe "shared object files". U kunt ze eenvoudig aanpassen voor uw gegevensbron. </para>
<informalexample>
<screen
>/***************************************************************************
                  template.h  -  template voor gegevensbron plugin
                             -------------------
    begin                : Fri Oct 17 2003
    copyright            : (C) 2003 The University of Toronto
    email                :
 ***************************************************************************/

/***************************************************************************
 *
 *   Dit programma is vrije software; U kunt het verspreiden en/of wijzigen
 *   onder de voorwaarden van de GNU General Public License zoals gepubliceerd
 *   door de Free Software Foundation; zowel version 2 van de licentie, als
 *   (als u wilt)   elke volgende versie.
 *
 ***************************************************************************/

#ifndef TEMPLATE_H
#define TEMPLATE_H

#include &amp;lt;kstdatasource.h&amp;gt;


class TemplateSource : public KstDataSource {
public:
  TemplateSource(const QString&amp; bestandsnaam, const QString&amp; type);

  virtual ~TemplateSource();

  virtual KstObject::UpdateType update(int = -1);

  virtual int readField(double *v, const QString &amp;veld, int s, int n);

  virtual bool isValidField(const QString &amp;veld) const;

  virtual int samplesPerFrame(const QString &amp;veld);

  virtual int frameCount() const;

  virtual QString fileType() const;

  virtual void save(QTextStream &amp;ts);
};


#endif
</screen>
</informalexample>
 
<informalexample>
<screen
>/***************************************************************************
                    template.cpp  -  template voor gegevensbron
                             -------------------
    begin                : Fri Oct 17 2003
    copyright            : (C) 2003 The University of Toronto
    email                :
 ***************************************************************************/

/***************************************************************************
 *
 *   Dit programma is vrije software; U kunt het verspreiden en/of wijzigen
 *   onder de voorwaarden van de GNU General Public License zoals gepubliceerd
 *   door de Free Software Foundation; zowel version 2 van de licentie, als
 *   (als u wilt)   elke volgende versie.
 *
 ***************************************************************************/

#include "template.h"


TemplateSource::TemplateSource(const QString&amp; bestandsnaam, const QString&amp; type)
: KstDataSource(bestandsnaam, type) {
}


TemplateSource::~TemplateSource() {
}


KstObject::UpdateType TemplateSource::update(int u) {
  Q_UNUSED(u)
  return KstObject::NO_CHANGE;
}


int TemplateSource::readField(double *v, const QString&amp; veld, int s, int n) {
  Q_UNUSED(v)
  Q_UNUSED(veld)
  Q_UNUSED(s)
  Q_UNUSED(n)
  return -1;
}


bool TemplateSource::isValidField(const QString&amp; veld) const {
  Q_UNUSED(veld)
  return false;
}


int TemplateSource::samplesPerFrame(const QString &amp;veld) {
  Q_UNUSED(veld)
  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; bestandsnaam, const QString&amp; type) {
  return new TemplateSource(bestandsnaam, type);
}

QStringList provides_template() {
  QStringList rc;
  // de lijst van strings maken
  return rc;
}

bool understands_template(const QString&amp; bestandsnaam) {
  // stel vast of het een X- bestand is
  Q_UNUSED(bestandsnaam)
  return false;
}

}
</screen>
</informalexample>
</sect3>

</sect2>

<sect2 id="supportingadditionalfileformatscreatingdatasourcedesktopfile">
<title
>Het <filename
>.desktop</filename
>-bestand</title>
<para
>Het volgende is een voorbeeld van een <filename
>.desktop</filename
>-bestand voor de template plugin: </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
>Hieraan kunt u vertalingen toevoegen van de Name- en Comment-regels (naam en commentaar) voor andere talen door er extra Name- en Comment-regels aan toe te voegen met <literal
>[xx]</literal
> aan het eind van de veldnamen, waarin <literal
>xx</literal
> de tweeletterige taalcode is (nl voor Nederlands). Bijvoorbeeld, voor het toevoegen van Nederlandse vertalingen moet u de volgende regels toevoegen: </para>
<informalexample>
<screen
>Name[nl]=Sjabloon (template) voor leesprogramma voor bestanden
Comment[nl]=Sjabloon voor de programmacode van een leesprogramma voor bestanden
</screen>
</informalexample>
<para
>Het veld <literal
>X-Kst-Plugin-Library</literal
> moet exact gelijk zijn aan de bibliotheeknaam die is gekozen voor de plugin. </para>
</sect2>

<sect2 id="supportingadditionalfileformatscreatingdatasourcecompiling">
<title
>Compileren en kopiëren</title>
<para
>Om het nieuwe aangepaste leesprogramma voor gegevensbronnen te compileren en te installeren maken wij eerst een nieuwe map onder <filename
>kst/datasources</filename
> van het bronpakket. Plaats de bronbestanden voor het object, samen met het <filename
>.desktop</filename
>-bestand in de nieuwe map. Daarna wijzigen we <filename
>kst/datasources/Makefile.am</filename
> zo dat <varname
>SUBDIRS</varname
> de naam bevat van de nieuwe submap. Bijvoorbeeld, als de nieuwe submap <filename
>template</filename
> heet kan <varname
>SUBDIRS</varname
> als volgt worden gewijzigd: <informalexample
> <screen
>SUBDIRS=ascii dirfile frame indirect template $(PIOLIB_SUBDIR) $(FITSIO_SUBDIR)
</screen>
</informalexample>
</para>


<para
>Als de vereiste bestanden in de nieuw gemaakte submap zijn geplaatst moet er ook een <filename
>Makefile.am</filename
> in worden gemaakt. Gebruik het volgende voorbeeld als een sjabloon (template) waarin u elke keer dat er <quote
>template</quote
> staat dit vervangt door uw bibliotheeknaam <varname
>kde_module_LTLIBRARIES</varname
>, <varname
>kstdata_template_la_SOURCES</varname
> en <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
>Als dit is gebeurd kunt u &kst; compileren en weer installeren vanuit het gewijzigde bronpakket, of anders alleen de nieuwe bibliotheken installeren, als volgt (de <quote
>template</quote
>-submap wordt als voorbeeld gebruikt). Ga eerst naar de root-map van het bronpakket van &kst;. Daarna: <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
>Als u nu &kst; opnieuw start moet het nieuwe leesprogramma voor gegevensbronnen worden ingelezen. </para>
</sect2>

</sect1>


</appendix>
