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
67module 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 */
80interface 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
373service SlideShow : XSlideShow;
374
375}; }; }; };
376
377#endif
378
379