>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
> 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:kio/index.html"
>kio</ulink
></term>
<listitem
><para
>La biblioteca <literal
>kio</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:khtml/index.html"
>khtml</ulink
></term>
<listitem
><para
>La biblioteca <literal
>khtml</literal
> contiene el módulo KHTML, 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>
>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>
>Preferencias del usuario para asignación de tipos MIME. </para>
</formalpara
></listitem>
<listitem
><formalpara
><title
><ulink url="kdeapi:kio/KServiceTypeProfile"
>KTrader</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>
>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>
>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>
>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>
>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>
>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>
>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>
>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 &, BrushStyle) - Crea una brocha de color con uno de los patrones mostrados a continuación.</para>
</listitem>
<listitem>
<para
>QBrush::QBrush(const QColor &, 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>
>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>
>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
>. 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
><MenuBar></literal
>, contiene una declaración de una barra de menú. También puede insertar cualquier número de declaraciones <literal
><ToolBar></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>
>, de modo que puedan ser tenidos en cuenta por los traductores. Tenga en cuenta que deberá escribir la marca de acceso rápido «&» en modo compatible con XML (en la forma «&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
><Action></literal
>. El separador de las capturas de pantalla corresponde al elemento <literal
><Separator></literal
>. </para>
<para
>Notará que algunos elementos del menú no poseen su correspondiente entrada en el archivo XML. Se trata de las <emphasis
>. 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
>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
><Menu name="file">
<text>&amp;Location</text>
...
<ActionList name="openwith">
...
</Menu>
</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 */ ) {
KAction *action = new KAction( ...);
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>
> 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
>...
<Menu name="context_popup">
<Action name="file_add"/>
<Action name="file_remove"/>
</Menu>
...
</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>
>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"
>. 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
>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"
>. 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:kparts/KParts::Factory"
>KParts::Factory</ulink
> que debe producir objetos <ulink url="kdeapi:kparts/KParts::ReadOnlyPart"
>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"
cout << "El servicio no implementa la fábrica correcta" << 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
>kio_uiserver</literal
>, que implementa la interacción del usuario como un diálogo de progreso en la biblioteca KIO. 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
> 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"
>, 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"
> 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>
>. 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>
cout << "El inicio de kioserver ha fallado con el mensaje " << error << endl;
}
...
QByteArray data, replyData;
QCString replyType;
QDataStream arg(data, IO_WriteOnly);
arg << true;
if (!client->call("kio_uiserver", "UIServer", "setListMode(bool)",
data, replyType, replyData))
cout << "Ha fallado la llamada a kio_uiserver" << 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
>, que toma el nombre del archivo «desktop» como argumento (en este caso, <literal
>«kio_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
>, 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
>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 << "No se puede encontrar el tipo" << endl;
>(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:kio/KMimeMagic.html"
>KMimeMagic</ulink
>, que posee un manejo de errores distinto: </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>
cout << "No se puede encontrar el tipo" << endl;
else
cout << "Tipo: " << type << endl;
</programlisting>
<para
>Esto comienza una tarea KIO 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 KIO explícitamente y conectarse a algunas de sus señales: </para>
>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
>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 KHTML. </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>
>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 KIO. 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>
>En muchos casos, las tareas se crean llamando a funciones del nombre de espacios KIO. 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
>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
>La tarea TDEIO::stat() y la tarea TDEIO::listDir() devuelven un resultado de tipo UDSEntry y UDSEntryList, respectivamente. Esta última está definida como QValueList<UDSEntry>. 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>
>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
>A menudo, la API asíncrona de KIO 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>
>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>
>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>
>Cuando use la API KIO 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, KIO 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, KIO 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>
>. 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>
>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>
> 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
>, 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 KIO 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 KIO 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
>), KIO 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); }
>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
> 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
> 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 <host>» 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
> - 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
