# Supporto di formati di file aggiuntivi

Questa sezione descrive come creare lettori aggiuntivi per formati di file non supportati. Se non sei in confidenza con i concetti delle sorgenti di dati, per piacere leggi Concetti di sorgenti di dati

## Creare lettori di sorgenti di dati

Se vuoi usare un formato di file diverso da quelli attualmente supportati, puoi scegliere di scrivere dei lettori di sorgenti di dati appositi.

Tutti i lettori di sorgenti di dati di &kst; sono normali plugin di &kde;. Come tutti i plugin di &kde;, ogni lettore di sorgenti di dati deve avere un file oggetto condiviso e un file `*.desktop`. Prima di scrivere il lettore, deve essere deciso il nome della libreria del plugin. Questo nome deve essere un valido nome di variabile in C, perché verrà usato nei nomi di funzione dell'oggetto condiviso. Per esempio, il nome della libreria del lettore per file ASCII è ascii.

I plugin di &kde; non sono la stessa cosa che i plugin di &kst; usati per manipolare dati. Tutti i riferimenti ai plugin in questa sezione sono ai plugin di &kde;.

### L'oggetto condiviso

Un lettore di sorgenti di dati dovrebbe essere una sottoclasse della classe astratta `KstDataSource`. Assicurati di includere il file di intestazione di `KstDataSource` nel codice sorgente per il tuo lettore di sorgenti di dati:

    #include <kstdatasource.h>

Ci sono certi requisiti che un lettore di sorgenti di dati deve soddisfare. Un requisito riguarda la presenza di funzioni C esportate. Altri requisiti sono conseguenze del fatto che i lettori di sorgenti di dati ereditano da `KstDataSource`. Entrambi gli insiemi di requisiti, insieme a suggerimenti e spiegazioni generali, sono dati nelle sezioni seguenti.

#### Funzioni C esportate

Le funzioni C esportate sono elencate sotto. Negli esempi seguenti, tutte le istanze di `<libname>` dovrebbero essere sostituite con il nome della libreria del plugin.

`KstDataSource *create_<libname>(const QString& `filename`, const QString& `type`)`

- Questa funzione dovrebbe creare un nuovo lettore di sorgenti di dati di tipo `<libname>`, dove `<libname>` è il nome della libreria del plugin. Dovrebbe essere restituito un puntatore al nuovo lettore di tipo `KstDataSource`.

`bool understands_<libname>(const QString& `filename`)`

- Questa funzione dovrebbe restituire vero se il file specificato da `filename` è di un tipo valido supportato da questo lettore, e falso altrimenti. La funzione dovrebbe controllare la validità dei contenuti del file, e non affidarsi a nessuna estensione dei file.

`QStringList provides_<libname>()`

- Questa funzione dovrebbe restituire una `QStringList` dei tipi di file supportati da questo lettore. Le stringhe restituite sono arbitrarie, ma dovrebbero essere descrittive e appropriate per i vari tipi di file.

#### Variabili membro protette

`KstDataSource` contiene varie variabili membro protette che il lettore personalizzato di sorgenti di dati può usare. Queste variabili sono descritte sotto.

`bool _valid`

- Questa variabile dovrebbe essere `true` se il lettore di sorgenti di dati personalizzato è valido. Molto probabilmente il lettore sarà valido, a meno che ci sia una condizione d'errore (come se i dati fossero illeggibili per il lettore). Questa variabile è usata dalla funzione `isValid()` di `KstDataSource`, che normalmente non viene reimplementata nelle sottoclassi.

`QStringList _fieldList`

- La variabile dovrebbe contenere un elenco dei nomi dei campi nella sorgente di dati.

`QString _filename`

- Questa variabile dovrebbe contenere il nome del file di dati a cui questo lettore di sorgenti di dati è associato.

`QString _source`

- Questa variabile dovrebbe contenere il nome del tipo della sorgente.

#### Funzioni virtuali

La classe `KstDataSource` contiene molte funzioni virtuali che dovrebbero essere ridefinite nel lettore delle sorgenti di dati personalizzato. Queste funzioni sono nei file modello `template.h` e `template.cpp`, elencati nella sezione Modelli d'esempio. Seguono le descrizioni delle funzioni.

`TemplateSource(const QString&amp; `filename`, const QString&amp; `type`)`

- Il costruttore del lettore di sorgente di dati. `filename` è il nome del file da cui leggere i dati, e `type` è il tipo di dati che il file contiene. Questo costruttore dovrebbe quasi sicuramente invocare il costruttore di `KstDataSource` nell'elenco di inizializzatori del costruttore, e probabilmente chiamare la funzione `update` elencata sotto per inizializzare le variabili membro. In particolare, la variabile `bool _valid` dovrebbe essere impostata opportunamente.

`virtual ~TemplateSource()`

- Il distruttore del lettore di sorgenti di dati. Dovrebbe essere liberata tutta la memoria allocata dinamicamente.

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

- Questa funzione dovrebbe restituire tutti i dati nuovi inseriti nel file di dati dall'ultima volta che è stata chiamata `update`, e aggiornare opportunamente le variabili membro. La funzione dovrebbe restituire `KstObject::UPDATE` se il file ha subito variazioni, o altrimenti `KstObject::NO_CHANGE`.

`virtual int readField(double *`v`, const QString &`field`, int `s`, int `n`)`

- Questa funzione dovrebbe leggere `n` fotogrammi di dati, a partire dal fotogramma `s` dal campo specificato dal nome di campo `field`, e restituire i contenuti nell'array `v`. Se `n` è minore di 0, la funzione dovrebbe invece leggere un campione dall'inizio del fotogramma `s`. Dovrebbe essere restituito il numero di fotogrammi letti.

`virtual bool isValidField(const QString &`field`) const`

- Questa funzione dovrebbe restituire vero se il campo specificato dal nome di campo `field` è un campo valido nella sorgente di dati attuale, o falso se il campo non è un campo valido.

`virtual int samplesPerFrame(const QString& `field`)`

- Questa funzione dovrebbe restituire il numero di campioni per fotogramma per il campo specificato dal nome di campo `field`. Per le sorgenti di dati che non usano questo concetto, il numero di campioni per fotogramma può essere impostato a `1`.

`virtual int frameCount() const`

- Questa funzione dovrebbe restituire il numero totale di fotogrammi nella sorgente di dati, aggiornato all'ultima volta che `update` è stata chiamata.

`virtual QString fileType() const ```

- Questa funzione dovrebbe restituire il tipo di file del file di dati attualmente in uso, normalmente lo stesso del parametro `type` che è stato passato al costruttore. Alternativamente, può contenere un messaggio d'errore (per indicare, per esempio, che il file non è valido).

`virtual void save(QTextStream &`ts`)`

- Questa funzione dovrebbe salvare le informazioni di descrizione del file in `ts`. Nella maggior parte dei casi l'implementazione fornita da `KstDataSource` dovrebbe essere sufficiente.

#### Modelli d'esempio

In generale, i due modelli seguenti possono essere usati per creare nuovi file oggetto condivisi. Semplicemente, modifica i corpi delle funzioni come opportuno per la tua particolare sorgente di dati.

    /***************************************************************************
                      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

    /***************************************************************************
                        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;
    }

    }

### Il file `.desktop`

Ciò che segue è un esempio di un file `.desktop` per il plugin modello:

    [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.

Dovresti aggiungere delle traduzioni in altre lingue per i campi Name e Comment aggiungendo altri campi Name e Comment con `[xx]` a seguire del nome dei campi, dove `xx` è il codice a due lettere della lingua. Per esempio, per aggiungere delle traduzioni in spagnolo, dovrebbero essere aggiunte le righe seguenti:

    Name[es]=Plantilla de lectura de ficheros
    Comment[es]=Plantilla de código para hacer un complemento de lectura de ficheros.

Il campo `X-Kst-Plugin-Library` dovrebbe essere esattamente lo stesso del nome della libreria scelta per il plugin.

### Compilazione e copia

Per compilare e installare il nuovo lettore di sorgenti di dati personalizzato, crea una nuova cartella sotto `kst/datasources` nel pacchetto sorgente. Posiziona i file sorgente per l'oggetto, oltre al file `.desktop` nella nuova cartella. Quindi, modifica `kst/datasources/Makefile.am` in modo che `SUBDIRS` contenga il nome della nuova sottocartella. Per esempio, se la nuova sottocartella è chiamata `template`, `SUBDIRS` potrebbe essere cambiata così:

    SUBDIRS=ascii dirfile frame indirect template $(PIOLIB_SUBDIR) $(FITSIO_SUBDIR)

Dopo che i file necessari saranno nella cartella appena creata, deve esserci creato anche un `Makefile.am`. Usa il campione seguente come un modello, sostituendo tutte le occorrenze di template con il nome della tua libreria personalizzata in `kde_module_LTLIBRARIES`, `kstdata_template_la_SOURCES` e `services_DATA`.

    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

Fatto questo, puoi compilare e reinstallare &kst; dal pacchetto sorgente modificato, o, alternativamente, installare solo le nuove librerie, come descritto di seguito (usando la cartella template come esempio). Prima passa alla cartella radice del pacchetto sorgente di &kst;. Poi,

    ./configure --prefix=`kde-config --prefix`
    cd ./kst/datasources/template
    make
    make install

Riavvia &kst; e il nuovo lettore di sorgenti di dati dovrebbe essere caricato.