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.