PCQRSCANER/venv/Lib/site-packages/pptx/dml/fill.py

403 lines
13 KiB
Python
Raw Normal View History

2019-12-22 21:51:47 +01:00
# encoding: utf-8
"""DrawingML objects related to fill."""
from __future__ import absolute_import, division, print_function, unicode_literals
from pptx.compat import Sequence
from pptx.dml.color import ColorFormat
from pptx.enum.dml import MSO_FILL
from pptx.oxml.dml.fill import (
CT_BlipFillProperties,
CT_GradientFillProperties,
CT_GroupFillProperties,
CT_NoFillProperties,
CT_PatternFillProperties,
CT_SolidColorFillProperties,
)
from pptx.shared import ElementProxy
from pptx.util import lazyproperty
class FillFormat(object):
"""
Provides access to the current fill properties object and provides
methods to change the fill type.
"""
def __init__(self, eg_fill_properties_parent, fill_obj):
super(FillFormat, self).__init__()
self._xPr = eg_fill_properties_parent
self._fill = fill_obj
@classmethod
def from_fill_parent(cls, eg_fillProperties_parent):
"""
Return a |FillFormat| instance initialized to the settings contained
in *eg_fillProperties_parent*, which must be an element having
EG_FillProperties in its child element sequence in the XML schema.
"""
fill_elm = eg_fillProperties_parent.eg_fillProperties
fill = _Fill(fill_elm)
fill_format = cls(eg_fillProperties_parent, fill)
return fill_format
@property
def back_color(self):
"""Return a |ColorFormat| object representing background color.
This property is only applicable to pattern fills and lines.
"""
return self._fill.back_color
def background(self):
"""
Sets the fill type to noFill, i.e. transparent.
"""
noFill = self._xPr.get_or_change_to_noFill()
self._fill = _NoFill(noFill)
@property
def fore_color(self):
"""
Return a |ColorFormat| instance representing the foreground color of
this fill.
"""
return self._fill.fore_color
def gradient(self):
"""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%.
"""
gradFill = self._xPr.get_or_change_to_gradFill()
self._fill = _GradFill(gradFill)
@property
def gradient_angle(self):
"""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).
"""
if self.type != MSO_FILL.GRADIENT:
raise TypeError("Fill is not of type MSO_FILL_TYPE.GRADIENT")
return self._fill.gradient_angle
@gradient_angle.setter
def gradient_angle(self, value):
if self.type != MSO_FILL.GRADIENT:
raise TypeError("Fill is not of type MSO_FILL_TYPE.GRADIENT")
self._fill.gradient_angle = value
@property
def gradient_stops(self):
"""|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.
"""
if self.type != MSO_FILL.GRADIENT:
raise TypeError("Fill is not of type MSO_FILL_TYPE.GRADIENT")
return self._fill.gradient_stops
@property
def pattern(self):
"""Return member of :ref:`MsoPatternType` 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.
"""
return self._fill.pattern
@pattern.setter
def pattern(self, pattern_type):
self._fill.pattern = pattern_type
def patterned(self):
"""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.
"""
pattFill = self._xPr.get_or_change_to_pattFill()
self._fill = _PattFill(pattFill)
def solid(self):
"""
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.
"""
solidFill = self._xPr.get_or_change_to_solidFill()
self._fill = _SolidFill(solidFill)
@property
def type(self):
"""
Return a value from the :ref:`MsoFillType` enumeration corresponding
to the type of this fill.
"""
return self._fill.type
class _Fill(object):
"""
Object factory for fill object of class matching fill element, such as
_SolidFill for ``<a:solidFill>``; also serves as the base class for all
fill classes
"""
def __new__(cls, xFill):
if xFill is None:
fill_cls = _NoneFill
elif isinstance(xFill, CT_BlipFillProperties):
fill_cls = _BlipFill
elif isinstance(xFill, CT_GradientFillProperties):
fill_cls = _GradFill
elif isinstance(xFill, CT_GroupFillProperties):
fill_cls = _GrpFill
elif isinstance(xFill, CT_NoFillProperties):
fill_cls = _NoFill
elif isinstance(xFill, CT_PatternFillProperties):
fill_cls = _PattFill
elif isinstance(xFill, CT_SolidColorFillProperties):
fill_cls = _SolidFill
else:
fill_cls = _Fill
return super(_Fill, cls).__new__(fill_cls)
@property
def back_color(self):
"""Raise TypeError for types that do not override this property."""
tmpl = "fill type %s has no background color, call .patterned() first"
raise TypeError(tmpl % self.__class__.__name__)
@property
def fore_color(self):
"""Raise TypeError for types that do not override this property."""
tmpl = (
"fill type %s has no foreground color, call .solid() or .pattern"
"ed() first"
)
raise TypeError(tmpl % self.__class__.__name__)
@property
def pattern(self):
"""Raise TypeError for fills that do not override this property."""
tmpl = "fill type %s has no pattern, call .patterned() first"
raise TypeError(tmpl % self.__class__.__name__)
@property
def type(self): # pragma: no cover
tmpl = ".type property must be implemented on %s"
raise NotImplementedError(tmpl % self.__class__.__name__)
class _BlipFill(_Fill):
@property
def type(self):
return MSO_FILL.PICTURE
class _GradFill(_Fill):
"""Proxies an `a:gradFill` element."""
def __init__(self, gradFill):
self._element = self._gradFill = gradFill
@property
def gradient_angle(self):
"""Angle in float degrees of line of a linear gradient.
Read/Write. May be |None|, indicating the angle is inherited from the
style hierarchy. An angle of 0.0 corresponds to a left-to-right
gradient. Increasing angles represent clockwise rotation of the line,
for example 90.0 represents a top-to-bottom 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).
"""
# ---case 1: gradient path is explicit, but not linear---
path = self._gradFill.path
if path is not None:
raise ValueError("not a linear gradient")
# ---case 2: gradient path is inherited (no a:lin OR a:path)---
lin = self._gradFill.lin
if lin is None:
return None
# ---case 3: gradient path is explicitly linear---
# angle is stored in XML as a clockwise angle, whereas the UI
# reports it as counter-clockwise from horizontal-pointing-right.
# Since the UI is consistent with trigonometry conventions, we
# respect that in the API.
clockwise_angle = lin.ang
counter_clockwise_angle = (
0.0 if clockwise_angle == 0.0 else (360.0 - clockwise_angle)
)
return counter_clockwise_angle
@gradient_angle.setter
def gradient_angle(self, value):
lin = self._gradFill.lin
if lin is None:
raise ValueError("not a linear gradient")
lin.ang = 360.0 - value
@lazyproperty
def gradient_stops(self):
"""|_GradientStops| object providing access to gradient colors.
Each stop represents a color between which the gradient smoothly
transitions.
"""
return _GradientStops(self._gradFill.get_or_add_gsLst())
@property
def type(self):
return MSO_FILL.GRADIENT
class _GrpFill(_Fill):
@property
def type(self):
return MSO_FILL.GROUP
class _NoFill(_Fill):
@property
def type(self):
return MSO_FILL.BACKGROUND
class _NoneFill(_Fill):
@property
def type(self):
return None
class _PattFill(_Fill):
"""Provides access to patterned fill properties."""
def __init__(self, pattFill):
super(_PattFill, self).__init__()
self._element = self._pattFill = pattFill
@lazyproperty
def back_color(self):
"""Return |ColorFormat| object that controls background color."""
bgClr = self._pattFill.get_or_add_bgClr()
return ColorFormat.from_colorchoice_parent(bgClr)
@lazyproperty
def fore_color(self):
"""Return |ColorFormat| object that controls foreground color."""
fgClr = self._pattFill.get_or_add_fgClr()
return ColorFormat.from_colorchoice_parent(fgClr)
@property
def pattern(self):
"""Return member of :ref:`MsoPatternType` indicating fill pattern.
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.
"""
return self._pattFill.prst
@pattern.setter
def pattern(self, pattern_type):
self._pattFill.prst = pattern_type
@property
def type(self):
return MSO_FILL.PATTERNED
class _SolidFill(_Fill):
"""Provides access to fill properties such as color for solid fills."""
def __init__(self, solidFill):
super(_SolidFill, self).__init__()
self._solidFill = solidFill
@lazyproperty
def fore_color(self):
"""Return |ColorFormat| object controlling fill color."""
return ColorFormat.from_colorchoice_parent(self._solidFill)
@property
def type(self):
return MSO_FILL.SOLID
class _GradientStops(Sequence):
"""Collection of |GradientStop| objects defining gradient colors.
A gradient must have a minimum of two stops, but can have as many more
than that as required to achieve the desired effect (three is perhaps
most common). Stops are sequenced in the order they are transitioned
through.
"""
def __init__(self, gsLst):
self._gsLst = gsLst
def __getitem__(self, idx):
return _GradientStop(self._gsLst[idx])
def __len__(self):
return len(self._gsLst)
class _GradientStop(ElementProxy):
"""A single gradient stop.
A gradient stop defines a color and a position.
"""
__slots__ = ("_gs", "_color")
def __init__(self, gs):
super(_GradientStop, self).__init__(gs)
self._gs = gs
@lazyproperty
def color(self):
"""Return |ColorFormat| object controlling stop color."""
return ColorFormat.from_colorchoice_parent(self._gs)
@property
def position(self):
"""Location of stop in gradient path as float between 0.0 and 1.0.
The value represents a percentage, where 0.0 (0%) represents the
start of the path and 1.0 (100%) represents the end of the path. For
a linear gradient, these would represent opposing extents of the
filled area.
"""
return self._gs.pos
@position.setter
def position(self, value):
self._gs.pos = float(value)