Text-related objects

TextFrame objects

class pptx.text.text.TextFrame

The part of a shape that contains its text.

Not all shapes have a text frame. Corresponds to the <p:txBody> element that can appear as a child element of <p:sp>. Not intended to be constructed directly.

add_paragraph()

Return new _Paragraph instance appended to the sequence of paragraphs contained in this text frame.

property auto_size

The type of automatic resizing that should be used to fit the text of this shape within its bounding box when the text would otherwise extend beyond the shape boundaries. May be None, MSO_AUTO_SIZE.NONE, MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT, or MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE.

clear()

Remove all paragraphs except one empty one.

fit_text(font_family='Calibri', max_size=18, bold=False, italic=False, font_file=None)

Fit text-frame text entirely within bounds of its shape.

Make the text in this text frame fit entirely within the bounds of its shape by setting word wrap on and applying the “best-fit” font size to all the text it contains. TextFrame.auto_size is set to MSO_AUTO_SIZE.NONE. The font size will not be set larger than max_size points. If the path to a matching TrueType font is provided as font_file, that font file will be used for the font metrics. If font_file is None, best efforts are made to locate a font file with matchhing font_family, bold, and italic installed on the current system (usually succeeds if the font is installed).

property margin_bottom

Length value representing the inset of text from the bottom text frame border. pptx.util.Inches() provides a convenient way of setting the value, e.g. text_frame.margin_bottom = Inches(0.05).

property margin_left

Inset of text from left text frame border as Length value.

property margin_right

Inset of text from right text frame border as Length value.

property margin_top

Inset of text from top text frame border as Length value.

property paragraphs

Immutable sequence of _Paragraph instances corresponding to the paragraphs in this text frame. A text frame always contains at least one paragraph.

property text

Unicode/str containing all text in this text-frame.

Read/write. The return value is a str (unicode) containing all text in this text-frame. A line-feed character ("\n") separates the text for each paragraph. A vertical-tab character ("\v") appears for each line break (aka. soft carriage-return) encountered.

The vertical-tab character is how PowerPoint represents a soft carriage return in clipboard text, which is why that encoding was chosen.

Assignment replaces all text in the text frame. The assigned value can be a 7-bit ASCII string, a UTF-8 encoded 8-bit string, or unicode. A bytes value (such as a Python 2 str) is converted to unicode assuming UTF-8 encoding. A new paragraph is added for each line-feed character ("\n") encountered. A line-break (soft carriage-return) is inserted for each vertical-tab character ("\v") encountered.

Any control character other than newline, tab, or vertical-tab are escaped as plain-text like “_x001B_” (for ESC (ASCII 32) in this example).

property vertical_anchor

Read/write member of MSO_VERTICAL_ANCHOR enumeration or None, representing the vertical alignment of text in this text frame. None indicates the effective value should be inherited from this object’s style hierarchy.

property word_wrap

Read-write setting determining whether lines of text in this shape are wrapped to fit within the shape’s width. Valid values are True, False, or None. True and False turn word wrap on and off, respectively. Assigning None to word wrap causes any word wrap setting to be removed from the text frame, causing it to inherit this setting from its style hierarchy.

Font objects

The Font object is encountered as a property of _Run, _Paragraph, and in future other presentation text objects.

class pptx.text.text.Font

Character properties object, providing font size, font name, bold, italic, etc. Corresponds to <a:rPr> child element of a run. Also appears as <a:defRPr> and <a:endParaRPr> in paragraph and <a:defRPr> in list style elements.

property bold

Get or set boolean bold value of Font, e.g. paragraph.font.bold = True. If set to None, the bold setting is cleared and is inherited from an enclosing shape’s setting, or a setting in a style or master. Returns None if no bold attribute is present, meaning the effective bold value is inherited from a master or the theme.

color

The ColorFormat instance that provides access to the color settings for this font.

fill

FillFormat instance for this font, providing access to fill properties such as fill color.

property italic

Get or set boolean italic value of Font instance, with the same behaviors as bold with respect to None values.

property language_id

Get or set the language id of this Font instance. The language id is a member of the MSO_LANGUAGE_ID enumeration. Assigning None removes any language setting, the same behavior as assigning MSO_LANGUAGE_ID.NONE.

property name

Get or set the typeface name for this Font instance, causing the text it controls to appear in the named font, if a matching font is found. Returns None if the typeface is currently inherited from the theme. Setting it to None removes any override of the theme typeface.

property size

Read/write Length value or None, indicating the font height in English Metric Units (EMU). None indicates the font size should be inherited from its style hierarchy, such as a placeholder or document defaults (usually 18pt). Length is a subclass of int having properties for convenient conversion into points or other length units. Likewise, the pptx.util.Pt class allows convenient specification of point values:

>> font.size = Pt(24)
>> font.size
304800
>> font.size.pt
24.0

property underline

Read/write. True, False, None, or a member of the MSO_TEXT_UNDERLINE_TYPE enumeration indicating the underline setting for this font. None is the default and indicates the underline setting should be inherited from the style hierarchy, such as from a placeholder. True indicates single underline. False indicates no underline. Other settings such as double and wavy underlining are indicated with members of the MSO_TEXT_UNDERLINE_TYPE enumeration.

_Paragraph objects

class pptx.text.text._Paragraph

Paragraph object. Not intended to be constructed directly.

add_line_break()

Add line break at end of this paragraph.

add_run()

Return a new run appended to the runs in this paragraph.

property alignment

Horizontal alignment of this paragraph, represented by either a member of the enumeration PP_PARAGRAPH_ALIGNMENT or None. The value None indicates the paragraph should ‘inherit’ its effective value from its style hierarchy. Assigning None removes any explicit setting, causing its inherited value to be used.

clear()

Remove all content from this paragraph. Paragraph properties are preserved. Content includes runs, line breaks, and fields.

property font

Font object containing default character properties for the runs in this paragraph. These character properties override default properties inherited from parent objects such as the text frame the paragraph is contained in and they may be overridden by character properties set at the run level.

property level

Read-write integer indentation level of this paragraph, having a range of 0-8 inclusive. 0 represents a top-level paragraph and is the default value. Indentation level is most commonly encountered in a bulleted list, as is found on a word bullet slide.

property line_spacing

Numeric or Length value specifying the space between baselines in successive lines of this paragraph. A value of None indicates no explicit value is assigned and its effective value is inherited from the paragraph’s style hierarchy. A numeric value, e.g. 2 or 1.5, indicates spacing is applied in multiples of line heights. A Length value such as Pt(12) indicates spacing is a fixed height. The Pt value class is a convenient way to apply line spacing in units of points.

property runs

Immutable sequence of _Run objects corresponding to the runs in this paragraph.

property space_after

Length value specifying the spacing to appear between this paragraph and the subsequent paragraph. A value of None indicates no explicit value is assigned and its effective value is inherited from the paragraph’s style hierarchy. Length objects provide convenience properties, such as .pt and .inches, that allow easy conversion to various length units.

property space_before

Length value specifying the spacing to appear between this paragraph and the prior paragraph. A value of None indicates no explicit value is assigned and its effective value is inherited from the paragraph’s style hierarchy. Length objects provide convenience properties, such as .pt and .cm, that allow easy conversion to various length units.

property text

str (unicode) representation of paragraph contents.

Read/write. This value is formed by concatenating the text in each run and field making up the paragraph, adding a vertical-tab character ("\v") for each line-break element (<a:br>, soft carriage-return) encountered.

While the encoding of line-breaks as a vertical tab might be surprising at first, doing so is consistent with PowerPoint’s clipboard copy behavior and allows a line-break to be distinguished from a paragraph boundary within the str return value.

Assignment causes all content in the paragraph to be replaced. Each vertical-tab character ("\v") in the assigned str is translated to a line-break, as is each line-feed character ("\n"). Contrast behavior of line-feed character in TextFrame.text setter. If line-feed characters are intended to produce new paragraphs, use TextFrame.text instead. Any other control characters in the assigned string are escaped as a hex representation like “_x001B_” (for ESC (ASCII 27) in this example).

The assigned value can be a 7-bit ASCII byte string (Python 2 str), a UTF-8 encoded 8-bit byte string (Python 2 str), or unicode. Bytes values are converted to unicode assuming UTF-8 encoding.

_Run objects

class pptx.text.text._Run

Text run object. Corresponds to <a:r> child element in a paragraph.

property font

Font instance containing run-level character properties for the text in this run. Character properties can be and perhaps most often are inherited from parent objects such as the paragraph and slide layout the run is contained in. Only those specifically overridden at the run level are contained in the font object.

hyperlink

_Hyperlink instance acting as proxy for any <a:hlinkClick> element under the run properties element. Created on demand, the hyperlink object is available whether an <a:hlinkClick> element is present or not, and creates or deletes that element as appropriate in response to actions on its methods and attributes.

property text

Read/write. A unicode string containing the text in this run.

Assignment replaces all text in the run. The assigned value can be a 7-bit ASCII string, a UTF-8 encoded 8-bit string, or unicode. String values are converted to unicode assuming UTF-8 encoding.

Any other control characters in the assigned string other than tab or newline are escaped as a hex representation. For example, ESC (ASCII 27) is escaped as “_x001B_”. Contrast the behavior of TextFrame.text and _Paragraph.text with respect to line-feed and vertical-tab characters.