Fill (for shapes)

Overview

In simple terms, fill is the color of a shape. The term fill is used to distinguish from line, the border around a shape, which can have a different color. It turns out that a line has a fill all its own, but that’s another topic.

While having a solid color fill is perhaps most common, it is just one of several possible fill types. A shape can have the following types of fill:

  • solid (color)
  • gradient – a smooth transition between multiple colors (see Gradient Fill)
  • picture – in which an image “shows through” and is cropped by the boundaries of the shape
  • pattern – in which a small square of pixels (tile) is repeated to fill the shape
  • background (no fill) – the body of the shape is transparent, allowing whatever is behind it to show through.

Elements that can have a fill include autoshape, line, text (treating each glyph as a shape), table, table cell, and slide background.

Scope

This analysis initially focused on solid fill for an autoshape (including text box). Later, pattern fills were added and then analysis for gradient fills. Picture fills are still outstanding.

  • FillFormat.type – MSO_FILL.SOLID or None for a start
  • FillFormat.solid() – changes fill type to <a:solidFill>
  • FillFormat.patterned() – changes fill type to <a:pattFill>
  • FillFormat.fore_color – read/write foreground color

maybe later:

  • FillFormat.transparency – adds/changes <a:alpha> or something

Protocol

Accessing fill. A shape object has a .fill property that returns a FillFormat object. The .fill property is idempotent; it always returns the same FillFormat object for a given shape object:

>>> fill = shape.fill
>>> assert(isinstance(fill, FillFormat)

Fill type. A fill has a type, indicated by a member of MSO_FILL on FillFormat.type:

>>> fill.type
MSO_FILL.SOLID (1)

The fill type may also be None, indicating the shape’s fill is inherited from the style hierarchy (generally the theme linked to the slide master). This is the default for a new shape:

>>> shape = shapes.add_shape(...)
>>> shape.fill.type
None

The fill type partially determines the valid calls on the fill:

>>> fill.solid()
>>> fill.type
1  # MSO_FILL.SOLID

>>> fill.fore_color = 'anything'
AttributeError: can't set attribute  # .fore_color is read-only
>>> fore_color = fill.fore_color
>>> assert(isinstance(fore_color, ColorFormat))

>>> fore_color.rgb = RGBColor(0x3F, 0x2c, 0x36)
>>> fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
>>> fore_color.brightness = -0.25

>>> fill.transparency
0.0
>>> fill.transparency = 0.25  # sets opacity to 75%

>>> sp.fill = None  # removes any fill, fill is inherited from theme

fill.solid()
fill.fore_color.rgb = RGBColor(0x01, 0x23, 0x45)
fill.fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
fill.fore_color.brightness = 0.25
fill.transparency = 0.25
shape.fill = None
fill.background()  # is almost free once the rest is in place

Pattern Fill.

>>> fill = shape.fill
>>> fill.type
None
>>> fill.patterned()
>>> fill.type
2  # MSO_FILL.PATTERNED
>>> fill.fore_color.rgb = RGBColor(79, 129, 189)
>>> fill.back_color.rgb = RGBColor(239, 169, 6)

Enumerations

MsoFillType

http://msdn.microsoft.com/EN-US/library/office/ff861408.aspx

msoFillBackground
5 – Fill is the same as the background.
msoFillGradient
3 – Gradient fill.
msoFillPatterned
2 – Patterned fill.
msoFillPicture
6 – Picture fill.
msoFillSolid
1 – Solid fill.
msoFillTextured
4 – Textured fill.
msoFillMixed
-2 – Mixed fill.

XML specimens

Inherited fill on autoshape:

<p:spPr>
   ...
  <a:prstGeom prst="roundRect">
    <a:avLst/>
  </a:prstGeom>
</p:spPr>

Solid RGB color on autoshape:

<p:spPr>
   ...
  <a:prstGeom prst="roundRect">
    <a:avLst/>
  </a:prstGeom>
  <a:solidFill>
    <a:srgbClr val="2CB731"/>
  </a:solidFill>
</p:spPr>

Patterned fill:

<a:pattFill prst="ltDnDiag">
  <a:fgClr>
    <a:schemeClr val="accent1"/>
  </a:fgClr>
  <a:bgClr>
    <a:schemeClr val="accent6"/>
  </a:bgClr>
</a:pattFill>

XML semantics

  • No `prst` attribute. When an a:pattFill element contains no prst attribute, the pattern defaults to 5% (dotted). This is the first one in the pattern gallery in the PowerPoint UI.
  • No `fgClr` or `bgClr` elements. When an a:pattFill element contains no fgClr or bgClr chile elements, the colors default to black and white respectively.