Gradient Fill

A gradient fill is a smooth gradual transition between two or more colors. A gradient fill can mimic the shading of real-life objects and allow a graphic to look less “flat”.

Each “anchor” color and its relative location in the overall transition is known as a stop. A gradient definition gathers these in a sequence known as the stop list, which contains two or more stops (a gradient with only one stop would be a solid color).

A gradient also has a path, which specifies the direction of the color transition. Perhaps most common is a linear path, where the transition is along a straight line, perhaps top-left to bottom-right. Other gradients like radial and rectangular are possible. The initial implementation supports only a linear path.

Protocol

Staring with a newly-created shape A newly created shape has a fill of None, indicating it’s fill is inherited:

>>> shape = shapes.add_shape(...)
>>> fill = shape.fill
>>> fill
<pptx.dml.fill.FillFormat object at 0x...>
>>> fill.type
None

Apply a gradient fill A gradient fill is applied by calling the .gradient() method on the FillFormat object. This applies a two-stop linear gradient in the bottom-to-top direction (90-degrees in UI):

>>> fill.gradient()
>>> fill._fill.xml
<a:gradFill rotWithShape="1">
  <a:gsLst>
    <a:gs pos="0">
      <a:schemeClr val="accent1">
        <a:tint val="100000"/>
        <a:shade val="100000"/>
        <a:satMod val="130000"/>
      </a:schemeClr>
    </a:gs>
    <a:gs pos="100000">
      <a:schemeClr val="accent1">
        <a:tint val="50000"/>
        <a:shade val="100000"/>
        <a:satMod val="350000"/>
      </a:schemeClr>
    </a:gs>
  </a:gsLst>
  <a:lin ang="16200000" scaled="0"/>
</a:gradFill>

Change angle of linear gradient.:

>>> fill.gradient_angle
270.0
>>> fill.gradient_angle = 45
>>> fill.gradient_angle
45.0

Access a stop. The GradientStops sequence provides access to an individual gradient stop.:

>>> gradient_stops = fill.gradient_stops
>>> gradient_stops
<pptx.dml.fill.GradientStops object at 0x...>

>>> len(gradient_stops)
3

>>> gradient_stop = gradient_stops[0]
>>> gradient_stop
<pptx.dml.fill.GradientStop object at 0x...>

Manipulate gradient stop color. The .color property of a gradient stop is a ColorFormat object, which may be manipulated like any other color to achieve the desired effect:

>>> color = gradient_stop.color
>>> color
<pptx.dml.color.ColorFormat object at 0x...>
>>> color.theme_color = MSO_THEME_COLOR.ACCENT_2

Manipulate gradient stop position.:

>>> gradient_stop.position
0.8  # ---represents 80%---
>>> gradient_stop.position = 0.5
>>> gradient_stop.position
0.5

Remove a gradient stop position.:

>>> gradient_stops[1].remove()
>>> len(gradient_stops)
2

PowerPoint UI features and behaviors

  • Gradient dialog enforces a two-stop minimum in the stops list. A stop that is one of only two stops cannot be deleted.
  • Gradient Gallery …

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.

MsoGradientStyle

https://msdn.microsoft.com/en-us/vba/office-shared-vba/articles/msogradientstyle-enumeration-office

msoGradientDiagonalDown
4 Diagonal gradient moving from a top corner down to the opposite corner.
msoGradientDiagonalUp
3 Diagonal gradient moving from a bottom corner up to the opposite corner.
msoGradientFromCenter
7 Gradient running from the center out to the corners.
msoGradientFromCorner
5 Gradient running from a corner to the other three corners.
msoGradientFromTitle
6 Gradient running from the title outward.
msoGradientHorizontal
1 Gradient running horizontally across the shape.
msoGradientVertical
2 Gradient running vertically down the shape.
msoGradientMixed
-2 Gradient is mixed.

MsoPresetGradientType

msoGradientBrass
20 Brass gradient.
msoGradientCalmWater
8 Calm Water gradient.
msoGradientChrome
21 Chrome gradient.
msoGradientChromeII
22 Chrome II gradient.
msoGradientDaybreak
4 Daybreak gradient.
msoGradientDesert
6 Desert gradient.
msoGradientEarlySunset
1 Early Sunset gradient.
msoGradientFire
9 Fire gradient.
msoGradientFog
10 Fog gradient.
msoGradientGold
18 Gold gradient.
msoGradientGoldII
19 Gold II gradient.
msoGradientHorizon
5 Horizon gradient.
msoGradientLateSunset
2 Late Sunset gradient.
msoGradientMahogany
15 Mahogany gradient.
msoGradientMoss
11 Moss gradient.
msoGradientNightfall
3 Nightfall gradient.
msoGradientOcean
7 Ocean gradient.
msoGradientParchment
14 Parchment gradient.
msoGradientPeacock
12 Peacock gradient.
msoGradientRainbow
16 Rainbow gradient.
msoGradientRainbowII
17 Rainbow II gradient.
msoGradientSapphire
24 Sapphire gradient.
msoGradientSilver
23 Silver gradient.
msoGradientWheat
13 Wheat gradient.
msoPresetGradientMixed
-2 Mixed gradient.

XML specimens

Gradient fill (preset selected from gallery on PowerPoint 2014):

<a:gradFill flip="none" rotWithShape="1">
  <a:gsLst>
    <a:gs pos="0">
      <a:schemeClr val="accent1">
        <a:tint val="66000"/>
        <a:satMod val="160000"/>
      </a:schemeClr>
    </a:gs>
    <a:gs pos="50000">
      <a:schemeClr val="accent1">
        <a:tint val="44500"/>
        <a:satMod val="160000"/>
      </a:schemeClr>
    </a:gs>
    <a:gs pos="100000">
      <a:schemeClr val="accent1">
        <a:tint val="23500"/>
        <a:satMod val="160000"/>
      </a:schemeClr>
    </a:gs>
  </a:gsLst>
  <a:lin ang="2700000" scaled="1"/>
  <a:tileRect/>
</a:gradFill>

Gradient fill (simple created with gradient dialog):

<a:gradFill flip="none" rotWithShape="1">
  <a:gsLst>
    <a:gs pos="0">
      <a:schemeClr val="accent1">
        <a:shade val="51000"/>
        <a:satMod val="130000"/>
      </a:schemeClr>
    </a:gs>
    <a:gs pos="100000">
      <a:schemeClr val="accent1">
        <a:lumMod val="40000"/>
        <a:lumOff val="60000"/>
      </a:schemeClr>
    </a:gs>
  </a:gsLst>
  <a:lin ang="2700000" scaled="0"/>
  <a:tileRect/>
</a:gradFill>

XML semantics

  • Each a:gs element is a fill format
  • a:lin@ang is angle in 1/60,000ths of a degree. Zero degrees is the vector (1, 0), pointing directly to the right. Degrees are measured counter-clockwise from that origin.