Source code for pptx.action

# encoding: utf-8

"""
Objects related to mouse click and hover actions on a shape or text.
"""

from __future__ import (
    absolute_import, division, print_function, unicode_literals
)

from .enum.action import PP_ACTION
from .opc.constants import RELATIONSHIP_TYPE as RT
from .shapes import Subshape
from .util import lazyproperty


[docs]class ActionSetting(Subshape): """Properties specifying how a shape or run reacts to mouse actions.""" # Subshape superclass provides access to the Slide Part, which is needed # to access relationships. def __init__(self, xPr, parent, hover=False): super(ActionSetting, self).__init__(parent) # xPr is either a cNvPr or rPr element self._element = xPr # _hover determines use of `a:hlinkClick` or `a:hlinkHover` self._hover = hover @property def action(self): """ A member of the :ref:`PpActionType` enumeration, such as `PP_ACTION.HYPERLINK`, indicating the type of action that will result when the specified shape or text is clicked or the mouse pointer is positioned over the shape during a slide show. """ hlink = self._hlink if hlink is None: return PP_ACTION.NONE action_verb = hlink.action_verb if action_verb == 'hlinkshowjump': relative_target = hlink.action_fields['jump'] return { 'firstslide': PP_ACTION.FIRST_SLIDE, 'lastslide': PP_ACTION.LAST_SLIDE, 'lastslideviewed': PP_ACTION.LAST_SLIDE_VIEWED, 'nextslide': PP_ACTION.NEXT_SLIDE, 'previousslide': PP_ACTION.PREVIOUS_SLIDE, 'endshow': PP_ACTION.END_SHOW, }[relative_target] return { None: PP_ACTION.HYPERLINK, 'hlinksldjump': PP_ACTION.NAMED_SLIDE, 'hlinkpres': PP_ACTION.PLAY, 'hlinkfile': PP_ACTION.OPEN_FILE, 'customshow': PP_ACTION.NAMED_SLIDE_SHOW, 'ole': PP_ACTION.OLE_VERB, 'macro': PP_ACTION.RUN_MACRO, 'program': PP_ACTION.RUN_PROGRAM, }[action_verb] @lazyproperty def hyperlink(self): """ A |Hyperlink| object representing the hyperlink action defined on this click or hover mouse event. A |Hyperlink| object is always returned, even if no hyperlink or other click action is defined. """ return Hyperlink(self._element, self._parent, self._hover) @property def target_slide(self): """ A reference to the slide in this presentation that is the target of the slide jump action in this shape. Slide jump actions include `PP_ACTION.FIRST_SLIDE`, `LAST_SLIDE`, `NEXT_SLIDE`, `PREVIOUS_SLIDE`, and `NAMED_SLIDE`. Returns |None| for all other actions. In particular, the `LAST_SLIDE_VIEWED` action and the `PLAY` (start other presentation) actions are not supported. A slide object may be assigned to this property, which makes the shape an "internal hyperlink" to the assigened slide:: slide, target_slide = prs.slides[0], prs.slides[1] shape = slide.shapes[0] shape.target_slide = target_slide Assigning |None| removes any slide jump action. Note that this is accomplished by removing any action present (such as a hyperlink), without first checking that it is a slide jump action. """ slide_jump_actions = ( PP_ACTION.FIRST_SLIDE, PP_ACTION.LAST_SLIDE, PP_ACTION.NEXT_SLIDE, PP_ACTION.PREVIOUS_SLIDE, PP_ACTION.NAMED_SLIDE, ) if self.action not in slide_jump_actions: return None if self.action == PP_ACTION.FIRST_SLIDE: return self._slides[0] elif self.action == PP_ACTION.LAST_SLIDE: return self._slides[-1] elif self.action == PP_ACTION.NEXT_SLIDE: next_slide_idx = self._slide_index + 1 if next_slide_idx >= len(self._slides): raise ValueError('no next slide') return self._slides[next_slide_idx] elif self.action == PP_ACTION.PREVIOUS_SLIDE: prev_slide_idx = self._slide_index - 1 if prev_slide_idx < 0: raise ValueError('no previous slide') return self._slides[prev_slide_idx] elif self.action == PP_ACTION.NAMED_SLIDE: rId = self._hlink.rId return self.part.related_parts[rId].slide @target_slide.setter def target_slide(self, slide): self._clear_click_action() if slide is None: return hlink = self._element.get_or_add_hlinkClick() hlink.action = "ppaction://hlinksldjump" this_part, target_part = self.part, slide.part hlink.rId = this_part.relate_to(target_part, RT.SLIDE) def _clear_click_action(self): """Remove any existing click action.""" hlink = self._hlink if hlink is None: return rId = hlink.rId if rId: self.part.drop_rel(rId) self._element.remove(hlink) @property def _hlink(self): """ Reference to the `a:hlinkClick` or `h:hlinkHover` element for this click action. Returns |None| if the element is not present. """ if self._hover: return self._element.hlinkHover return self._element.hlinkClick @lazyproperty def _slide(self): """ Reference to the slide containing the shape having this click action. """ return self.part.slide @lazyproperty def _slide_index(self): """ Position in the slide collection of the slide containing the shape having this click action. """ return self._slides.index(self._slide) @lazyproperty def _slides(self): """ Reference to the slide collection for this presentation. """ return self.part.package.presentation_part.presentation.slides