Accéder au contenu des documents par programmation

4D v17

4D Write Pro propose un ensemble complet de commandes de langage vous permettant de modifier les attributs de texte et d'image de vos documents. Grâce à ces fonctionnalités, les développeurs 4D peuvent concevoir leurs propres interfaces (à l'aide de boutons, menus, cases à cocher, etc.) pour les documents 4D Write Pro. Les commandes peuvent s'appliquer à tout le document ou uniquement à certaines parties, basées soit sur la sélection utilisateur, soit sur des sélections créées par programmation. Les attributs disponibles incluent les unités du document, les marges internes et externes, les arrière-plans, les propriétés des paragraphes, couleurs, polices, styles, ainsi que les propriétés des images.

Par exemple, l'objet de la bibliothèque Zone 4D Write Pro s'appuie sur toutes ces fonctionnalités pour proposer une interface de zone 4D Write Pro complète et sophistiquée :

Gestion des plages

4D Write Pro permet de sélectionner et de manipuler par programmation les contenus des documents. Comme le contenu sélectionné peut inclure du texte, des images, des tableaux, etc, et également des balises (invisibles) de formatage, 4D Write Pro travaille avec des objets appelés plages.

Une plage est un objet qui représente une portion de document 4D Write Pro :

Une plage de caractères, de paragraphes, d'images ou de tableaux est définie grâce à l'emplacement des caractères dans le document parent,
Une plage de cellules, de colonnes et de lignes est définie grâce à l'emplacement des cellules et sont ancrées au tableau parent.

Une plage est utilisée pour désigner les éléments à sélectionner ou pour manipuler des attributs sur une partie du document (à l'aide des commandes WP GET ATTRIBUTES et WP SET ATTRIBUTES).

Il existe différents types de plages. Vous pouvez connaître le type d'une plage à l'aide de l'attribut wk type (en lecture seule). Chaque plage contient plusieurs attributs privés qui la définissent :

Constante	Valeur	Comment
wk end	end	(Attribut de plage en lecture seule) Position fin de plage. Valeur : entier long
wk owner	owner	(Attribut en lecture seule) Possesseur de la plage. Valeur : objet
wk start	start	(Attribut de plage en lecture seule) Position début de plage. Valeur : entier long
wk type	type	(Attribut de plage en lecture seule) Type d'objet 4D Write Pro. Valeurs possibles : wk type default : Plage sans type défini wk type paragraph : Plage de type paragraphe wk type image : Image (ancrée ou en ligne) wk type image anchored : Image ancrée wk type image inline : Image en ligne wk type container : En-tête ou pied, par exemple wk type table : Référence de tableau wk type table row : Référence de ligne de tableau wk type table cell : Référence de cellule de tableau wk type table column : Référence de colonne de tableau (uniquement pour plage colonne) wk type body : Référence de corps (body)

Note : Les plages de cellules, de colonnes et de lignes contiennent des attributs spécifiques (cf. paragraphe ci-dessous).

Plusieurs commandes vous permettent de définir les plages d'un document :

WP Create range retourne une nouvelle plage correspondant aux limites que vous avez passées en paramètres.
WP Get selection retourne une nouvelle plage correspondant à la sélection utilisateur courante.
WP Create picture range retourne une nouvelle plage contenant uniquement les images.
WP Create paragraph range retourne une nouvelle plage contenant uniquement les paragraphes.
WP Create table range retourne une nouvelle plage contenant uniquement les tableaux.

Vous pouvez obtenir des informations sur l'emplacement d'une plage dans un document (numéro de page, numéro de colonne...) à l'aide de la commande WP Get position.

Gestion des tableaux

Les tableaux 4D Write Pro sont créés et construits par programmation à l'aide des commandes suivantes :

WP Insert table pour insérer un tableau et obtenir sa référence
WP Table append row pour ajouter des lignes au tableau et obtenir la plage correspondante
WP Table get rows pour obtenir une plage de lignes
WP Table get columns pour obtenir une plage de colonnes(*)
WP Table get cells pour obtenir une plage de cellules

(*) Les colonnes n'ont pas d'équivalent en html. Dans 4D Write Pro, une plage de colonne est en réalité une plage de cellules.

Les plages de lignes, colonnes et cellules disposent d'attributs privés spécifiques permettant de les définir :

Constante	Valeur	Comment
wk column count	columnCount	(Disponible pour les tableaux, les documents les sections) Nombre de colonnes. Type de valeur : Entier long Pour un tableau : attribut en lecture seulement Pour un document ou une section : attribut en lecture/écriture. Valeur par défaut=1 (colonne unique). Valeur maximum=20
wk first column	firstColumn	(Attribut en lecture seule) Numéro de la première colonne du tableau incluse dans la plage. Valeur : Entier long
wk first row	firstRow	(Attribut en lecture seule) Numéro de la première ligne du tableau incluse dans la plage. Valeur : Entier long
wk row count	rowCount	(Attribut en lecture seule) Nombre total de lignes. Valeur : Entier long
wk table ID	tableID	(Attribut en lecture seule) ID du tableau parent. Valeur : Chaîne

Gestion des signets

4D Write Pro vous permet de créer et de manipuler des références dynamiques sur des parties de vos documents, appelées signets. Un signet est une référence nommée associée à une plage spécifique dans un document 4D Write Pro.

Les signets sont dynamiques, ce qui signifie que si l'utilisateur déplace, ajoute ou supprime du texte appartenant au signet, la plage associée sera automatiquement mise à jour et le signet continuera de référencer le même contenu dans le document. Par exemple :

Vous créez un signet nommé "MyBM" qui référence la plage de texte "Hello world" à la page 20 de votre document.
Puis vous insérez 50 pages au début du document.
Vous pouvez toujours accéder automatiquement au même contenu "Hello world", maintenant à la page 70 du document, par l'intermédiaire du signet "MyBM".

Un document peut contenir un nombre illimité de signets. Plusieurs signets peuvent référencer la même plage, et les plages des signets peuvent être entrelacées. Cependant, chaque nom de signet doit être unique dans le document. Les signets ne sont pas importés lorsque la commande WP INSERT DOCUMENT est utilisée (les signets dans le document de destination ne peuvent pas être écrasés).

Une fois créé, un signet est stocké dans le document. Il est enregistré avec le document, et peut être manipulé par différentes commandes.

Les signets peuvent être utilisés pour référencer des parties d'un document modèle (template). Ces parties peuvent alors être automatiquement assemblées avec des données de la base afin de générer des documents finaux tels que des catalogues ou des factures.

Plusieurs commandes vous permettent de créer, supprimer et utiliser les signets :

WP CREATE BOOKMARK pour créer un signet à partir d'une plage,
WP GET BOOKMARKS pour récupérer tous les signets définis dans le document,
WP Get bookmark range pour récupérer une plage depuis un signet existant,
WP DELETE BOOKMARK pour supprimer un signet.

Gestion des attributs

Les commandes suivantes permettent de lire et de fixer tout attribut dans le document :

WP SET ATTRIBUTES fixe une ou plusieurs paires attribut/valeur dans le document ou la plage.
WP GET ATTRIBUTES lit la valeur courante d'un ou plusieurs attribut(s) dans le document ou la plage.
WP RESET ATTRIBUTES réinitialise la valeurs d'attribut(s) dans le document ou la plage.

Les attributs sont détaillés dans la section Attributs 4D Write Pro.

Gestion des polices

Une commande vous permet d'obtenir des informations sur la prise en charge des styles dans une plage :

WP Is font style supported vous permet de savoir si une plage prend en charge un style de police spécifique (utile pour concevoir une interface).

Gestion des URLs

4D Write Pro vous permet d'associer un lien hypertexte à n'importe quelle plage de votre document (texte, paragraphe, image, colonne, cellule de tableau...). Par exemple, vous pouvez définir un lien pour une plage de type image ; une fois le document 4D Write Pro exporté en HTML, les utilisateurs pourront cliquer sur l'image et ouvrir la page Web qui correspond à l'adresse du lien.

Note : Les liens hypertexte peuvent être activés directement depuis les documents 4D Write Pro via Ctrl+clic (Windows) ou Commande+clic (macOS).

Les liens hypertexte sont gérés par 4D Write Pro en tant qu'attributs de plage, et sont définis ou lus à l'aide des commandes WP SET ATTRIBUTES et WP RESET ATTRIBUTES, associées à la constante wk link url. Par exemple, si vous voulez transformer en URL le texte sélectionné par l'utilisateur :

Vous pouvez écrire :

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

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

Note : 4D Write Pro ne traduit pas les caractères spéciaux des URLs, s'il y en a. Vous devez vous charger de l'encodage des caractères spéciaux. Si l'URL n'est pas valide, une erreur est générée.

Les liens insérés adoptent le format par défaut des liens hypertexte (couleur bleue et souligné), sauf si un style de texte est déjà appliqué à la plage.

Pour le traitement des URLs dans vos documents, 4D Write Pro applique les règles suivantes :

Si vous associez un lien à une plage qui contient plusieurs paragraphes, plusieurs liens individuels seront créés.
Si vous associez un lien à une plage qui contient déjà un ou plusieurs lien(s) :
- si un lien existant est entièrement inclus dans la plage, il est supprimé et le nouveau lien est appliqué à la plage
- si un lien est partiellement sélectionné (intersection avec la plage), il est réduit de manière à ce que la partie extérieure conserve le lien précédent et que le nouveau lien soit appliqué à la partie intérieure.
Lors de la lecture de liens avec la commande WP GET ATTRIBUTES, les cas suivants peuvent se produire :
- la plage contient un seul lien : la commande retourne la chaîne de l'URL
- la plage contient plusieurs liens : la commande retourne la chaîne du premier URL
- la plage ne contient aucun lien : la commande retourne une chaîne vide.
Pour supprimer un lien dans une plage, vous pouvez appeler :
WP RESET ATTRIBUTES($range;wk link url)

ou bien :
WP SET ATTRIBUTES($range;wk link url;"")

Voir aussi