slideshow/source/inc/usereventqueue.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: usereventqueue.hxx,v $
  10  * $Revision: 1.7 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef INCLUDED_SLIDESHOW_USEREVENTQUEUE_HXX
  32 #define INCLUDED_SLIDESHOW_USEREVENTQUEUE_HXX
  33
  34 #include <com/sun/star/animations/XAnimationNode.hpp>
  35
  36 #include "eventmultiplexer.hxx"
  37 #include "eventqueue.hxx"
  38 #include "shape.hxx"
  39
  40 #include <boost/noncopyable.hpp>
  41
  42 /* Definition of UserEventQueue class */
  43
  44 namespace slideshow {
  45 namespace internal {
  46
  47 class PlainEventHandler;
  48 class AllAnimationEventHandler;
  49 class ShapeClickEventHandler;
  50 class ClickEventHandler;
  51 class CursorManager;
  52 class SkipEffectEventHandler;
  53 class RewindEffectEventHandler;
  54 class MouseEnterHandler;
  55 class MouseLeaveHandler;
  56
  57 /** This class schedules user-activated events.
  58
  59     This class registeres at the EventMultiplexer and fires
  60     events registered for certain user actions. Note that all
  61     events will not be fired immediately after the user action
  62     occured, but always added to the EventQueue (and fired the
  63     next time that queue is processed). Which is actually a
  64     feature.
  65
  66     Conceptually, an event is an object that typically is
  67     fired only once. After that, the event is exhausted, and
  68     should be discarded. Therefore, all events registered on
  69     this object are fired and then all references to them are
  70     removed.
  71 */
  72 class UserEventQueue : private ::boost::noncopyable
  73 {
  74 public:
  75     /** Create a user event queue
  76
  77         @param rEventMultiplexer
  78         The slideshow-global event source, where this class
  79         registeres its event handlers.
  80
  81         @param rEventQueue
  82         Reference to the main event queue. Since we hold this
  83         object by plain reference, it must live longer than we
  84         do. On the other hand, that queue must not fire events
  85         after this object is destroyed, since we might
  86         schedule events there which itself contain plain
  87         references to this object. Basically, EventQueue and
  88         UserEventQueue should have the same lifetime, and since
  89         this is not possible, both must be destructed in a
  90         phased mode: first clear both of any remaining events,
  91         then destruct them.
  92     */
  93     UserEventQueue( EventMultiplexer&   rMultiplexer,
  94                     EventQueue&         rEventQueue,
  95                     CursorManager&      rCursorManager );
  96     ~UserEventQueue();
  97
  98     /** Query whether there are any events still pending.
  99      */
 100     bool isEmpty() const;
 101
 102     /** Clear all registered events.
 103
 104         This method clears all registered, but
 105         not-yet-executed events. This comes in handy when
 106         force-ending a slide, to avoid interference with the
 107         next slide's event registration.
 108     */
 109     void clear();
 110
 111     /** Set advance on click behaviour.
 112
 113         @param bAdvanceOnClick
 114         When true, a click somewhere on the slide will also
 115         generate next effect event.  In this case, it is
 116         irrelevant where on the slide the mouse is clicked,
 117         i.e. the shape need not be hit by the mouse.
 118     */
 119     void setAdvanceOnClick( bool bAdvanceOnClick );
 120
 121     /** Register an event that will be fired when the slide is
 122         just shown.
 123
 124         Note that <em>all</em> registered events will be fired
 125         when the slide start occurs. This is in contrast to
 126         the mouse events below.
 127     */
 128     void registerSlideStartEvent( const EventSharedPtr& rEvent );
 129
 130     /** Register an event that will be fired when the slide is
 131         about to vanish.
 132
 133         Note that <em>all</em> registered events will be fired
 134         when the slide end occurs. This is in contrast to
 135         the mouse events below.
 136     */
 137     void registerSlideEndEvent( const EventSharedPtr& rEvent );
 138
 139     /** Register an event that will be fired when the given
 140         animation node starts.
 141
 142         Note that <em>all</em> registered events will be fired
 143         when the animation start occurs. This is in contrast to
 144         the mouse events below.
 145     */
 146     void registerAnimationStartEvent(
 147         const EventSharedPtr&                             rEvent,
 148         const ::com::sun::star::uno::Reference<
 149         ::com::sun::star::animations::XAnimationNode>&    xNode );
 150
 151     /** Register an event that will be fired when the given
 152         animation node ends its active duration.
 153
 154         Note that <em>all</em> registered events will be fired
 155         when the animation end occurs. This is in contrast to
 156         the mouse events below.
 157     */
 158     void registerAnimationEndEvent(
 159         const EventSharedPtr&                               rEvent,
 160         const ::com::sun::star::uno::Reference<
 161         ::com::sun::star::animations::XAnimationNode>&      xNode );
 162
 163     /** Register an event that will be fired when audio output
 164         stopped for the given animation node.
 165
 166         Note that <em>all</em> registered events will be fired
 167         when the audio stopping occurs. This is in contrast to
 168         the mouse events below.
 169     */
 170     void registerAudioStoppedEvent(
 171         const EventSharedPtr&                               rEvent,
 172         const ::com::sun::star::uno::Reference<
 173         ::com::sun::star::animations::XAnimationNode>&      xNode );
 174
 175     /** Register an event that is fired when a shape is clicked
 176
 177         For every mouse click, only one of the events
 178         registered here is fired. The order of fired events is
 179         the order of registration, i.e. the first event
 180         registered will be the one fired for the first mouse
 181         click on the given shape.
 182     */
 183     void registerShapeClickEvent( const EventSharedPtr& rEvent,
 184                                   const ShapeSharedPtr& rShape );
 185
 186     /** Registes an event that is fired when the current effects(s)
 187         are skipped, .e.g. when the left mouse button is pressed.
 188         Then, all registered events are fired and removed from this
 189         queue.  After firing, a next effect event is issued to this
 190         queue to start the next effect.
 191         @param pEvent
 192             The event to execute when skipping the current effect.
 193         @param bSkipTriggersNextEffect
 194             When <TRUE/> then after skipping the current effect the next
 195             effect is triggered.  When <FALSE/> then the next effect is not
 196             triggered.
 197     */
 198     void registerSkipEffectEvent(
 199         EventSharedPtr const& pEvent,
 200         const bool bSkipTriggersNextEffect);
 201
 202     /** Registes an event that is fired when the current effects(s)
 203         are rewound, .e.g. when the right mouse button is pressed.
 204         Then, all registered events are fired and removed from this
 205         queue.
 206     */
 207     void registerRewindEffectEvent( EventSharedPtr const& rEvent );
 208
 209     /** Register an event that is fired to show the next event
 210
 211         For every next effect event, only one of the events
 212         registered here is fired. The order of fired events is
 213         the order of registration, i.e. the first event
 214         registered will be the one fired for the first mouse
 215         click. When advance-on-click (see method
 216         setAdvanceOnClick()) is enabled, a mouse click
 217         somewhere on the slide will also generate a next
 218         effect event. In this case, it is irrelevant where on
 219         the slide the mouse is clicked, i.e. the shape need
 220         not be hit by the mouse.
 221     */
 222     void registerNextEffectEvent( const EventSharedPtr& rEvent );
 223
 224     /** Register an event that is fired on a double mouse
 225         click on a shape
 226
 227         For every mouse double click, only one of the events
 228         registered here is fired. The order of fired events is
 229         the order of registration, i.e. the first event
 230         registered will be the one fired for the first mouse
 231         double click. It is irrelevant where on the slide the
 232         mouse is clicked, i.e. the shape need not be hit by
 233         the mouse.
 234     */
 235     void registerShapeDoubleClickEvent( const EventSharedPtr& rEvent,
 236                                         const ShapeSharedPtr& rShape );
 237
 238     /** Register an event that is fired on a double mouse click
 239
 240         For every mouse double click, only one of the events
 241         registered here is fired. The order of fired events is
 242         the order of registration, i.e. the first event
 243         registered will be the one fired for the first mouse
 244         double click. It is irrelevant where on the slide the
 245         mouse is clicked, i.e. the shape need not be hit by
 246         the mouse.
 247     */
 248     void registerDoubleClickEvent( const EventSharedPtr& rEvent );
 249
 250     /** Register an event that is fired when the mouse enters
 251         the area of the given shape
 252
 253         For every enter, only one of the events registered
 254         here is fired. The order of fired events is the order
 255         of registration, i.e. the first event registered will
 256         be the one fired for the first time the mouse enters
 257         the given shape.
 258     */
 259     void registerMouseEnterEvent( const EventSharedPtr& rEvent,
 260                                   const ShapeSharedPtr& rShape );
 261
 262     /** Register an event that is fired when the mouse leaves
 263         the area of the given shape
 264
 265         For every leave, only one of the events registered
 266         here is fired. The order of fired events is the order
 267         of registration, i.e. the first event registered will
 268         be the one fired for the first time the mouse leaves
 269         the given shape area.
 270     */
 271     void registerMouseLeaveEvent( const EventSharedPtr& rEvent,
 272                                   const ShapeSharedPtr& rShape );
 273
 274     /** Typically skipping the current effect is triggered by mouse clicks
 275         or key presses that trigger the next effect.  This method allows the
 276         skipping of effects to be triggered programatically.
 277     */
 278     void callSkipEffectEventHandler (void);
 279
 280 private:
 281     /** Generically register an event on one of the handlers.
 282
 283         If the handler is not yet created, do that and
 284         register it via the Functor
 285     */
 286     template< typename Handler, typename Functor >
 287     void registerEvent( ::boost::shared_ptr< Handler >& rHandler,
 288                         const EventSharedPtr&           rEvent,
 289                         const Functor&                  rRegistrationFunctor );
 290
 291     /** Generically register an event on one of the handlers.
 292
 293         If the handler is not yet created, do that and
 294         register it via the Functor. This version of the
 295         registerEvent method takes an additional parameter
 296         rArg, which is passed as the second argument to
 297         rHandler's addEvent() method.
 298     */
 299     template< typename Handler, typename Arg, typename Functor >
 300     void registerEvent( ::boost::shared_ptr< Handler >& rHandler,
 301                         const EventSharedPtr&           rEvent,
 302                         const Arg&                      rArg,
 303                         const Functor&                  rRegistrationFunctor );
 304
 305     EventMultiplexer&                               mrMultiplexer;
 306     EventQueue&                                     mrEventQueue;
 307     CursorManager&                                  mrCursorManager;
 308
 309     ::boost::shared_ptr<PlainEventHandler>          mpStartEventHandler;
 310     ::boost::shared_ptr<PlainEventHandler>          mpEndEventHandler;
 311     ::boost::shared_ptr<AllAnimationEventHandler>   mpAnimationStartEventHandler;
 312     ::boost::shared_ptr<AllAnimationEventHandler>   mpAnimationEndEventHandler;
 313     ::boost::shared_ptr<AllAnimationEventHandler>   mpAudioStoppedEventHandler;
 314     ::boost::shared_ptr<ShapeClickEventHandler>     mpShapeClickEventHandler;
 315     ::boost::shared_ptr<ClickEventHandler>          mpClickEventHandler;
 316     ::boost::shared_ptr<SkipEffectEventHandler>     mpSkipEffectEventHandler;
 317     ::boost::shared_ptr<RewindEffectEventHandler>   mpRewindEffectEventHandler;
 318     ::boost::shared_ptr<ShapeClickEventHandler>     mpShapeDoubleClickEventHandler;
 319     ::boost::shared_ptr<ClickEventHandler>          mpDoubleClickEventHandler;
 320     ::boost::shared_ptr<MouseEnterHandler>          mpMouseEnterHandler;
 321     ::boost::shared_ptr<MouseLeaveHandler>          mpMouseLeaveHandler;
 322
 323     bool                                            mbAdvanceOnClick;
 324 };
 325
 326 } // namespace internal
 327 } // namespace presentation
 328
 329 #endif /* INCLUDED_SLIDESHOW_USEREVENTQUEUE_HXX */
 330