offapi/com/sun/star/presentation/XSlideShow.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef _com_sun_star_presentation_XSlideShow_idl
  20 #define _com_sun_star_presentation_XSlideShow_idl
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/beans/PropertyValue.idl>
  24 #include <com/sun/star/geometry/RealRectangle2D.idl>
  25 #include <com/sun/star/rendering/XSpriteCanvas.idl>
  26 #include <com/sun/star/animations/XAnimationNode.idl>
  27 #include <com/sun/star/lang/XMultiServiceFactory.idl>
  28 #include <com/sun/star/drawing/XDrawPage.idl>
  29 #include <com/sun/star/drawing/XDrawPagesSupplier.idl>
  30 #include <com/sun/star/drawing/XShape.idl>
  31 #include <com/sun/star/presentation/XSlideShowView.idl>
  32 #include <com/sun/star/presentation/XSlideShowListener.idl>
  33 #include <com/sun/star/presentation/XShapeEventListener.idl>
  34
  35 module com {  module sun {  module star {  module presentation {
  36
  37 /** Slide show interface to perform slide show presentations.<p>
  38
  39     This interface provides the necessary methods to run and control a
  40     slide show from a given set of XDrawPage slides. The slide show can
  41     be displayed simultaneously on multiple targets.<p>
  42
  43     Note: To control a running slide show inside a presentation, please
  44     use XPresentation2 and XSlideShowController.
  45
  46     @since OOo 3.0
  47  */
  48 interface XSlideShow : ::com::sun::star::uno::XInterface
  49 {
  50     /** Trigger the next effect of the slide show.<p>
  51
  52         This method triggers the next effect on the currently
  53         displayed slide. If there is currently no slide show running,
  54         this method does nothing. If there are no more effects on the
  55         current slide, a possible slide transition effect is issued
  56         and the next slide is displayed.<p>
  57
  58         @return `TRUE`, if the next effect was successfully
  59         triggered. This method returns `FALSE`, if there is no show
  60         running, the last effect on the last slide was already
  61         triggered, or the implementation failed to trigger the next
  62         effect.
  63      */
  64     boolean nextEffect();
  65
  66     /** Undo the last effect in the main sequence of the slide show.<p>
  67
  68         The current slide is displayed as if the last user-triggered effect
  69         has never been triggered.  If there is no previous effect on the
  70         current slide then slideEnded(true) is called at the registered
  71         XSlideShowListener objects, which can then trigger a change to the
  72         previous slide.  Note that this command is executed asynchronously.
  73         Multiple calls to update() may be necessary to complete its execution.
  74         If there is currently no slide show running, this method does
  75         nothing.<p>
  76
  77         @return `TRUE`, if the previous effect was successfully
  78         triggered. This method returns `FALSE`, if there is no show
  79         running, the first effect on the first slide was not yet
  80         triggered, or the implementation failed to trigger the previous
  81         effect.
  82      */
  83     boolean previousEffect();
  84
  85     /** Start a shape-intrinsic animation or activity.<p>
  86
  87         This method starts an animation or activity intrinsic to the
  88         given shape. Shape-intrinsic activities are things like video
  89         playback for multimedia shapes, sounds, GIF animations and
  90         drawing layer animations (flipping between shapes in a group,
  91         or scroll text).<p>
  92
  93         @param xShape
  94         The shape to start the activity for
  95      */
  96     boolean startShapeActivity( [in] ::com::sun::star::drawing::XShape xShape );
  97
  98     /** Stop a shape-intrinsic animation or activity.<p>
  99
 100         This method stops an animation or activity intrinsic to the
 101         given shape. Shape-intrinsic activities are things like video
 102         playback for multimedia shapes, sounds, GIF animations and
 103         drawing layer animations (flipping between shapes in a group,
 104         or scroll text).<p>
 105
 106         @param xShape
 107         The shape to stop the activity for
 108      */
 109     boolean stopShapeActivity( [in] ::com::sun::star::drawing::XShape xShape );
 110
 111     /** Jump to the given slide.<p>
 112
 113         This method ends all effects on the current slide, displays a
 114         possible slide transition, followed by the given slide. If the
 115         current slide is equal to the requested slide here, this
 116         method does nothing (this especially means, that any currently
 117         active effects will remain running).<p>
 118
 119         @param xSlide
 120         The slide to display.
 121
 122         @param xDrawPages
 123         For future use.
 124
 125         @param AnimationNode
 126         The animation node determine the animations to display.
 127
 128         @param aProperties
 129         Sequence of property values, which influence the way the
 130         slide is displayed. Currently, the
 131         following values are recognized:
 132         <ul>
 133             <li>name: Prefetch, value: ::com::sun::star::drawing::XDrawPage. When given,
 134                 this slide is prepared in the background to be displayed next. The next
 135                 call to displaySlide() with the given slide may be faster if there was
 136                 enough time for prefetching. If the next call to displaySlide() uses
 137                 a different slide, this will still work but will not have any performance
 138                 improvements
 139                 </li>
 140             <li>name: SkipAllMainSequenceEffects, value: boolean.
 141                 When `TRUE` then all main sequence effects on the new slide
 142                 are triggered.  This is typically used when going back one
 143                 effect leads to the previous slide.  On that slide all
 144                 effects have to be shown in order to continue the backward
 145                 traveling.
 146                 When `FALSE`, the default, then no main sequence effect is
 147                 triggered.
 148                 </li>
 149             <li>name: SkipSlideTransition, value: boolean.
 150                 When `TRUE` then the slide transition animation, if there
 151                 is any, is not displayed.  This is typically used when going
 152                 back one effect leads to the previous slide.  Typically used
 153                 together with SkipAllMainSequenceEffects also being `TRUE`.
 154                 When `FALSE`, the default, then the slide transition
 155                 effect, if it exists, is played.
 156                 </li>
 157         </ul>
 158     */
 159     void displaySlide(
 160         [in] ::com::sun::star::drawing::XDrawPage xSlide,
 161         [in] ::com::sun::star::drawing::XDrawPagesSupplier xDrawPages,
 162         [in] ::com::sun::star::animations::XAnimationNode AnimationNode,
 163         [in] sequence< ::com::sun::star::beans::PropertyValue > aProperties );
 164
 165     /** Change the pause state of the slide show.<p>
 166
 167         This method either pauses the slide show (all currently
 168         running effects are stopped), or starts a previously stopped
 169         show again (all paused effects start again).<p>
 170
 171         @param bPauseShow
 172         When `TRUE`, the show is paused. When `FALSE`, and the show
 173         was paused, it starts running at the paused position again.
 174
 175         @return `TRUE`, if the requested action was successfully
 176         performed.
 177      */
 178     boolean pause( [in] boolean bPauseShow );
 179
 180     /** Query the currently displayed slide.<p>
 181
 182         @return the instance of the current slide. If there's no
 183         slide show running at the moment, this method returns an
 184         empty reference.
 185      */
 186     ::com::sun::star::drawing::XDrawPage getCurrentSlide();
 187
 188     /** Register drawn polygons in presentation mode
 189
 190      @param xDocFactory
 191
 192      */
 193
 194     void registerUserPaintPolygons([in] ::com::sun::star::lang::XMultiServiceFactory xDocFactory);
 195
 196     /** Change a property of the slide show.<p>
 197
 198         @param aShowProperty
 199         Property values, which influence the way the slides are
 200         shown. Note that this might possibly be a subset of what is
 201         supported on show(). Currently, the following values
 202         are recognized:
 203         <ul>
 204             <li>name: AutomaticAdvancement, value: double. When given, effects
 205                 and slides are advanced automatically. The double value specifies
 206                 the timeout between the end of one effect until the start of the
 207                 next one. Negative values are truncated to zero here. When given,
 208                 but with empty value, automatic advancement is disabled again.</li>
 209             <li>name: UserPaintColor, value: long. When given, the slide show
 210                 will display a small stylus as the mouse cursor. When pressing the
 211                 left mouse key, the user can paint a thin line in the given color.</li>
 212         </ul>
 213         A changed property is effective immediately.
 214      */
 215     boolean setProperty(
 216         [in] ::com::sun::star::beans::PropertyValue aShowProperty );
 217
 218     /** Add a view to the slide show.<p>
 219
 220         This method adds a view to the slide show. After successful
 221         completion of this method, the slide show will be visible on
 222         the added view, scaled according to the view's output area.<p>
 223
 224         @param xView
 225         The view to add
 226
 227         @return `TRUE`, if the view has been successfully
 228         added. Otherwise, `FALSE` is returned (e.g. if the view is
 229         already added).
 230      */
 231     boolean addView( [in] XSlideShowView xView );
 232
 233     /** Remove view from the slide show.<p>
 234
 235         This method removes the given view from the slide show. After
 236         successful completion of this method, the slide show will
 237         cease to display on this view.<p>
 238
 239         @param xView
 240         View to remove
 241
 242         @return `TRUE`, if the view was successfully removed, `FALSE`
 243         otherwise (e.g. if the view was not added in the first place).
 244      */
 245     boolean removeView( [in] XSlideShowView xView );
 246
 247     /** Update the animations.<p>
 248
 249         This method updates all currently active slide animations. The
 250         XSlideShow implementations do not render animations
 251         automatically, but must be called from their clients. This
 252         allows for various update mechanisms to be employed, ranging
 253         from a dedicated rendering thread, over timer-based updates,
 254         to rendering in an idle function. Either way, the client of
 255         this interface decide about the details.<p>
 256
 257         @param nNextTimeout
 258         Via this value, the implementation can return a timeout value,
 259         denoting the maximal time span that must not be exceeded from
 260         the return of this method to the next update call. Otherwise,
 261         the animations might show visible jerks.
 262
 263         @return `TRUE`, if further update calls are required. If
 264         `FALSE` is returned, no further update calls are necessary,
 265         until anyone of the other interface methods is called (most
 266         notably, the next/previousSlide(), nextEffect() and show()
 267         methods will nearly always make further update() calls
 268         necessary).
 269      */
 270     boolean update( [out] double nNextTimeout );
 271
 272     /** Add a slide show listener.<p>
 273
 274         This method adds a listener to the slide show, which will get
 275         notified when a registered shape is clicked upon, or a new
 276         slide is about to be displayed. Note that the listeners will
 277         <em>not</em> be notified, when the slide change is directly
 278         requested by one of the nextSlide(), previousSlide() or
 279         displaySlide() methods.
 280
 281         @param xListener
 282         Listener to add.
 283      */
 284     void addSlideShowListener( [in] XSlideShowListener xListener );
 285
 286     /** Revoke a previously registered slide show listener.<p>
 287
 288         @param xListener
 289         Listener interface to revoke from being called.
 290      */
 291     void removeSlideShowListener( [in] XSlideShowListener xListener );
 292
 293     /** Add a shape event listener.<p>
 294
 295         This method adds a listener to the slide show, which will get
 296         notified when a mouse click is performed on the given
 297         shape. This can be used by clients of the slide show to
 298         trigger external actions, such as jumps to different slides.<p>
 299
 300         @param xListener
 301         Listener to add.
 302
 303         @param xShape
 304         Shape to register a listener for.
 305      */
 306     void addShapeEventListener(
 307         [in] XShapeEventListener xListener,
 308         [in] ::com::sun::star::drawing::XShape xShape );
 309
 310     /** Revoke a previously registered shape event listener.<p>
 311
 312         @param xListener
 313         Listener interface to revoke from being called.
 314
 315         @param xShape
 316         Shape for which the listener should be revoked.
 317      */
 318     void removeShapeEventListener(
 319         [in] XShapeEventListener xListener,
 320         [in] ::com::sun::star::drawing::XShape xShape );
 321
 322     /** Set a special mouse cursor for a shape.<p>
 323
 324         This method requests the slide show to display a special
 325         cursor, whenever the mouse is hovering over the given shape.<p>
 326
 327         @param xShape
 328         Shape to display a special mouse cursor.
 329
 330         @param nPointerShape
 331         Type of mouse cursor to display. Must be one of the
 332         ::com::sun::star::awt::SystemPointer values.
 333      */
 334     void setShapeCursor(
 335         [in] ::com::sun::star::drawing::XShape xShape,
 336         [in] short nPointerShape );
 337
 338 };
 339
 340 }; }; }; };
 341
 342 #endif
 343
 344 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */