DrawingML objects

Low-level drawing elements like fill and color that appear repeatedly in various aspects of shapes.

ChartFormat objects

class pptx.dml.chtfmt.ChartFormat(element)

The ChartFormat object provides access to visual shape properties for chart elements like Axis, Series, and MajorGridlines. It has two properties, fill and line, which return a FillFormat and LineFormat object respectively. The ChartFormat object is provided by the format property on the target axis, series, etc.

fill

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

line

The LineFormat object providing access to the visual properties of this object, such as line color and line style.

FillFormat objects

class pptx.dml.fill.FillFormat(eg_fill_properties_parent, fill_obj)

Provides access to the current fill properties object and provides methods to change the fill type.

property back_color

Return a ColorFormat object representing background color.

This property is only applicable to pattern fills and lines.

background()

Sets the fill type to noFill, i.e. transparent.

property fore_color

Return a ColorFormat instance representing the foreground color of this fill.

gradient()

Sets the fill type to gradient.

If the fill is not already a gradient, a default gradient is added. The default gradient corresponds to the default in the built-in PowerPoint “White” template. This gradient is linear at angle 90-degrees (upward), with two stops. The first stop is Accent-1 with tint 100%, shade 100%, and satMod 130%. The second stop is Accent-1 with tint 50%, shade 100%, and satMod 350%.

property gradient_angle

Angle in float degrees of line of a linear gradient.

Read/Write. May be None, indicating the angle should be inherited from the style hierarchy. An angle of 0.0 corresponds to a left-to-right gradient. Increasing angles represent counter-clockwise rotation of the line, for example 90.0 represents a bottom-to-top gradient. Raises TypeError when the fill type is not MSO_FILL_TYPE.GRADIENT. Raises ValueError for a non-linear gradient (e.g. a radial gradient).

property gradient_stops

GradientStops object providing access to stops of this gradient.

Raises TypeError when fill is not gradient (call fill.gradient() first). Each stop represents a color between which the gradient smoothly transitions.

property pattern

Return member of MSO_PATTERN_TYPE indicating fill pattern.

Raises TypeError when fill is not patterned (call fill.patterned() first). Returns None if no pattern has been set; PowerPoint may display the default PERCENT_5 pattern in this case. Assigning None will remove any explicit pattern setting, although relying on the default behavior is discouraged and may produce rendering differences across client applications.

patterned()

Selects the pattern fill type.

Note that calling this method does not by itself set a foreground or background color of the pattern. Rather it enables subsequent assignments to properties like fore_color to set the pattern and colors.

solid()

Sets the fill type to solid, i.e. a solid color. Note that calling this method does not set a color or by itself cause the shape to appear with a solid color fill; rather it enables subsequent assignments to properties like fore_color to set the color.

property type

Return a value from the MSO_FILL_TYPE enumeration corresponding to the type of this fill.

LineFormat objects

class pptx.dml.line.LineFormat(parent)

Provides access to line properties such as color, style, and width.

A LineFormat object is typically accessed via the .line property of a shape such as Shape or Picture.

color

The ColorFormat instance that provides access to the color settings for this line. Essentially a shortcut for line.fill.fore_color. As a side-effect, accessing this property causes the line fill type to be set to MSO_FILL.SOLID. If this sounds risky for your use case, use line.fill.type to non-destructively discover the existing fill type.

property dash_style

Return value indicating line style.

Returns a member of MSO_LINE_DASH_STYLE indicating line style, or None if no explicit value has been set. When no explicit value has been set, the line dash style is inherited from the style hierarchy.

Assigning None removes any existing explicitly-defined dash style.

fill

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

property width

The width of the line expressed as an integer number of English Metric Units. The returned value is an instance of Length, a value class having properties such as .inches, .cm, and .pt for converting the value into convenient units.

ColorFormat objects

class pptx.dml.color.ColorFormat(eg_colorChoice_parent, color)

Provides access to color settings such as RGB color, theme color, and luminance adjustments.

property brightness

Read/write float value between -1.0 and 1.0 indicating the brightness adjustment for this color, e.g. -0.25 is 25% darker and 0.4 is 40% lighter. 0 means no brightness adjustment.

property rgb

RGBColor value of this color, or None if no RGB color is explicitly defined for this font. Setting this value to an RGBColor instance causes its type to change to MSO_COLOR_TYPE.RGB. If the color was a theme color with a brightness adjustment, the brightness adjustment is removed when changing it to an RGB color.

property theme_color

Theme color value of this color.

Value is a member of MSO_THEME_COLOR_INDEX, e.g. MSO_THEME_COLOR.ACCENT_1. Raises AttributeError on access if the color is not type MSO_COLOR_TYPE.SCHEME. Assigning a member of MSO_THEME_COLOR_INDEX causes the color’s type to change to MSO_COLOR_TYPE.SCHEME.

property type

Read-only. A value from MSO_COLOR_TYPE, either RGB or SCHEME, corresponding to the way this color is defined, or None if no color is defined at the level of this font.

RGBColor objects

class pptx.dml.color.RGBColor(r, g, b)

Immutable value object defining a particular RGB color.

classmethod from_string(rgb_hex_str)

Return a new instance from an RGB color hex string like '3C2F80'.

ShadowFormat objects

class pptx.dml.effect.ShadowFormat(spPr)

Provides access to shadow effect on a shape.

property inherit

True if shape inherits shadow settings.

Read/write. An explicitly-defined shadow setting on a shape causes this property to return False. A shape with no explicitly-defined shadow setting inherits its shadow settings from the style hierarchy (and so returns True).

Assigning True causes any explicitly-defined shadow setting to be removed and inheritance is restored. Note this has the side-effect of removing all explicitly-defined effects, such as glow and reflection, and restoring inheritance for all effects on the shape. Assigning False causes the inheritance link to be broken and no effects to appear on the shape.