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 control a running slideshow inside a presentation, please
72    use <type>XPresentation2</type> and <type>XSlideShowController</type>.
73
74	@since OpenOffice 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
153        @param xAnimationNode
154        The animation node determine the animations to display.
155
156        @param aProperties
157        Sequence of property values, which influence the way the
158        slide is displayed. Currently, the
159        following values are recognized:
160        <ul>
161            <li>name: Prefetch, value: ::com::sun::star::drawing::XDrawPage. When given,
162                this slide is prepared in the background to be displayed next. The next
163                call to displaySlide() with the given slide may be faster if there was
164                enough time for prefatching. If the next call to displaySlide() uses
165                a different slide, this will still work but will not have any performance
166                improvements
167                </li>
168            <li>name: SkipAllMainSequenceEffects, value: boolean.
169                When <TRUE/> then all main sequence effects on the new slide
170                are triggered.  This is typically used when going back one
171                effect leads to the previous slide.  On that slide all
172                effects have to be shown in order to continue the backward
173                travelling.
174                When <FALSE/>, the default, then no main sequence effect is
175                triggered.
176                </li>
177            <li>name: SkipSlideTransition, value: boolean.
178                When <TRUE/> then the slide transition animation, if there
179                is any, is not displayed.  This is typically used when going
180                back one effect leads to the previous slide.  Typically used
181                together with SkipAllMainSequenceEffects also being <TRUE/>.
182                When <FALSE/>, the default, then the slide transition
183                effect, if it exists, is played.
184                </li>
185        </ul>
186    */
187    void displaySlide(
188        [in] ::com::sun::star::drawing::XDrawPage xSlide,
189        [in] ::com::sun::star::drawing::XDrawPagesSupplier xDrawPages,
190        [in] ::com::sun::star::animations::XAnimationNode aAnimationNode,
191        [in] sequence< ::com::sun::star::beans::PropertyValue > aProperties );
192
193    /** Change the pause state of the slide show.<p>
194
195        This method either pauses the slide show (all currently
196        running effects are stopped), or starts a previously stopped
197        show again (all paused effects start again).<p>
198
199        @param bPauseShow
200        When <TRUE>, the show is paused. When <FALSE>, and the show
201        was paused, it starts running at the paused position again.
202
203        @return <TRUE>, if the requested action was successfully
204        performed.
205     */
206    boolean pause( [in] boolean bPauseShow );
207
208    /** Query the currently displayed slide.<p>
209
210        @return the instance of the current slide. If there's no
211        slideshow running at the moment, this method returns an
212        empty reference.
213     */
214    ::com::sun::star::drawing::XDrawPage getCurrentSlide();
215
216    /** Register drawn polygons in presentation mode
217
218	 @param xDocFactory
219
220     */
221
222    void registerUserPaintPolygons([in] ::com::sun::star::lang::XMultiServiceFactory xDocFactory);
223
224    /** Change a property of the slideshow.<p>
225
226        @param aShowProperty
227        Property values, which influence the way the slides are
228        shown. Note that this might possibly be a subset of what is
229        supported on show(). Currently, the following values
230        are recognized:
231        <ul>
232            <li>name: AutomaticAdvancement, value: double. When given, effects
233                and slides are advanced automatically. The double value specifies
234                the timeout between the end of one effect until the start of the
235                next one. Negative values are truncated to zero here. When given,
236                but with empty value, automatic advancement is disabled again.</li>
237            <li>name: UserPaintColor, value: long. When given, the slide show
238                will display a small stylus as the mouse cursor. When pressing the
239                left mouse key, the user can paint a thin line in the given color.</li>
240        </ul>
241        A changed property is effective immediately.
242     */
243    boolean setProperty(
244        [in] ::com::sun::star::beans::PropertyValue aShowProperty );
245
246    /** Add a view to the slide show.<p>
247
248        This method adds a view to the slide show. After successful
249        completion of this method, the slide show will be visible on
250        the added view, scaled according to the view's output area.<p>
251
252        @param xView
253        The view to add
254
255        @return <TRUE>, if the view has been successfully
256        added. Otherwise, <FALSE> is returned (e.g. if the view is
257        already added).
258     */
259    boolean addView( [in] XSlideShowView xView );
260
261    /** Remove view from the slide show.<p>
262
263        This method removes the given view from the slide show. After
264        successful completion of this method, the slide show will
265        cease to display on this view.<p>
266
267        @param xView
268        View to remove
269
270        @return <TRUE>, if the view was successfully removed, <FALSE>
271        otherwise (e.g. if the view was not added in the first place).
272     */
273    boolean removeView( [in] XSlideShowView xView );
274
275    /** Update the animations.<p>
276
277        This method updates all currently active slide animations. The
278        XSlideShow implementations do not render animations
279        automatically, but must be called from their clients. This
280        allows for various update mechanisms to be employed, ranging
281        from a dedicated rendering thread, over timer-based updates,
282        to rendering in an idle function. Either way, the client of
283        this interface decide about the details.<p>
284
285        @param nNextTimeout
286        Via this value, the implementation can return a timeout value,
287        denoting the maximal time span that must not be exceeded from
288        the return of this method to the next update call. Otherwise,
289        the animations might show visible jerks.
290
291        @return <TRUE>, if further update calls are required. If
292        <FALSE> is returned, no further update calls are necessary,
293        until anyone of the other interface methods is called (most
294        notably, the next/previousSlide(), nextEffect() and show()
295        methods will nearly always make further update() calls
296        necessary).
297     */
298    boolean update( [out] double nNextTimeout );
299
300    /** Add a slide show listener.<p>
301
302        This method adds a listener to the slide show, which will get
303        notified when a registerend shape is clicked upon, or a new
304        slide is about to be displayed. Note that the listeners will
305        <em>not</em> be notified, when the slide change is directly
306        requested by one of the nextSlide(), previousSlide() or
307        displaySlide() methods.
308
309        @param xListener
310        Listener to add.
311     */
312    void addSlideShowListener( [in] XSlideShowListener xListener );
313
314    /** Revoke a previously registered slide show listener.<p>
315
316        @param xListener
317        Listener interface to revoke from being called.
318     */
319    void removeSlideShowListener( [in] XSlideShowListener xListener );
320
321    /** Add a shape event listener.<p>
322
323        This method adds a listener to the slide show, which will get
324        notified when a mouse click is performed on the given
325        shape. This can be used by clients of the slide show to
326        trigger external actions, such as jumps to different slides.<p>
327
328        @param xListener
329        Listener to add.
330
331        @param xShape
332        Shape to register a listener for.
333     */
334    void addShapeEventListener(
335        [in] XShapeEventListener xListener,
336        [in] ::com::sun::star::drawing::XShape xShape );
337
338    /** Revoke a previously registered shape event listener.<p>
339
340        @param xListener
341        Listener interface to revoke from being called.
342
343        @param xShape
344        Shape for which the listener should be revoked.
345     */
346    void removeShapeEventListener(
347        [in] XShapeEventListener xListener,
348        [in] ::com::sun::star::drawing::XShape xShape );
349
350    /** Set a special mouse cursor for a shape.<p>
351
352        This method requests the slide show to display a special
353        cursor, whenever the mouse is hovering over the given shape.<p>
354
355        @param xShape
356        Shape to display a special mouse cursor.
357
358        @param nPointerShape
359        Type of mouse cursor to display. Must be one of the
360        ::com::sun::star::awt::SystemPointer values.
361     */
362    void setShapeCursor(
363        [in] ::com::sun::star::drawing::XShape xShape,
364        [in] short nPointerShape );
365
366};
367
368}; }; }; };
369
370#endif
371
372