Text-related objects — python-pptx 1.0.0 documentation (original) (raw)
TextFrame objects¶
class pptx.text.text. TextFrame[source]¶
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.
Return new _Paragraph instance appended to the sequence of paragraphs contained in this text frame.
auto_size¶
Resizing strategy used to fit text within this shape.
Determins the type of automatic resizing used to fit the text of this shape within its bounding box when the text would otherwise extend beyond the shape boundaries. May beNone, MSO_AUTO_SIZE.NONE, MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT, orMSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE.
Remove all paragraphs except one empty one.
fit_text(font_family: str = 'Calibri', max_size: int = 18, bold: bool = False, italic: bool = False, font_file: str | None = None)[source]¶
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, anditalic installed on the current system (usually succeeds if the font is installed).
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).
margin_left¶
Inset of text from left text frame border as Length value.
margin_right¶
Inset of text from right text frame border as Length value.
margin_top¶
Inset of text from top text frame border as Length value.
paragraphs¶
Sequence of paragraphs in this text frame.
A text frame always contains at least one paragraph.
text¶
All text in this text-frame as a single string.
Read/write. The return value contains 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. 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).
vertical_anchor¶
Represents the vertical alignment of text in this text frame.
None indicates the effective value should be inherited from this object’s style hierarchy.
word_wrap¶
True when lines of text in this shape are wrapped to fit within the shape’s width.
Read-write. 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[source]¶
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 anda:endParaRPr in paragraph and a:defRPr in list style elements.
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.
The ColorFormat instance that provides access to the color settings for this font.
FillFormat instance for this font.
Provides access to fill properties such as fill color.
italic¶
Get or set boolean italic value of Font instance.
Has the same behaviors as bold with respect to None values.
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 Noneremoves any language setting, the same behavior as assigning MSO_LANGUAGE_ID.NONE.
name¶
Get or set the typeface name for this Font instance.
Causes 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 Noneremoves any override of the theme typeface.
size¶
Indicates the font height in English Metric Units (EMU).
Read/write. 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 inthaving 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
underline¶
Indicaties the underline setting for this font.
Value is True, False, None, or a member of the MSO_TEXT_UNDERLINE_TYPEenumeration. 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[source]¶
Paragraph object. Not intended to be constructed directly.
Add line break at end of this paragraph.
add_run() → pptx.text.text._Run[source]¶
Return a new run appended to the runs in this paragraph.
alignment¶
Horizontal alignment of this paragraph.
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.
Remove all content from this paragraph.
Paragraph properties are preserved. Content includes runs, line breaks, and fields.
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.
level¶
Indentation level of this paragraph.
Read-write. Integer in range 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.
line_spacing¶
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 asPt(12) indicates spacing is a fixed height. The Pt value class is a convenient way to apply line spacing in units of points.
runs¶
Sequence of runs in this paragraph.
space_after¶
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.
space_before¶
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.
text¶
Text of paragraph as a single string.
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.textinstead. Any other control characters in the assigned string are escaped as a hex representation like “_x001B_” (for ESC (ASCII 27) in this example).
_Run objects¶
class pptx.text.text. _Run[source]¶
Text run object. Corresponds to a:r child element in a paragraph.
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.
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.
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.