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

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