The fax PageText property

class PageText

This class provides the option to add a simple line of text to a fax page. Typically, this would be a brief banner, a page number, or the date. An object of this type must first be created by calling the create_page_text function on the fax document object.

Text can be added to three different positions on a page at the same time; the left hand side; the right hand side; or the middle. The default text for each position is None, i.e., no text.

Text must be added to an existing page. This class cannot be used to create a new page.

The options provided are:

left_text

Add text starting at the left margin.

right_text

Add text ending at the right margin; this may be truncated so as not to overlap left_text.

centre_text

Add text in the middle; but may be moved or truncated to avoid both left_text and right_text.

position

This option is of type PageTextPosition. It provides settings for positioning the text on the page.

mode

This option is of type PageTextMode. It describes the method of adding text to the page.

Usage example:

# create a page text object
page_text = my_fax.create_page_text()

# add some text at the left margin of the first page
page_text.left_text = 'This is a fax from Bob'
my_fax.add_text_to_page(1, page_text)

class PageTextMode

The method used when adding text to a page. The PageText object returned by the create_page_text function exposes a property mode of this type.

The available options are:

INSERT

Adds the text by moving the remainder of the page down.

REPLACE

Overwrites the existing lines. Replaces the whole line.

MERGE

Adds the text to the existing lines.

Usage example:

# create a page text object
page_text = my_fax.create_page_text()

# set mode to REPLACE
page_text.mode = page_text.PageTextMode.REPLACE

class PageText.PageTextPosition

This provides options for positioning the line of text on the page. The PageText object returned by the create_page_text function exposes a property position of this type.

unit

This is the unit used when calculating margin and from_page_top. It is of type PagePositionUnits.

from_page_top

This is the offset of the top of the line of text from the top of the page. A value representing a number of units. The default value is 2.54 centimetres. Note that there is no limit to the length of a fax page, so if from_page_top is larger than the existing length of the page, the page length will simply grow to accommodate it. Be careful when doing this. A large gap between the bottom of the existing page and the text to be added could cause the receiving fax machine to fill the gap with blank pages.

margin

This is the size of both the left and right margin. A value representing a number of units. The default value is 0.8.

Usage example:

# create a page text object
page_text = my_fax.create_page_text()

# set text to be one inch from the top
page_text.Position.unit = page_text.Position.PagePositionUnits.INCHES
page_text.Position.from_page_top = 1

class PagePositionUnits

The unit used when calculating the position of text on a page. The class PageTextPosition exposes a property unit of this type.

The available units are:

• PIXELS
• INCHES
• CENTIMETRES

The default value is CENTIMETRES.

Usage example:

# create a page text object
page_text = my_fax.create_page_text()

# set units to INCHES
page_text.Position.unit = page_text.Position.PagePositionUnits.INCHES