# encoding: utf-8
"""Slide-related objects, including masters, layouts, and notes."""
from pptx.dml.fill import FillFormat
from pptx.enum.shapes import PP_PLACEHOLDER
from pptx.shapes.shapetree import (
LayoutPlaceholders,
LayoutShapes,
MasterPlaceholders,
MasterShapes,
NotesSlidePlaceholders,
NotesSlideShapes,
SlidePlaceholders,
SlideShapes,
)
from pptx.shared import ElementProxy, ParentedElementProxy, PartElementProxy
from pptx.util import lazyproperty
class _BaseSlide(PartElementProxy):
"""Base class for slide objects, including masters, layouts and notes."""
@lazyproperty
def background(self):
"""|_Background| object providing slide background properties.
This property returns a |_Background| object whether or not the
slide, master, or layout has an explicitly defined background.
The same |_Background| object is returned on every call for the same
slide object.
"""
return _Background(self._element.cSld)
@property
def name(self):
"""
String representing the internal name of this slide. Returns an empty
string (`''`) if no name is assigned. Assigning an empty string or
|None| to this property causes any name to be removed.
"""
return self._element.cSld.name
@name.setter
def name(self, value):
new_value = "" if value is None else value
self._element.cSld.name = new_value
class _BaseMaster(_BaseSlide):
"""
Base class for master objects such as |SlideMaster| and |NotesMaster|.
Provides access to placeholders and regular shapes.
"""
@lazyproperty
def placeholders(self):
"""
Instance of |MasterPlaceholders| containing sequence of placeholder
shapes in this master, sorted in *idx* order.
"""
return MasterPlaceholders(self._element.spTree, self)
@lazyproperty
def shapes(self):
"""
Instance of |MasterShapes| containing sequence of shape objects
appearing on this slide.
"""
return MasterShapes(self._element.spTree, self)
class NotesMaster(_BaseMaster):
"""
Proxy for the notes master XML document. Provides access to shapes, the
most commonly used of which are placeholders.
"""
[docs]class NotesSlide(_BaseSlide):
"""Notes slide object.
Provides access to slide notes placeholder and other shapes on the notes handout
page.
"""
def clone_master_placeholders(self, notes_master):
"""Selectively add placeholder shape elements from *notes_master*.
Selected placeholder shape elements from *notes_master* are added to the shapes
collection of this notes slide. Z-order of placeholders is preserved. Certain
placeholders (header, date, footer) are not cloned.
"""
def iter_cloneable_placeholders(notes_master):
"""
Generate a reference to each placeholder in *notes_master* that
should be cloned to a notes slide when the a new notes slide is
created.
"""
cloneable = (
PP_PLACEHOLDER.SLIDE_IMAGE,
PP_PLACEHOLDER.BODY,
PP_PLACEHOLDER.SLIDE_NUMBER,
)
for placeholder in notes_master.placeholders:
if placeholder.element.ph_type in cloneable:
yield placeholder
shapes = self.shapes
for placeholder in iter_cloneable_placeholders(notes_master):
shapes.clone_placeholder(placeholder)
@property
def notes_placeholder(self):
"""
Return the notes placeholder on this notes slide, the shape that
contains the actual notes text. Return |None| if no notes placeholder
is present; while this is probably uncommon, it can happen if the
notes master does not have a body placeholder, or if the notes
placeholder has been deleted from the notes slide.
"""
for placeholder in self.placeholders:
if placeholder.placeholder_format.type == PP_PLACEHOLDER.BODY:
return placeholder
return None
@property
def notes_text_frame(self):
"""
Return the text frame of the notes placeholder on this notes slide,
or |None| if there is no notes placeholder. This is a shortcut to
accommodate the common case of simply adding "notes" text to the
notes "page".
"""
notes_placeholder = self.notes_placeholder
if notes_placeholder is None:
return None
return notes_placeholder.text_frame
[docs] @lazyproperty
def placeholders(self):
"""
An instance of |NotesSlidePlaceholders| containing the sequence of
placeholder shapes in this notes slide.
"""
return NotesSlidePlaceholders(self.element.spTree, self)
[docs] @lazyproperty
def shapes(self):
"""
An instance of |NotesSlideShapes| containing the sequence of shape
objects appearing on this notes slide.
"""
return NotesSlideShapes(self._element.spTree, self)
[docs]class Slide(_BaseSlide):
"""Slide object. Provides access to shapes and slide-level properties."""
@property
def background(self):
"""|_Background| object providing slide background properties.
This property returns a |_Background| object whether or not the slide
overrides the default background or inherits it. Determining which of
those conditions applies for this slide is accomplished using the
:attr:`follow_master_background` property.
The same |_Background| object is returned on every call for the same
slide object.
"""
return super(Slide, self).background
@property
def follow_master_background(self):
"""|True| if this slide inherits the slide master background.
Assigning |False| causes background inheritance from the master to be
interrupted; if there is no custom background for this slide,
a default background is added. If a custom background already exists
for this slide, assigning |False| has no effect.
Assigning |True| causes any custom background for this slide to be
deleted and inheritance from the master restored.
"""
return self._element.bg is None
@property
def has_notes_slide(self):
"""
Return True if this slide has a notes slide, False otherwise. A notes
slide is created by :attr:`.notes_slide` when one doesn't exist; use
this property to test for a notes slide without the possible side
effect of creating one.
"""
return self.part.has_notes_slide
@property
def notes_slide(self):
"""
Return the |NotesSlide| instance for this slide. If the slide does
not have a notes slide, one is created. The same single instance is
returned on each call.
"""
return self.part.notes_slide
[docs] @lazyproperty
def placeholders(self):
"""
Instance of |SlidePlaceholders| containing sequence of placeholder
shapes in this slide.
"""
return SlidePlaceholders(self._element.spTree, self)
[docs] @lazyproperty
def shapes(self):
"""
Instance of |SlideShapes| containing sequence of shape objects
appearing on this slide.
"""
return SlideShapes(self._element.spTree, self)
@property
def slide_id(self):
"""
The integer value that uniquely identifies this slide within this
presentation. The slide id does not change if the position of this
slide in the slide sequence is changed by adding, rearranging, or
deleting slides.
"""
return self.part.slide_id
@property
def slide_layout(self):
"""
|SlideLayout| object this slide inherits appearance from.
"""
return self.part.slide_layout
[docs]class Slides(ParentedElementProxy):
"""
Sequence of slides belonging to an instance of |Presentation|, having
list semantics for access to individual slides. Supports indexed access,
len(), and iteration.
"""
def __init__(self, sldIdLst, prs):
super(Slides, self).__init__(sldIdLst, prs)
self._sldIdLst = sldIdLst
def __getitem__(self, idx):
"""
Provide indexed access, (e.g. 'slides[0]').
"""
try:
sldId = self._sldIdLst[idx]
except IndexError:
raise IndexError("slide index out of range")
return self.part.related_slide(sldId.rId)
def __iter__(self):
"""
Support iteration (e.g. 'for slide in slides:').
"""
for sldId in self._sldIdLst:
yield self.part.related_slide(sldId.rId)
def __len__(self):
"""
Support len() built-in function (e.g. 'len(slides) == 4').
"""
return len(self._sldIdLst)
[docs] def add_slide(self, slide_layout):
"""
Return a newly added slide that inherits layout from *slide_layout*.
"""
rId, slide = self.part.add_slide(slide_layout)
slide.shapes.clone_layout_placeholders(slide_layout)
self._sldIdLst.add_sldId(rId)
return slide
[docs] def get(self, slide_id, default=None):
"""
Return the slide identified by integer *slide_id* in this
presentation, or *default* if not found.
"""
slide = self.part.get_slide(slide_id)
if slide is None:
return default
return slide
[docs] def index(self, slide):
"""
Map *slide* to an integer representing its zero-based position in
this slide collection. Raises |ValueError| on *slide* not present.
"""
for idx, this_slide in enumerate(self):
if this_slide == slide:
return idx
raise ValueError("%s is not in slide collection" % slide)
[docs]class SlideLayout(_BaseSlide):
"""
Slide layout object. Provides access to placeholders, regular shapes, and
slide layout-level properties.
"""
def iter_cloneable_placeholders(self):
"""
Generate a reference to each layout placeholder on this slide layout
that should be cloned to a slide when the layout is applied to that
slide.
"""
latent_ph_types = (
PP_PLACEHOLDER.DATE,
PP_PLACEHOLDER.FOOTER,
PP_PLACEHOLDER.SLIDE_NUMBER,
)
for ph in self.placeholders:
if ph.element.ph_type not in latent_ph_types:
yield ph
[docs] @lazyproperty
def placeholders(self):
"""
Instance of |LayoutPlaceholders| containing sequence of placeholder
shapes in this slide layout, sorted in *idx* order.
"""
return LayoutPlaceholders(self._element.spTree, self)
[docs] @lazyproperty
def shapes(self):
"""
Instance of |LayoutShapes| containing the sequence of shapes
appearing on this slide layout.
"""
return LayoutShapes(self._element.spTree, self)
@property
def slide_master(self):
"""
Slide master from which this slide layout inherits properties.
"""
return self.part.slide_master
@property
def used_by_slides(self):
"""Tuple of slide objects based on this slide layout."""
# ---getting Slides collection requires going around the horn a bit---
slides = self.part.package.presentation_part.presentation.slides
return tuple(s for s in slides if s.slide_layout == self)
[docs]class SlideLayouts(ParentedElementProxy):
"""Sequence of slide layouts belonging to a slide-master.
Supports indexed access, len(), iteration, index() and remove().
"""
def __init__(self, sldLayoutIdLst, parent):
super(SlideLayouts, self).__init__(sldLayoutIdLst, parent)
self._sldLayoutIdLst = sldLayoutIdLst
def __getitem__(self, idx):
"""
Provide indexed access, (e.g. ``slide_layouts[2]``).
"""
try:
sldLayoutId = self._sldLayoutIdLst[idx]
except IndexError:
raise IndexError("slide layout index out of range")
return self.part.related_slide_layout(sldLayoutId.rId)
def __iter__(self):
"""
Generate a reference to each of the |SlideLayout| instances in the
collection, in sequence.
"""
for sldLayoutId in self._sldLayoutIdLst:
yield self.part.related_slide_layout(sldLayoutId.rId)
def __len__(self):
"""
Support len() built-in function (e.g. 'len(slides) == 4').
"""
return len(self._sldLayoutIdLst)
[docs] def get_by_name(self, name, default=None):
"""Return SlideLayout object having *name* or *default* if not found."""
for slide_layout in self:
if slide_layout.name == name:
return slide_layout
return default
[docs] def index(self, slide_layout):
"""Return zero-based index of *slide_layout* in this collection.
Raises ValueError if *slide_layout* is not present in this collection.
"""
for idx, this_layout in enumerate(self):
if slide_layout == this_layout:
return idx
raise ValueError("layout not in this SlideLayouts collection")
[docs] def remove(self, slide_layout):
"""Remove *slide_layout* from the collection.
Raises ValueError when *slide_layout* is in use; a slide layout which is the
basis for one or more slides cannot be removed.
"""
# ---raise if layout is in use---
if slide_layout.used_by_slides:
raise ValueError("cannot remove slide-layout in use by one or more slides")
# ---target layout is identified by its index in this collection---
target_idx = self.index(slide_layout)
# --remove layout from p:sldLayoutIds of its master
# --this stops layout from showing up, but doesn't remove it from package
target_sldLayoutId = self._sldLayoutIdLst.sldLayoutId_lst[target_idx]
self._sldLayoutIdLst.remove(target_sldLayoutId)
# --drop relationship from master to layout
# --this removes layout from package, along with everything (only) it refers to,
# --including images (not used elsewhere) and hyperlinks
slide_layout.slide_master.part.drop_rel(target_sldLayoutId.rId)
[docs]class SlideMaster(_BaseMaster):
"""
Slide master object. Provides access to slide layouts. Access to
placeholders, regular shapes, and slide master-level properties is
inherited from |_BaseMaster|.
"""
[docs] @lazyproperty
def slide_layouts(self):
"""|SlideLayouts| object providing access to this slide-master's layouts."""
return SlideLayouts(self._element.get_or_add_sldLayoutIdLst(), self)
[docs]class SlideMasters(ParentedElementProxy):
"""Sequence of |SlideMaster| objects belonging to a presentation.
Has list access semantics, supporting indexed access, len(), and iteration.
"""
def __init__(self, sldMasterIdLst, parent):
super(SlideMasters, self).__init__(sldMasterIdLst, parent)
self._sldMasterIdLst = sldMasterIdLst
def __getitem__(self, idx):
"""
Provide indexed access, (e.g. ``slide_masters[2]``).
"""
try:
sldMasterId = self._sldMasterIdLst[idx]
except IndexError:
raise IndexError("slide master index out of range")
return self.part.related_slide_master(sldMasterId.rId)
def __iter__(self):
"""
Generate a reference to each of the |SlideMaster| instances in the
collection, in sequence.
"""
for smi in self._sldMasterIdLst:
yield self.part.related_slide_master(smi.rId)
def __len__(self):
"""
Support len() built-in function (e.g. 'len(slide_masters) == 4').
"""
return len(self._sldMasterIdLst)
class _Background(ElementProxy):
"""Provides access to slide background properties.
Note that the presence of this object does not by itself imply an
explicitly-defined background; a slide with an inherited background still
has a |_Background| object.
"""
def __init__(self, cSld):
super(_Background, self).__init__(cSld)
self._cSld = cSld
@lazyproperty
def fill(self):
"""|FillFormat| instance for this background.
This |FillFormat| object is used to interrogate or specify the fill
of the slide background.
Note that accessing this property is potentially destructive. A slide
background can also be specified by a background style reference and
accessing this property will remove that reference, if present, and
replace it with NoFill. This is frequently the case for a slide
master background.
This is also the case when there is no explicitly defined background
(background is inherited); merely accessing this property will cause
the background to be set to NoFill and the inheritance link will be
interrupted. This is frequently the case for a slide background.
Of course, if you are accessing this property in order to set the
fill, then these changes are of no consequence, but the existing
background cannot be reliably interrogated using this property unless
you have already established it is an explicit fill.
If the background is already a fill, then accessing this property
makes no changes to the current background.
"""
bgPr = self._cSld.get_or_add_bgPr()
return FillFormat.from_fill_parent(bgPr)