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

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