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

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