Accéder au contenu des documents par programmation

4D v20 R7

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 Text range retourne une nouvelle plage correspondant aux limites que vous avez passées en paramètres.
WP Selection range retourne une nouvelle plage correspondant à la sélection utilisateur courante.
WP Picture range retourne une nouvelle plage contenant uniquement les images.
WP Paragraph range retourne une nouvelle plage contenant uniquement les paragraphes.
WP 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 cell count	cellCount	Nombre total de cellules dans la ligne. Type de valeur : Entier long (valeur pour wk type table row)
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 header row count	headerRowCount	(Lecture/Écriture) Nombre de lignes du tableau pour lesquelles l'attribut wk header est défini sur True. La valeur maximale est 5. Si vous indiquez une valeur supérieure à 5, wk header est défini sur True pour les cinq premières lignes uniquement (voir Répétition des en-têtes).
wk row count	rowCount	(Attribut en lecture seule) Nombre total de lignes. Valeur : Entier long
wk table	table	(Attribut en lecture seule) La table parente. Type de valeur : Objet
wk table ID	tableID	(Attribut en lecture seule) ID du tableau parent. Valeur : Chaîne

Commandes de sections et sous-sections

Comme indiqué dans le paragraphe Gestion des en-têtes, pieds de pages et sections, les documents 4D Write Pro peuvent contenir :

une ou plusieurs sections (une section par défaut)
jusqu'à trois sous-sections par section :
- sous-section de première page
- sous-section de(s) page(s) de gauche
- sous-section de(s) page(s) de droite

Les sections et sous-sections sont des objets qui peuvent être gérés par programmation à l'aide des commandes suivantes :

Notez également que des en-têtes et pieds de page spécifiques peuvent être associés à des sections ou des sous-sections, à l'aide des commandes suivantes :

Les objets section et sous-section prennent en charge les attributs suivants :

Des attributs génériques (hérités par défaut) : Fond, Bordures, Marges intérieures (padding) et Configuration
Des attributs spécifiques : Sections et sous-sections

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 NEW 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 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 liens

4D Write Pro vous permet d'associer des liens hypertexte à n'importe quel objet cible de votre document, y compris à des plages (texte, image, etc.), à des éléments (tableau, corps, pied, etc.), ou au document intégral. Par exemple, vous pouvez définir un hyperlien URL pour une plage de type image ; si le document 4D Write Pro est exporté en HTML, les utilisateurs pourront cliquer sur l'image et ouvrir la page Web qui correspond à l'adresse du lien.

Les liens hypertexte peuvent également être activés directement depuis les documents 4D Write Pro à l'aide des raccourcis Ctrl+clic (Windows) ou Commande+clic (macOS). Dans un document 4D Write Pro non saisissable, un lien peut être activé par un simple clic.

4D Write Pro prend en charge les types de liens suivants :

Type de lien	Description
url	Crée des liens vers des pages web ou à tout type de document, ou bien ouvre l'application associée lorsqu'il est activé (). L'activation d'un lien URL vers un document 4D Write Pro (.4wp, .4w7) remplace le document courant dans la zone 4D Write Pro. () tout comme la commande OPEN URL.
signet	Crée des liens vers les signets du document
méthode	L'association d'un lien à une méthode 4D exécute la méthode (sous réserve d'être enregistré par la méthode SET ALLOWED METHODS).

Les liens hypertexte sont gérés via les commandes suivantes :

WP SET LINK pour insérer un lien à l'aide de l'objet cible
WP Get links pour lire la collection de tous les liens dans un objet cible.

Note : Les liens sont gérés en tant qu'attributs, ils peuvent donc être définis ou lus à l'aide des commandes WP SET ATTRIBUTES et WP GET ATTRIBUTES associées à la constante wk link url. Toutefois, il est recommandé d'utiliser les commandes WP SET LINK et WP Get links, puisqu'elles encodent/décodent automatiquement les liens hypertexte sous forme d'URL. Lorsque les liens sont lus à l'aide de la commande WP GET ATTRIBUTES, si l'objet cible contient plusieurs liens, la commande retourne la chaine du premier lien.

Par exemple, si vous souhaitez transformer le texte sélectionné par l'utilisateur en URL :

Vous pouvez écrire :

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

 WP SET LINK($range;New object("url";"http://www.4d.com"))

Pour supprimer un lien dans un objet cible, vous pouvez écrire :

WP RESET ATTRIBUTES($range;wk link url)

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

Note : Si $range ne contient pas le lien complet, ce dernier est tronqué mais n'est pas entièrement supprimé.

Commandes feuilles de style

Une feuille de style est un objet composé d'un ensemble de paramètres d'attributs définis pour gérer l'apparence de vos documents 4D Write Pro. Ces paramètres peuvent s'appliquer aux paragraphes et aux caractères, tels que la police à afficher, sa taille, sa couleur et son poids. Une fois la feuille de style définie, elle est sauvegardée en tant qu'objet dans le document 4D Write Pro afin d'être réutilisée facilement. Les feuilles de style vous permettent de donner à vos documents un aspect unique et distinctif, tout en gagnant du temps et au moindre effort.

Style par défaut

Tous les documents 4D Write Pro ont une feuille de style de paragraphe par défaut nommée "Normal". De nouvelles feuilles de style (créées à l'aide de la commande WP New style sheet) sont héritées automatiquement du style Normal. Les attributs modifiés par une feuille de style ont uniquement une incidence sur les paragraphes auxquels ils s'appliquent, le reste des documents conserve les paramètres par défaut (Normal). Si une feuille de style est supprimée, les attributs qui ont été modifiés reprendront le style Normal.

Le style Normal définit une valeur par défaut à chaque feuille de style dans un document 4D Write Pro et peut être récupéré à l'aide de la commande WP Get style sheet. La feuille de style Normal peut être modifiée (mais ne peut pas être renommée) à l'aide de la commande WP SET ATTRIBUTES. Si les feuilles de style créées avec la commande WP New style sheet peuvent être supprimées avec la commande WP DELETE STYLE SHEET, la feuille de style Normal ne peut pas être supprimée.

Attributs des feuilles de style de paragraphe et de caractère

Les feuilles de style vous permettent de définir les attributs de paragraphes entiers ou de caractères spécifiques :

Paragraphe - La majorité des attributs pouvant être modifiés s'appliquent uniquement aux paragraphes. Les feuilles de style de paragraphe incluent les paramètres de style de caractère ainsi que les attributs de formatage qui ne peuvent s'appliquer qu'au niveau des paragraphes (ex : marges, bordures, tabulations, etc.).
Caractère - Les feuilles de style de caractère utilisent uniquement les attributs appropriés pour distinguer le style du texte (un ou plusieurs caractères) du style du paragraphe (ex : en-têtes, titres, texte surligné, etc.).

A noter que les styles de paragraphe s'appliquent à l'ensemble des paragraphes. Si vous souhaitez appliquer un style uniquement à une partie spécifique du paragraphe, vous devez utiliser une feuille de style de caractère.

Priorité des feuilles de style

Plusieurs feuilles de style de paragraphe et de caractère peuvent être intégrées au document 4D Write Pro. Il est important de noter que la priorité des feuilles de style est déterminée selon l'ordre dans lequel elles s'appliquent :

Si vous appliquez une feuille de style de paragraphe suivie d'une feuille de style de caractère, la feuille de style de caractère sera prioritaire par rapport à la feuille de style de paragraphe. Par exemple, vous pouvez appliquer une feuille de style de paragraphe au corps de votre document et créer ensuite une feuille de caractère "gras" et l'appliquer à certains mots. La feuille de style de paragraphe continuera de s'appliquer au reste du texte, mais la feuille de style de caractère sera prooritaire pour les mots qui avaient été désignés.
Si vous appliquez une feuille de style de caractère suivie d'une feuille de style de paragraphe, la feuille de style de paragraphe s'appliquera à l'ensemble du texte et tous les style de caractères liés à la feuille de style de caractère seront supprimés.

Appliquer les feuilles de style

Les feuilles de style s'appliquent à l'aide de la commande WP SET ATTRIBUTES et des constantes wk style sheet ou wk new line style sheet (ou à l'aide de la notation objets). Pour plus d'informations, consultez Attributs 4D Write Pro.

Récupérer les feuilles de style

La commande WP Get style sheets vous permet de récupérer toutes les feuilles de style d'un document en fonction de leur type. La commande WP Get style sheet vous permet de récupérer une feuille de style via son nom.

Importer et exporter des feuilles de style

Les feuilles de style étant stockées sous forme d'objets, elles peuvent être facilement importées dans d'autres documents 4D Write Pro ou maintenues lorsqu'elles sont exportées sous plusieurs formats.

Import - Vous pouvez obtenir tous les objets de la feuille de style à partir d'un document 4D Write Pro spécifique et les utiliser dans un nouveau document à l'aide de la commande WP IMPORT STYLE SHEETS.
Export - Les commandes WP EXPORT DOCUMENT ou WP EXPORT VARIABLE exportent vos documents avec leurs feuilles de style.

Attributs des feuilles de style

Les attributs de paragraphe et de caractère ci-dessous peuvent être modifiés à l'aide des commandes WP SET ATTRIBUTES et WP RESET ATTRIBUTES, ou récupérés à l'aide de la commande WP GET ATTRIBUTES.

Note : Certains attributs sont liés. Ainsi, lorsque vous ajoutez l'un de ces attributs, les autres attributs qui sont liés seront également créés avec les valeurs par défaut. La valeur par défaut des attributs liés peut être différente de la valeur définie dans la feuille de style Normal. Par exemple, si vous définissez uniquement une bordure gauche de couleur rouge, les autres bordures seront noires (valeur par défaut) même si les bordures de la feuille de style Normal étaient précédemment définies comme violettes.

Attributs	Paragraphe	Caractère	Lié à
wk avoid widows and orphans	X
wk background clip	X
wk background color	X	X
wk background height	X		wk background width
wk background image	X
wk background image url	X
wk background origin	X
wk background position horizontal	X		wk background position vertical
wk background position vertical	X		wk background position horizontal
wk background repeat	X
wk background width	X		wk background height
wk border color	X		wk border color bottom, wk border color left, wk border color right, wk border color top
wk border color bottom	X		wk border color, wk border color left, wk border color right, wk border color top
wk border color left	X		wk border color, wk border color bottom, wk border color right, wk border color top
wk border color right	X		wk border color, wk border color bottom, wk border color left, wk border color top
wk border color top	X		wk border color, wk border color bottom, wk border color left, wk border color right
wk border radius	X
wk border style	X		wk border style bottom, wk border style left, wk border style right, wk border style top
wk border style bottom	X		wk border style, wk border style left, wk border style right, wk border style top
wk border style left	X		wk border style, wk border style bottom, wk border style right, wk border style top
wk border style right	X		wk border style, wk border style bottom, wk border style left, wk border style top
wk border style top	X		wk border style, wk border style, wk border style bottom, wk border style left
wk border width	X		wk border width bottom, wk border width left, wk border width right, wk border width top
wk border width bottom	X		wk border width, wk border width left, wk border width right, wk border width top
wk border width left	X		wk border width, wk border width bottom, wk border width right, wk border width top
wk border width right	X		wk border width, wk border width bottom, wk border width left, wk border width top
wk border width top	X		wk border width, wk border width bottom, wk border width left, wk border width right
wk direction	X
wk font	X	X	wk font bold, wk font italic, wk font size
wk font bold	X	X	wk font, wk font family, wk font italic, wk font size
wk font family	X	X	wk font, wk font bold, wk font italic, wk font size
wk font italic	X	X	wk font, wk font bold, wk font family, wk font size
wk font size	X	X	wk font, wk font bold, wk font family, wk font italic
wk line height	X
wk list font	X
wk list string format LTR	X
wk list string format RTL	X
wk list style image	X
wk list style image height	X
wk list style image url	X
wk list style type	X
wk margin	X		wk margin bottom, wk margin left, wk margin right, wk margin top
wk margin bottom	X		wk margin, wk margin left, wk margin right, wk margin top
wk margin left	X		wk margin, wk margin bottom, wk margin right, wk margin top
wk margin right	X		wk margin, wk margin bottom, wk margin left, wk margin top
wk margin top	X		wk margin, wk margin bottom, wk margin left, wk margin right
wk min height	X
wk min width	X
wk name	X	X
wk new line style sheet	X
wk owner	X	X
wk padding	X		wk padding bottom, wk padding left, wk padding right, wk padding top
wk padding bottom	X		wk padding, wk padding left, wk padding right, wk padding top
wk padding box	X
wk padding left	X		wk padding, wk padding bottom, wk padding right, wk padding top
wk padding right	X		wk padding, wk padding bottom, wk padding left, wk padding top
wk padding top	X		wk padding, wk padding bottom, wk padding left, wk padding right
_o_wk page break inside	X
wk tab default	X		wk tabs, wk tab stop offsets, wk tab stop types, wk tab stop leadings
wk tabs	X		wk tab default, wk tab stop offsets, wk tab stop types, wk tab stop leadings
wk tab stop offsets	X		wk tabs, wk tab default, wk tab stop types, wk tab stop leadings
wk tab stop types	X		wk tabs, wk tab default, wk tab stop offsets, wk tab stop leadings
wk tab stop leadings	X		wk tabs, wk tab default, wk tab stop offsets, wk tab stop types
wk text align	X
wk text color	X	X
wk text indent	X
wk text linethrough color	X	X
wk text linethrough style	X	X	wk text underline style
wk text shadow color	X	X	wk text shadow offset
wk text shadow offset	X	X	wk text shadow color
wk text transform	X	X
wk text underline color	X	X
wk text underline style	X	X	wk text linethrough style
wk type	X (lecture seule)	X (lecture seule)
wk vertical align	X	X
wk width	X

Voir aussi

Download HDI database