tde-i18n/tde-i18n-es/docs/tdevelop/kdearch/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY % addindex "INCLUDE">
  <!ENTITY % Spanish "INCLUDE"> <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
<title>Introducción a la arquitectura de KDE</title>

<date></date>
<releaseinfo></releaseinfo>

<authorgroup>
<author><firstname>Bernd</firstname> <surname>Gehrmann</surname> <affiliation><address><email>bernd@kdevelop.org</email></address></affiliation>
</author>
</authorgroup>

<copyright>
<year>2001</year>
<year>2002</year>
<holder>Bernd Gehrmann</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<abstract>
<para>Esta documentación es una introducción a la plataforma de desarrollo de KDE</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>arquitectura</keyword>
<keyword>desarrollo</keyword>
<keyword>programación</keyword>
</keywordset>

</bookinfo>

<chapter id="structure">
<title>Estructura de bibliotecas</title>

<simplesect id="structure-byname">
<title>Bibliotecas por nombre</title>

<variablelist>

<varlistentry>
<term><ulink url="kdeapi:tdecore/index.html">tdecore</ulink></term>
<listitem><para>La biblioteca tdecore es el marco de trabajo de aplicación básico para cualquier programa basado en KDE. Proporciona acceso al sistema de configuración, a la gestión de la línea de órdenes, a la carga y manipulación de iconos, a algunos tipos especiales de comunicación entre procesos, al manejo de archivos y a otras utilidades varias. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:tdeui/index.html">tdeui</ulink></term>
<listitem><para>La biblioteca <literal>tdeui</literal> proporciona muchos widgets y diálogos estándar que Qt no incluye o proporciona de forma menos completa. También incluye varios componentes que son subclases de otros de Qt y están mejor integrados en el entorno KDE al respetar las preferencias de los usuarios. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:tdeio/index.html">tdeio</ulink></term>
<listitem><para>La biblioteca <literal>tdeio</literal> contiene facilidades para la E/S transparente y asíncrona de red, así como acceso al manejo de tipos MIME. También proporciona el diálogo de archivos de KDE y sus clases auxiliares. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:kjs/index.html">kjs</ulink></term>
<listitem><para>La biblioteca <literal>kjs</literal> proporciona una implementación de JavaScript. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:tdehtml/index.html">tdehtml</ulink></term>
<listitem><para>La biblioteca <literal>tdehtml</literal> contiene el módulo TDEHTML, un widget de navegación HTML, el API y un procesador de DOM, incluyendo interfaces para Java y JavaScript. </para></listitem>
</varlistentry>

</variablelist>

</simplesect>


<simplesect id="structure-grouped">
<title>Clases agrupadas</title>

<para>Esquema principal de una aplicación - clases que son necesarias en casi cualquier aplicación. </para>

<itemizedlist>

<listitem><formalpara>
<title><ulink url="kdeapi:tdecore/TDEApplication">TDEApplication</ulink></title>
<para>Inicia y controla una aplicación de KDE. </para>
</formalpara></listitem>

<listitem><formalpara>
<title><ulink url="kdeapi:tdecore/KUniqueApplication">KUniqueApplication</ulink></title>
<para>Se asegura de que solo se ejecuta una sesión de la aplicación en cada momento. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEAboutData">TDEAboutData</ulink></title>
<para>Contiene la información de la ventana «Acerca de». </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDECmdLineArgs">TDECmdLineArgs</ulink></title>
<para>Procesamiento de argumentos de la línea de órdenes. </para>
</formalpara></listitem>

</itemizedlist>

<para>Preferencias de configuración - acceso a la base de datos de configuración jerárquica de KDE, a las preferencias globales y a los recursos de la aplicación. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEConfig">TDEConfig</ulink></title>
<para>Proporciona acceso a la base de datos de configuración de KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KSimpleConfig">KSimpleConfig</ulink></title>
<para>Acceso a archivos de configuración simples y no jerárquicos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KDesktopFile">KDesktopFile</ulink></title>
<para>Acceso a los archivo <literal>.desktop</literal>. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEGlobalSettings">TDEGlobalSettings</ulink></title>
<para>Acceso cómodo a las preferencias que no son específicas de la aplicación. </para>
</formalpara></listitem>

</itemizedlist>

<para>Manejo de archivos y URLs - descodificación de URLs, archivos temporales, etc. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KURL">KURL</ulink></title>
<para>Representa y procesa URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KTempFile">KTempFile</ulink></title>
<para>Crea archivos de nombre único para almacenamiento temporal. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KSaveFile">KSaveFile</ulink></title>
<para>Permite guardar archivos en segmentos. </para>
</formalpara></listitem>

</itemizedlist>

<para>Comunicación entre procesos - clases auxiliares para DCOP e invocación de subprocesos. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEProcess">TDEProcess</ulink></title>
<para>Invoca y controla procesos hijo. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KShellProcess">KShellProcess</ulink></title>
<para>Invoca procesos hijo a través de un intérprete de comandos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdesu/PtyProcess">PtyProcess</ulink></title>
<para>Comunicación con procesos hijo a través de una pseudo terminal. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KIPC">KIPC</ulink></title>
<para>Comunicación entre procesos simple utilizando ClientMessages de X11. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:dcop/DCOPClient">DCOPClient</ulink></title>
<para>Mensajería DCOP. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KDCOPPropertyProxy">KDCOPPropertyProxy</ulink></title>
<para>Una clase proxy que publica las propiedades de Qt a través de DCOP. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KDCOPActionProxy">KDCOPActionProxy</ulink></title>
<para>Una clase proxy que publica un interfaz DCOP para realizar acciones. </para>
</formalpara></listitem>

</itemizedlist>

<para>Clases de utilidades - gestión de memoria, expresiones regulares, manipulación de cadenas, números aleatorios </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KRegExp">KRegExp</ulink></title>
<para>Tratamiento de expresiones regulares según POSIX. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KStringHandler">KStringHandler</ulink></title>
<para>Una extravagante interfaz para la manipulación de cadenas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEZoneAllocator">TDEZoneAllocator</ulink></title>
<para>Localización eficiente de memoria para grandes grupos de pequeños objetos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KRandomSequence">KRandomSequence</ulink></title>
<para>Generador de números pseudo aleatorios. </para>
</formalpara></listitem>

</itemizedlist>

<para>Aceleradores de teclado - clases de ayuda para el establecimiento de atajos de teclado consistentes con el escritorio. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEAccel">TDEAccel</ulink></title>
<para>Collección de atajos de teclado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEStdAccel">TDEStdAccel</ulink></title>
<para>Acceso sencillo a los atajos de teclado más comunes. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEGlobalAccel"></ulink></title>
<para>Colección de atajos de teclado que afectan a todo el sistema. </para>
</formalpara></listitem>

</itemizedlist>

<para>Procesamiento de imágenes - carga y manipulación de iconos. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEIconLoader">TDEIconLoader</ulink></title>
<para>Carga iconos de una forma consistente con los temas de escritorio. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEIconTheme">TDEIconTheme</ulink></title>
<para>Clases de ayuda para TDEIconLoader. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KPixmap">KPixmap</ulink></title>
<para>Una clase de mapa de pixels con posibilidades extendidas de optimización de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPixmapEffect">KPixmapEffect</ulink></title>
<para>Efectos de mapas de píxels como gradientes y patrones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPixmapIO">KPixmapIO</ulink></title>
<para>Conversión rápida de <classname>QImage</classname> a <classname>QPixmap</classname>. </para>
</formalpara></listitem>

</itemizedlist>

<para>Arrastrar y soltar - objetos de arrastre para colores y URLs. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KURLDrag">KURLDrag</ulink></title>
<para>Un objeto de arrastre para URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorDrag">KColorDrag</ulink></title>
<para>Un objeto de arrastre para colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KMultipleDrag">KMultipleDrag</ulink></title>
<para>Permite construir objetos de arrastre a partir varios otros. </para>
</formalpara></listitem>

</itemizedlist>

<para>Autocompletado </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDECompletion">TDECompletion</ulink></title>
<para>Autocompletado de cadenas genérico. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KURLCompletion">KURLCompletion</ulink></title>
<para>Autocompletado de URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KShellCompletion">KShellCompletion</ulink></title>
<para>Autocompletado de ejecutables. </para>
</formalpara></listitem>

</itemizedlist>

<para>Widgets - clases de widgets para vistas de lista, reglas, selección de colores, etc. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">TDEListView</ulink></title>
<para>Una variante de <classname>QListView</classname> que se ajusta a las preferencias globales del sistema KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">TDEListBox</ulink></title>
<para>Una variante de <classname>QListBox</classname> que se ajusta a las preferencias globales del sistema KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">TDEIconView</ulink></title>
<para>Una variante de <classname>QIconView</classname> que se ajusta a las preferencias globales del sistema KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">KLineEdit</ulink></title>
<para>Una variante de <classname>QLineEdit</classname> con soporte para autocompletado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KComboBox">KComboBox</ulink></title>
<para>Una variante de <classname>QComboBox</classname> con soporte para autocompletado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEFontCombo">TDEFontCombo</ulink></title>
<para>Una lista desplegable para la selección de fuentes. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorCombo">KColorCombo</ulink></title>
<para>Una lista desplegable para la selección de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorButton">KColorButton</ulink></title>
<para>Un botón para la selección de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KURLCombo">KURLCombo</ulink></title>
<para>Una lista desplegable para la selección de nombres de archivos y URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/KURLRequester">KURLRequester</ulink></title>
<para>Una línea de edición para seleccionar nombres de archivos y URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KRuler">KRuler</ulink></title>
<para>Un widget de una regla. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink
url="kdeapi:tdeui/KAnimWidget">KAnimWidget</ulink></title>
<para>animaciones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KNumInput">KNumInput</ulink></title>
<para>Un widget para la entrada de números. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPasswordEdit">KPasswordEdit</ulink></title>
<para>Un widget para la entrada de contraseñas. </para>
</formalpara></listitem>

</itemizedlist>

<para>Diálogos - díalogos completos para la selección de archivos, colores y fuentes. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/KFileDialog">KFileDialog</ulink></title>
<para>Un diálogo de selección de archivos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorDialog">KColorDialog</ulink></title>
<para>Un diálogo de selección de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEFontDialog">TDEFontDialog</ulink></title>
<para>Un diálogo para la selección de fuentes. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/TDEIconDialog">TDEIconDialog</ulink></title>
<para>Un diálogo para la selección de iconos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KKeyDialog">KKeyDialog</ulink></title>
<para>Un diálogo para la edición de atajos de teclado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KEditToolBar">KEditToolBar</ulink></title>
<para>Un diálogo para la edición de barras de herramientas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KTipDialog">KTipDialog</ulink></title>
<para>Un diálogo para mostrar consejos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEAboutDialog">TDEAboutDialog</ulink></title>
<para>Un diálogo de información de la aplicación. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KLineEditDlg">KLineEditDlg</ulink></title>
<para>Un diálogo simple para la entrada de texto. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/KURLRequesterDlg">KURLRequesterDlg</ulink></title>
<para>Un diálogo simple para la entrada de URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KMessageBox">KMessageBox</ulink></title>
<para>Un diálogo para indicar errores y advertencias. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPasswordDialog">KPasswordDialog</ulink></title>
<para>Un diálogo para la entrada de contraseñas. </para>
</formalpara></listitem>

</itemizedlist>

<para>Acciones y entorno gráfico XML </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEAction">TDEAction</ulink></title>
<para>Abstracción de una acción que puede ser conectada a barras de menús y barras de herramientas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEActionCollection">TDEActionCollection</ulink></title>
<para>Un conjunto de acciones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KXMLGUIClient">KXMLGUIClient</ulink></title>
<para>Un fragmento de entorno gráfico que contiene una colección de acciones y un árbol DOM que representa su ubicación en el entorno gráfico. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeparts/KPartManager">KPartManager</ulink></title>
<para>Gestiona la activación de cliente de entorno gráfico XML. </para>
</formalpara></listitem>

</itemizedlist>

<para>Extensiones y componentes </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KLibrary">KLibrary</ulink></title>
<para>Representa una biblioteca de carga dinámica. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KLibrary">KLibLoader</ulink></title>
<para>Carga de bibliotecas compartidas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KLibFactory">KLibFactory</ulink></title>
<para>Factoría de objetos en las extensiones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KServiceType">KServiceType</ulink></title>
<para>Representa un tipo de servicio. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KService">KService</ulink></title>
<para>Representa un servicio. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KMimeType">KMimeType</ulink></title>
<para>Representa un tipo MIME. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KServiceTypeProfile">KServiceTypeProfile</ulink></title>
<para>Preferencias del usuario para asignación de tipos MIME. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KServiceTypeProfile">TDETrader</ulink></title>
<para>Consultas para servicios. </para>
</formalpara></listitem>

</itemizedlist>

</simplesect>

</chapter>



<chapter id="graphics">
<title>Gráficos</title>

<sect1 id="graphics-qpainter">
<title>Gráficos de bajo nivel con QPainter</title>

<simplesect id="qpainter-rendering">
<title>Procesado con QPainter</title>

<para>El model de gráficos de bajo nivel de Qt se basa en las capacidades proporcionadas por X11 y otros sitemas de ventanas para los que existen versiones de Qt. Pero también extiende las opciones mencionadas implementando características adicionales como transformaciones de tamaño arbitrario para textos y mapas de pixels. </para>

<para>La clase central para la realización de gráficos 2D en Qt es <ulink url="kdeapi:qt/QPainter">QPainter</ulink>. Puede dibujar en un <ulink url="kdeapi:qt/QPaintDevice">QPaintDevice</ulink>. Hay implementados tres dispositivos de pintura posibles: uno es <ulink url="kdeapi:qt/QWidget">QWidget</ulink>, que representa un widget de la pantalla. El segundo es <ulink url="kdeapi:qt/QPrinter">QPrinter</ulink> que representa una impresora y produce salida PostScript. El tercero es la clase <ulink url="kdeapi:qt/QPicture">QPicture</ulink>, que almacena comandos de dibujo y puede guardarlos en el disco para reproducirlos posteriormente. Un formato de almacenamiento posible para los comandos de dibujo es el estándar de W3C denominado SVG. </para>

<para>Por lo tanto, es posible reutilizar el código de procesado que se utiliza para mostrar un widget en su impresión posterior, con las mismas características soportadas. Obviamente, en la práctica, el código se utiliza en un contexto ligeramente distinto. El dibujo en un widget se realiza casi exclusivamente en el método paintEvent() de la clase del widget. </para>

<programlisting>void FooWidget::paintEvent()
{
    QPainter p(esto);
    // Configurar sistema de dibujo
    // Utilizar sistema de dibujo
}
</programlisting>

<para>Al dibujar en la impresora, hay que asegurarse de utilizar QPrinter::newPage() para terminar una página y comenzar la siguiente - algo que, naturalmente, no resulta relevante al dibujar en los widgets. Además, al imprimir, puede ser interesante utilizar la <ulink url="kdeapi:qt/QPaintDeviceMetrics">métrica del dispositivo</ulink> para computar las coordenadas. </para>

</simplesect>


<simplesect id="qpainter-transformations">
<title>Transformaciones</title>

<para>De forma predeterminada, al utilizar QPainter, este dibuja en el sistema de coordenadas natural del dispositivo utilizado. Esto significa, si usted dibuja una línea a lo largo del eje horizontal con una longitud de 10 unidades, que aparecerá como una línea horizontal con una longitud de 10 píxeles en la pantalla. Sin embargo, QPainter puede aplicar transformaciones de tamaño arbitrario antes de dibujar físicamente las formas y las curvas. Una transformación de tamaño asigna las coordenadas x e y de forma lineal a x' e y' de acuerdo con </para>

<mediaobject>
<imageobject><imagedata fileref="affine-general.png"/></imageobject>
</mediaobject>

<para>La matriz 3x3 de esta ecuación se puede establecer con QPainter::setWorldMatrix() y es de tipo <ulink url="kdeapi:qt/QWMatrix">QWMatrix</ulink>. Normalmente, esta es la matriz de identidad, es decir, m11 y m22 son uno, y el resto de parámetros son cero. Básicamente hay tres grupos diferentes de transformaciones: </para>

<itemizedlist>

<listitem><formalpara>
<title>Desplazamientos</title>
<para>Mueven todos los puntos de un objeto una cantidad determinada en alguna dirección. Una matriz de desplazamiento se puede obtener invocando el método m.translate(dx, dy) de una QWMatrix. Esto corresponde a la matriz </para>
</formalpara>

<mediaobject>
<imageobject><imagedata fileref="affine-translate.png"/></imageobject>
</mediaobject>

</listitem>

<listitem><formalpara>
<title>Escalado</title>
<para>Amplian o reducen las coordenadas de un objeto para hacerlo mayor o menor evitando la distorsión. Una transformación de escalado se puede aplicar a una QWMatrix invocando m.scale(sx, sy). Esto corresponde a la matriz </para>
</formalpara>

<mediaobject>
<imageobject><imagedata fileref="affine-scale.png"/></imageobject>
</mediaobject>

<para>Si se establece uno de los parámetros a un valor negativo, se puede conseguir una visión simétrica del sistema de coordenadas. </para>

</listitem>

<listitem><formalpara>
<title>Corte</title>
<para>Una distorsión del sistema de coordenadas con dos parámetros. Una transformación de corte se puede aplicar invocanza m.shear(sh, sv), correspondiente a la matriz </para>
</formalpara>

<mediaobject>
    <imageobject><imagedata fileref="affine-shear.png"/></imageobject>
</mediaobject>

</listitem>

<listitem><formalpara>
<title>Giro</title>
<para>Gira un objeto. Una transformación de giro se puede aplicar invocando m.rotate(alpha). Tenga en cuenta que el ángulo debe ser expresado en grados, y no como un ángulo matemático. La matriz correspondiente es </para>
</formalpara>

<mediaobject>
<imageobject><imagedata fileref="affine-rotate.png"/></imageobject>
</mediaobject>

<para>Fíjese en que un giro es equivalente a una combinación de escalado y corte. </para>

</listitem>

</itemizedlist>

<para>Aquí se muestran algunas imágenes que muestran el efecto de transformaciones elementales sobre nuestra mascota: </para>

<informaltable frame="none">
<tgroup cols="3">
<tbody>
<row>
<entry><mediaobject>
    <imageobject><imagedata fileref="konqi-normal.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="konqi-rotated.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="konqi-sheared.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
   <imageobject><imagedata fileref="konqi-mirrored.png"/></imageobject>
</mediaobject></entry>
</row>
<row>
<entry>a) Normal</entry>
<entry>b) Girado 30 grados</entry>
<entry>c) Corte a 0.4</entry>
<entry>d) Simétrico</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>Es posible combinar las transformaciones multiplicando matrices elementales. Tenga en cuenta que las operaciones entre matrices normalmente no son conmutables, y por lo tanto el efecto combinado de una concatenación depende del orden en el que las matrices hayan sido multiplicadas. </para>

</simplesect>


<simplesect id="qpainter-strokeattributes">
<title>Establecimiento de atributos de ajuste</title>

<para>Es posible modificar el procesado de líneas, curvas y bordes de polígonos estableciendo un pincel especial con QPainter::setPen(). El argumento de esta función es un objeto <ulink url="kdeapi:qt/QPen">QPen</ulink>. Las propiedades que almacena son estilo, color, estilo de unión y estilo de tope. </para>

<para>El estilo de pincel es un miembro de la enumeración <ulink url="kdeapi:qt/Qt#PenStyle-enum">Qt::PenStyle</ulink>. Puede tomar uno de los siguientes valores: </para>

<mediaobject>
    <imageobject><imagedata fileref="penstyles.png"/></imageobject>
</mediaobject>

<para>El estilo de unión es un miembro de la enumeración <ulink url="kdeapi:qt/Qt#PenJoinStyle-enum">Qt::PenJoinStyle</ulink>. Especifica cómo se debe dibujar la unión entre múltiples líneas que están conectadas unas con otras. Puede tomar uno de los siguientes valores: </para>

<informaltable frame="none">
<tgroup cols="3">
<tbody>
<row>
<entry><mediaobject>
    <imageobject><imagedata fileref="joinmiter.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="joinbevel.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="joinround.png"/></imageobject>
</mediaobject></entry>
</row>
<row>
<entry>a) MiterJoin</entry>
<entry>c) BevelJoin</entry>
<entry>b) RoundJoin</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>El estilo de tope es un miembro de la enumeración <ulink url="kdeapi:qt/Qt#PenCapStyle-enum">Qt::PenCapStyle</ulink>, y especifica cómo se deben dibujar los puntos finales de las líneas. Toma uno de los valores de la siguiente tabla: </para>

<informaltable frame="none">
<tgroup cols="3">
<tbody>
<row>
<entry><mediaobject>
    <imageobject><imagedata fileref="capflat.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="capsquare.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="capround.png"/></imageobject>
</mediaobject></entry>
</row>
<row>
<entry>a) FlatCap</entry>
<entry>b) SquareCap</entry>
<entry>c) RoundCap</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</simplesect>


<simplesect id="qpainter-fillattributes">
<title>Establecimiento de atributos de relleno</title>

<para>El estilo de relleno de los polígonos, círculos o rectángulos se puede modificar especificanto un tipo especial de brocha con QPainter::setBrush(). Esta función tiene un objeto <ulink url="kdeapi:qt/QBrush">QBrush</ulink> como argumento. Las brochas se pueden construir de cuatro maneras diferentes: </para>

<itemizedlist>
<listitem>
<para>QBrush::QBrush() - Crea una brocha que no rellena las figuras.</para>
</listitem>
<listitem>
<para>QBrush::QBrush(BrushStyle) - Crea una brocha negra con uno de los siguientes patrones mostrados a continuación.</para>
</listitem>
<listitem>
<para>QBrush::QBrush(const QColor &amp;, BrushStyle) - Crea una brocha de color con uno de los patrones mostrados a continuación.</para>
</listitem>
<listitem>
<para>QBrush::QBrush(const QColor &amp;, const QPixmap) - Crea una brocha de color con el patrón personalizado que se proporcione como segundo parámetro.</para>
</listitem>
</itemizedlist>

<para>Un estilo de brocha predeterminado se obtiene de la enumeración <ulink url="kdeapi:qt/Qt#BrushStyle-enum">Qt::BrushStyle</ulink>. Esta es una muestra de todos los patrones predefinidos: </para>

<mediaobject>
    <imageobject><imagedata fileref="brushstyles.png"/></imageobject>
</mediaobject>

<para>Una forma más avanzada de personalizar el comportamiento de la brocha es mediante la función QPainter::setBrushOrigin(). </para>

</simplesect>


<simplesect id="qpainter-color">
<title>Color</title>

<para>Los colores juegan un papel tanto al ajustar curvas como al rellenar figuras. En Qt, los colores están representados por la clase <ulink url="kdeapi:qt/QColor">QColor</ulink>. Qt no soporta características gráficas avanzadas como perfiles de color ICC y corrección de color. Los colores se construyen normalmente especificando sus componentes rojo, verde y azul, siguiendo el modelo RGB que utilizan los monitores para dibujar los pixels. </para>

<para>También es posible utilizar tono, saturación y valor. Esta representación (HSV) es la que se utiliza en el diálogo de color de Gtk, por ejemplo en GIMP. En este caso, el tono corresponde al ángulo en la rueda de color, mientras que la saturación corresponde a la distancia desde el centro de círuclo. El valor se puede elegir con un selector independiente. </para>

</simplesect>


<simplesect id="qpainter-paintsettings">
<title>Otros parámetros</title>

<para>Normalmente, al pintar en un dispositivo de pintura, los pixels que se dibujan reemplazan a los existentes anteriormente. Esto significa que si usted pinta ciertas regiones de uno color rojo y después pinta las mismas zonas con un color azul, únicamente será visible el color azul. El modelo de dibujo de Qt no soporta la transparencia, es decir, una forma de mezclar los colores principal y de fondo de un dibujo. Sin embargo, hay un método muy sencillo para combinar el primer plano y el fondo a través de operadores booleanos. El método QPainter::setRasterOp() establece el operador utilizado, que viene de la enumeración <ulink url="kdeapi:qt/Qt#RasterOp-enum">RasterOp</ulink>. </para>

<para>El predeterminado es CopyROP, que ignora el color de fondo. Otra elección popular es XorROP. Si dibuja una línea negra con este operador sobre una imagen en color, el área cubierta aparecerá invertida. Este efecto se utiliza, por ejemplo, para crear el borde de los cuadros de selección de los programas de manipulación de imágenes, y que se conoce como "ejército de hormigas". </para>

</simplesect>


<simplesect id="qpainter-primitives">
<title>Primitivas de dibujo</title>

<para>A continuación se muestra una lista de los elementos gráficos básicos soportados por QPainter. La mayoría van acompañados de versiones sobrecargadas que admiten un diferente número de argumentos. Por ejemplo, los métodos relacionados con rectácngulos normalmente admiten como argumentos un <ulink url="kdeapi:qt/QRect">QRect</ulink> o un conjunto de cuatro enteros. </para>

<itemizedlist>
<listitem>
<para>Dibujo de un único punto - drawPoint().</para>
</listitem>
<listitem>
<para>Dibujo de líneas - drawLine(), drawLineSegments() y drawPolyLine().</para>
</listitem>
<listitem>
<para>Dibujo y relleno de rectángulos - drawRect(), drawRoundRect(), fillRect() y eraseRect().</para>
</listitem>
<listitem>
<para>Dibujo y relleno de círculos, elipses o parte de ellos - drawEllipse(), drawArc(), drawPie y drawChord().</para>
</listitem>
<listitem>
<para>Dibujo y relleno de polígonos generales - drawPolygon().</para>
</listitem>
<listitem>
<para>Dibujo de curvas bezier - drawQuadBezier() [drawCubicBezier en Qt 3.0].</para>
</listitem>
</itemizedlist>

</simplesect>


<simplesect id="qpainter-pixmaps">
<title>Dibujo de mapas de pixels e imágenes</title>

<para>Qt proporciona dos clases muy diferentes para la representación de imágenes. </para>

<para><ulink url="kdeapi:qt/QPixmap">QPixmap</ulink> corresponde directamente a los objetos de mapas de pixels de X11. Los mapas de pixels son objetos del lado del servidor y pueden (en la mayoría de las tarjetas gráficas modernas) ser almacenadas directamente en la memoria de la tarjeta. Esto hace que sean <emphasis>muy</emphasis> eficientes para tranferir mapas de pixels a la pantalla. Los mapas de pixels también funcionan como los equivales de fuera de la pantalla de los widgets; la clase QPixmap es una subclase de QPaintDevice, por lo que es posible dibujarla con un QPainter. Las operaciones elementales de dibujo normalmente se ven aceleradas por los adaptadores gráficos modernos. Por lo tanto, una conducta muy habitual es la de utilizar mapas de pixels para trabajar con doble buffer. Esto significa, en vez de dibujar directamente sobre un widget, que sea crea un objeto de mapa de pixels temporal y se utiliza la función <ulink url="kdeapi:qt/QPaintDevice#bitBlt-1">bitBlt</ulink> para tranferir el mapa de pixels al widget. En casos de redibujados complejos, esto ayuda a evitar el efecto de parpadeo. </para>

<para>Por contra, el objeto <ulink url="kdeapi:qt/QImage">QImage</ulink> permanece en el lado del cliente. Su ventaja está en que proporciona acceso directo a los pixels de la imagen. Esto lo hace útil para la manipulación de imágenes, y operaciones como la carga y almacenamiento en disco (el método load() de QPixmap utiliza QImage en un paso intermedio). Por otro lado, dibujar una imagen en un widget es una operación con un consumo de recursos relativamente alto, ya que implica una transferencia al servidor X, lo que puede llevar algún tiempo, especialmente en imágenes grandes y servidores remotos. Dependiendo de la profundidad de color, la conversión de QImage a QPixmap puede requerir también un proceso de reducción del número de colores. </para>

</simplesect>


<simplesect id="qpainter-drawingtext">
<title>Dibujo de texto</title>

<para>Es posible dibujar texto con una de las variantes sobrecargadas del método QPainter::drawText(). De esta forma se dibuja una QString en un punto o en un rectángulo dado, utilizando la fuente establecida por QPainter::setFont(). También hay un parámetro que admite una combinación OR de algunos parámetros obtenidos de las enumeraciones <ulink url="kdeapi:qt/Qt#AlignmentFlags-enum">Qt::AlignmentFlags</ulink> y <ulink url="kdeapi:qt/Qt#TextFlags-enum">Qt::TextFlags</ulink> </para>

<para>A partir de la versión 3.0, Qt se encarga completamente de la disposición del texto incluso en los idiomas escritos de derecha a izquierda. </para>

<para>Una forma más avanzada de mostrar texto con formato es la clase <ulink url="kdeapi:qt/QSimpleRichText">QSimpleRichText</ulink>. Los objetos de esta clase se pueden construir a partir de un texto que utilice un subconjunto de etiquetas HTML, lo cual mejora el aspecto y puede proporcionar incluso tablas. El estilo del texto se puede personalizar utilizando un <ulink url="kdeapi/qt/QStyleSheet">QStyleSheet</ulink> (también se puede encontrar aquí la documentación de las etiquetas). Una vez que se ha construido el objeto de texto enriquecido, se puede dibujar sobre un widget u otro dispositivo de dibujo utilizando el método QSimpleRichText::draw(). </para>

</simplesect>

</sect1>


<sect1 id="graphics-qcanvas">
<title>Gráficos estructurados con QCanvas</title>

<para>QPainter ofrece un potente modelo de dibujo para realizar representaciones sobre widgets y mapas de pixels. Sin embargo, puede ser complicado de utilizar. Cada vez que un widget recibe un evento de dibujo, tiene que analizar la QPaintEvent::region() o la QPaintEvent::rect() que debe ser redibujada. También tiene que configurar un QPainter y dibujar todos los objetos que se superponen con ese área. Por ejemplo, imagine un programa de gráficos vectoriales que permite arrastrar y mover objetos como polígonos, círculos o grupos de ellos. Cada vez que uno de esos objetos se mueve un poco, el evento de movimiento del ratón de widget dispara un evento de dibujo para toda la zona cubierta por los objetos de las posiciones antigua y nueva. Calcular las operaciones de redibujado necesarias y realizarlas de forma eficientes puede resultar difícil, y también podría entrar en conflicto con las estructura orientada a objetos del código fuente del programa. </para>

<para>Como alternativa, Qt contiene la clase <ulink url="kdeapi:qt/QCanvas">QCanvas</ulink> en la que es posible colocar objetos gráficos como polígonos, texto y mapas de pixels. También es posible incluir elementos adicionales a través de una subclase de <ulink url="kdeapi:qt/QCanvasItem">QCanvasItem</ulink> o de una de sus subclases más especializadas. Un espacio de dibujo puede ser mostrado en la pantalla por uno o más widgets de la clase <ulink url="kdeapi:qt/QCanvas">QCanvasView</ulink> de la que hay que derivar subclases para manejar la interacción con el usuario. Qt se encarga de todas las operaciones de redibujado de los objetos en la vista, ya sean estas causadas por el widget mostrado, por nuevos objetos creados o modificados u otras razones. Al utilizar un doble búfer, estas operaciones se realizan con eficiencia y evitando el efecto parpadeo. </para>

<para>Los espacios de dibujo se pueden superponer. Este este caso, el que resultará visible depende el orden en el eje z al que hayan sido asignados mediante QCanvasItem::setZ(). Los elementos también pueden ser visibles o invisibles. También puede proporcionar un fondo para que sea dibujado "detrás" de todos los demás elementos. Para asociar eventos del ratón a los objetos del espacio de dibujo, existe el método QCanvas::collisions(), de devuelve una lista de elementos superpuestos en un punto dado. Aquí mostramos una instantánea de una vista de espacio de dibujo en acción: </para>

<mediaobject>
<imageobject><imagedata fileref="canvas.png"/></imageobject>
</mediaobject>

<para>En este caso, la malla está dibujada en el fondo. Además hay un elemento QCanvasText y un QCanvasPolygon violeta. La mariposa es un QCanvasPixmap. Tiene zonas transparentes, por lo que se pueden ver los demás objetos a través de ella. </para>

<para>Se puede encontrar un tutorial para el uso de QCanvas en el desarrollo de juegos basados en sprites <ulink url="http://zez.org/article/articleview/2/1/">aquí</ulink>. </para>

</sect1>


<sect1 id="graphics-qglwidget">
<title>Gráficos 3D con OpenGL</title>

<simplesect id="qglwidget-lowlevel">
<title>Interfaz de bajo nivel</title>

<para>El estándar de facto actual para la realización de gráficos 3D es <ulink url="http://www.opengl.org">OpenGL</ulink>. Se encuentran implementaciones de esta especificación en Microsoft Windows, Mac OS X y XFree86 y normalmente también está soportado en la aceleración por hardware de las tarjetas gráficas modernas. OpenGL en sí únicamente se ocupa del procesado en un área de un framebuffer a través de un <emphasis>contexto GL</emphasis> y no tiene ningún tipo de interacción con el entorno de desarrollo. </para>

<para>Qt ofrece el widget <ulink url="kdeapi:qt/QGLWidget">QGL Widget</ulink> que encapsula una ventana con un contexto GL asociado. Básicamente se utiliza realizando subclases y reimplementando algunos métodos. </para>

<itemizedlist>

<listitem><para>En vez de reimplementar paintEvent() y utilizar QPainter para dibujar el contenido de un widget, es mejor utilizar paintGL() y emplear comandos GL para procesar una escena. QLWidget se encargará de hacer que su contexto GL sea el activo antes de que se llame a paintGL(), y posteriormente volcará toda la información. </para></listitem>

<listitem><para>El método virtual initializeGL() se llama una vez antes de las primera invocaciones de resizeGL() o paintGL(). Esto se utiliza para la construcción de listas visuales para objetos y para iniciar el entorno. </para></listitem>

<listitem><para>En ver se reimplementar resizeEvent(), se utiliza resizeGL(). Sirve para establacer el modo vista de forma correcta. </para></listitem>

<listitem><para>En vez de llamar a update() cuando el estado de la escena haya cambiado (por ejemplo, si se realiza animación con un temporizador), debería llamar a updateGL(). Esto provocará el redibujado. </para></listitem>

</itemizedlist>

<para>En general, QGLWidget se comporta como cualquier otro widget, es decir, los eventos del ratón se procesan normalmente, se puede redimensionar el widget y combinarlo con otros en una vista. </para>

<mediaobject>
<imageobject><imagedata fileref="opengl.png"/></imageobject>
</mediaobject>

<para>Qt contiene algunos ejemplos del uso de QGLWidget en su ejemplo <literal>demo</literal>. Se puede encontrar una colección de tutoriales <ulink url="http://www.libsdl.org/opengl/intro.html">aquí</ulink>, y más información junto a una referencia de OpenGL está disponible en la <ulink url="http://www.opengl.org">página web de OpenGL</ulink>. </para>

</simplesect>


<simplesect id="qglwidget-highlevel">
<title>Interfaces de alto nivel</title>

<para>OpenGL es un interfaz de relativo bajo nivel para el trazado de gráficos en 3D. De la misma forma que QCanvas proporciona al programador un interfaz de alto nivel para tratar con detalle los objetos y sus propiedades, también hay interfaces de alto nivel para los gráficos en 3D. Uno de los más populares es Open Inventor. Una tecnología desarrolladoa originalmente por SGI, que hoy en día tiene una implementación de código abierto llamada <ulink url="http://www.coin3d.org">Coin</ulink>, complementada por un entorno de desarrollo para Qt llamado SoQt. </para>

<para>El concepto básico de Open Inventor es la <emphasis>escena</emphasis>. Es posible cargar una escena del disco y guardarla en un formato especial muy unido a <ulink url="http://www.vrml.org">VRML</ulink>. Una escena consta de una colección de objetos llamados <emphasis>nodos</emphasis>. Inventor proporciona una interesante colección de nodos reutilizables, como cubos, cilindros y mallas, además de fuentes de luz, materiales, cámaras, etc. Los nodos están representados por clases de C++ y pueden ser combinados y tratados como subclases. </para>

<para>Puede encontrar una introducción a Inventor <ulink url="http://www.motifzone.com/tmd/articles/OpenInventor/OpenInventor.html">aquí</ulink> (por regla general, es posible sustituir los métodos de SoXt descritos en el artículo por los de SoQt). </para>

</simplesect>

</sect1>

</chapter>



<chapter id="userinterface">
<title>Interfaz de usuario</title>

<sect1 id="userinterface-actionpattern">
<title>El patrón de acción</title>

<para></para>

</sect1>


<sect1 id="userinterface-xmlgui">
<title>Definición de menús y barras de herramientas en XML</title>

<simplesect id="xmlgui-intro">
<title>Introducción</title>

<para>Mientras que el <link linkend="userinterface-actionpattern">patrón de acción</link> permite encapsular acciones disparadas por el usuario en un objeto que puede ser "conectado" en cualquier punto de las barrás de menú o de herramientas, no resuelve por sí mismo el problema de construir los propios menús. En particular, es necesario construir los menús desplegables en el código C++ e insertar explícitamente las acciones en un cierto orden, teniendo en consideración la guía de estilo de las acciones estándar. Esto hace muy difícil que es usuario pueda personalizar los menús o modificar los accesos directos a su gusto, ya que debería modificar el código fuente. </para>

<para>Este problema se resuelve por medio de un conjunto de clases llamado <literal>XMLGUI</literal>. Básicamente separa las acciones (programadas en C++) de su aspecto en las barras de menú y herramientas (programadas en XML). Sin tener que modificar el código fuente, es posible personalizar los menús ajustando un archivo XML. Además, esto ayuda a asegurar que las acciones estándar (como <menuchoice><guimenu>Archivo</guimenu><guimenuitem>Abrir</guimenuitem></menuchoice> o <menuchoice><guimenu>Ayuda</guimenu><guimenuitem>Acerca de...</guimenuitem></menuchoice>) aparezcan en las ubicaciones sugeridas por la guía de estilo. XMLGUI es especialmente importante en los programas modulares, donde los elementos que aparecen en las barras de menú pueden varias en función de las extensiones instaladas. </para>

<para>La clase de KDE para las ventanas de primer nivel, <ulink url="kdeapi:tdeui/TDEMainWindow.html">TDEMainWindow</ulink> es heredera de <ulink url="kdeapi:tdeui/KXMLGUIClient.html">KXMLGUIClient</ulink> y, por lo tanto, soporta XMLGUI directamente. Todas las acciones creadas dentro deben tener como superior jerárquico un <literal>actionCollection()</literal> del cliente. Una llamada a <literal>createGUI()</literal> construirá el conjunto completo de menús y barras de herramientas definidos en el archivo XML de la aplicación (normalmente con el sufijo <literal>ui.rc</literal>). </para>

</simplesect>


<simplesect id="xmlgui-kviewexample">
<title>Un ejemplo: el menú de KView</title>

<para>A continuación tomamos como ejemplo el visor de imágenes de KDE <application>KView</application>. Tiene un archivo <literal>ui.rc</literal> llamado <filename>kviewui.rc</filename> que es instalado por orden de <filename>Makefile.am</filename> </para>

<programlisting>rcdir = $(kde_datadir)/kview
rc_DATA = kviewui.rc
</programlisting>

<para>Esto es un extracto de <filename>kviewui.rc</filename>. Para simplificar el ejemplo, mostramos únicamente la definición del menú <guimenu>Ver</guimenu>. </para>

<programlisting>&lt;!DOCTYPE kpartgui&gt;
&lt;kpartgui name="kview"&gt;
  &lt;MenuBar&gt;
    &lt;Menu name="view" &gt;
      &lt;Action name="zoom50" /&gt;
      &lt;Action name="zoom100" /&gt;
      &lt;Action name="zoom200" /&gt;
      &lt;Action name="zoomMaxpect" /&gt;
      &lt;Separator/&gt;
      &lt;Action name="fullscreen" /&gt;
    &lt;/Menu&gt;
  &lt;/MenuBar&gt;
&lt;/kpartgui&gt;
</programlisting>

<para>La parte de código correspondiente en C++ es: </para>

<programlisting>KStdAction::zoomIn    ( this, SLOT(slotZoomIn()), actionCollection() );
  KStdAction::zoomOut   ( this, SLOT(slotZoomOut()), actionCollection() );
  KStdAction::zoom      ( this, SLOT(slotZoom()), actionCollection() );
  new TDEAction           ( i18n("&amp;Half size"), ALT+Key_0, 
                          this, SLOT(slotHalfSize()), 
                          actionCollection(), "zoom50" );
  new TDEAction           ( i18n("&amp;Normal size"), ALT+Key_1,
                          this, SLOT(slotDoubleSize()), 
                          actionCollection(), "zoom100" );
  new TDEAction           ( i18n("&amp;Double size"), ALT+Key_2, 
                          this, SLOT(slotDoubleSize()), 
                          actionCollection(), "zoom200" );
  new TDEAction           ( i18n("&amp;Fill Screen"), ALT+Key_3, 
                          this, SLOT(slotFillScreen()), 
                          actionCollection(), "zoomMaxpect" );
  new TDEAction           ( i18n("Fullscreen &amp;Mode"), CTRL+SHIFT+Key_F, 
                          this, SLOT(slotFullScreen()), 
                          actionCollection(), "fullscreen" );
</programlisting>

<para>El menú <guimenu>Ver</guimenu> que aparece en el entorno gráfico resultante tiene este aspecto: </para>

<mediaobject>
<imageobject><imagedata fileref="kview-menu.png"/></imageobject>
</mediaobject>

<para>El archivo XML comienza con una declaración del tipo de documento. La DTD para kpartgui se puede encontrar en el código fuente de kdelib, en el archivo <filename>tdeui/kpartgui.dtd</filename>. El elemento más externo del archivo contiene el nombre de la instancia de la aplicación como atributo. También puede contener un número de versión con el formato "version=2". Esto le puede resultar útil cuando crea nuevas versiones de una aplicación con una estructura de menú distinta (por ejemplo, con más características). Si incrementa el número de versión del archivo <literal>ui.rc</literal>, KDE se asegura de que cualquier versión personalizada del archivo sea desechada y se use en su lugar el nuevo archivo. </para>

<para>La siguiente línea, <literal>&lt;MenuBar&gt;</literal>, contiene una declaración de una barra de menú. También puede insertar cualquier número de declaraciones <literal>&lt;ToolBar&gt;</literal> para crear algunas barras de herramientas. El menú contiene un submenú con el nombre «view». Este nombre ya está predefinido, por lo que verá una versión traducida de la palabra «View» en la captura de pantalla. Si declara sus propios submenús, tendrá que añadir su título explícitamente. Por ejemplo, <application>KView</application> tiene un submenú con el título «Image», que está declarado del siguiente modo: </para>

<programlisting>&lt;Menu name="image" &gt;
   &lt;text&gt;&amp;amp;Image&lt;/text&gt;
   ...
&lt;/Menu&gt;
</programlisting>

<para>En la infraestructura automake de KDE, estos títulos se extraen automáticamente y se ponen en el archivo <ulink url="tde-i18n-howto.html"><literal>.po</literal></ulink>, de modo que puedan ser tenidos en cuenta por los traductores. Tenga en cuenta que deberá escribir la marca de acceso rápido «&amp;» en modo compatible con XML (en la forma «&amp;amp;»). </para>

<para>Volvamos al ejemplo. El menú <guimenu>View</guimenu> de <application>KView</application> contiene varias acciones personalizadas: <literal>zoom50</literal>, <literal>zoom100</literal>, <literal>zoom200</literal>, <literal>zoomMaxpect</literal> y <literal>fullscreen</literal>, declarados mediante un elemento <literal>&lt;Action&gt;</literal>. El separador de las capturas de pantalla corresponde al elemento <literal>&lt;Separator&gt;</literal>. </para>

<para>Notará que algunos elementos del menú no poseen su correspondiente entrada en el archivo XML. Se trata de las <emphasis>acciones estándar</emphasis>. Las acciones estándar son creadas por la clase <ulink url="kdeapi:tdeui/KStdAction.html">KStdAction</ulink>. Cuando cree estas acciones en su aplicación (como las del anterior ejemplo en C++ ), se insertarán de forma automática en una posición preestablecida, y posiblemente con un icono y un acceso rápido. Puede buscar estas posiciones en el archivo <filename>tdeui/ui_standards.rc</filename> en el código fuente de tdelibs. </para>

</simplesect>


<simplesect id="xmlgui-konqexample">
<title>Un ejemplo: las barras de herramientas de Konqueror</title>

<para>Para ilustrar la discusión sobre las barras de herramientas, veremos la definición de la interfaz gráfica de <application>Konqueror</application>. Este trozo de código define la barra de dirección, que contiene el campo de entrada para introducir una URL. </para>

<programlisting>&lt;ToolBar name="locationToolBar" fullWidth="true" newline="true" &gt;
  &lt;text&gt;Location Toolbar&lt;/text&gt;
  &lt;Action name="clear_location" /&gt;
  &lt;Action name="location_label" /&gt;
  &lt;Action name="toolbar_url_combo" /&gt;
  &lt;Action name="go_url" /&gt;
&lt;/ToolBar&gt;
</programlisting>

<para>Lo primero que notamos es que hay muchos más atributos que para las barras de menú, como: </para>

<itemizedlist>

<listitem><para><literal>fullWidth</literal>: Comunica a XMLGUI que la barra de herramientas tiene el mismo ancho que la ventana de nivel superior. Si tiene el valor «false», la barra de herramientas solo ocupará el espacio que necesite, y el resto de barras de herramientas se colocará en la misma fila. </para></listitem>

<listitem><para><literal>newline</literal>: Esto está relacionado con la opción anterior. Si «newline» es «true», la barra de herramientas se coloca al comienzo de una nueva fila. En caso contrario podrá ser colocada en la misma fila que la barra de herramientas previa. </para></listitem>

<listitem><para><literal>noEdit</literal>: Normalmente, el usuario puede personalizar las barras de herramientas, por ejemplo en <menuchoice><guimenu>Preferencias</guimenu><guimenuitem>Configurar barras de herramientas</guimenuitem></menuchoice> en <application>Konqueror</application>. Si se cambia el valor de esta opción a «true», la barra de herramientas será marcada como no editable. Esto es importante para las barras de herramientas que se rellenan con elementos en tiempo de ejecución, como la barra de marcadores de <application>Konqueror</application>. </para></listitem>

<listitem><para><literal>iconText</literal>: Hace que la interfaz gráfica XML muestre el texto de la acción junto al icono. Normalmente, el texto solo se muestra como ayuda emergente cuando el cursor del ratón permanece sobre el icono durante un corto espacio de tiempo. Los valores posibles para este atributo son «iconolny» (muestra solo el icono), «textonly» (muestra solo el texto), «icontextright» (muestra el texto a la derecha del icono) e «icontextbottom» (muestra el texto debajo del icono). </para></listitem>


<listitem><para><literal>hidden</literal>: Si vale «true», la barra de herramientas no será visible inicialmente y tendrá que ser activada mediante algún elemento del menú. </para></listitem>


<listitem><para><literal>position</literal>: El valor predeterminado para este atributo es «top», y significa que la barra de herramientas será posicionada bajo la barra de menú. Para los programas con muchas herramientas, como los programas de gráficos, puede ser interesante sustituir este valor por «left», «right» o «bottom». </para></listitem>

</itemizedlist>

</simplesect>


<simplesect id="xmlgui-dynamical">
<title>Menús dinámicos</title>

<para>Obviamente, un archivo XML solo puede contener una descripción estática de una interfaz de usuario. A menudo, existen menús que se modifican en tiempo real. Por ejemplo, el menú <guimenu>Dirección</guimenu> de <application>Konqueror</application> contiene un conjunto de elementos <guimenuitem>Abrir con X</guimenuitem> con las aplicaciones capaces de cargar un archivo con un tipo MIME concreto. Cada vez que cambia el documento mostrado, se modifica la lista de estos elementos del menú. XMLGUI está preparado para manejar estos casos mediante el uso de <emphasis>listas de acciones</emphasis>. Una lista de acciones se declara como un único elemento en el archivo XML, pero consta de varias acciones que se conectan al menú en tiempo de ejecución. El ejemplo anterior se implementa con la siguiente declaración en el archivo XML de <application>Konqueror</application>: </para>

<programlisting>&lt;Menu name="file"&gt;
  &lt;text&gt;&amp;amp;Location&lt;/text&gt;
  ...
  &lt;ActionList name="openwith"&gt;
  ...
&lt;/Menu&gt;
</programlisting>

<para>La función <function>KXMLGUIClient::plugActionList()</function> se usará para añadir acciones a ser mostradas, mientras que la función <function>KXMLGuiClient::unplugActionList()</function> eliminará todas las acciones conectadas. La rutina responsable de la actualización es semejante a la siguiente: </para>

<programlisting>void MainWindow::updateOpenWithActions()
{
    unplugActionList("openwith");
    openWithActions.clear();
    for ( /* repetir sobre los servicios importantes */ ) {
        TDEAction *action = new TDEAction( ...);
        openWithActions.append(action);
    }
    plugActionList("openwith", openWithActions);
}
</programlisting>

<para>Tenga en cuenta que, al contrario que las acciones estáticas, las que se crean aquí <emphasis>no</emphasis> están construidas con la colección de acciones como objeto padre, por lo que usted será el responsable de eliminarlas. El modo más sencillo de realizar esto consiste en usar <literal>openWithActions.setAutoDelete(true)</literal>, como en el ejemplo anterior. </para>

</simplesect>


<simplesect id="xmlgui-contextmenus">
<title>Menús de contexto</title>

<para>Los ejemplos anteriores solo trataban de casos en los que se creaba una barra de menú y barras de herramientas para la ventana principal. En estos casos, los procesos que construyen estos contenedores están completamente ocultos en la llamada a <function>createGUI()</function> (excepto cuando hay que crear contenedores personalizados). De todos modos, existen casos en los que se necesita construir otros contenedores y llenarlos con definiciones de interfaz gráfica procedentes de un archivo XML. Uno de estos ejemplos son los menús de contexto. Para obtener un puntero a un menú de contexto, necesitará pedírselo a la «fábrica» del cliente: </para>

<programlisting>void MainWindow::popupRequested()
{
    QWidget *w = factory()->container("context_popup", this);
    QPopupMenu *popup = static_cast&lt;QPopupMenu *&gt;(w);
    popup->exec(QCursor::pos());
}
</programlisting>

<para>El método <function>KXMLGUIFactory::container()</function> usado arriba comprueba si puede encontrar un contenedor con un nombre dado en el archivo XML. De este modo, una posible definición podría ser: </para>

<programlisting>...
&lt;Menu name="context_popup"&gt;
  &lt;Action name="file_add"/&gt;
  &lt;Action name="file_remove"/&gt;
&lt;/Menu&gt;
...
</programlisting>

</simplesect>

</sect1>


<sect1 id="help">
<title>Proporcionando ayuda en línea</title>

<para>Hacer que un programa sea fácil e intuitivo de manejar requiere de un amplio abanico de utilidades que normalmente se denominan ayuda en línea. La ayuda en línea tiene varios objetivos (a veces conflictivos): por un lado, debe proporcionar al usuario respuestas a la pregunta «¿Cómo puedo hacer una determinada tarea?», y por otro, debe ayudar al usuario a explorar la aplicación y a encontrar características que aún no conocía. Es importante reconocer que esto solo se puede conseguir ofreciendo diversos niveles de ayuda: </para>

<itemizedlist>

<listitem><para>Las ayudas emergentes son pequeñas etiquetas que aparecen sobre los elementos de la interfaz de usuario cuando el cursor del ratón permanece sobre ellos durante un corto espacio de tiempo. Son especialmente importantes para las barras de herramientas, donde un icono no siempre resulta suficiente para explicar el propósito de un botón. </para></listitem>

<listitem><para>La ayuda «¿Qué es esto?» consiste normalmente en una larga y rica explicación sobre un «widget» o sobre un elemento del menú. También es algo más lenta de usar. En los diálogos, se puede invocar de dos formas: bien pulsando <keycombo><keycap>Mayúsculas</keycap><keycap>F1</keycap></keycombo>, o pulsando con el ratón sobre el símbolo de interrogación en la barra de título (aunque esto depende de la configuración del gestor de ventanas que esté usando). El puntero del ratón cambia entonces a una flecha con un signo de interrogación, y la ventana de ayuda aparecerá cuando el usuario pulse sobre algún elemento de la interfaz. En los elementos de los menús, la ayuda «¿Qué es esto?» se activa normalmente mediante un botón de la barra de herramientas que contiene una flecha y un signo de interrogación. </para></listitem>

<listitem><para>El problema de esta aproximación es que el usuario no puede ver cuándo un «widget» proporciona ayuda o no. Si un usuario activa el botón con el signo de interrogación y no obtiene ninguna ventana de ayuda al pulsar sobre un elemento de la interfaz de usuario, probablemente se sentirá frustrado. </para>

<para>La ventaja de las ventanas de ayuda «¿Qué es esto?» tal y como las proporcionan Qt y KDE consiste en que pueden contener <ulink url="kdeapi:qt/QStyleSheet">texto enriquecido</ulink>, es decir, que pueden contener diferentes tipos de letra, negrita, cursiva, e incluso imágenes y tablas. </para>

<para>Un ejemplo de la ayuda «¿Qué es esto?»: </para>

<mediaobject>
<imageobject><imagedata fileref="whatsthis.png"/></imageobject>
</mediaobject>

</listitem>

<listitem><para>Finalmente, cada programa debe tener un manual. El manual se visualiza normalmente en <application>KHelpCenter</application> tras activar la opción correspondiente del menú <guimenu>Ayuda</guimenu>. Esto significa que aparecerá una aplicación completa adicional que distraerá al usuario de su trabajo. Como consecuencia, consultar el manual solo debería ser necesario si otras facilidades, como las ayudas emergentes y las ayudas «¿Qué es esto?», no resultan suficientes. Por supuesto, un manual tiene la ventaja de que no explica aspectos aislados de la interfaz de usuario. En cambio, puede explicar aspectos de la aplicación en un contexto más amplio. Los manuales para KDE están escritos mediante el uso del lenguaje de etiquetas <ulink url="http://i18n.kde.org">DocBook</ulink>. </para></listitem>

</itemizedlist>

<para>Desde el punto de vista del programador, Qt proporciona una API para ayuda en línea fácil de usar. Para asignar una ayuda emergente a un widget, utilice la clase <ulink url="kdeapi:qt/QToolTip">QToolTip</ulink>. </para>

<programlisting>QToolTip::add(w, i18n("Este widget realiza alguna acción."))
</programlisting>

<para>Si las barras de menú y de herramientas han sido creadas usando el <ulink url="actionpattern.html">patrón de acciones</ulink>, la cadena usada como ayuda emergente procede el primer argumento del constructor de <ulink url="kdeapi:tdeui/TDEAction.html">TDEAction</ulink>: </para>

<programlisting>action = new TDEAction(i18n("&amp;Delete"), "editdelete", 
                     SHIFT+Key_Delete, actionCollection(), "del")
</programlisting>

<para>Aquí también es posible asignar un texto para que se muestre en la barra de estado cuando se seleccione el correspondiente elemento del menú. </para>

<programlisting>action->setStatusText(i18n("Deletes the marked file"))
</programlisting>

<para>La API para la ayuda «¿Qué es esto?» es muy similar. En los diálogos, utilice el siguiente código: </para>

<programlisting>QWhatsThis::add(w, i18n("&lt;qt&gt;This demonstrates &lt;b&gt;Qt&lt;/b&gt;'s"
                        " rich text engine.&lt;ul&gt;"
                        "&lt;li&gt;Foo&lt;/li&gt;"
                        "&lt;li&gt;Bar&lt;/li&gt;"
                        "&lt;/ul&gt;&lt;/qt&gt;"))
</programlisting>

<para>Para los elementos del menú, utilice </para>

<programlisting>action->setWhatsThis(i18n("Deletes the marked file"))
</programlisting>

<para>La invocación de <application>KHelpCenter</application> está encapsulada en la clase <ulink url="kdeapi:tdecore/TDEApplication">TDEApplication</ulink>. Para mostrar el manual de su aplicación, use </para>

<programlisting>kapp->invokeHelp()
</programlisting>

<para>Esto muestra la primera página con la tabla de contenidos. Cuando solo quiera mostrar cierta sección del manual, puede proporcionar un argumento adicional a la función <function>invokeHelp()</function> con la etiqueta a la que debe saltar el navegador. </para>

</sect1>

</chapter>



<chapter id="components">
<title>Componentes y servicios</title>

<sect1 id="components-services">
<title>Servicios de KDE</title>

<simplesect id="services-whatarekdeservices">
<title>¿Qué son los servicios de KDE?</title>

<para>La noción de <emphasis>servicio</emphasis> es un concepto central de la arquitectura modular de KDE. No existe una implementación técnica estricta conectada a este término (los servicios pueden ser extensiones en la forma de bibliotecas compartidas, o programas controlados mediante <ulink url="dcop.html">DCOP</ulink>. Al ser declarado de cierto <emphasis>tipo de servicio</emphasis>, promete implementar ciertos APi o características. En términos de C++, se puede pensar que un tipo de servicio es una clase abstracta, y que un servicio es una implementación de esta interfaz. </para>

<para>La ventaja de esta separación es clara. Una aplicación que utilice un tipo de servicio no tiene que conocer nada sobre sus posibles implementaciones. Solo tiene que usar el API asociado al tipo de servicio. De este modo, el servicio usado se puede cambiar sin afectar a la aplicación. Además, el usuario puede configurar qué servicios prefiere para ciertas características. </para>

<para>Algunos ejemplos: </para>

<itemizedlist>

<listitem><para>El motor de visualización HTML usado en <application>Konqueror</application> es un componente que se puede integrar y que implementa los tipos de servicio <literal>KParts/ReadOnlyPart</literal> y <literal>Browser/View</literal>. </para></listitem>
<listitem><para>En la rama HEAD de <application>KDevelop</application>, una gran parte de la funcionalidad está empaquetada en extensiones con el tipo de servicio <literal>KDevelop/Part</literal>. Durante el inicio se cargan todos los servicios de este tipo, de modo que pueda extender el IDE de una manera muy flexible. </para></listitem>
<listitem><para>En la vista de iconos, <application>Konqueror</application> muestra (si están activadas) miniaturas de los archivos de imágenes, páginas HTML, PDF y texto. Esta característica se puede extender. Si desea mostrar previsualizaciones de sus propios archivos de datos mediante algún tipo MIME, puede implementar un servicio con el tipo de servicio <classname>ThumbCreator</classname>. </para></listitem>

</itemizedlist>

<para>Obviamente, un servicio no se caracteriza únicamente por los tipos de servicio que implementa, sino también por algunas <emphasis>propiedades</emphasis>. Por ejemplo, ThumCreator no solo implementa la clase C++ con el tipo <classname>ThumbCreator</classname>, sino que también posee una lista de tipos MIME de los que es responsable. De modo similar, las partes de KDevelop tienen como propiedad el lenguaje de programación que soportan. Cuando una aplicación solicita un tipo de servicio, también puede listar restricciones de las propiedades del servicio. En el ejemplo anterior, cuando KDevelop carga las extensiones para un proyecto Java, solicita únicamente las extensiones que tienen Java como propiedad de lenguaje de programación. Para este propósito, KDE contiene un <emphasis>trader</emphasis> semejante a CORBA con un complejo lenguaje de consultas. </para>

</simplesect>


<simplesect id="services-definingservicetypes">
<title>Definición de tipos de servicios</title>

<para>Los nuevos tipos de servicio se añaden instalando una descripción en la carpeta <filename>TDEDIR/share/servicetypes</filename>. En un entorno automake, esto se puede realizar con el siguiente fragmento de <filename>Makefile.am</filename>: </para>

<programlisting>kde_servicetypesdir_DATA = tdeveloppart.desktop
EXTRA_DIST = $(kde_servicetypesdir_DATA)
</programlisting>

<para>La definición <filename>tdeveloppart.desktop</filename> de una parte <application>KDevelop</application> es similar a lo siguiente: </para>

<programlisting>[Desktop Entry]
Type=ServiceType
X-TDE-ServiceType=KDevelop/Part
Name=KDevelop Part

[PropertyDef::X-KDevelop-Scope]
Type=QString

[PropertyDef::X-KDevelop-ProgrammingLanguages]
Type=QStringList

[PropertyDef::X-KDevelop-Args]
Type=QString
</programlisting>

<para>Además de las entradas usuales, este ejemplo demuestra cómo declarar que un servicio posee algunas propiedades. Cada definición de propiedad corresponde a un grupo <literal>[PropertyDef::name]</literal> en el archivo de configuración. En este grupo, la entrada <literal>Type</literal> declara el tipo de la propiedad. Los tipos posibles son cualquier cosa que se pueda almacenar en un <ulink url="kdeapi:qt/QVariant">QVariant</ulink>. </para>

</simplesect>


<simplesect id="services-defininglibraryservices">
<title>Definición de servicios de bibliotecas compartidas</title>

<para>Las definiciones de servicios se guardan en la carpeta <filename>TDEDIR/share/services</filename>: </para>

<programlisting>kde_servicesdir_DATA = kdevdoxygen.desktop
EXTRA_DIST = $(kde_servicesdir_DATA)
</programlisting>

<para>El contenido del siguiente archivo de ejemplo <filename>kdevdoxygen.desktop</filename> define la extensión <literal>KDevDoxygen</literal> con el tipo de servicio <literal>KDevelop/Part</literal>: </para>

<programlisting>[Desktop Entry]
Type=Service
Comment=Doxygen
Name=KDevDoxygen
ServiceTypes=KDevelop/Part
X-TDE-Library=libkdevdoxygen
X-KDevelop-ProgrammingLanguages=C,C++,Java
X-KDevelop-Scope=Project
</programlisting>

<para>Aparte de las declaraciones usuales, una entrada importante es <literal>X-TDE-Library</literal>. Contiene el nombre de la biblioteca «libtool» (sin la extensión <literal>.la</literal>). También fija (mediante el prefijo <literal>init_</literal>) el nombre de los símbolos exportados en la biblioteca que devuelven una «fábrica de objetos». En el ejemplo anterior, la biblioteca debe contener la siguiente función: </para>

<programlisting>extern "C" {
    void *init_libkdevdoxygen()
    {
        return new DoxygenFactory;
    }
};
</programlisting>

<para>El tipo de la clase fábrica <classname>DoxygenFactory</classname> depende del tipo de servicio específico que implementa el servicio. En nuestro ejemplo de una extensión para KDevelop, la fábrica debe ser del tipo <classname>KDevFactory</classname> (que deriva de <classname>KLibFactory</classname>). Otros ejemplos más comunes son <ulink url="kdeapi:tdeparts/KParts::Factory">KParts::Factory</ulink> que debe producir objetos <ulink url="kdeapi:tdeparts/KParts::ReadOnlyPart">KParts::ReadOnlyPart</ulink>, o, en muchos casos, <ulink url="kdeapi:tdecore/KLibFactory">KLibFactory</ulink>. </para>

</simplesect>


<simplesect id="services-usinglibraryservices">
<title>Uso de servicios de bibliotecas compartidas</title>

<para>Para poder usar un servicio de biblioteca compartida en una aplicación, necesita obtener un objeto <ulink url="kdeapi:tdeio/KService.html">KService</ulink> que lo represente. Esto se discute en la <ulink url="mime.html">sección sobre tipos MIME</ulink> (y en una sección sobre el «trader» pendiente de escribir). </para>

<para>Una vez que disponga de un objeto <classname>KService</classname>, solo necesita cargar la biblioteca y obtener un puntero a su objeto fábrica: </para>

<programlisting>KService *service = ...
QString libName = QFile::encodeName(service->library());
KLibFactory *factory = KLibLoader::self()->factory(libName);
if (!factory) {
    QString name = service->name();
    QString errorMessage = KLibLoader::self()->lastErrorMessage();
    KMessageBox::error(0, i18n("There was an error loading service %1.\n"
                               "The diagnostics from libtool is:\n%2")
                          .arg(name).arg(errorMessage);
}
</programlisting>

<para>A partir de este momento, el procedimiento a seguir depende de nuevo del tipo de servicio. Para las extensiones genéricas, puede crear objetos con el método <ulink url="kdeapi:tdecore/KLibFactory.html#ref3">KLibFactory::create()</ulink>. Para KParts, debe moldear el puntero de la fábrica al tipo más específico KParts::Factory y usar su método create(): </para>

<programlisting>if (factory->inherits("KParts::Factory")) {
    KParts::Factory *partFactory = static_cast&lt;KParts::Factory*&gt;(factory);
    QObject *obj = partFactory->createPart(parentWidget, widgetName, 
                                           parent, name, "KParts::ReadOnlyPart");
    ...
} else {
    cout &lt;&lt; "El servicio no implementa la fábrica correcta" &lt;&lt; endl;
}
</programlisting>

</simplesect>


<simplesect id="services-definingdcopservices">
<title>Definición de servicios DCOP</title>

<para>Un servicio DCOP se implementa normalmente como un programa que se arranca cuando es necesario y que luego entra en un bucle para escuchar conexiones DCOP. El programa puede ser interactivo, pero también puede funcionar completa o parcialmente como un «demonio» en segundo plano sin que el usuario lo note. Un ejemplo de este tipo de «demonio» es <literal>tdeio_uiserver</literal>, que implementa la interacción del usuario como un diálogo de progreso en la biblioteca TDEIO. La ventaja de este tipo de «demonio» centralizado en este contexto radica en que, por ejemplo, los progresos de descarga de varios archivos distintos se pueden mostrar en una única ventana, incluso si todas las descargas se iniciaron desde aplicaciones diferentes. </para>

<para>Un servicio DCOP se define de un modo distinto a como se hace con un servicio de biblioteca compartida. Por supuesto, no especifica una biblioteca, sino un ejecutable. Además, los servicios DCOP no contienen una línea <literal>ServiceType</literal>, debido a que suelen ser iniciados por su nombre. También contienen las dos líneas siguientes como propiedades adicionales: </para>

<para><literal>X-DCOP-ServiceType</literal> especifica el modo en que se inicia el servicio. El valor <literal>Unique</literal> indica que el servicio no se debe iniciar más de una vez. Esto significa que si trata de iniciar este servicio, por ejemplo mediante <ulink url="kdeapi:tdecore/TDEApplication.html#startServiceByName">TDEApplication::startServiceByName()</ulink>, KDE comprueba si ya estaba registrado en DCOP. En caso afirmativo, usa el servicio que está en ejecución. Si todavía no estaba registrado, KDE lo iniciará y esperará hasta que esté registrado. De este modo puede enviar llamadas DCOP al servicio inmediatamente. En tal caso, el servicio debe implementarse como <ulink url="kdeapi:tdecore/KUniqueApplication.html">KUniqueApplication</ulink>. </para>

<para>El valor <literal>Multi</literal> para <literal>X-DCOP-ServiceType</literal> indica que pueden coexistir múltiples instancias del servicio, de modo que cada intento de iniciar el servicio creará un nuevo proceso. Como última posibilidad, también puede usar el valor <literal>None</literal>. En este caso, el inicio del servicio no esperará a estar registrado en DCOP. </para>

<para><literal>X-TDE-StartupNotify</literal> debe ser establecido normalmente como <literal>false</literal>. En caso contrario, cuando se inicie el programa, la barra de tareas mostrará una notificiación de lanzamiento o, dependiendo de las preferencias del usuario, se modificará el cursor. </para>

<para>Esta es la definición de <literal>tdeio_uiserver</literal>: </para>

<programlisting>[Desktop Entry]
Type=Service
Name=tdeio_uiserver
Exec=tdeio_uiserver
X-DCOP-ServiceType=Unique
X-TDE-StartupNotify=false
</programlisting>

</simplesect>


<simplesect id="services-usingdcopservices">
<title>Uso de servicios DCOP</title>

<para>Un servicio DCOP comienza con uno de entre varios métodos en la clase TDEApplication: </para>

<programlisting>DCOPClient *client = kapp->dcopClient();
client->attach();
if (!client->isApplicationRegistered("tdeio_uiserver")) {
    QString error;
    if (TDEApplication::startServiceByName("tdeio_uiserver", QStringList(), &amp;error))
        cout &lt;&lt; "El inicio de kioserver ha fallado con el mensaje " &lt;&lt; error &lt;&lt; endl;
}
...
QByteArray data, replyData;
QCString replyType;
QDataStream arg(data, IO_WriteOnly);
arg &lt;&lt; true;
if (!client->call("tdeio_uiserver", "UIServer", "setListMode(bool)", 
                  data, replyType, replyData))
    cout &lt;&lt; "Ha fallado la llamada a tdeio_uiserver" &lt;&lt; endl;
...
</programlisting>

<para>Tenga en cuenta que el ejemplo de llamada DCOP que se proporciona aquí usa ordenación de argumentos. A menudo deseará usar una plantilla generada por «dcopidl2cpp» en su lugar, porque es mucho más simple y menos propensa a errores. </para>

<para>En el ejemplo propuesto, el servicio se inició «por nombre»; es decir, el primer argumento de <function>TDEApplication::startServiceByName()</function> es el nombre que aparece en la línea <literal>Name</literal> del archivo «desktop». Una alternativa consiste en usar <function>TDEApplication::startServiceByDesktopName()</function>, que toma el nombre del archivo «desktop» como argumento (en este caso, <literal>«tdeio_uiserver.desktop»</literal>). </para>

<para>Todas estas llamadas tienen una lista de URL como segundo parámetro, que se proporciona al servicio en la línea de comando. El tercer argumento es un puntero a una clase <classname>QString</classname>. Si el inicio del servicio falla, este argumento contendrá un mensaje de error traducido. </para>

</simplesect>

</sect1>


<sect1 id="components-mime">
<title>Tipos MIME</title>

<simplesect id="mime-whataremimetypes">
<title>¿Qué son los tipos MIME?</title>

<para>Los tipos MIME se utilizan para describir el tipo de contenido de los archivos o de segmentos de datos. Al principio fueron introducidos para permitir el envío de archivos de imágenes, sonidos, etc., por correo electrónico (MIME significa «Multipurpose Internet Mail Extensions», «extensiones de correo Internet multipropósito» en español). Más tarde, este sistema también fue utilizado por los navegadores web para determinar cómo presentar los datos enviados al usuario por un servidor web. Por ejemplo, una página HTML posee el tipo MIME «text/html», y un archivo postscript, «application/postscript». En KDE, este concepto se usa en varios lugares: </para>

<itemizedlist>

<listitem><para>En la vista de iconos de <application>Konqueror</application>, los archivos se representan por iconos. Cada tipo MIME tiene asociado su propio icono. </para></listitem>

<listitem><para>Cuando pulse sobre un icono de archivo o sobre su nombre en <application>Konqueror</application>, el archivo será mostrado en una vista empotrada, o se abrirá una aplicación asociada con su tipo de archivo. </para></listitem>

<listitem><para>Cuando arrastra y suelta varios datos de una aplicación a otra (o dentro de la misma aplicación), el objetivo donde se sueltan puede decidir aceptar solo ciertos tipos de datos. Aún más, manejará datos de imágenes de un modo distinto a como maneja datos de texto. </para></listitem>

<listitem><para>Los datos del Portapapeles poseen un tipo MIME. Tradicionalmente, los programas de X solo manejan mapas de píxeles y textos, pero con Qt no existen restricciones sobre los tipos de datos. </para></listitem>

</itemizedlist>

<para>De los ejemplos anteriores se deduce que la manipulación de tipos MIME es algo complejo. En primer lugar, es necesario establecer una correspondencia entre los nombres de archivo y los tipos MIME. KDE va un paso más lejos al permitir correspondencias incluso entre contenido de archivos y tipos MIME para aquellos casos en los que no se dispone de un nombre de archivo. En segundo lugar, es necesario establecer una correspondencia entre tipos MIME y aplicaciones y bibliotecas que puedan visualizar o editar un archivo de cierto tipo, o crear una imagen en miniatura para él. </para>

<para>Existen diversas API para deducir el tipo MIME de datos o archivos. En general, existe una cierta compensación entre velocidad y fiabilidad que debe realizar. Puede encontrar el tipo de un archivo examinando solo su nombre de archivo (es decir, su extensión, en la mayoría de los casos). Por ejemplo, un archivo <filename>nombre.jpg</filename> es normalmente de tipo «image/jpeg». Pero no es fiable en los casos en los que se ha eliminado la extensión, donde tendrá que examinar el contenido del archivo. Por supuesto, se trata de un proceso más lento, especialmente para los archivos que tienen que ser descargados vía HTTP en primer lugar. Este método dependiente del contenido está basado en el archivo <filename>TDEDIR/share/mimelnk/magic</filename>, por lo que resulta difícil de extender. Pero, en general, la información de tipo MIME se puede facilitar al sistema de forma rápida instalando un archivo <literal>.desktop</literal>, con lo que estará disponible de forma eficiente y conveniente para todas las bibliotecas de KDE. </para>

</simplesect>


<simplesect id="mime-definingmimetypes">
<title>Definición de tipos MIME</title>

<para>Definamos un tipo MIME <literal>«application/x-foo»</literal> para nuestro programa <application>foobar</application>. Para este fin, deberá escribir un archivo <filename>foo.desktop</filename> e instalarlo en <filename>TDEDIR/share/mimelnk/application</filename> (que es su ubicación usual, aunque puede diferir entre distribuciones). Esto se consigue añadiendo lo siguiente al archivo <filename>Makefile.am</filename>: </para>

<programlisting>mimedir = $(kde_mimedir)/application
mime_DATA = foo.desktop
EXTRA_DIST = $(mime_DATA)
</programlisting>

<para>El archivo <filename>foo.desktop</filename> debería ser similar al siguiente: </para>

<programlisting>[Desktop Entry]
Type=MimeType
MimeType=application/x-foo
Icon=fooicon
Patterns=*.foo;
DefaultApp=foobar
Comment=Foo Data File
Comment[es]=Archivo de datos de ejemplo
</programlisting>

<para>La entrada <literal>Comment</literal> debe ser traducida. Como el archivo <filename>.desktop</filename> especifica un icono, también debe instalar un icono <filename>fooicon.png</filename> que represente al archivo, por ejemplo, en <application>Konqueror</application>. </para>

<para>En las bibliotecas de KDE, este tipo de definición se mapea a una instancia de la clase <ulink url="kdeapi:tdeio/KMimeType.html">KMimeType</ulink>. Use esto como en el siguiente ejemplo: </para>

<programlisting>KMimeType::Ptr type = KMimeType::mimeType("application/x-foo");
cout &lt;&lt; "Tipo:    " &lt;&lt; type->name() &lt; endl;
cout &lt;&lt; "Icono:    " &lt;&lt; type->icon() &lt; endl;
cout &lt;&lt; "Comentario: " &lt;&lt; type->icon() &lt; endl;
QStringList patterns = type->patterns();
QStringList::ConstIterator it;
for (it = patterns.begin(); it != patterns.end(); ++it)
  cout &lt;&lt; "Patrón: " &lt;&lt; (*it) &lt;&lt; endl;
</programlisting>

</simplesect>


<simplesect id="mime-determiningmimetypes">
<title>Determinación del tipo MIME de los datos</title>

<para>El método más rápido para determinar el tipo MIME de un archivo es usar la función <function>KMimeType::findByURL()</function>, que busca en la cadena de la URL y determina, en la mayoría de casos, el tipo MIME a partir de la extensión. Este mecanismo no se usa con ciertos protocolos (como http, man o info). Por ejemplo, los guiones CGI de un servidor web escritos en Perl suelen tener la extensión <literal>.pl</literal>, lo que indica un tipo MIME <literal>«text/x-perl»</literal>. No obstante, el archivo entregado por el servidor es la salida de este guión, que normalmente es de tipo HTML. En este caso, <function>KMimeType::findByURL()</function> devuelve el tipo MIME <literal>«application/octet-stream»</literal> (disponible mediante <function>KMimeType::defaultMimeType()</function>), que indica un fallo al encontrar el tipo MIME. </para>

<programlisting>KMimeType::Ptr type = KMimeType::findByURL("/home/bernd/foobar.jpg");
if (type->name() == KMimeType::defaultMimeType())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; type->name() &lt;&lt; endl;
</programlisting>

<para>(Este método posee algunos argumentos más, pero no están documentados, así que puede olvidarse de ellos sin más). </para>

<para>Es posible que quiera encontrar un tipo MIME a partir del contenido de un archivo en lugar de a partir de su nombre. Esto es mucho más eficaz, pero también más lento, ya que necesita leer una parte del archivo. Esto se hace con la clase <ulink url="kdeapi:tdeio/KMimeMagic.html">KMimeMagic</ulink>, que posee un manejo de errores distinto: </para>

<programlisting>KMimeMagicResult *result = KMimeMagic::self()->findFileType("/home/bernd/foobar.jpg");
if (!result || !result->isValid())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; result->mimeType() &lt;&lt; endl;
</programlisting>

<para>Como variante de esta función, también puede determinar el tipo de un segmento de memoria. Esto se usa, por ejemplo, en <application>Kate</application> para encontrar el modo de resaltado adecuado: </para>

<programlisting>QByteArray array;
...
KMimeMagicResult *result = KMimeMagic::self()->findBufferType(array);
if (!result || !result->isValid())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; result->mimeType() &lt;&lt; endl;
</programlisting>

<para>Por supuesto, incluso KMimeMagic sólo es capaz de determinar un tipo de archivo a partir del contenido de un archivo local. Para los archivos remotos existe otra posibilidad adicional: </para>

<programlisting>KURL url("http://developer.kde.org/favicon.ico");
QString type = TDEIO::NetAccess::mimetype(url);
if (type == KMimeType::defaultMimeType())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; type &lt;&lt; endl;
</programlisting>

<para>Esto comienza una tarea TDEIO para descargar una parte del archivo y comprobar su tipo MIME. Tenga en cuenta que esta función puede resultar bastante lenta y bloquear el programa. Normalmente solo querrá usar esto si <function>KMimeType::findByURL()</function> ha devuelto <literal>«application/octect-stream»</literal>. </para>

<para>Por otra parte, si no desea bloquear su aplicación, también puede iniciar la tarea TDEIO explícitamente y conectarse a algunas de sus señales: </para>

<programlisting>void FooClass::findType()
{
    KURL url("http://developer.kde.org/favicon.ico");
    TDEIO::MimetypeJob *job = TDEIO::mimetype(url);
    connect( job, SIGNAL(result(TDEIO::Job*)),
             this, SLOT(mimeResult(TDEIO::Job*)) );
}

void FooClass::mimeResult(TDEIO::Job *job)
{
    if (job->error())
        job->showErrorDialog();
    else
        cout &lt;&lt; "Tipo MIME: " &lt;&lt; ((TDEIO::MimetypeJob *)job)->mimetype() &lt;&lt; endl;
}
</programlisting>

</simplesect>


<simplesect id="mime-mappingmimetypes">
<title>Mapear un tipo MIME a una aplicación o a un servicio</title>

<para>Cuando se instala una aplicación, se copia un archivo <literal>.desktop</literal> que contiene una lista de tipos MIME que esta aplicación puede cargar. De modo similar, los componentes como KParts hacen que esta información esté disponible por sus archivos <literal>.desktop</literal> de servicio. De modo que, en general, existen varios programas y componentes que pueden procesar un tipo MIME dado. Puede obtener una lista de ellos usando la clase <classname>KServiceTypeProfile</classname>: </para>

<programlisting>KService::OfferList offers = KServiceTypeProfile::offers("text/html", "Application");
KService::OfferList::ConstIterator it;
for (it = offers.begin(); it != offers.end(); ++it) {
    KService::Ptr service = (*it);
    cout &lt;&lt; "Nombre: " &lt;&lt; service->name() &lt;&lt; endl;
}
</programlisting>

<para>El valor devuelto por esta función es una lista de ofertas de servicio. Un objeto <classname>KServiceOffer</classname> empaqueta un KService::Ptr junto a un número de preferencia. La lista devuelta por <function>KServiceTypeProfile::offers()</function> está ordenada según la preferencia del usuario. El usuario puede cambiarla llamando a <command>keditfiletype text/html</command> o seleccionando <guimenuitem>Editar tipo de archivo</guimenuitem> en el menú de contexto de <application>Konqueror</application> sobre un archivo HTML. </para>

<para>En el ejemplo anterior, se solicitó una lista de las aplicaciones que ofrecen soporte para <literal>text/html</literal>. Entre otros, esta lista contendrá editores HTML, como <application>Quanta Plus</application>. También puede sustituir el segundo argumento <literal>"Application"</literal> por <literal>"KParts::ReadOnlyPart"</literal>. En este caso, obtendrá una lista de componentes integrables para visualizar HTML, como TDEHTML. </para>

<para>En la mayor parte de los casos no estará interesado en la lista de todos los servicios ofrecidos por una combinación de tipo MIME y tipo de servicio. Existe una función más conveniente que le proporciona solo el servicio ofrecido con la preferencia más alta: </para>

<programlisting>KService::Ptr offer = KServiceTypeProfile::preferredService("text/html", "Application");
if (offer)
    cout &lt;&lt; "Nombre: " &lt;&lt; service->name() &lt;&lt; endl;
else
    cout &lt;&lt; "No se ha encontrado un servicio apropiado" &lt;&lt; endl;
</programlisting>

<para>Para solicitudes aún más complejas existe un <ulink url="kdeapi:tdeio/TDETrader.html">«trader»</ulink> desarrollado de modo similar a CORBA. </para>

<para>Para ejecutar una aplicación de servicio con algunas URLs, use <ulink url="kdeapi:tdeio/KRun.html">KRun</ulink>: </para>

<programlisting>KURL::List urlList;
urlList &lt;&lt; "http://www.ietf.org/rfc/rfc1341.txt?number=1341";
urlList &lt;&lt; "http://www.ietf.org/rfc/rfc2046.txt?number=2046";
KRun::run(offer.service(), urlList);
</programlisting>

</simplesect>


<simplesect id="mime-misc">
<title>Otros</title>

<para>En esta sección listaremos algunas APIs directamente relacionadas con las de la sección anterior. </para>

<para>Obtener un icono para una URL. Esto busca el tipo de URL y devuelve el icono asociado. </para>

<programlisting>KURL url("ftp://ftp.kde.org/pub/incoming/wibble.c");
QString icon = KMimeType::iconForURL(url);
</programlisting>

<para>Ejecutar una URL. Esto busca el tipo de URL y ejecuta el programa preferente del usuario que está asociado a este tipo. </para>

<programlisting>KURL url("http://dot.kde.org");
new KRun(url);
</programlisting>

</simplesect>

</sect1>


<sect1 id="nettransparency">
<title>Transparencia de red</title>

<simplesect id="nettransparency-intro">
<title>Introducción</title>

<para>En la era de la Web resulta de capital importancia que las aplicaciones de escritorio puedan acceder a recursos situados en Internet: deben ser capaces de descargar archivos de un servidor web, escribir archivos en un servidor ftp o leer mensajes de correo en un servidor web. Esta capacidad de acceder a archivos sin que importe su ubicación se suele denominar <emphasis>transparencia de red</emphasis>. </para>

<para>En el pasado se implementaron diferentes aproximaciones para conseguir este objetivo. El viejo sistema de archivos NFS es un intento de implementar transparencia de red en el nivel de la API POSIX. Aunque esta aproximación funciona bastante bien en redes locales, estrechamente unidas, no es adecuada para recursos cuyo acceso no es fiable o es posiblemente lento. En este caso, el <emphasis>asincronismo</emphasis> es importante. Mientras usted espera que su navegador web descargue una página, la interfaz de usuario no debería estar bloqueada. Además, la visualización de la página no debería comenzar cuando la página esté completamente disponible, sino que debe actualizarse a medida que los datos vayan llegando. </para>

<para>En las bibliotecas de KDE, la transparencia de red está implementada en la API TDEIO. El concepto central de esta arquitectura es una <emphasis>tarea</emphasis> de entrada/salida. Una tarea puede copiar o borrar archivos o cosas similares. Una vez que una tarea ha comenzado, funcionará en segundo plano y no bloqueará la aplicación. Cualquier comunicación de vuelta entre la tarea y la aplicación (como la entrega de datos o de información de progreso) se realiza de forma integrada en el bucle de eventos de Qt. </para>

<para>La operación en segundo plano se realiza mediante el inicio de <emphasis>ioslaves</emphasis> para realizar ciertas tareas. Los «ioslaves» se inician como procesos independientes y se comunica con ellos mediante «sockets» de dominio UNIX. De este modo no es necesaria la programación multihilo, y los esclavos inestables no pueden bloquear la aplicación que los usa. </para>

<para>Las ubicaciones de los archivos se expresan mediante las ampliamente usadas URL. Pero, en KDE, las URL no solo expanden el alcance de los archivos direccionables más allá del sistema de archivos local, sino que también van en el sentido contrario: por ejemplo, puede navegar por el interior de archivos «tar». Esto se consigue anidando URL. Por ejemplo, un archivo que resida dentro de un archivo comprimido «tar» en un servidor web, tendría la URL </para>

<programlisting>http://www-com.physik.hu-berlin.de/~bernd/article.tgz#tar:/paper.tex
</programlisting>

</simplesect>


<simplesect id="nettransparency-usingkio">
<title>Uso de TDEIO</title>

<para>En muchos casos, las tareas se crean llamando a funciones del nombre de espacios TDEIO. Estas funciones tienen una o dos URL como argumento, además de otros parámetros posiblemente necesarios. Cuando la tarea termina, emite la señal <literal>result(TDEIO::Job*)</literal>. Tras emitir esta señal, la tarea se borra a sí misma. De este modo, un caso de uso típico podría ser: </para>

<programlisting>void FooClass::makeDirectory()
{
    SimpleJob *job = TDEIO::mkdir(KURL("file:/home/bernd/kiodir"));
    connect( job, SIGNAL(result(TDEIO::Job*)), 
             this, SLOT(mkdirResult(TDEIO::Job*)) );
}

void FooClass::mkdirResult(TDEIO::Job *job)
{
    if (job->error())
        job->showErrorDialog();
    else
        cout &lt;&lt; "mkdir funcionó bien" &lt;&lt; endl;
}
</programlisting>

<para>Dependiendo del tipo de tarea, también podrá conectarla a otras señales. </para>

<para>Lo que sigue es una introducción a las posibles funciones: </para>

<variablelist>

<varlistentry><term>TDEIO::mkdir(const KURL &amp;url, int permission)</term>
<listitem><para>Crea un directorio, opcionalmente con ciertos permisos. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::rmdir(const KURL &amp;url)</term>
<listitem><para>Elimina un directorio. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::chmod(const KURL &amp;url, int permissions)</term>
<listitem><para>Cambia los permisos de un archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::rename(const KURL &amp;src, const KURL &amp;dest, bool overwrite)</term>
<listitem><para>Renombra un archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::symlink(const QString &amp;target, const KURL &amp;dest, bool overwrite, bool showProgressInfo)</term>
<listitem><para>Crea un enlace simbólico. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::stat(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Obtiene cierta información sobre el archivo, como su tamaño, hora de modificación y permisos. La información puede obtenerse de TDEIO::StatJob::statResult() una vez que el trabajo haya finalizado. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::get(const KURL &amp;url, bool reload, bool showProgressInfo)</term>
<listitem><para>Transfiere datos desde un URL. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::put(const KURL &amp;url, int permissions, bool overwrite, bool resume, bool showProgressInfo)</term>
<listitem><para>Transfiere datos a un URL. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::http_post(const KURL &amp;url, const QByteArray &amp;data, bool showProgressInfo)</term>
<listitem><para>Envía datos. Específica de HTTP. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::mimetype(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Intenta encontrar el tipo MIME de un URL. El tipo se puede obtener de TDEIO::MimetypeJob::mimetype() una vez que el trabajo haya finalizado. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::file_copy(const KURL &amp;src, const KURL &amp;dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)</term>
<listitem><para>Copia un único archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::file_move(const KURL &amp;src, const KURL &amp;dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)</term>
<listitem><para>Renombra o mueve un único archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::file_delete(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Elimina un único archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::listDir(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Lista el contenido de un directorio. Cada vez que se conozcan nuevas entradas será emitida la señal TDEIO::ListJob::entries(). </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::listRecursive(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Similar a la función listDir(), aunque esta es recursiva. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::copy(const KURL &amp;src, const KURL &amp;dest, bool showProgressInfo)</term>
<listitem><para>Copia un archivo o un directorio. Los directorios se copian recursivamente. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::move(const KURL &amp;src, const KURL &amp;dest, bool showProgressInfo)</term>
<listitem><para>Mueve o renombra un archivo o un directorio. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::del(const KURL &amp;src, bool shred, bool showProgressInfo)</term>
<listitem><para>Elimina un archivo o un directorio. </para></listitem>
</varlistentry>

</variablelist>

</simplesect>


<simplesect id="nettransparency-direntries">
<title>Entradas de directorio</title>

<para>La tarea TDEIO::stat() y la tarea TDEIO::listDir() devuelven un resultado de tipo UDSEntry y UDSEntryList, respectivamente. Esta última está definida como QValueList&lt;UDSEntry&gt;. El acrónimo de UDS significa «servicio de directorio universal», en inglés. El principio subyacente consiste en que una entrada de directorio solo contiene la información que puede proporcionar un «ioslave», pero no más. Por ejemplo, el esclavo http no proporciona ninguna información sobre permisos de acceso o propietarios del archivo. En lugar de ello, una USDEntry consiste en una lista de UDSAtoms, cada uno de los cuales proporciona una pieza de información específica (que consiste en un tipo almacenado en «m_uds», y en un valor entero en «m_long» o en una cadena de texto en «m_str», dependiendo del tipo). </para>

<para>Actualmente están definidos los siguientes tipos: </para>

<itemizedlist>

<listitem><para>UDS_SIZE (integer) - Tamaño del archivo. </para></listitem>

<listitem><para>UDS_USER (string) - Usuario al que pertenece el archivo. </para></listitem>

<listitem><para>UDS_GROUP (string) - Grupo al que pertenece el archivo. </para></listitem>

<listitem><para>UDS_NAME (string) - Nombre del archivo. </para></listitem>

<listitem><para>UDS_ACCESS (integer) - Permisos del archivo, tal y como se almacenan, por ejemplo, en el campo st_mode usando la función stat() de libc. </para></listitem>

<listitem><para>UDS_FILE_TYPE (integer) - El tipo de archivo, del mismo modo que se proporciona, por ejemplo, por stat() en el campo st_mode. Por lo tanto, puede usar las típicas macros de libc (como S_ISDIR) para comprobar este valor. Tenga en cuenta que los datos proporcionados por los «ioslaves» corresponden a los de stat(), no a los de lstat(). Es decir, en el caso de los enlaces simbólicos, el tipo de archivo será el tipo del archivo apuntado por el enlace, no el del enlace en sí mismo. </para></listitem>

<listitem><para>UDS_LINK_DEST (string) - En caso de un enlace simbólico, el nombre del archivo al que apunta. </para></listitem>

<listitem><para>UDS_MODIFICATION_TIME (integer) - La fecha y hora (del tipo time_t) de la última vez que se modificó el archivo, como se guarda, por ejemplo, en el campo st_mtime de stat(). </para></listitem>

<listitem><para>UDS_ACCESS_TIME (integer) - La fecha y hora de la última vez que se accedió al archivo, como se guarda, por ejemplo, en el campo st_atime de stat(). </para></listitem>

<listitem><para>UDS_CREATION_TIME (integer) - La fecha y hora de creación del archivo, como se guarda, por ejemplo, en el campo st_ctime de stat(). </para></listitem>

<listitem><para>UDS_URL (string) - Proporciona una URL de un archivo. No consiste simplemente en la suma de la URL del directorio y del nombre del archivo. </para></listitem>

<listitem><para>UDS_MIME_TYPE (string) - Tipo MIME del archivo. </para></listitem>

<listitem><para>UDS_GUESSED_MIME_TYPE (string) - El tipo MIME del archivo deducido por el esclavo. La diferencia con el tipo anterior reside en que este no se debe tomar como fiable (debido a que su determinación de una forma fiable resultaría muy costosa). Por ejemplo, la clase KRun comprueba explícitamente el tipo MIME si no posee información fiable sobre él. </para></listitem>

</itemizedlist>

<para>Aunque la forma de almacenar información sobre los archivos en una <classname>UDSEntry</classname> es flexible y práctica desde el punto de vista del «ioslave», resulta confusa para el programador de la aplicación. Por ejemplo, para encontrar el tipo MIME de un archivo, deberá recorrer todos los átomos y comprobar si <literal>m_uds</literal> contiene el valor <literal>UDS_MIME_TYPE</literal>. Afortunadamente, existe una API que es mucho más fácil de usar: la clase <classname>KFileItem</classname>. </para>

</simplesect>


<simplesect id="nettransparency-syncuse">
<title>Utilización síncrona</title>

<para>A menudo, la API asíncrona de TDEIO resulta demasiado compleja de usar, por lo que la implementación de asincronismo total no es una prioridad. Por ejemplo, en un programa que solo puede manejar un archivo de documento a la vez, realmente hay pocas cosas que se puedan hacer mientras el programa descarga el archivo. Para estos casos simples, existe una API mucho más simple bajo la forma de funciones estáticas en TDEIO::NetAccess. Por ejemplo, para copiar un archivo, utilice </para>

<programlisting>KURL origen, destino;
origen = ...;
destino = ...
TDEIO::NetAccess::copy(origen, destino);
</programlisting>

<para>La función retornará cuando haya finalizado el proceso de copia completamente. Además, este método proporciona un diálogo de proceso y se asegura de que la aplicación procesa los eventos de actualización gráfica. </para>

<para>Existe una combinación de funciones particularmente interesante: <function>download()</function> junto a <function>removeTempFile()</function>. La primera descarga un archivo de una determinada URL y lo almacena en un archivo temporal con un nombre único (este nombre se guarda en el segundo argumento). <emphasis>Si</emphasis> la URL es local, el archivo no se descarga, sino que se utiliza el segundo argumento como nombre para el archivo local. La función <function>removeTempFile()</function> borra el archivo proporcionado como argumento si este archivo fue el resultado de una descarga previa. En caso contrario, no hace nada. De este modo, el siguiente fragmento de código proporciona una manera muy fácil de descargar archivos independientemente de su ubicación: </para>

<programlisting>KURL url;
url = ...;
QString tempFile;
if (TDEIO::NetAccess::download(url, tempFile) {
    // cargar el archivo de nombre tempFile
    TDEIO::NetAccess::removeTempFile(tempFile);
}
</programlisting>

</simplesect>


<simplesect id="nettransparency-metadata">
<title>Metadatos</title>

<para>Como se ha visto anteriormente, la interfaz para tareas de entrada/salida es bastante abstracta y no considera los intercambios de información entre la aplicación y el esclavo de entrada/salida que sean específicos del protocolo. Esto no siempre resulta apropiado. Por ejemplo, puede proporcionar ciertos parámetros al esclavo HTTP para controlar el comportamiento de su caché o para enviar varias «cookies» con la petición. Para esta necesidad se introdujo el concepto de metadatos. Cuando se crea una tarea, puede configurarla añadiéndole metadatos. Cada elemento de metadatos consiste en una pareja clave/valor. Por ejemplo, para evitar que el esclavo HTTP descargue una página web de su caché, puede usar: </para>
 
<programlisting>void FooClass::reloadPage()
{
    KURL url("http://www.kdevelop.org/index.html");
    TDEIO::TransferJob *job = TDEIO::get(url, true, false);
    job->addMetaData("cache", "reload");
    ...
}
</programlisting>

<para>La misma técnica se puede usar en el sentido contrario, o sea, para la comunicación del esclavo hacia la aplicación. El método <function>Job::queryMetaData()</function> pregunta por el valor de cierta clave entregada por el esclavo. Para el esclavo HTTP, un ejemplo sería la clave <literal>«modified»</literal>, que contiene la fecha (representada en forma de cadena de texto) de cuando la página web fue modificada por última vez. Por ejemplo: </para>
 
<programlisting>void FooClass::printModifiedDate()
{
    KURL url("http://developer.kde.org/documentation/kde2arch/index.html");
    TDEIO::TransferJob *job = TDEIO::get(url, true, false);
    connect( job, SIGNAL(result(TDEIO::Job*)),
             this, SLOT(transferResult(TDEIO::Job*)) );
}

void FooClass::transferResult(TDEIO::Job *job)
{
    QString mimetype;
    if (job->error())
        job->showErrorDialog();
    else {
        TDEIO::TransferJob *transferJob = (TDEIO::TransferJob*) job;
        QString modified = transferJob->queryMetaData("modified");
        cout &lt;&lt; "Última modificación: " &lt;&lt; modified &lt;&lt; endl;
}
</programlisting>

</simplesect>


<simplesect id="nettransparency-scheduling">
<title>Programación</title>

<para>Cuando use la API TDEIO no tendrá que preocuparse normalmente de los detalles de iniciar esclavos de entrada/salida y comunicarse con ellos. El uso normal consiste en comenzar una tarea con algunos parámetros y manejar las señales que emita esta tarea. </para>

<para>Pero detrás del telón, el escenario es bastante más complejo. Cuando crea una tarea, ésta va a parar a una cola. Cuando la aplicación retorna al bucle de eventos, TDEIO asigna procesos esclavos para las tareas que hay en esta cola. Para las primeras tareas iniciadas, resulta obvio: se inicia un esclavo de entrada/salida para el protocolo apropiado. No obstante, una vez que la tarea (por ejemplo, una descarga de un servidor web) haya terminado, no se elimina inmediatamente. En lugar de ello, se coloca en un almacén de tareas inactivas y se elimina tras cierto tiempo de inactividad (3 minutos en la actualidad). Si durante este tiempo se produce una nueva petición para el mismo protocolo y servidor, se vuelve a reutilizar el esclavo. La ventaja obvia consiste en que, para una serie de tareas con el mismo servidor, se ahorra el costo de tener que crear nuevos procesos y posiblemente de repetir acciones de autenticación. </para>

<para>Por supuesto, esta reutilización solo es posible cuando el esclavo existente ya ha terminado su anterior tarea. Si llega una nueva petición mientras un proceso esclavo existente todavía está en funcionamiento, se debe iniciar y usar un nuevo proceso. En el uso de la API de los ejemplos anteriores no existe ninguna limitación para la creación de nuevos procesos esclavos: si inicia una serie de descargas consecutivas para 20 archivos distintos, TDEIO iniciará 20 procesos esclavos. Este esquema de asignación de esclavos a las tareas se denomina <emphasis>directo</emphasis>. No siempre es el esquema más adecuado, ya que puede necesitar mucha memoria y sobrecargar tanto a la máquina cliente como a la servidora. </para>

<para>Por lo tanto, existe una manera diferente: puede <emphasis>programar</emphasis> tareas. Si hace esto, solo podrá crear un limitado número (actualmente 3) de procesos esclavos para un protocolo determinado. Si crea más tareas, se colocarán en una cola y serán procesadas cuando un proceso esclavo quede inactivo. Esto se hace como sigue: </para>

<programlisting>KURL url("http://developer.kde.org/documentation/kde2arch/index.html");
TDEIO::TransferJob *job = TDEIO::get(url, true, false);
TDEIO::Scheduler::scheduleJob(job);
</programlisting>

<para>Existe una tercera posibilidad <emphasis>orientada a conexiones</emphasis>. Por ejemplo, para el esclavo IMAP, no tiene sentido iniciar múltiples procesos para el mismo servidor: solo se debe forzar una conexión IMAP a la vez. En este caso, la aplicación debe tratar explícitamente con la noción de esclavo. Debe desasignar un esclavo de cierta conexión y luego asignar todas las tareas que pueda realizar la misma conexión con el mismo esclavo. De nuevo, esto se puede conseguir fácilmente usando TDEIO::Scheduler: </para>

<programlisting>KURL baseUrl("imap://bernd@albert.physik.hu-berlin.de");
TDEIO::Slave *slave = TDEIO::Scheduler::getConnectedSlave(baseUrl);

TDEIO::TransferJob *job1 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=79374"));
TDEIO::Scheduler::assignJobToSlave(slave, job1);

TDEIO::TransferJob *job2 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=86793"));
TDEIO::Scheduler::assignJobToSlave(slave, job2);

...

TDEIO::Scheduler::disconnectSlave(slave);
</programlisting>

<para>Solo debe desconectar el esclavo una vez que se garantice que han finalizado todos los trabajos que le hayan sido asignados. </para>

</simplesect>


<simplesect id="nettransparency-definingslaves">
<title>Definición de un ioslave</title>

<para>A continuación discutiremos cómo añadir un nuevo «ioslave» al sistema. Del mismo modo que ocurre con los servicios, los nuevos «ioslaves» se notifican al sistema mediante la instalación de un pequeño archivo de configuración. El siguiente fragmento de archivo «Makefile.am» instala el protocolo ftp: </para>

<programlisting>protocoldir = $(kde_servicesdir)
protocol_DATA = ftp.protocol
EXTRA_DIST = $(mime_DATA)
</programlisting>

<para>El contenido del archivo ftp.protocol sería el siguiente: </para>

<programlisting>[Protocol]
exec=tdeio_ftp
protocol=ftp
input=none
output=filesystem
listing=Name,Type,Size,Date,Access,Owner,Group,Link,
reading=true
writing=true
makedir=true
deleting=true
Icon=ftp
</programlisting>

<para>La entrada <literal>«protocol»</literal> define de qué protocolo se hace responsable este esclavo. La entrada <literal>«exec»</literal> es (al contrario de lo que hubiera esperado) el nombre de la biblioteca que implementa el esclavo. Cuando deba iniciarse el esclavo, se ejecuta el comando <command>«tdeinit»</command>, que es el encargado de cargar la biblioteca en su espacio de direcciones. Así que, en la práctica, puede pensar que un esclavo en funcionamiento es un proceso independiente, aunque esté implementado en una biblioteca. La ventaja de este mecanismo reside en que así se ahorra gran cantidad de memoria y se reduce el tiempo que necesita el enlazador en tiempo de ejecución. </para>

<para>Las líneas «input» y «output» no se usan actualmente. </para>

<para>Las restantes líneas del archivo <literal>.protocol</literal> definen qué propiedades tiene el esclavo. En general, las características que debe implementar un esclavo son más simples que las que proporciona la API TDEIO para la aplicación. La razón para esto reside en que las tareas complejas se programan en un conjunto de subtareas. Por ejemplo, para listar un directorio recursivamente se iniciará una tarea para el directorio de nivel superior, y luego una adicional para cada subdirectorio que contenga. Un programador interno de TDEIO se asegura de que no estén activas demasiadas tareas al mismo tiempo. De forma similar, para copiar un archivo con un protocolo que no proporciona copias directamente (como el protocolo <literal>ftp:</literal>), TDEIO puede leer el archivo de origen y luego escribir los datos en el archivo de destino. Para que esto funcione, el archivo <literal>.protocol</literal> debe notificar las acciones que proporciona su esclavo. </para>

<para>Debido a que los esclavos se cargan como bibliotecas compartidas, aunque constituyen programas independientes, su infraestructura de código parece algo distinta a la de las extensiones para bibliotecas compartidas normales. La función que se llama para iniciar el esclavo se denomina <function>kdemain()</function>. Esta función realiza algún tipo de inicialización y luego entra en un bucle de eventos a la espera de peticiones por parte de la aplicación que la usa. El siguiente fragmento ilustra el proceso: </para>

<programlisting>extern "C" { int kdemain(int argc, char **argv); }

int kdemain(int argc, char **argv)
{
    TDELocale::setMainCatalogue("tdelibs");
    TDEInstance instance("tdeio_ftp");
    (void) TDEGlobal::locale();

    if (argc != 4) {
        fprintf(stderr, "Uso: tdeio_ftp protocol "
                        "domain-socket1 domain-socket2\n");
        exit(-1);
    }

    FtpSlave slave(argv[2], argv[3]);
    slave.dispatchLoop();
    return 0;
}
</programlisting>

</simplesect>


<simplesect id="nettransparency-implementingslaves">
<title>Implementación de un ioslave</title>

<para>Los esclavos se implementan como subclases de <classname>TDEIO::SlaveBase</classname> (FtpSlave en el ejemplo anterior). De este modo, las acciones que se listan en el archivo <literal>.protocol</literal> corresponden a ciertas funciones virtuales de <classname>TDEIO::SlaveBase</classname> que la implementación del esclavo debe reimplementar. Estas son algunas de las posibles acciones y sus correspondientes funciones virtuales: </para>

<variablelist>

<varlistentry><term>reading - Lee datos desde una URL</term>
<listitem><para>void get(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>writing - Escribe datos en una URL y crea el archivo de destino si no existe.</term>
<listitem><para>void put(const KURL &amp;url, int permissions, bool overwrite, bool resume)</para></listitem></varlistentry>

<varlistentry><term>moving - Renombra un archivo.</term>
<listitem><para>void rename(const KURL &amp;src, const KURL &amp;dest, bool overwrite)</para></listitem></varlistentry>

<varlistentry><term>deleting - Borra un archivo o directorio.</term>
<listitem><para>void del(const KURL &amp;url, bool isFile)</para></listitem></varlistentry>

<varlistentry><term>listing - Lista el contenido de un directorio.</term>
<listitem><para>void listDir(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>makedir - Crea un directorio.</term>
<listitem><para>void mkdir(const KURL &amp;url, int permissions)</para></listitem></varlistentry>

</variablelist>

<para>Adicionalmente, existen funciones reimplementables que no están listadas en el archivo <literal>.protocol</literal>. Para estas operaciones, TDEIO determina automáticamente si están soportadas o no (es decir, la implementación por defecto devuelve un error). </para>

<variablelist>

<varlistentry><term>Entrega información sobre el archivo, similar a la función stat() de C.</term>
<listitem><para>void stat(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>Cambia los permisos de acceso de un archivo.</term>
<listitem><para>void chmod(const KURL &amp;url, int permissions)</para></listitem></varlistentry>

<varlistentry><term>Determina el tipo MIME de un archivo.</term>
<listitem><para>void mimetype(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>Copia un archivo.</term>
<listitem><para>copy(const KURL &amp;url, const KURL &amp;dest, int permissions, bool overwrite)</para></listitem></varlistentry>

<varlistentry><term>Crea un enlace simbólico.</term>
<listitem><para>void symlink(const QString &amp;target, const KURL &amp;dest, bool overwrite)</para></listitem></varlistentry>

</variablelist>

<para>Todas estas implementaciones deben finalizar con una de estas dos llamadas: si la operación fue exitosa, se debería llamar a <literal>finished()</literal>; si ocurrió un error, <literal>error()</literal> debería ser llamada con un código de error como primer argumento y una cadena de texto como segundo. Los códigos de error posibles se listan como enumeraciones de tipo <type>TDEIO::Error</type>. El segundo argumento suele ser la URL en cuestión. Se usa, por ejemplo, en la función <function>TDEIO::Kob::showErrorDialgog()</function> para parametizar el mensaje de error legible por el usuario. </para>

<para>En el caso de los esclavos que se corresponden con protocolos de red, resulta interesante reimplementar el método <function>SlaveBase::setHost()</function>. Este método se llama para comunicar al proceso esclavo información sobre el servidor, el puerto a usar, el nombre de usuario y su contraseña para iniciar la sesión. En general, los metadatos ajustados por la aplicación se pueden solicitar mediante <function>SlaveBase::metaData()</function>. Puede comprobar la existencia de metadatos para cualquier clave con la función <function>SlaveBase::hasMetaData()</function>. </para>

</simplesect>


<simplesect id="nettransparency-communication">
<title>Devolviendo datos a la aplicación</title>

<para>Varias acciones implementadas en un proceso esclavo necesitan algún modo de devolver datos a la aplicación que está usando dicho proceso esclavo: </para>

<itemizedlist>

<listitem><para><function>get()</function> envía bloques de datos. Esto se lleva a cabo con <function>data()</function>, que tiene como argumento un <classname>QByteArray</classname>. Por supuesto, no es necesario que envíe todos los datos al mismo tiempo. Si tiene que enviar un archivo grande, llame a <function>data()</function> con bloques más pequeños de datos, de modo que la aplicación pueda procesarlos. Llame a <function>finished()</function> cuando la transferencia haya terminado. </para></listitem>
    
<listitem><para><function>listDir()</function> devuelve información sobre las entradas de un directorio. Para este propósito, llame a <function>listEntries()</function> con una <classname>TDEIO::UDSEntryList</classname> como argumento. Del mismo modo que ocurría con <function>data()</function>, puede llamar a esta función varias veces. Cuando haya terminado, llame a <function>listEntry()</function> con «true» como segundo parámetro. También puede llamar a <function>totalSize()</function> para devolver el número total de entradas de directorio, si es conocido. </para></listitem>

<listitem><para><function>stat()</function> devuelve información sobre el archivo, como su tamaño, tipo MIME, etc. Esta información está empaquetada en una <classname>TDEIO::UDSEntry</classname>, que se describirá más adelante. Use <function>statEntry()</function> para enviar este tipo de elementos a la aplicación. </para></listitem>

<listitem><para><function>mimetype()</function> llama a <function>mimeType()</function> con un argumento de cadena. </para></listitem>

<listitem><para><function>get()</function> y <function>copy()</function> pueden necesitar proporcionar información de progreso. Esto se lleva a cabo con los métodos <function>totalSize()</function>, <function>processedSize()</function> y <function>speed()</function>. El tamaño total y el procesado se devuelven en bytes, y la velocidad en bytes por segundo. </para></listitem>

<listitem><para>Puede enviar pares clave/valor de metadatos arbitrarios con <function>setMetaData()</function>. </para></listitem>

</itemizedlist>

</simplesect>


<simplesect id="nettransparency-interacting">
<title>Interacción con el usuario</title>

<para>A veces, un proceso esclavo debe interacturar con el usuario. Como ejemplos se pueden incluir los mensajes de información, los diálogos de autenticación y los de confirmación cuando se va a sobrescribir un archivo. </para>

<itemizedlist>

<listitem><para><function>infoMessage()</function> - Se usa para propósitos informativos, tales como el mensaje «Obteniendo datos de &lt;host&gt;» del esclavo http, que se muestra a menudo en la barra de estado del programa. En el lado de la aplicación, este método se corresponde a la señal <function>TDEIO::Job::infoMessage()</function>. </para></listitem>

<listitem><para><function>warning()</function> - Muestra un aviso en una caja de mensaje con <function>KMessageBox::information()</function>. No ocurre nada si ya hubiera otra caja de mensaje abierta como consecuencia de una llamada anterior a warning() desde el mismo proceso esclavo. </para></listitem>

<listitem><para><function>messageBox()</function> - Este método es más rico que el anterior, ya que permite abrir una caja de mensaje con texto, título y algunos botones. Vea el tipo enum <type>SlaveBase::MessageBoxType</type> como referencia. </para></listitem>

<listitem><para><function>openPassDlg()</function> - Abre un diálogo para introducir el nombre de usuario y la contraseña. </para></listitem>

</itemizedlist>

</simplesect>

</sect1>

</chapter>



<appendix id="misc">
<title>Licencias</title>

&underFDL;
&underGPL;

</appendix>

</book>