Acceder a contenidos de documentos por programación

4D v17

4D Write Pro ofrece un conjunto completo de comandos que permiten modificar los atributos de texto e imagen en sus documentos. Gracias a estas funcionalidades, los desarrolladores 4D pueden diseñar sus propias interfaces de usuario (utilizando botones, menús, casillas de verificación, etc.) para documentos 4D Write Pro. Los comandos se pueden aplicar a documentos completos o a partes específicas (rangos), ya sea basado en las selecciones del usuario o valores personalizados. Las propiedades disponibles incluyen unidades, márgenes, rellenos, fondo, configuración de párrafo, colores, fuentes, estilos de fuente, así como también propiedades de imagen del documento.

Por ejemplo, el objeto de la librería Área 4D Write Pro hace un amplio uso de estas funcionalidades para ofrecer una interfaz 4D Write Pro sofisticada:

Comandos de gestión de rangos

4D Write Pro le permite seleccionar y manipular por programación el contenido del documento. Dado que el contenido seleccionado puede incluir texto, imágenes, tablas, etc., y también etiquetas de formato (invisibles), 4D Write Pro funciona con objetos llamados rangos.

Un rango es un objeto que representa una porción de un documento 4D Write Pro:

un rango de caracteres, párrafos, imágenes o tablas se define a través de posiciones de caracteres dentro del documento principal,
un rango de celdas, columnas y filas se define a través de las posiciones de las celdas y están ancladas a la tabla principal.

Puede usarse para designar elementos a seleccionar o manipular atributos en una parte del documento (usando WP GET ATTRIBUTES y WP SET ATTRIBUTES).

Hay diferentes tipos de rangos. Puede determinar el tipo de rango utilizando el atributo wk type (sólo lectura). Cada rango contiene varios atributos privados que lo definen:

Constante	Valor	Comentario
wk end	end	(Atributo de rango de sólo lectura)
wk owner	owner	(Atributo de rango de sólo lectura)
wk start	start	(Atributo de rango de sólo lectura)
wk type	type	(Atributo de rango de sólo lectura) Tipo de rango 4D Write Pro. Puede ser 0: rango por defecto (por defecto), 1: rango párrafo, 2: rango imagen

Nota: los rangos de celdas, columnas y filas contienen atributos específicos (ver el párrafo abajo).

Varios comandos le permiten definir rangos:

WP Create range( wpArea ; inicioRango ; finRango ) -> objRango: devuelve un nuevo rango correspondiente a los límites que pasan como parámetros.
WP Get selection( {*;} wpArea ) -> rangeObj: devuelve un nuevo rango que corresponde a la selección usuario actual.
WP Create picture range( rangeObj ) -> rangeObj: devuelve un nuevo rango que contiene solo las imágenes.
WP Create paragraph range( rangeObj ) -> rangeObj: devuelve un nuevo rango que contiene solo los párrafos.
WP Create table range( rangeObj ) -> rangeObj: devuelve un nuevo rango que contiene solo las tablas.

Puede obtener información sobre la posición de un rango en un documento (número de página, número de columna...) utilizando el comando WP Get position.

Comandos Tabla

Las tablas 4D Write Pro se crean y construyen por programación utilizando los siguientes comandos:

WP Insert table para insertar una tabla y obtener su referencia
WP Table append row para agregar filas a la tabla y obtener el rango correspondiente
WP Table get rows para obtener un rango de filas
WP Table get columns para obtener un rango de columnas (*)
WP Table get cells para obtener un rango de celdas

(*) Las columnas no tienen equivalente en html. En 4D Write Pro, un rango de columnas es en realidad un rango de celdas.

Los rangos de filas, columnas y celdas tienen atributos privados específicos que permiten definirlos:

Constante	Valor	Comentario
wk column count	columnCount	(Atributo de rango de sólo lectura) Número total de columnas del rango. Valor: Entero largo
wk first column	firstColumn	(Atributo de rango de sólo lectura) Número de la primera columna del rango. Valor: Entero largo
wk first row	firstRow	(Atributo de rango de sólo lectura) Número de la primera fila del rango. Valor: Entero largo
wk row count	rowCount	(Atributo de rango de sólo lectura) Número total de columnas en el rango. Valor: Entero largo
wk table ID	tableID	(Atributo de rango de sólo lectura) ID de la tabla principal del rango. Valor: cadena

Comandos Marcadores

4D Write Pro le permite crear y trabajar con referencias dinámicas para intervalos, llamados marcadores. Un marcador es una referencia con nombre asociada a un rango específico en un documento 4D Write Pro.

Los marcadores son dinámicos, lo que significa que si el usuario mueve, añade o elimina del texto el marcador, el rango asociado se actualizará automáticamente y el marcador seguirá haciendo referencia al mismo contenido dentro del documento. Por ejemplo:

Se crea un marcador llamado "MyBM" que hace referencia al texto "Hola mundo" en la página 20 del documento.
Luego, inserta 50 páginas al principio del documento.
Usted aún podrá acceder automáticamente al mismo texto "Hola mundo", ahora en la página 70 del documento, mediante el marcador "MyBM".

Un documento puede contener un número ilimitado de marcadores. Varios marcadores pueden hacer referencia al mismo rango, y los rangos de marcadores pueden ser intercalados. Sin embargo, cada nombre de marcador debe ser único en el documento. Los marcadores no se importan cuando se utiliza el comando WP INSERT DOCUMENT (los marcadores en el documento de destino no pueden ser sobrescritos).

Una vez creado, un marcador se almacena dentro del documento. Se guarda con el documento y puede ser manejado por diferentes comandos. También se puede utilizar para hacer referencia a partes de un documento plantilla. Estas piezas pueden ensamblarse de forma automática con los datos de la base para producir documentos de salida dinámicos tales como facturas o catálogos.

Varios comandos permiten crear, eliminar y utilizar marcadores:

WP CREATE BOOKMARK para crear un nuevo marcador de un rango,
WP GET BOOKMARKS para obtener todos los marcadores definidos en un documento,
WP Get bookmark range para recuperar un rango de un marcador existente,
WP DELETE BOOKMARK para eliminar un marcador.

Comandos de gestión de atributos

Los siguientes nuevos comandos permiten leer o definir los atributos en el documento:

WP SET ATTRIBUTES( objRango | wpDoc ; nomAtrib ; valorAtrib {; nomAtrib2 ; valorAtrib2 ; ... ; nomAtribN ; valorAtribN} ): define uno o más pares atributo/valor en el documento o rango.
WP GET ATTRIBUTES( objRango | wpDoc ; nomAtrib ; attribValue {; nomAtrib2 ; valorAtrib2 ; ... ; nomAtribN ; valorAtribN} ): obtiene el valor actual de los atributos en el documento o rango.
WP RESET ATTRIBUTES( objRango ; nomAtrib {; nomAtrib 2 ; ... ;nomAtribN } ): reinicializa los valores de los atributos en el documento o rango.

Los atributos se detallan en la sección Atributos 4D Write Pro .

Comandos de gestión de fuentes

Este comando le permite obtener información sobre el soporte de estilo para un rango:

WP Is font style supported (objRango ; wpFuenteEstilo) -> true o false: le permite saber si un rango soporta un determinado estilo (útil para diseñar una interfaz).

Gestión de URLs

4D Write Pro le permite asignar hipervínculos a todo rango de su documento, incluyendo rangos de texto, párrafo, imagen, filas de tabla o celdas. Por ejemplo, puede definir un hipervínculo a un rango imagen; Una vez que el documento 4D Write Pro se exporta a HTML, los usuarios pueden hacer clic en la imagen para abrir una página en una dirección especifica.

Nota: los hipervínculos se pueden activar desde los documentos de 4D Write Pro utilizando el atajo Ctrl+clic (Windows) o Cmd+clic (macOS).

Los hipervínculos se manejan como atributos de rango y se definen u obtienen utilizando los comandos WP SET ATTRIBUTES y WP RESET ATTRIBUTES junto con la constante wk link url. Por ejemplo, si desea transformar el texto seleccionado por el usuario en una URL:

Puede escribir:

 $range:=WP Get selection(*;"WParea")

 WP SET ATTRIBUTES($range;wk link url;"http://doc.4d.com")

Nota: 4D Write Pro no traduce los caracteres especiales de la URL, si los hay. Debe codificar caracteres especiales si es necesario. Si la URL no es válida, se genera un error.

Las URL insertadas obtienen el formato de hipervínculo predeterminado (color azul subrayado), a menos que un estilo de texto ya se haya aplicado al rango.

Al manejar direcciones URL en sus documentos, 4D Write Pro aplica las siguientes reglas:

Si define un vínculo a un rango que contiene varios párrafos, se definirán varios enlaces independientes.
Si define un enlace a un rango que ya contiene enlaces:
- Se eliminan todos los enlaces existentes que se incluyen totalmente en el rango y se aplica el nuevo enlace al rango
- Si se selecciona parcialmente un enlace (se intersecta el rango), se reduce de modo que la parte externa mantiene el enlace anterior y el nuevo enlace se aplica al rango.
Cuando se leen enlaces utilizando el comando WP GET ATTRIBUTES, pueden producirse los siguientes casos:
- El rango contiene un solo hipervínculo: el comando devuelve la cadena url
- El rango contiene varios hipervínculos: el comando devuelve la primera cadena de url
- El rango no contiene ningún hipervínculo: el comando devuelve una cadena vacía.
Para eliminar un vínculo de rango, puede hacer lo siguiente:
WP RESET ATTRIBUTES($range;wk link url)

o
WP SET ATTRIBUTES($range;wk link url;"")

Ver también