sd/source/ui/inc/framework/FrameworkHelper.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: FrameworkHelper.hxx,v $
  10  * $Revision: 1.6 $
  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 SD_FRAMEWORK_FRAMEWORK_HELPER_HXX
  32 #define SD_FRAMEWORK_FRAMEWORK_HELPER_HXX
  33
  34 #include "ViewShell.hxx"
  35
  36 #include "tools/SdGlobalResourceContainer.hxx"
  37
  38 #include <com/sun/star/drawing/framework/XConfigurationController.hpp>
  39 #include <com/sun/star/drawing/framework/XView.hpp>
  40 #include <com/sun/star/lang/XEventListener.hpp>
  41
  42 #include <boost/scoped_ptr.hpp>
  43 #include <boost/shared_ptr.hpp>
  44 #include <boost/enable_shared_from_this.hpp>
  45 #include <boost/function.hpp>
  46 #include <map>
  47
  48 namespace sd {
  49 class ViewShell;
  50 class ViewShellBase;
  51 }
  52
  53 namespace rtl {
  54 class OUString;
  55 }
  56
  57 namespace css = ::com::sun::star;
  58
  59 namespace sd { namespace framework {
  60
  61 /** The FrameworkHelper is a convenience class that simplifies the
  62     access to the drawing framework.
  63     It has three main tasks:
  64     1. Provide frequently used strings of resource URLs and event names.
  65     2. Provide shortcuts for accessing the sd framework.
  66     3. Easy the migration to the drawing framwork.
  67
  68     Note that a FrameworkHelper disposes itself when one of the resource
  69     controllers called by it throw a DisposedException.
  70 */
  71 class FrameworkHelper
  72     : public ::boost::enable_shared_from_this<FrameworkHelper>,
  73       public SdGlobalResource
  74 {
  75 public:
  76     // URLs of frequently used panes.
  77     static const ::rtl::OUString msPaneURLPrefix;
  78     static const ::rtl::OUString msCenterPaneURL;
  79     static const ::rtl::OUString msFullScreenPaneURL;
  80     static const ::rtl::OUString msLeftImpressPaneURL;
  81     static const ::rtl::OUString msLeftDrawPaneURL;
  82     static const ::rtl::OUString msRightPaneURL;
  83
  84     // URLs of frequently used views.
  85     static const ::rtl::OUString msViewURLPrefix;
  86     static const ::rtl::OUString msImpressViewURL;
  87     static const ::rtl::OUString msDrawViewURL;
  88     static const ::rtl::OUString msOutlineViewURL;
  89     static const ::rtl::OUString msNotesViewURL;
  90     static const ::rtl::OUString msHandoutViewURL;
  91     static const ::rtl::OUString msSlideSorterURL;
  92     static const ::rtl::OUString msPresentationViewURL;
  93     static const ::rtl::OUString msTaskPaneURL;
  94
  95     // URLs of frequently used tool bars.
  96     static const ::rtl::OUString msToolBarURLPrefix;
  97     static const ::rtl::OUString msViewTabBarURL;
  98
  99     // URLs of task panels.
 100     static const ::rtl::OUString msTaskPanelURLPrefix;
 101     static const ::rtl::OUString msMasterPagesTaskPanelURL;
 102     static const ::rtl::OUString msLayoutTaskPanelURL;
 103     static const ::rtl::OUString msTableDesignPanelURL;
 104     static const ::rtl::OUString msCustomAnimationTaskPanelURL;
 105     static const ::rtl::OUString msSlideTransitionTaskPanelURL;
 106
 107     // Names of frequently used events.
 108     static const ::rtl::OUString msResourceActivationRequestEvent;
 109     static const ::rtl::OUString msResourceDeactivationRequestEvent;
 110     static const ::rtl::OUString msResourceActivationEvent;
 111     static const ::rtl::OUString msResourceDeactivationEvent;
 112     static const ::rtl::OUString msConfigurationUpdateStartEvent;
 113     static const ::rtl::OUString msConfigurationUpdateEndEvent;
 114
 115     // Service names of the common controllers.
 116     static const ::rtl::OUString msModuleControllerService;
 117     static const ::rtl::OUString msConfigurationControllerService;
 118
 119     /** Return the FrameworkHelper object that is associated with the given
 120         ViewShellBase.  If such an object does not yet exist, a new one is
 121         created.
 122     */
 123     static ::boost::shared_ptr<FrameworkHelper> Instance (ViewShellBase& rBase);
 124
 125     static ::boost::shared_ptr<FrameworkHelper> Instance (
 126         const css::uno::Reference<css::frame::XController>& rxController);
 127
 128     /** Mark the FrameworkHelper object for the given ViewShellBase as
 129         disposed.  A following ReleaseInstance() call will destroy the
 130         FrameworkHelper object.
 131
 132         Do not call this method.  It is an internally used method that can
 133         not be made private.
 134     */
 135     static void DisposeInstance (ViewShellBase& rBase);
 136
 137     /** Destroy the FrameworkHelper object for the given ViewShellBase.
 138
 139         Do not call this method.  It is an internally used method that can
 140         not be made private.
 141     */
 142     static void ReleaseInstance (ViewShellBase& rBase);
 143
 144     /** Return an identifier for the given view URL.  This identifier can be
 145         used in a switch statement.  See GetViewURL() for a mapping in the
 146         opposite direction.
 147     */
 148     static ViewShell::ShellType GetViewId (const rtl::OUString& rsViewURL);
 149
 150     /** Return a view URL for the given identifier.  See GetViewId() for a
 151         mapping in the opposite direction.
 152     */
 153     static ::rtl::OUString GetViewURL (ViewShell::ShellType eType);
 154
 155     /** Return a ViewShell pointer for the given XView reference.  This
 156         assumes that the given reference is implemented by the
 157         ViewShellWrapper class that supports the XTunnel interface.
 158         @return
 159             When the ViewShell pointer can not be inferred from the given
 160             reference then an empty pointer is returned.
 161     */
 162     static ::boost::shared_ptr<ViewShell> GetViewShell (
 163         const css::uno::Reference<css::drawing::framework::XView>& rxView);
 164
 165     ~FrameworkHelper (void);
 166
 167     typedef ::boost::function<bool(const css::drawing::framework::ConfigurationChangeEvent&)>
 168         ConfigurationChangeEventFilter;
 169     typedef ::boost::function<void(bool bEventSeen)> Callback;
 170     typedef ::boost::function<
 171         void(
 172             const css::uno::Reference<
 173                 css::drawing::framework::XResourceId>&)
 174         > ResourceFunctor;
 175
 176     /** Test whether the called FrameworkHelper object is valid.
 177         @return
 178             When the object has already been disposed then <FALSE/> is returned.
 179     */
 180     bool IsValid (void);
 181
 182     /** Return a pointer to the view shell that is displayed in the
 183         specified pane.  See GetView() for a variant that returns a
 184         reference to XView instead of a ViewShell pointer.
 185         @return
 186             An empty pointer is returned when for example the specified pane
 187             does not exist or is not visible or does not show a view or one
 188             of the involved objects does not support XUnoTunnel (where
 189             necessary).
 190     */
 191     ::boost::shared_ptr<ViewShell> GetViewShell (const ::rtl::OUString& rsPaneURL);
 192
 193     /** Return a reference to the view that is displayed in the specified
 194         pane.  See GetViewShell () for a variant that returns a ViewShell
 195         pointer instead of a reference to XView.
 196         @param rxPaneOrViewId
 197             When this ResourceId specifies a view then that view is
 198             returned.  When it belongs to a pane then one view in that pane
 199             is returned.
 200         @return
 201             An empty reference is returned when for example the specified pane
 202             does not exist or is not visible or does not show a view or one
 203             of the involved objects does not support XTunnel (where
 204             necessary).
 205     */
 206     css::uno::Reference<css::drawing::framework::XView>
 207         GetView (
 208             const css::uno::Reference<
 209                 css::drawing::framework::XResourceId>& rxPaneOrViewId);
 210
 211     /** Request the specified view to be displayed in the specified pane.
 212         When the pane is not visible its creation is also requested.  The
 213         update that creates the actual view object is done asynchronously.
 214         @param rsResourceURL
 215             The resource URL of the view to show.
 216         @param rsAnchorURL
 217             The URL of the pane in which to show the view.
 218         @return
 219             The resource id of the requested view is returned.  With that
 220             the caller can, for example, call RunOnResourceActivation() to
 221             do some initialization after the requested view becomes active.
 222     */
 223     css::uno::Reference<css::drawing::framework::XResourceId> RequestView (
 224         const ::rtl::OUString& rsResourceURL,
 225         const ::rtl::OUString& rsAnchorURL);
 226
 227     /** Request the activation of the specified task panel in the standard
 228         task pane.
 229     */
 230     void RequestTaskPanel (
 231         const ::rtl::OUString& rsTaskPanelURL);
 232
 233     /** Process a slot call that requests a view shell change.
 234     */
 235     void HandleModeChangeSlot (
 236         ULONG nSlotId,
 237         SfxRequest& rRequest);
 238
 239     /** Run the given callback when the specified event is notified by the
 240         ConfigurationManager.  When there are no pending requests and
 241         therefore no events would be notified (in the foreseeable future)
 242         then the callback is called immediately.
 243         The callback is called with a flag that tells the callback whether
 244         the event it waits for has been sent.
 245     */
 246     void RunOnConfigurationEvent(
 247         const ::rtl::OUString& rsEventType,
 248         const Callback& rCallback);
 249
 250     /** Run the given callback when the specified resource has been
 251         activated.  When the resource is active already when this method is
 252         called then rCallback is called before this method returns.
 253         @param rxResourceId
 254             Wait for the activation of this resource before calling
 255             rCallback.
 256         @param rCallback
 257             The callback to be called when the resource is activated.
 258
 259     */
 260     void RunOnResourceActivation(
 261         const css::uno::Reference<css::drawing::framework::XResourceId>& rxResourceId,
 262         const Callback& rCallback);
 263
 264     /** Normally the requested changes of the configuration are executed
 265         asynchronously.  However, there is at least one situation (searching
 266         with the Outliner) where the surrounding code does not cope with
 267         this.  So, instead of calling Reschedule until the global event loop
 268         executes the configuration update, this method does (almost) the
 269         same without the reschedules.
 270
 271         Do not use this method until there is absolutely no other way.
 272     */
 273     void RequestSynchronousUpdate (void);
 274
 275     /** Block until the specified event is notified by the configuration
 276         controller.  When the configuration controller is not processing any
 277         requests the method returns immediately.
 278     */
 279     void WaitForEvent (const ::rtl::OUString& rsEventName) const;
 280
 281     /** This is a short cut for WaitForEvent(msConfigurationUpdateEndEvent).
 282         Call this method to execute the pending requests.
 283     */
 284     void WaitForUpdate (void) const;
 285
 286     /** Explicit request for an update of the current configuration.  Call
 287         this method when one of the resources managed by the sd framework
 288         has been activated or deactivated from the outside, i.e. not by the
 289         framework itself.  An example for this is a click on the closer
 290         button of one of the side panes.
 291     */
 292     void UpdateConfiguration (void);
 293
 294     /** Return a string representation of the given XResourceId object.
 295     */
 296     static ::rtl::OUString ResourceIdToString (
 297         const css::uno::Reference<
 298             css::drawing::framework::XResourceId>& rxResourceId);
 299
 300     /** Create a new XResourceId object for the given resource URL.
 301     */
 302     static css::uno::Reference<
 303         css::drawing::framework::XResourceId>
 304             CreateResourceId (
 305                 const ::rtl::OUString& rsResourceURL);
 306
 307     /** Create a new XResourceId object for the given resource URL and a
 308         single anchor URL.
 309     */
 310     static css::uno::Reference<
 311         css::drawing::framework::XResourceId>
 312             CreateResourceId (
 313                 const ::rtl::OUString& rsResourceURL,
 314                 const ::rtl::OUString& rsAnchorURL);
 315
 316     /** Create a new XResourceId object for the given resource URL and the
 317         two given anchor URLs.
 318     */
 319     static css::uno::Reference<
 320         css::drawing::framework::XResourceId>
 321             CreateResourceId (
 322                 const ::rtl::OUString& rsResourceURL,
 323                 const ::rtl::OUString& rsFirstAnchorURL,
 324                 const ::rtl::OUString& rsSecondAnchorURL);
 325
 326     /** Create a new XResourceId object for the given resource URL.
 327     */
 328     static css::uno::Reference<
 329         css::drawing::framework::XResourceId>
 330             CreateResourceId (
 331                 const ::rtl::OUString& rsResourceURL,
 332                 const css::uno::Reference<
 333                     css::drawing::framework::XResourceId>& rxAnchor);
 334
 335     css::uno::Reference<css::drawing::framework::XConfigurationController>
 336         GetConfigurationController (void) const;
 337
 338
 339 private:
 340     typedef ::std::map<
 341         ViewShellBase*,
 342         ::boost::shared_ptr<FrameworkHelper> > InstanceMap;
 343     /** The instance map holds (at least) one FrameworkHelper instance for
 344         every ViewShellBase object.
 345     */
 346     static InstanceMap maInstanceMap;
 347     class ViewURLMap;
 348     static ::boost::scoped_ptr<ViewURLMap> mpViewURLMap;
 349
 350     ViewShellBase& mrBase;
 351     css::uno::Reference<css::drawing::framework::XConfigurationController>
 352         mxConfigurationController;
 353
 354     class DisposeListener;
 355     friend class DisposeListener;
 356     css::uno::Reference<css::lang::XComponent>
 357         mxDisposeListener;
 358
 359     FrameworkHelper (ViewShellBase& rBase);
 360     FrameworkHelper (const FrameworkHelper& rHelper); // Not implemented.
 361     FrameworkHelper& operator= (const FrameworkHelper& rHelper); // Not implemented.
 362
 363     void Initialize (void);
 364
 365     void Dispose (void);
 366
 367     /** Run the given callback when an event of the specified type is
 368         received from the ConfigurationController or when the
 369         ConfigurationController has no pending change requests.
 370         @param rsEventType
 371             Run rCallback only on this event.
 372         @param rFilter
 373             This filter has to return <TRUE/> in order for rCallback to be
 374             called.
 375         @param rCallback
 376             The callback functor to be called.
 377     */
 378     void RunOnEvent(
 379         const ::rtl::OUString& rsEventType,
 380         const ConfigurationChangeEventFilter& rFilter,
 381         const Callback& rCallback) const;
 382
 383     /** This disposing method is forwarded from the inner DisposeListener class.
 384     */
 385     void disposing (const css::lang::EventObject& rEventObject);
 386 };
 387
 388
 389
 390 /** This functor wraps a slot call.  It is used to call a slot after an
 391     asynchronous configuration update, eg after switching views.
 392 */
 393 class DispatchCaller
 394 {
 395     SfxDispatcher& mrDispatcher;
 396     USHORT mnSId;
 397 public:
 398     /** Create a new DispatchCaller object that, when executed, will call
 399         the given slot at the given dispatcher.
 400     */
 401     DispatchCaller(SfxDispatcher& rDispatcher, USHORT nSId);
 402     void operator() (bool bEventSeen);
 403 };
 404
 405
 406 } } // end of namespace sd::framework
 407
 408
 409
 410 namespace sd { namespace framework {
 411
 412 namespace {
 413
 414     class FrameworkHelperAllPassFilter
 415     {
 416     public:
 417         bool operator() (const css::drawing::framework::ConfigurationChangeEvent&) { return true; }
 418     };
 419
 420
 421     class FrameworkHelperResourceIdFilter
 422     {
 423     public:
 424         FrameworkHelperResourceIdFilter (
 425             const css::uno::Reference<css::drawing::framework::XResourceId>& rxResourceId);
 426         bool operator() (const css::drawing::framework::ConfigurationChangeEvent& rEvent)
 427         { return mxResourceId.is() && rEvent.ResourceId.is()
 428                 && mxResourceId->compareTo(rEvent.ResourceId) == 0; }
 429     private:
 430         css::uno::Reference<css::drawing::framework::XResourceId> mxResourceId;
 431     };
 432
 433 } // end of anonymous namespace
 434
 435
 436
 437
 438 } } // end of namespace sd::framework
 439
 440
 441 #endif