]> Bernd Gehrmann

bernd@kdevelop.org

2001 2002 Bernd Gehrmann &FDLNotice; Esta documentación es una introducción a la plataforma de desarrollo de KDE KDE arquitectura desarrollo programación tdecore 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. tdeui La biblioteca tdeui 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. tdeio La biblioteca tdeio 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. kjs La biblioteca kjs proporciona una implementación de JavaScript. tdehtml La biblioteca tdehtml contiene el módulo TDEHTML, un widget de navegación HTML, el API y un procesador de DOM, incluyendo interfaces para Java y JavaScript. Esquema principal de una aplicación - clases que son necesarias en casi cualquier aplicación. Inicia y controla una aplicación de KDE. Se asegura de que solo se ejecuta una sesión de la aplicación en cada momento. Contiene la información de la ventana «Acerca de». Procesamiento de argumentos de la línea de órdenes. 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. Proporciona acceso a la base de datos de configuración de KDE. Acceso a archivos de configuración simples y no jerárquicos. Acceso a los archivo .desktop. Acceso cómodo a las preferencias que no son específicas de la aplicación. Manejo de archivos y URLs - descodificación de URLs, archivos temporales, etc. Representa y procesa URLs. Crea archivos de nombre único para almacenamiento temporal. Permite guardar archivos en segmentos. Comunicación entre procesos - clases auxiliares para DCOP e invocación de subprocesos. Invoca y controla procesos hijo. Invoca procesos hijo a través de un intérprete de comandos. Comunicación con procesos hijo a través de una pseudo terminal. Comunicación entre procesos simple utilizando ClientMessages de X11. Mensajería DCOP. Una clase proxy que publica las propiedades de Qt a través de DCOP. Una clase proxy que publica un interfaz DCOP para realizar acciones. Clases de utilidades - gestión de memoria, expresiones regulares, manipulación de cadenas, números aleatorios Tratamiento de expresiones regulares según POSIX. Una extravagante interfaz para la manipulación de cadenas. Localización eficiente de memoria para grandes grupos de pequeños objetos. Generador de números pseudo aleatorios. Aceleradores de teclado - clases de ayuda para el establecimiento de atajos de teclado consistentes con el escritorio. Collección de atajos de teclado. Acceso sencillo a los atajos de teclado más comunes. Colección de atajos de teclado que afectan a todo el sistema. Procesamiento de imágenes - carga y manipulación de iconos. Carga iconos de una forma consistente con los temas de escritorio. Clases de ayuda para TDEIconLoader. Una clase de mapa de pixels con posibilidades extendidas de optimización de colores. Efectos de mapas de píxels como gradientes y patrones. Conversión rápida de TQImage a QPixmap. Arrastrar y soltar - objetos de arrastre para colores y URLs. Un objeto de arrastre para URLs. Un objeto de arrastre para colores. Permite construir objetos de arrastre a partir varios otros. Autocompletado Autocompletado de cadenas genérico. Autocompletado de URLs. Autocompletado de ejecutables. Widgets - clases de widgets para vistas de lista, reglas, selección de colores, etc. Una variante de QListView que se ajusta a las preferencias globales del sistema KDE. Una variante de QListBox que se ajusta a las preferencias globales del sistema KDE. Una variante de QIconView que se ajusta a las preferencias globales del sistema KDE. Una variante de QLineEdit con soporte para autocompletado. Una variante de QComboBox con soporte para autocompletado. Una lista desplegable para la selección de fuentes. Una lista desplegable para la selección de colores. Un botón para la selección de colores. Una lista desplegable para la selección de nombres de archivos y URLs. Una línea de edición para seleccionar nombres de archivos y URLs. Un widget de una regla. animaciones. Un widget para la entrada de números. Un widget para la entrada de contraseñas. Diálogos - díalogos completos para la selección de archivos, colores y fuentes. Un diálogo de selección de archivos. Un diálogo de selección de colores. Un diálogo para la selección de fuentes. Un diálogo para la selección de iconos. Un diálogo para la edición de atajos de teclado. Un diálogo para la edición de barras de herramientas. Un diálogo para mostrar consejos. Un diálogo de información de la aplicación. Un diálogo simple para la entrada de texto. Un diálogo simple para la entrada de URLs. Un diálogo para indicar errores y advertencias. Un diálogo para la entrada de contraseñas. Acciones y entorno gráfico XML Abstracción de una acción que puede ser conectada a barras de menús y barras de herramientas. Un conjunto de acciones. 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. Gestiona la activación de cliente de entorno gráfico XML. Extensiones y componentes Representa una biblioteca de carga dinámica. Carga de bibliotecas compartidas. Factoría de objetos en las extensiones. Representa un tipo de servicio. Representa un servicio. Representa un tipo MIME. Preferencias del usuario para asignación de tipos MIME. Consultas para servicios. 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. La clase central para la realización de gráficos 2D en Qt es QPainter. Puede dibujar en un QPaintDevice. Hay implementados tres dispositivos de pintura posibles: uno es TQWidget, que representa un widget de la pantalla. El segundo es QPrinter que representa una impresora y produce salida PostScript. El tercero es la clase QPicture, 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. 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. void FooWidget::paintEvent() { QPainter p(esto); // Configurar sistema de dibujo // Utilizar sistema de dibujo } 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 métrica del dispositivo para computar las coordenadas. 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 La matriz 3x3 de esta ecuación se puede establecer con QPainter::setWorldMatrix() y es de tipo QWMatrix. 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: 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 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 Si se establece uno de los parámetros a un valor negativo, se puede conseguir una visión simétrica del sistema de coordenadas. 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 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 Fíjese en que un giro es equivalente a una combinación de escalado y corte. Aquí se muestran algunas imágenes que muestran el efecto de transformaciones elementales sobre nuestra mascota: a) Normal b) Girado 30 grados c) Corte a 0.4 d) Simétrico 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. 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 QPen. Las propiedades que almacena son estilo, color, estilo de unión y estilo de tope. El estilo de pincel es un miembro de la enumeración TQt::PenStyle. Puede tomar uno de los siguientes valores: El estilo de unión es un miembro de la enumeración TQt::PenJoinStyle. 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: a) MiterJoin c) BevelJoin b) RoundJoin El estilo de tope es un miembro de la enumeración TQt::PenCapStyle, y especifica cómo se deben dibujar los puntos finales de las líneas. Toma uno de los valores de la siguiente tabla: a) FlatCap b) SquareCap c) RoundCap 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 QBrush como argumento. Las brochas se pueden construir de cuatro maneras diferentes: QBrush::QBrush() - Crea una brocha que no rellena las figuras. QBrush::QBrush(BrushStyle) - Crea una brocha negra con uno de los siguientes patrones mostrados a continuación. QBrush::QBrush(const TQColor &, BrushStyle) - Crea una brocha de color con uno de los patrones mostrados a continuación. QBrush::QBrush(const TQColor &, const QPixmap) - Crea una brocha de color con el patrón personalizado que se proporcione como segundo parámetro. Un estilo de brocha predeterminado se obtiene de la enumeración TQt::BrushStyle. Esta es una muestra de todos los patrones predefinidos: Una forma más avanzada de personalizar el comportamiento de la brocha es mediante la función QPainter::setBrushOrigin(). Los colores juegan un papel tanto al ajustar curvas como al rellenar figuras. En Qt, los colores están representados por la clase TQColor. 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. 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. 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 RasterOp. 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". 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 QRect o un conjunto de cuatro enteros. Dibujo de un único punto - drawPoint(). Dibujo de líneas - drawLine(), drawLineSegments() y drawPolyLine(). Dibujo y relleno de rectángulos - drawRect(), drawRoundRect(), fillRect() y eraseRect(). Dibujo y relleno de círculos, elipses o parte de ellos - drawEllipse(), drawArc(), drawPie y drawChord(). Dibujo y relleno de polígonos generales - drawPolygon(). Dibujo de curvas bezier - drawQuadBezier() [drawCubicBezier en Qt 3.0]. Qt proporciona dos clases muy diferentes para la representación de imágenes. QPixmap 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 muy 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 bitBlt para tranferir el mapa de pixels al widget. En casos de redibujados complejos, esto ayuda a evitar el efecto de parpadeo. Por contra, el objeto TQImage 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 TQImage 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 TQImage a QPixmap puede requerir también un proceso de reducción del número de colores. Es posible dibujar texto con una de las variantes sobrecargadas del método QPainter::drawText(). De esta forma se dibuja una TQString 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 TQt::AlignmentFlags y TQt::TextFlags 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. Una forma más avanzada de mostrar texto con formato es la clase QSimpleRichText. 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 QStyleSheet (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(). 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. Como alternativa, Qt contiene la clase QCanvas 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 QCanvasItem 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 QCanvasView 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. 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: 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. Se puede encontrar un tutorial para el uso de QCanvas en el desarrollo de juegos basados en sprites aquí. El estándar de facto actual para la realización de gráficos 3D es OpenGL. 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 contexto GL y no tiene ningún tipo de interacción con el entorno de desarrollo. Qt ofrece el widget QGL Widget que encapsula una ventana con un contexto GL asociado. Básicamente se utiliza realizando subclases y reimplementando algunos métodos. 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. 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. En ver se reimplementar resizeEvent(), se utiliza resizeGL(). Sirve para establacer el modo vista de forma correcta. 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. 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. Qt contiene algunos ejemplos del uso de QGLWidget en su ejemplo demo. Se puede encontrar una colección de tutoriales aquí, y más información junto a una referencia de OpenGL está disponible en la página web de OpenGL. 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 Coin, complementada por un entorno de desarrollo para Qt llamado SoQt. El concepto básico de Open Inventor es la escena. Es posible cargar una escena del disco y guardarla en un formato especial muy unido a VRML. Una escena consta de una colección de objetos llamados nodos. 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. Puede encontrar una introducción a Inventor aquí (por regla general, es posible sustituir los métodos de SoXt descritos en el artículo por los de SoQt). Mientras que el patrón de acción 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. Este problema se resuelve por medio de un conjunto de clases llamado XMLGUI. 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 ArchivoAbrir o AyudaAcerca de...) 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. La clase de KDE para las ventanas de primer nivel, TDEMainWindow es heredera de KXMLGUIClient y, por lo tanto, soporta XMLGUI directamente. Todas las acciones creadas dentro deben tener como superior jerárquico un actionCollection() del cliente. Una llamada a createGUI() construirá el conjunto completo de menús y barras de herramientas definidos en el archivo XML de la aplicación (normalmente con el sufijo ui.rc). A continuación tomamos como ejemplo el visor de imágenes de KDE KView. Tiene un archivo ui.rc llamado kviewui.rc que es instalado por orden de Makefile.am rcdir = $(kde_datadir)/kview rc_DATA = kviewui.rc Esto es un extracto de kviewui.rc. Para simplificar el ejemplo, mostramos únicamente la definición del menú Ver. <!DOCTYPE kpartgui> <kpartgui name="kview"> <MenuBar> <Menu name="view" > <Action name="zoom50" /> <Action name="zoom100" /> <Action name="zoom200" /> <Action name="zoomMaxpect" /> <Separator/> <Action name="fullscreen" /> </Menu> </MenuBar> </kpartgui> La parte de código correspondiente en C++ es: KStdAction::zoomIn ( this, TQ_SLOT(slotZoomIn()), actionCollection() ); KStdAction::zoomOut ( this, TQ_SLOT(slotZoomOut()), actionCollection() ); KStdAction::zoom ( this, TQ_SLOT(slotZoom()), actionCollection() ); new TDEAction ( i18n("&Half size"), ALT+Key_0, this, TQ_SLOT(slotHalfSize()), actionCollection(), "zoom50" ); new TDEAction ( i18n("&Normal size"), ALT+Key_1, this, TQ_SLOT(slotDoubleSize()), actionCollection(), "zoom100" ); new TDEAction ( i18n("&Double size"), ALT+Key_2, this, TQ_SLOT(slotDoubleSize()), actionCollection(), "zoom200" ); new TDEAction ( i18n("&Fill Screen"), ALT+Key_3, this, TQ_SLOT(slotFillScreen()), actionCollection(), "zoomMaxpect" ); new TDEAction ( i18n("Fullscreen &Mode"), CTRL+SHIFT+Key_F, this, TQ_SLOT(slotFullScreen()), actionCollection(), "fullscreen" ); El menú Ver que aparece en el entorno gráfico resultante tiene este aspecto: 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 tdeui/kpartgui.dtd. 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 ui.rc, KDE se asegura de que cualquier versión personalizada del archivo sea desechada y se use en su lugar el nuevo archivo. La siguiente línea, <MenuBar>, contiene una declaración de una barra de menú. También puede insertar cualquier número de declaraciones <ToolBar> 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, KView tiene un submenú con el título «Image», que está declarado del siguiente modo: <Menu name="image" > <text>&amp;Image</text> ... </Menu> En la infraestructura automake de KDE, estos títulos se extraen automáticamente y se ponen en el archivo .po, 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;»). Volvamos al ejemplo. El menú View de KView contiene varias acciones personalizadas: zoom50, zoom100, zoom200, zoomMaxpect y fullscreen, declarados mediante un elemento <Action>. El separador de las capturas de pantalla corresponde al elemento <Separator>. Notará que algunos elementos del menú no poseen su correspondiente entrada en el archivo XML. Se trata de las acciones estándar. Las acciones estándar son creadas por la clase KStdAction. 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 tdeui/ui_standards.rc en el código fuente de tdelibs. Para ilustrar la discusión sobre las barras de herramientas, veremos la definición de la interfaz gráfica de Konqueror. Este trozo de código define la barra de dirección, que contiene el campo de entrada para introducir una URL. <ToolBar name="locationToolBar" fullWidth="true" newline="true" > <text>Location Toolbar</text> <Action name="clear_location" /> <Action name="location_label" /> <Action name="toolbar_url_combo" /> <Action name="go_url" /> </ToolBar> Lo primero que notamos es que hay muchos más atributos que para las barras de menú, como: fullWidth: 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. newline: 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. noEdit: Normalmente, el usuario puede personalizar las barras de herramientas, por ejemplo en PreferenciasConfigurar barras de herramientas en Konqueror. 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 Konqueror. iconText: 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). hidden: Si vale «true», la barra de herramientas no será visible inicialmente y tendrá que ser activada mediante algún elemento del menú. position: 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». 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ú Dirección de Konqueror contiene un conjunto de elementos Abrir con X 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 listas de acciones. 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 Konqueror: <Menu name="file"> <text>&amp;Location</text> ... <ActionList name="openwith"> ... </Menu> La función KXMLGUIClient::plugActionList() se usará para añadir acciones a ser mostradas, mientras que la función KXMLGuiClient::unplugActionList() eliminará todas las acciones conectadas. La rutina responsable de la actualización es semejante a la siguiente: void MainWindow::updateOpenWithActions() { unplugActionList("openwith"); openWithActions.clear(); for ( /* repetir sobre los servicios importantes */ ) { TDEAction *action = new TDEAction( ...); openWithActions.append(action); } plugActionList("openwith", openWithActions); } Tenga en cuenta que, al contrario que las acciones estáticas, las que se crean aquí no 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 openWithActions.setAutoDelete(true), como en el ejemplo anterior. 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 createGUI() (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: void MainWindow::popupRequested() { TQWidget *w = factory()->container("context_popup", this); QPopupMenu *popup = static_cast<QPopupMenu *>(w); popup->exec(QCursor::pos()); } El método KXMLGUIFactory::container() 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: ... <Menu name="context_popup"> <Action name="file_add"/> <Action name="file_remove"/> </Menu> ... 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: 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. 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 MayúsculasF1, 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. 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. La ventaja de las ventanas de ayuda «¿Qué es esto?» tal y como las proporcionan Qt y KDE consiste en que pueden contener texto enriquecido, es decir, que pueden contener diferentes tipos de letra, negrita, cursiva, e incluso imágenes y tablas. Un ejemplo de la ayuda «¿Qué es esto?»: Finalmente, cada programa debe tener un manual. El manual se visualiza normalmente en KHelpCenter tras activar la opción correspondiente del menú Ayuda. 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 DocBook. 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 QToolTip. QToolTip::add(w, i18n("Este widget realiza alguna acción.")) Si las barras de menú y de herramientas han sido creadas usando el patrón de acciones, la cadena usada como ayuda emergente procede el primer argumento del constructor de TDEAction: action = new TDEAction(i18n("&Delete"), "editdelete", SHIFT+Key_Delete, actionCollection(), "del") 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ú. action->setStatusText(i18n("Deletes the marked file")) La API para la ayuda «¿Qué es esto?» es muy similar. En los diálogos, utilice el siguiente código: QWhatsThis::add(w, i18n("<qt>This demonstrates <b>Qt</b>'s" " rich text engine.<ul>" "<li>Foo</li>" "<li>Bar</li>" "</ul></qt>")) Para los elementos del menú, utilice action->setWhatsThis(i18n("Deletes the marked file")) La invocación de KHelpCenter está encapsulada en la clase TDEApplication. Para mostrar el manual de su aplicación, use kapp->invokeHelp() 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 invokeHelp() con la etiqueta a la que debe saltar el navegador. La noción de servicio 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 DCOP. Al ser declarado de cierto tipo de servicio, 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. 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. Algunos ejemplos: El motor de visualización HTML usado en Konqueror es un componente que se puede integrar y que implementa los tipos de servicio KParts/ReadOnlyPart y Browser/View. En la rama HEAD de KDevelop, una gran parte de la funcionalidad está empaquetada en extensiones con el tipo de servicio KDevelop/Part. Durante el inicio se cargan todos los servicios de este tipo, de modo que pueda extender el IDE de una manera muy flexible. En la vista de iconos, Konqueror 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 ThumbCreator. Obviamente, un servicio no se caracteriza únicamente por los tipos de servicio que implementa, sino también por algunas propiedades. Por ejemplo, ThumCreator no solo implementa la clase C++ con el tipo ThumbCreator, 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 trader semejante a CORBA con un complejo lenguaje de consultas. Los nuevos tipos de servicio se añaden instalando una descripción en la carpeta TDEDIR/share/servicetypes. En un entorno automake, esto se puede realizar con el siguiente fragmento de Makefile.am: kde_servicetypesdir_DATA = tdeveloppart.desktop EXTRA_DIST = $(kde_servicetypesdir_DATA) La definición tdeveloppart.desktop de una parte KDevelop es similar a lo siguiente: [Desktop Entry] Type=ServiceType X-TDE-ServiceType=KDevelop/Part Name=KDevelop Part [PropertyDef::X-KDevelop-Scope] Type=TQString [PropertyDef::X-KDevelop-ProgrammingLanguages] Type=QStringList [PropertyDef::X-KDevelop-Args] Type=TQString 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 [PropertyDef::name] en el archivo de configuración. En este grupo, la entrada Type declara el tipo de la propiedad. Los tipos posibles son cualquier cosa que se pueda almacenar en un QVariant. Las definiciones de servicios se guardan en la carpeta TDEDIR/share/services: kde_servicesdir_DATA = kdevdoxygen.desktop EXTRA_DIST = $(kde_servicesdir_DATA) El contenido del siguiente archivo de ejemplo kdevdoxygen.desktop define la extensión KDevDoxygen con el tipo de servicio KDevelop/Part: [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 Aparte de las declaraciones usuales, una entrada importante es X-TDE-Library. Contiene el nombre de la biblioteca «libtool» (sin la extensión .la). También fija (mediante el prefijo init_) 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: extern "C" { void *init_libkdevdoxygen() { return new DoxygenFactory; } }; El tipo de la clase fábrica DoxygenFactory 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 KDevFactory (que deriva de KLibFactory). Otros ejemplos más comunes son KParts::Factory que debe producir objetos KParts::ReadOnlyPart, o, en muchos casos, KLibFactory. Para poder usar un servicio de biblioteca compartida en una aplicación, necesita obtener un objeto KService que lo represente. Esto se discute en la sección sobre tipos MIME (y en una sección sobre el «trader» pendiente de escribir). Una vez que disponga de un objeto KService, solo necesita cargar la biblioteca y obtener un puntero a su objeto fábrica: KService *service = ... TQString libName = QFile::encodeName(service->library()); KLibFactory *factory = KLibLoader::self()->factory(libName); if (!factory) { TQString name = service->name(); TQString 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); } 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 KLibFactory::create(). Para KParts, debe moldear el puntero de la fábrica al tipo más específico KParts::Factory y usar su método create(): if (factory->inherits("KParts::Factory")) { KParts::Factory *partFactory = static_cast<KParts::Factory*>(factory); TQObject *obj = partFactory->createPart(parentWidget, widgetName, parent, name, "KParts::ReadOnlyPart"); ... } else { cout << "El servicio no implementa la fábrica correcta" << endl; } 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 tdeio_uiserver, 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. 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 ServiceType, debido a que suelen ser iniciados por su nombre. También contienen las dos líneas siguientes como propiedades adicionales: X-DCOP-ServiceType especifica el modo en que se inicia el servicio. El valor Unique 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 TDEApplication::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 TDEUniqueApplication. El valor Multi para X-DCOP-ServiceType 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 None. En este caso, el inicio del servicio no esperará a estar registrado en DCOP. X-TDE-StartupNotify debe ser establecido normalmente como false. 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. Esta es la definición de tdeio_uiserver: [Desktop Entry] Type=Service Name=tdeio_uiserver Exec=tdeio_uiserver X-DCOP-ServiceType=Unique X-TDE-StartupNotify=false Un servicio DCOP comienza con uno de entre varios métodos en la clase TDEApplication: DCOPClient *client = kapp->dcopClient(); client->attach(); if (!client->isApplicationRegistered("tdeio_uiserver")) { TQString error; if (TDEApplication::startServiceByName("tdeio_uiserver", QStringList(), &error)) 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("tdeio_uiserver", "UIServer", "setListMode(bool)", data, replyType, replyData)) cout << "Ha fallado la llamada a tdeio_uiserver" << endl; ... 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. En el ejemplo propuesto, el servicio se inició «por nombre»; es decir, el primer argumento de TDEApplication::startServiceByName() es el nombre que aparece en la línea Name del archivo «desktop». Una alternativa consiste en usar TDEApplication::startServiceByDesktopName(), que toma el nombre del archivo «desktop» como argumento (en este caso, «tdeio_uiserver.desktop»). 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 TQString. Si el inicio del servicio falla, este argumento contendrá un mensaje de error traducido. 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: En la vista de iconos de Konqueror, los archivos se representan por iconos. Cada tipo MIME tiene asociado su propio icono. Cuando pulse sobre un icono de archivo o sobre su nombre en Konqueror, el archivo será mostrado en una vista empotrada, o se abrirá una aplicación asociada con su tipo de archivo. 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. 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. 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. 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 nombre.jpg 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 TDEDIR/share/mimelnk/magic, 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 .desktop, con lo que estará disponible de forma eficiente y conveniente para todas las bibliotecas de KDE. Definamos un tipo MIME «application/x-foo» para nuestro programa foobar. Para este fin, deberá escribir un archivo foo.desktop e instalarlo en TDEDIR/share/mimelnk/application (que es su ubicación usual, aunque puede diferir entre distribuciones). Esto se consigue añadiendo lo siguiente al archivo Makefile.am: mimedir = $(kde_mimedir)/application mime_DATA = foo.desktop EXTRA_DIST = $(mime_DATA) El archivo foo.desktop debería ser similar al siguiente: [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 La entrada Comment debe ser traducida. Como el archivo .desktop especifica un icono, también debe instalar un icono fooicon.png que represente al archivo, por ejemplo, en Konqueror. En las bibliotecas de KDE, este tipo de definición se mapea a una instancia de la clase KMimeType. Use esto como en el siguiente ejemplo: KMimeType::Ptr type = KMimeType::mimeType("application/x-foo"); cout << "Tipo: " << type->name() < endl; cout << "Icono: " << type->icon() < endl; cout << "Comentario: " << type->icon() < endl; QStringList patterns = type->patterns(); QStringList::ConstIterator it; for (it = patterns.begin(); it != patterns.end(); ++it) cout << "Patrón: " << (*it) << endl; El método más rápido para determinar el tipo MIME de un archivo es usar la función KMimeType::findByURL(), 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 .pl, lo que indica un tipo MIME «text/x-perl». No obstante, el archivo entregado por el servidor es la salida de este guión, que normalmente es de tipo HTML. En este caso, KMimeType::findByURL() devuelve el tipo MIME «application/octet-stream» (disponible mediante KMimeType::defaultMimeType()), que indica un fallo al encontrar el tipo MIME. KMimeType::Ptr type = KMimeType::findByURL("/home/bernd/foobar.jpg"); if (type->name() == KMimeType::defaultMimeType()) cout << "No se puede encontrar el tipo" << endl; else cout << "Tipo: " << type->name() << endl; (Este método posee algunos argumentos más, pero no están documentados, así que puede olvidarse de ellos sin más). 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 KMimeMagic, que posee un manejo de errores distinto: KMimeMagicResult *result = KMimeMagic::self()->findFileType("/home/bernd/foobar.jpg"); if (!result || !result->isValid()) cout << "No se puede encontrar el tipo" << endl; else cout << "Tipo: " << result->mimeType() << endl; Como variante de esta función, también puede determinar el tipo de un segmento de memoria. Esto se usa, por ejemplo, en Kate para encontrar el modo de resaltado adecuado: QByteArray array; ... KMimeMagicResult *result = KMimeMagic::self()->findBufferType(array); if (!result || !result->isValid()) cout << "No se puede encontrar el tipo" << endl; else cout << "Tipo: " << result->mimeType() << endl; 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: KURL url("http://developer.kde.org/favicon.ico"); TQString type = TDEIO::NetAccess::mimetype(url); if (type == KMimeType::defaultMimeType()) cout << "No se puede encontrar el tipo" << endl; else cout << "Tipo: " << type << endl; 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 KMimeType::findByURL() ha devuelto «application/octect-stream». 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: void FooClass::findType() { KURL url("http://developer.kde.org/favicon.ico"); TDEIO::MimetypeJob *job = TDEIO::mimetype(url); connect( job, TQ_SIGNAL(result(TDEIO::Job*)), this, TQ_SLOT(mimeResult(TDEIO::Job*)) ); } void FooClass::mimeResult(TDEIO::Job *job) { if (job->error()) job->showErrorDialog(); else cout << "Tipo MIME: " << ((TDEIO::MimetypeJob *)job)->mimetype() << endl; } Cuando se instala una aplicación, se copia un archivo .desktop 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 .desktop 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 KServiceTypeProfile: 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 << "Nombre: " << service->name() << endl; } El valor devuelto por esta función es una lista de ofertas de servicio. Un objeto KServiceOffer empaqueta un KService::Ptr junto a un número de preferencia. La lista devuelta por KServiceTypeProfile::offers() está ordenada según la preferencia del usuario. El usuario puede cambiarla llamando a keditfiletype text/html o seleccionando Editar tipo de archivo en el menú de contexto de Konqueror sobre un archivo HTML. En el ejemplo anterior, se solicitó una lista de las aplicaciones que ofrecen soporte para text/html. Entre otros, esta lista contendrá editores HTML, como Quanta Plus. También puede sustituir el segundo argumento "Application" por "KParts::ReadOnlyPart". En este caso, obtendrá una lista de componentes integrables para visualizar HTML, como TDEHTML. 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: KService::Ptr offer = KServiceTypeProfile::preferredService("text/html", "Application"); if (offer) cout << "Nombre: " << service->name() << endl; else cout << "No se ha encontrado un servicio apropiado" << endl; Para solicitudes aún más complejas existe un «trader» desarrollado de modo similar a CORBA. Para ejecutar una aplicación de servicio con algunas URLs, use KRun: KURL::List urlList; urlList << "http://www.ietf.org/rfc/rfc1341.txt?number=1341"; urlList << "http://www.ietf.org/rfc/rfc2046.txt?number=2046"; KRun::run(offer.service(), urlList); En esta sección listaremos algunas APIs directamente relacionadas con las de la sección anterior. Obtener un icono para una URL. Esto busca el tipo de URL y devuelve el icono asociado. KURL url("ftp://ftp.kde.org/pub/incoming/wibble.c"); TQString icon = KMimeType::iconForURL(url); Ejecutar una URL. Esto busca el tipo de URL y ejecuta el programa preferente del usuario que está asociado a este tipo. KURL url("http://dot.kde.org"); new KRun(url); 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 transparencia de red. 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 asincronismo 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. En las bibliotecas de KDE, la transparencia de red está implementada en la API TDEIO. El concepto central de esta arquitectura es una tarea 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. La operación en segundo plano se realiza mediante el inicio de ioslaves 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. 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 http://www-com.physik.hu-berlin.de/~bernd/article.tgz#tar:/paper.tex 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 result(TDEIO::Job*). Tras emitir esta señal, la tarea se borra a sí misma. De este modo, un caso de uso típico podría ser: void FooClass::makeDirectory() { SimpleJob *job = TDEIO::mkdir(KURL("file:/home/bernd/kiodir")); connect( job, TQ_SIGNAL(result(TDEIO::Job*)), this, TQ_SLOT(mkdirResult(TDEIO::Job*)) ); } void FooClass::mkdirResult(TDEIO::Job *job) { if (job->error()) job->showErrorDialog(); else cout << "mkdir funcionó bien" << endl; } Dependiendo del tipo de tarea, también podrá conectarla a otras señales. Lo que sigue es una introducción a las posibles funciones: TDEIO::mkdir(const KURL &url, int permission) Crea un directorio, opcionalmente con ciertos permisos. TDEIO::rmdir(const KURL &url) Elimina un directorio. TDEIO::chmod(const KURL &url, int permissions) Cambia los permisos de un archivo. TDEIO::rename(const KURL &src, const KURL &dest, bool overwrite) Renombra un archivo. TDEIO::symlink(const TQString &target, const KURL &dest, bool overwrite, bool showProgressInfo) Crea un enlace simbólico. TDEIO::stat(const KURL &url, bool showProgressInfo) 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. TDEIO::get(const KURL &url, bool reload, bool showProgressInfo) Transfiere datos desde un URL. TDEIO::put(const KURL &url, int permissions, bool overwrite, bool resume, bool showProgressInfo) Transfiere datos a un URL. TDEIO::http_post(const KURL &url, const QByteArray &data, bool showProgressInfo) Envía datos. Específica de HTTP. TDEIO::mimetype(const KURL &url, bool showProgressInfo) Intenta encontrar el tipo MIME de un URL. El tipo se puede obtener de TDEIO::MimetypeJob::mimetype() una vez que el trabajo haya finalizado. TDEIO::file_copy(const KURL &src, const KURL &dest, int permissions, bool overwrite, bool resume, bool showProgressInfo) Copia un único archivo. TDEIO::file_move(const KURL &src, const KURL &dest, int permissions, bool overwrite, bool resume, bool showProgressInfo) Renombra o mueve un único archivo. TDEIO::file_delete(const KURL &url, bool showProgressInfo) Elimina un único archivo. TDEIO::listDir(const KURL &url, bool showProgressInfo) Lista el contenido de un directorio. Cada vez que se conozcan nuevas entradas será emitida la señal TDEIO::ListJob::entries(). TDEIO::listRecursive(const KURL &url, bool showProgressInfo) Similar a la función listDir(), aunque esta es recursiva. TDEIO::copy(const KURL &src, const KURL &dest, bool showProgressInfo) Copia un archivo o un directorio. Los directorios se copian recursivamente. TDEIO::move(const KURL &src, const KURL &dest, bool showProgressInfo) Mueve o renombra un archivo o un directorio. TDEIO::del(const KURL &src, bool shred, bool showProgressInfo) Elimina un archivo o un directorio. 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). Actualmente están definidos los siguientes tipos: UDS_SIZE (integer) - Tamaño del archivo. UDS_USER (string) - Usuario al que pertenece el archivo. UDS_GROUP (string) - Grupo al que pertenece el archivo. UDS_NAME (string) - Nombre del archivo. 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. 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. UDS_LINK_DEST (string) - En caso de un enlace simbólico, el nombre del archivo al que apunta. 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(). 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(). 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(). 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. UDS_MIME_TYPE (string) - Tipo MIME del archivo. 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. Aunque la forma de almacenar información sobre los archivos en una UDSEntry 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 m_uds contiene el valor UDS_MIME_TYPE. Afortunadamente, existe una API que es mucho más fácil de usar: la clase KFileItem. 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 KURL origen, destino; origen = ...; destino = ... TDEIO::NetAccess::copy(origen, destino); 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. Existe una combinación de funciones particularmente interesante: download() junto a removeTempFile(). 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). Si 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 removeTempFile() 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: KURL url; url = ...; TQString tempFile; if (TDEIO::NetAccess::download(url, tempFile) { // cargar el archivo de nombre tempFile TDEIO::NetAccess::removeTempFile(tempFile); } 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: void FooClass::reloadPage() { KURL url("http://www.kdevelop.org/index.html"); TDEIO::TransferJob *job = TDEIO::get(url, true, false); job->addMetaData("cache", "reload"); ... } 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 Job::queryMetaData() pregunta por el valor de cierta clave entregada por el esclavo. Para el esclavo HTTP, un ejemplo sería la clave «modified», que contiene la fecha (representada en forma de cadena de texto) de cuando la página web fue modificada por última vez. Por ejemplo: void FooClass::printModifiedDate() { KURL url("http://developer.kde.org/documentation/kde2arch/index.html"); TDEIO::TransferJob *job = TDEIO::get(url, true, false); connect( job, TQ_SIGNAL(result(TDEIO::Job*)), this, TQ_SLOT(transferResult(TDEIO::Job*)) ); } void FooClass::transferResult(TDEIO::Job *job) { TQString mimetype; if (job->error()) job->showErrorDialog(); else { TDEIO::TransferJob *transferJob = (TDEIO::TransferJob*) job; TQString modified = transferJob->queryMetaData("modified"); cout << "Última modificación: " << modified << endl; } 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. 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. 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 directo. 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. Por lo tanto, existe una manera diferente: puede programar 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: KURL url("http://developer.kde.org/documentation/kde2arch/index.html"); TDEIO::TransferJob *job = TDEIO::get(url, true, false); TDEIO::Scheduler::scheduleJob(job); Existe una tercera posibilidad orientada a conexiones. 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: 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); Solo debe desconectar el esclavo una vez que se garantice que han finalizado todos los trabajos que le hayan sido asignados. 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: protocoldir = $(kde_servicesdir) protocol_DATA = ftp.protocol EXTRA_DIST = $(mime_DATA) El contenido del archivo ftp.protocol sería el siguiente: [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 La entrada «protocol» define de qué protocolo se hace responsable este esclavo. La entrada «exec» 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 «tdeinit», 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. Las líneas «input» y «output» no se usan actualmente. Las restantes líneas del archivo .protocol 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 ftp:), TDEIO puede leer el archivo de origen y luego escribir los datos en el archivo de destino. Para que esto funcione, el archivo .protocol debe notificar las acciones que proporciona su esclavo. 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 kdemain(). 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: 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; } Los esclavos se implementan como subclases de TDEIO::SlaveBase (FtpSlave en el ejemplo anterior). De este modo, las acciones que se listan en el archivo .protocol corresponden a ciertas funciones virtuales de TDEIO::SlaveBase que la implementación del esclavo debe reimplementar. Estas son algunas de las posibles acciones y sus correspondientes funciones virtuales: reading - Lee datos desde una URL void get(const KURL &url) writing - Escribe datos en una URL y crea el archivo de destino si no existe. void put(const KURL &url, int permissions, bool overwrite, bool resume) moving - Renombra un archivo. void rename(const KURL &src, const KURL &dest, bool overwrite) deleting - Borra un archivo o directorio. void del(const KURL &url, bool isFile) listing - Lista el contenido de un directorio. void listDir(const KURL &url) makedir - Crea un directorio. void mkdir(const KURL &url, int permissions) Adicionalmente, existen funciones reimplementables que no están listadas en el archivo .protocol. Para estas operaciones, TDEIO determina automáticamente si están soportadas o no (es decir, la implementación por defecto devuelve un error). Entrega información sobre el archivo, similar a la función stat() de C. void stat(const KURL &url) Cambia los permisos de acceso de un archivo. void chmod(const KURL &url, int permissions) Determina el tipo MIME de un archivo. void mimetype(const KURL &url) Copia un archivo. copy(const KURL &url, const KURL &dest, int permissions, bool overwrite) Crea un enlace simbólico. void symlink(const TQString &target, const KURL &dest, bool overwrite) Todas estas implementaciones deben finalizar con una de estas dos llamadas: si la operación fue exitosa, se debería llamar a finished(); si ocurrió un error, error() 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 TDEIO::Error. El segundo argumento suele ser la URL en cuestión. Se usa, por ejemplo, en la función TDEIO::Kob::showErrorDialgog() para parametizar el mensaje de error legible por el usuario. En el caso de los esclavos que se corresponden con protocolos de red, resulta interesante reimplementar el método SlaveBase::setHost(). 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 SlaveBase::metaData(). Puede comprobar la existencia de metadatos para cualquier clave con la función SlaveBase::hasMetaData(). Varias acciones implementadas en un proceso esclavo necesitan algún modo de devolver datos a la aplicación que está usando dicho proceso esclavo: get() envía bloques de datos. Esto se lleva a cabo con data(), que tiene como argumento un QByteArray. Por supuesto, no es necesario que envíe todos los datos al mismo tiempo. Si tiene que enviar un archivo grande, llame a data() con bloques más pequeños de datos, de modo que la aplicación pueda procesarlos. Llame a finished() cuando la transferencia haya terminado. listDir() devuelve información sobre las entradas de un directorio. Para este propósito, llame a listEntries() con una TDEIO::UDSEntryList como argumento. Del mismo modo que ocurría con data(), puede llamar a esta función varias veces. Cuando haya terminado, llame a listEntry() con «true» como segundo parámetro. También puede llamar a totalSize() para devolver el número total de entradas de directorio, si es conocido. stat() devuelve información sobre el archivo, como su tamaño, tipo MIME, etc. Esta información está empaquetada en una TDEIO::UDSEntry, que se describirá más adelante. Use statEntry() para enviar este tipo de elementos a la aplicación. mimetype() llama a mimeType() con un argumento de cadena. get() y copy() pueden necesitar proporcionar información de progreso. Esto se lleva a cabo con los métodos totalSize(), processedSize() y speed(). El tamaño total y el procesado se devuelven en bytes, y la velocidad en bytes por segundo. Puede enviar pares clave/valor de metadatos arbitrarios con setMetaData(). 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. infoMessage() - 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 TDEIO::Job::infoMessage(). warning() - Muestra un aviso en una caja de mensaje con KMessageBox::information(). No ocurre nada si ya hubiera otra caja de mensaje abierta como consecuencia de una llamada anterior a warning() desde el mismo proceso esclavo. messageBox() - 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 SlaveBase::MessageBoxType como referencia. openPassDlg() - Abre un diálogo para introducir el nombre de usuario y la contraseña. &underFDL; &underGPL;