<appendix id="supportingadditionalfileformats">
<title
>Soporte para formatos adicionales de archivos</title>
<para
>Esta sección describe como crear lectores adicionales para la lectura de archivos de datos no soportados. Si no está familiarizado con los conceptos de fuentes de datos, por favor, lea los <link linkend="supportingadditionalfileformatsdatasourceconcepts"
>Conceptos de fuentes de datos</link
>. </para>
<sect1 id="supportingadditionalfileformatscreatingdatasource">
<title
>Crear lectores de fuentes de datos</title>
<para
>Si desea usar un formato de archivos diferente a aquellos que ya están soportados, puede escribir sus propios lectores de datos de fuentes. </para>
<para
>Todos los lectores de fuentes de &kst; son extensiones normales de &kde;. Como todas las extensiones de &kde;, cada lector de fuentes de datos debe tener una biblioteca dinámica y un archivo <filename
>*.desktop</filename
>. Antes de escribir el lector, debe decidirse el nombre de la biblioteca a usar por la extensión. Éste debe ser un nombre válido como variable C, pues se usará en los nombres de las funciones de la biblioteca dinámica. Por ejemplo, el nombre de biblioteca del lector para archivos ASCII es «ascii». </para>
<note>
<para
>Las extensiones de &kde; <emphasis
>no</emphasis
> son diferentes de las extensiones de &kst; que se usan para manipular datos. Todas las referencias de las extensiones que damos en esta sección se refieren a extensiones de &kde;. </para>
</note>
<sect2 id="supportingadditionalfileformatscreatingdatasourceobjectfile">
<title
>La biblioteca dinámica</title>
<para
>Un lector de fuentes de datos debe ser una subclase de la clase abstracta <classname
>KstDataSource</classname
>. Asegúrese de que incluye el archivo de cabecera para dicha <classname
>KstDataSource</classname
> en el código de su lector:<screen>
#include <kstdatasource.h>
</screen
> Hay ciertos requerimientos que su lector tiene que cumplir. Unos son que hay que exportar ciertas funciones C. Otros son consecuencia de heredar de la clase <classname
>KstDataSource</classname
>. A continuación explicamos tales requerimientos, junto con sugerencias y explicaciones generales. </para>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexportedfxns">
<title
>Funciones en C a exportar</title>
<para
>A continuación se listan las funciones en C a exportar. En los ejemplos siguientes, se deben reemplazar todas las instancias de la <varname
><libname></varname
> con el nombre de la biblioteca de la extensión. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>KstDataSource *</returnvalue
>create_<libname>(const QString& <parameter
>nombrearchivo</parameter
>, const QString& <parameter
>type</parameter
>)</function
></term>
<listitem>
<para
>Esta función debe crear un nuevo lector de datos fuentes del tipo <varname
><libname></varname
>, donde <varname
><libname></varname
> es el nombre de biblioteca de la extensión. Se devuelve un puntero al nuevo lector del tipo <classname
>KstDataSource</classname
>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
><returnvalue
>bool</returnvalue
> understands_<libname>(const QString& <parameter
>nombrearchivo</parameter
>)</function
></term>
<listitem>
<para
>Esta función debe devolver el valor verdadero si el archivo especificado por <varname
>nombrearchivo</varname
> es de un tipo válido soportado por este lector, y falso si no lo es. Esta función solo debe examinar los contenidos del archivo para validar, y no debe basarse en la extensión del archivo. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
><returnvalue
>QStringList</returnvalue
> provides_<libname>()</function
></term>
<listitem>
<para
>Esta función devuelve una lista del tipo <classname
>QStringList</classname
> con los tipos de archivos soportados por este lector. Las cadenas que se devuelven son arbitrarias, pero deben ser descriptivas y apropiadas para los tipos de archivo actual. </para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilemembervars">
<title
>Variables miembros protegidas</title>
<para
><classname
>KstDataSource</classname
> contiene varias variables miembro protegidas que el lector puede usar. Las describimos a continuación. </para>
<variablelist>
<varlistentry>
<term
><varname
>bool _valid</varname
></term>
<listitem>
<para
>Esta variable debe ser <literal
>true</literal
> (verdadero) si nuestro lector de fuentes de datos es válido. Lo más probable es que así sea, a menos que exista una condición de error (tal que el archivo de datos no sea legible por el lector). Esta variable se usa junto con la función <function
>isValid()</function
> de <classname
>KstDataSource</classname
>, la cual no suele reimplementarse en las subclases. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>QStringList _fieldList</varname
></term>
<listitem>
<para
>Esta variable debe contener una lista de los nombres de los campos en la fuente de datos. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>QString _filename</varname
></term>
<listitem>
<para
>Esta variable debe asociarse al nombre del archivo de datos al que se asocia el lector de datos. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>QString _source</varname
></term>
<listitem>
<para
>Esta variable debe contener el nombre del tipo de la fuente. </para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfilevirtualfxns">
<title
>Funciones virtuales</title>
<para
>La clase <classname
>KstDataSource</classname
> contiene numerosas funciones virtuales que deben redefinirse en nuestro lector de datos. Estas funciones están en los archivos de plantilla <filename
>template.h</filename
> y <filename
>template.cpp</filename
>, listados en la sección <link linkend="supportingadditionalfileformatscreatingdatasourceobjectfileexample"
>Plantillas de ejemplo</link
>. A continuación se presenta una descripción de las funciones. </para>
<variablelist>
<varlistentry>
<term
><function
>TemplateSource(const QString&amp; <parameter
>nombrearchivo</parameter
>, const QString&amp; <parameter
>type</parameter
>) </function
></term>
<listitem>
<para
>El constructor del lector de datos. El nombre del archivo del cual se leen los datos es <varname
>nombrearchivo</varname
>, y el tipo de datos que contiene es <varname
>type</varname
>. Lo más normal es que este constructor invoque el constructor de la clase <classname
>KstDataSource</classname
> en la lista de inicialización del constructor, y que llame a la función <function
>update</function
> (ver más abajo) para inicializar las variables miembro. En particular, hay que asignar la variable <varname
>bool _valid</varname
> de forma adecuada. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual ~TemplateSource()</function
></term>
<listitem>
<para
>El destructor del lector de datos. Debe liberar la memoria dinámica que se halla requerido al sistema. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>KstObject::UpdateType</returnvalue
> update(<parameter
>int = -1</parameter
>) </function
></term>
<listitem>
<para
>Esta función debe leer cualesquiera datos nuevos que se hayan añadido al archivo de datos desde la última llamada a <function
>update</function
>, y actualizar las variables miembro de forma apropiada. La función debe devolver <varname
>KstObject::UPDATE</varname
> si ha habido cambios en el archivo, y <varname
>KstObject::NO_CHANGE</varname
> si no. </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
>Esta función debe leer <varname
>n</varname
> estructuras de datos, comenzando en la estructura <varname
>s</varname
> desde el campo especificado por el campo <varname
>campo</varname
>, y devolver los contenidos en el vector <varname
>v</varname
>. Si <varname
>n</varname
> vale menos que 0, la función debe leer 1 muestra comenzando en la estructura <varname
>s</varname
>. Debe devolverse el número de estructuras que se hayan leído. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>bool</returnvalue
> isValidField(const QString &<parameter
>field</parameter
>) const</function
></term>
<listitem>
<para
>Esta función debe devolver el valor verdadero si el campo <varname
>field</varname
> es un campo válido en la fuente de datos actual, o falso cuando no lo es. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> samplesPerFrame(const QString& <parameter
>field</parameter
>)</function
></term>
<listitem>
<para
>Esta función devuelve la tasa de muestras por estructuras para el campo especificado por <varname
>field</varname
>. Si las fuentes de datos no hacen uso de este concepto, el número de muestras por estructura debe valer <literal
>1</literal
>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>int</returnvalue
> frameCount() const</function
></term>
<listitem>
<para
>Esta función debe devolver el número de estructuras en la fuente de datos existentes en el momento de la última llamada <function
>update</function
>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>QString</returnvalue
> fileType() const <parameter
></parameter
></function
></term>
<listitem>
<para
>Esta función debe devolver el tipo del archivo de datos que se está usando, normalmente el mismo que el parámetro <varname
>type</varname
> que se pasó al constructor. Alternativamente, puede contener un mensaje de error (para indicar, por ejemplo, que el campo no es válido). </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><function
>virtual <returnvalue
>void</returnvalue
> save(QTextStream &<parameter
>ts</parameter
>)</function
></term>
<listitem>
<para
>Esta función debe guardar la información de descripción del archivo a <varname
>ts</varname
>. En la mayoría de los casos es suficiente usar la implementación dada por <classname
>KstDataSource</classname
>. </para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="supportingadditionalfileformatscreatingdatasourceobjectfileexample">
<title
>Plantillas ejemplo</title>
<para
>Puede usar los dos archivos plantilla siguientes para crear nuevas bibliotecas dinámicas. Simplemente modifique los cuerpos de las funciones como sea necesario para su fuente de datos particular. </para>
<informalexample>
<screen
>/***************************************************************************
template.h - Plantilla de extensión para fuentes de datos
-------------------
inicio : Vie 17 Oct 2003
derechos de autor : (C) 2003. La univerdad de Toronto
correo electrónico :
***************************************************************************/
/***************************************************************************
* *
* Éste programa es software libre. Puede distribuirlo y/o modificarlo *
* bajo los términos de la Licencia Pública General GNU y publicado por *
* la Free Software Foundation, en su versión 2 de la licencia o *
* posterior (a su elección). *
* *
***************************************************************************/
#ifndef TEMPLATE_H
#define TEMPLATE_H
#include &lt;kstdatasource.h&gt;
class TemplateSource : public KstDataSource {
public:
TemplateSource(const QString& nombrearchivo, 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 - Plantilla de fuente de datos
-------------------
inicio : Vie 17 Oct 2003
derechos de autor : (C) 2003 La universidad de Toronto
correo electrónico :
***************************************************************************/
/***************************************************************************
* *
* Éste programa es software libre. Puede distribuirlo y/o modificarlo *
* bajo los términos de la Licencia Pública General GNU y publicado por *
* la Free Software Foundation, en su versión 2 de la licencia o *
* posterior (a su elección). *
* *
***************************************************************************/
n#include "template.h"
TemplateSource::TemplateSource(const QString& nombrearchivo, const QString& type)
: KstDataSource(nombrearchivo, 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& nombrearchivo, const QString& type) {
return new TemplateSource(nombrearchivo, type);
}
QStringList provides_template() {
QStringList rc;
// create the stringlist
return rc;
}
bool understands_template(const QString& nombrearchivo) {
// determine if it is an X file
Q_UNUSED(nombrearchivo)
return false;
}
}
</screen>
</informalexample>
</sect3>
</sect2>
<sect2 id="supportingadditionalfileformatscreatingdatasourcedesktopfile">
<title
>El archivo <filename
>.desktop</filename
></title>
<para
>A continuación se muestra un ejemplo del archivo <filename
>.desktop</filename
> para la plantilla de la extensión: </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
>Debería añadir traducciones en idiomas adicionales para los campos Name y Comment, añadiendo campos Name y Comment adicionales con el sufijo <literal
>[xx]</literal
> añadido, donde <literal
>xx</literal
> es el código de dos letras del lenguaje. Por ejemplo, para añadir la traducción española, deberían añadirser estas líneas: </para>
<informalexample>
<screen
>Name[es]=Plantilla de lectura de archivos
Comment[es]=Plantilla de código para hacer una extensión de lectura de archivos.
</screen>
</informalexample>
<para
>El campo <literal
>X-Kst-Plugin-Library</literal
> debe ser exactamente igual al nombre de la biblioteca de la extensión. </para>
</sect2>
<sect2 id="supportingadditionalfileformatscreatingdatasourcecompiling">
<title
>Compilando y copiando</title>
<para
>Para compilar e instalar una versión personalizada de nuestro lector de datos, cree un nuevo directorio bajo <filename
>kst/datasources</filename
> del paquete con las fuentes de kst. Ponga sus fuentes junto con el archivo <filename
>.desktop</filename
> en tal directorio. Entonces edite <filename
>kst/datasources/Makefile.am</filename
> tal que <varname
>SUBDIRS</varname
> contenga el nombre del nuevo subdirectorio. Por ejemplo, si el nuevo subdirectorio se llama <filename
>template</filename
>, <varname
>SUBDIRS</varname
> puede cambiarse a: <informalexample
> <screen
>SUBDIRS=ascii dirfile frame indirect template $(PIOLIB_SUBDIR) $(FITSIO_SUBDIR)
</screen>
</informalexample>
</para>
<para
>Despues de tener a los archivos en el directorio ya creado, se necesita crear ahí un archivo <filename
>Makefile.am</filename
>. Use el ejemplo siguiente como plantilla, reemplazando «template» con el nombre de su biblioteca en <varname
>kde_module_LTLIBRARIES</varname
>, <varname
>kstdata_template_la_SOURCES</varname
> y <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
>Una vez que se haya hecho esto, puede compilar y reinstalar &kst; desde el paquete fuente modificado, o alternativamente, solo instalar las nuevas bibliotecas, como sigue (usando el subdirectorio «template» como ejemplo). Primero cambie las directorio raíz de las fuentes de &kst;. Y después escriba <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
>Vuelva a iniciar &kst; y se debería cargar el nuevo lector de datos. </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:
-->
