Accessing document contents by programming

Home

4D v17

4D Write Pro provides a full set of commands allowing you to modify text and image attributes in your documents. Thanks to these features, 4D developers can design their own user interfaces (using buttons, menus, check boxes, etc.) for 4D Write Pro documents. Commands can be applied to whole documents or to specific portions (ranges), either based on user selections or custom values. Available properties include document units, margins, padding, background, paragraph settings, colors, fonts, font styles, as well as image properties.

For example, the 4D Write Pro area library object makes extensive use of these features to provide a sophisticated 4D Write Pro interface:

Range handling commands

4D Write Pro allows you to programmatically select and manipulate document contents. Since the selected content can include text, images, tables, etc., and also (invisible) formatting tags, 4D Write Pro works with objects called ranges.

A range is an object that represents a portion of a 4D Write Pro document:

a range of characters, paragraphs, pictures, or tables is defined through character positions within the parent document,
a range of cells, columns and rows is defined through cell positions and are anchored to the parent table.

A range is used to designate elements to be selected or manipulate attributes on a part of the document (using WP GET ATTRIBUTES and WP SET ATTRIBUTES).

There are different types of ranges. You can determine the type of a range using the wk type attribute (read-only). Each range contains several private attributes that define it:

Constant	Value	Comment
wk end	end	(Read-only attribute) Range end offset, or Section or subsection text end index in the document body (for subsection, text end index of the parent section). Value type: Longint
wk owner	owner	(Read-only attribute) Owner of the range/object/section/subsection (reference to the document for section/subsection). Value type: Object
wk start	start	(Read-only attribute) Range start offset, or Section or subsection text start index in the document body (for subsection, text start index of the parent section). Value type: Longint
wk type	type	(Read-only attribute) Type of 4D Write Pro object. Possible values: wk type default: Range or section with not defined type wk type paragraph: Paragraph type range wk type image: Image (anchored and inline) wk type container: Header or footer, for instance wk type table: Table reference For ranges of cells, columns and rows only: wk type table row: Table row reference wk type table cell: Table cell reference wk type table column: Table column reference For subsections only: wk first page: First page subsection wk right page: Right page subsection wk left page: Left page subsection

Note: Ranges of cells, columns and rows contain specific attributes (see paragraph below).

Several commands allow you to define document ranges:

WP Create range returns a new range corresponding to boundaries you passed as parameters.
WP Get selection returns a new range corresponding to the current user selection.
WP Create picture range returns a new range containing only the pictures.
WP Create paragraph range returns a new range containing only the paragraphs.
WP Create table range returns a new range containing only the tables.

You can get information about the position of a range in a document (page number, column number...) using the WP Get position command.

Table commands

4D Write Pro tables are created and built programmatically by using the following commands:

WP Insert table to insert a table and get its reference
WP Table append row to add rows to the table and get the corresponding range
WP Table get rows to get a range of rows
WP Table get columns to get a range of columns (*)
WP Table get cells to get a range of cells

(*) Columns have no equivalent in html. In 4D Write Pro, a column range is actually a range of cells.

The ranges of rows, columns and cells have specific, private attributes allowing to define them:

Constant	Value	Comment
wk column count	columnCount	(Available for tables, documents and sections) Number of columns. Value type: Longint For a table: read-only attribute For a document or a section: read-write attribute. Default value=1 (single column). Maximum value=20
wk first column	firstColumn	(Read-only attribute) Number of the first table column included in the range. Value type: Longint
wk first row	firstRow	(Read-only attribute) Number of the first table row included in the range. Value type: Longint
wk row count	rowCount	(Read-only attribute) Total number of rows. Value type: Longint
wk table ID	tableID	(Read-only attribute) ID of the parent table. Value type: String

Bookmark commands

4D Write Pro allows you to create and work with dynamic references to parts of your documents, called bookmarks. A bookmark is a named reference attached to a specific range in a 4D Write Pro document.

Bookmarks are dynamic, which means that if the user moves, adds or removes text belonging to the bookmark, the associated range will be updated automatically and the bookmark will continue to reference the same content within the document. For example:

You create a bookmark named "MyBM" that references the "Hello world" text on page 20 of your document.
Then you insert 50 pages at the beginning of the document.
You will still be able to access the same "Hello world" text automatically, now on page 70 of the document, by means of the "MyBM" bookmark.

A document can contain an unlimited number of bookmarks. Several bookmarks can reference the same range, and bookmark ranges can be interleaved. However, each bookmark name must be unique in the document. Bookmarks are not imported when using the WP INSERT DOCUMENT command (bookmarks in the destination document cannot be overwritten).

Once created, a bookmark is stored within the document. It is saved with the document, and can be handled by several different commands. It can also be used to reference parts of a template document. These parts can then be assembled automatically with data from the database to produce dynamic output documents such as invoices or catalogs.

Several commands allow you to create, remove, and use bookmarks:

WP CREATE BOOKMARK to create a new bookmark from a range,
WP GET BOOKMARKS to get all bookmarks defined in a document,
WP Get bookmark range to retrieve a range from an existing bookmark,
WP DELETE BOOKMARK to delete a bookmark.

Attribute handling commands

The following commands can get or set any attributes of the document:

WP SET ATTRIBUTES sets one or more attribute/value pairs in the document or range.
WP GET ATTRIBUTES gets the current value of attributes in the document or range.
WP RESET ATTRIBUTES resets attribute values in the document or range.

Attributes are detailed in the 4D Write Pro Attributes section.

Font handling command

This command allows you to get information about style support for a range:

WP Is font style supported allows you to know if a range supports a given style (useful to design an interface).

Handling URLs

4D Write Pro allows you to assign hyperlinks to any range of your document, including ranges of text, paragraph, picture, table rows, or cells. For example, you can set a hyperlink to a picture range; once the 4D Write Pro document is exported to HTML, users can click the picture to open a page at a specified address.

Note: Hyperlinks can be activated from within 4D Write Pro documents using the Ctrl+click (Windows) or Cmd+click (macOS) shortcut.

Hyperlinks are handled as range attributes, and are set or get using the WP SET ATTRIBUTES and WP RESET ATTRIBUTES commands along with the wk link url constant. For example, if you want to transform the text selected by the user to an URL:

You can write:

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

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

Note: 4D Write Pro does not translate the URL's special characters, if any. You need to encode special characters if necessary. If the URL is not valid, an error is generated.

Inserted URLs get the default hyperlink format (underline blue color), unless a text style is already applied to the range.

When handling URLs in your documents, 4D Write Pro applies the following rules:

If you set a link to a range that contains several paragraphs, several separate links will be defined.
If you set a link to a range that already contains link(s):
- any existing links that are fully included in the range are removed and the new link is applied to the range
- if a link is partially selected (it intersects the range), it is reduced so that the external part keeps the previous link and the new link is applied to the range.
When reading links using the WP GET ATTRIBUTES command, the following cases can occur:
- the range contains a single hyperlink: the command returns the url string
- the range contains several hyperlinks: the command returns the first url string
- the range does not contain any hyperlink: the command returns an empty string.
To remove a link from a range, you can do either:
WP RESET ATTRIBUTES($range;wk link url)

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