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