<appendix id="supportingadditionalfileformats">
<title
>Supporto di formati di file aggiuntivi</title>
<para
>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 <link linkend="supportingadditionalfileformatsdatasourceconcepts"
>Concetti di sorgenti di dati</link
> </para>
<sect1 id="supportingadditionalfileformatscreatingdatasource">
<title
>Creare lettori di sorgenti di dati</title>
<para
>Se vuoi usare un formato di file diverso da quelli attualmente supportati, puoi scegliere di scrivere dei lettori di sorgenti di dati appositi. </para>
<para
>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 <filename
>*.desktop</filename
>. 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 è <quote
>ascii</quote
>. </para>
<note>
<para
>I plugin di &kde; <emphasis
>non</emphasis
> 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;. </para>
</note>
<sect2 id="supportingadditionalfileformatscreatingdatasourceobjectfile">
<title
>L'oggetto condiviso</title>
<para
>Un lettore di sorgenti di dati dovrebbe essere una sottoclasse della classe astratta <classname
>KstDataSource</classname
>. Assicurati di includere il file di intestazione di <classname
>KstDataSource</classname
> nel codice sorgente per il tuo lettore di sorgenti di dati: <screen>
#include <kstdatasource.h>
</screen
> 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 <classname
>KstDataSource</classname
>. Entrambi gli insiemi di requisiti, insieme a suggerimenti e spiegazioni generali, sono dati nelle sezioni seguenti. </para>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexportedfxns">
<title
>Funzioni C esportate</title>
<para
>Le funzioni C esportate sono elencate sotto. Negli esempi seguenti, tutte le istanze di <varname
><libname></varname
> dovrebbero essere sostituite con il nome della libreria del plugin. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>KstDataSource *</returnvalue
>create_<libname>(const QString& <parameter
>filename</parameter
>, const QString& <parameter
>type</parameter
>)</function
></term>
<listitem>
<para
>Questa funzione dovrebbe creare un nuovo lettore di sorgenti di dati di tipo <varname
><libname></varname
>, dove <varname
><libname></varname
> è il nome della libreria del plugin. Dovrebbe essere restituito un puntatore al nuovo lettore di tipo <classname
>KstDataSource</classname
>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
><returnvalue
>bool</returnvalue
> understands_<libname>(const QString& <parameter
>filename</parameter
>)</function
></term>
<listitem>
<para
>Questa funzione dovrebbe restituire vero se il file specificato da <varname
>filename</varname
> è 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. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
><returnvalue
>QStringList</returnvalue
> provides_<libname>()</function
></term>
<listitem>
<para
>Questa funzione dovrebbe restituire una <classname
>QStringList</classname
> 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. </para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilemembervars">
<title
>Variabili membro protette</title>
<para
><classname
>KstDataSource</classname
> contiene varie variabili membro protette che il lettore personalizzato di sorgenti di dati può usare. Queste variabili sono descritte sotto. </para>
<variablelist>
<varlistentry>
<term
><varname
>bool _valid</varname
></term>
<listitem>
<para
>Questa variabile dovrebbe essere <literal
>true</literal
> 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 <function
>isValid()</function
> di <classname
>KstDataSource</classname
>, che normalmente non viene reimplementata nelle sottoclassi. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>QStringList _fieldList</varname
></term>
<listitem>
<para
>La variabile dovrebbe contenere un elenco dei nomi dei campi nella sorgente di dati. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>QString _filename</varname
></term>
<listitem>
<para
>Questa variabile dovrebbe contenere il nome del file di dati a cui questo lettore di sorgenti di dati è associato. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>QString _source</varname
></term>
<listitem>
<para
>Questa variabile dovrebbe contenere il nome del tipo della sorgente. </para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilevirtualfxns">
<title
>Funzioni virtuali</title>
<para
>La classe <classname
>KstDataSource</classname
> contiene molte funzioni virtuali che dovrebbero essere ridefinite nel lettore delle sorgenti di dati personalizzato. Queste funzioni sono nei file modello <filename
>template.h</filename
> e <filename
>template.cpp</filename
>, elencati nella sezione <link linkend="supportingadditionalfileformatscreatingdatasourceobjectfileexample"
>Modelli d'esempio</link
>. Seguono le descrizioni delle funzioni. </para>
<variablelist>
<varlistentry>
<term
><function
>TemplateSource(const QString&amp; <parameter
>filename</parameter
>, const QString&amp; <parameter
>type</parameter
>) </function
></term>
<listitem>
<para
>Il costruttore del lettore di sorgente di dati. <varname
>filename</varname
> è il nome del file da cui leggere i dati, e <varname
>type</varname
> è il tipo di dati che il file contiene. Questo costruttore dovrebbe quasi sicuramente invocare il costruttore di <classname
>KstDataSource</classname
> nell'elenco di inizializzatori del costruttore, e probabilmente chiamare la funzione <function
>update</function
> elencata sotto per inizializzare le variabili membro. In particolare, la variabile <varname
>bool _valid</varname
> dovrebbe essere impostata opportunamente. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual ~TemplateSource()</function
></term>
<listitem>
<para
>Il distruttore del lettore di sorgenti di dati. Dovrebbe essere liberata tutta la memoria allocata dinamicamente. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>KstObject::UpdateType</returnvalue
> update(<parameter
>int = -1</parameter
>) </function
></term>
<listitem>
<para
>Questa funzione dovrebbe restituire tutti i dati nuovi inseriti nel file di dati dall'ultima volta che è stata chiamata <function
>update</function
>, e aggiornare opportunamente le variabili membro. La funzione dovrebbe restituire <varname
>KstObject::UPDATE</varname
> se il file ha subito variazioni, o altrimenti <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
>Questa funzione dovrebbe leggere <varname
>n</varname
> fotogrammi di dati, a partire dal fotogramma <varname
>s</varname
> dal campo specificato dal nome di campo <varname
>field</varname
>, e restituire i contenuti nella matrice <varname
>v</varname
>. Se <varname
>n</varname
> è inferiore a 0, la funzione dovrebbe invece leggere un campione partendo dal fotogramma <varname
>s</varname
>. Dovrebbe essere restituito il numero di fotogrammi letti. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>bool</returnvalue
> isValidField(const QString &<parameter
>field</parameter
>) const</function
></term>
<listitem>
<para
>Questa funzione dovrebbe restituire vero se il campo specificato dal nome di campo <varname
>field</varname
> è un campo valido nella sorgente di dati attuale, o falso se il campo non è un campo valido. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> samplesPerFrame(const QString& <parameter
>field</parameter
>)</function
></term>
<listitem>
<para
>Questa funzione dovrebbe restituire il numero di campioni per fotogramma per il campo specificato dal nome di campo <varname
>field</varname
>. Per le sorgenti di dati che non usano questo concetto, il numero di campioni per fotogramma può essere impostato a <literal
>1</literal
>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> frameCount() const</function
></term>
<listitem>
<para
>Questa funzione dovrebbe restituire il numero totale di fotogrammi nella sorgente di dati, aggiornato all'ultima volta che <function
>update</function
> è stata chiamata. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>QString</returnvalue
> fileType() const <parameter
></parameter
></function
></term>
<listitem>
<para
>Questa funzione dovrebbe restituire il tipo di file del file di dati attualmente in uso, normalmente lo stesso del parametro <varname
>type</varname
> che è stato passato al costruttore. Alternativamente, può contenere un messaggio d'errore (per indicare, per esempio, che il file non è valido). </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>void</returnvalue
> save(QTextStream &<parameter
>ts</parameter
>)</function
></term>
<listitem>
<para
>Questa funzione dovrebbe salvare le informazioni di descrizione del file in <varname
>ts</varname
>. Nella maggior parte dei casi l'implementazione fornita da <classname
>KstDataSource</classname
> dovrebbe essere sufficiente. </para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexample">
<title
>Modelli d'esempio</title>
<para
>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. </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
>Il file <filename
>.desktop</filename
></title>
<para
>Ciò che segue è un esempio di un file <filename
>.desktop</filename
> per il plugin modello: </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
>Dovresti aggiungere delle traduzioni in altre lingue per i campi Name e Comment aggiungendo altri campi Name e Comment con <literal
>[xx]</literal
> a seguire del nome dei campi, dove <literal
>xx</literal
> è il codice a due lettere della lingua. Per esempio, per aggiungere delle traduzioni in spagnolo, dovrebbero essere aggiunte le righe seguenti: </para>
<informalexample>
<screen
>Name[es]=Plantilla de lectura de ficheros
Comment[es]=Plantilla de código para hacer un complemento de lectura de ficheros.
</screen>
</informalexample>
<para
>Il campo <literal
>X-Kst-Plugin-Library</literal
> dovrebbe essere esattamente lo stesso del nome della libreria scelta per il plugin. </para>
</sect2>
<sect2 id="supportingadditionalfileformatscreatingdatasourcecompiling">
<title
>Compilazione e copia</title>
<para
>Per compilare e installare il nuovo lettore di sorgenti di dati personalizzato, crea una nuova cartella sotto <filename
>kst/datasources</filename
> nel pacchetto sorgente. Posiziona i file sorgente per l'oggetto, oltre al file <filename
>.desktop</filename
> nella nuova cartella. Quindi, modifica <filename
>kst/datasources/Makefile.am</filename
> in modo che <varname
>SUBDIRS</varname
> contenga il nome della nuova sottocartella. Per esempio, se la nuova sottocartella è chiamata <filename
>template</filename
>, <varname
>SUBDIRS</varname
> potrebbe essere cambiata così: <informalexample
> <screen
>SUBDIRS=ascii dirfile frame indirect template $(PIOLIB_SUBDIR) $(FITSIO_SUBDIR)
</screen>
</informalexample>
</para>
<para
>Dopo che i file necessari saranno nella cartella appena creata, deve esserci creato anche un <filename
>Makefile.am</filename
>. Usa il campione seguente come un modello, sostituendo tutte le occorrenze di <quote
>template</quote
> con il nome della tua libreria personalizzata in <varname
>kde_module_LTLIBRARIES</varname
>, <varname
>kstdata_template_la_SOURCES</varname
> e <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
>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 <quote
>template</quote
> come esempio). Prima passa alla cartella radice del pacchetto sorgente di &kst;. Poi, <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
>Riavvia &kst; e il nuovo lettore di sorgenti di dati dovrebbe essere caricato. </para>
</sect2>
</sect1>
</appendix>
distrib
>
Mandriva
>
10.2
>
i586
>
media
>
contrib
>
by-pkgid
>
eb2ca3fa8cac6766aebe2c4233348281
>
files
>
293
