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