sd/source/ui/inc/framework/FrameworkHelper.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_SD_SOURCE_UI_INC_FRAMEWORK_FRAMEWORKHELPER_HXX
  21 #define INCLUDED_SD_SOURCE_UI_INC_FRAMEWORK_FRAMEWORKHELPER_HXX
  22
  23 #include "ViewShell.hxx"
  24
  25 #include "tools/SdGlobalResourceContainer.hxx"
  26
  27 #include <com/sun/star/drawing/framework/XConfigurationController.hpp>
  28 #include <com/sun/star/drawing/framework/XView.hpp>
  29 #include <com/sun/star/lang/XEventListener.hpp>
  30
  31 #include <boost/scoped_ptr.hpp>
  32 #include <boost/shared_ptr.hpp>
  33 #include <boost/enable_shared_from_this.hpp>
  34 #include <boost/function.hpp>
  35 #include <map>
  36
  37 namespace sd {
  38 class ViewShell;
  39 class ViewShellBase;
  40 }
  41
  42
  43 namespace sd { namespace framework {
  44
  45 /** The FrameworkHelper is a convenience class that simplifies the
  46     access to the drawing framework.
  47     It has three main tasks:
  48     1. Provide frequently used strings of resource URLs and event names.
  49     2. Provide shortcuts for accessing the sd framework.
  50     3. Ease the migration to the drawing framwork.
  51
  52     Note that a FrameworkHelper disposes itself when one of the resource
  53     controllers called by it throws a DisposedException.
  54 */
  55 class FrameworkHelper
  56     : public ::boost::enable_shared_from_this<FrameworkHelper>,
  57       public SdGlobalResource
  58 {
  59 public:
  60     // URLs of frequently used panes.
  61     static const OUString msPaneURLPrefix;
  62     static const OUString msCenterPaneURL;
  63     static const OUString msFullScreenPaneURL;
  64     static const OUString msLeftImpressPaneURL;
  65     static const OUString msLeftDrawPaneURL;
  66     static const OUString msSidebarPaneURL;
  67
  68     // URLs of frequently used views.
  69     static const OUString msViewURLPrefix;
  70     static const OUString msImpressViewURL;
  71     static const OUString msDrawViewURL;
  72     static const OUString msOutlineViewURL;
  73     static const OUString msNotesViewURL;
  74     static const OUString msHandoutViewURL;
  75     static const OUString msSlideSorterURL;
  76     static const OUString msPresentationViewURL;
  77     static const OUString msSidebarViewURL;
  78
  79     // URLs of frequently used tool bars.
  80     static const OUString msToolBarURLPrefix;
  81     static const OUString msViewTabBarURL;
  82
  83     // URLs of task panels.
  84     static const OUString msTaskPanelURLPrefix;
  85     static const OUString msAllMasterPagesTaskPanelURL;
  86     static const OUString msRecentMasterPagesTaskPanelURL;
  87     static const OUString msUsedMasterPagesTaskPanelURL;
  88     static const OUString msLayoutTaskPanelURL;
  89     static const OUString msTableDesignPanelURL;
  90     static const OUString msCustomAnimationTaskPanelURL;
  91     static const OUString msSlideTransitionTaskPanelURL;
  92
  93     // Names of frequently used events.
  94     static const OUString msResourceActivationRequestEvent;
  95     static const OUString msResourceDeactivationRequestEvent;
  96     static const OUString msResourceActivationEvent;
  97     static const OUString msResourceDeactivationEvent;
  98     static const OUString msResourceDeactivationEndEvent;
  99     static const OUString msConfigurationUpdateStartEvent;
 100     static const OUString msConfigurationUpdateEndEvent;
 101
 102     // Service names of the common controllers.
 103     static const OUString msModuleControllerService;
 104     static const OUString msConfigurationControllerService;
 105
 106     /** Return the FrameworkHelper object that is associated with the given
 107         ViewShellBase.  If such an object does not yet exist, a new one is
 108         created.
 109     */
 110     static ::boost::shared_ptr<FrameworkHelper> Instance (ViewShellBase& rBase);
 111
 112     /** Mark the FrameworkHelper object for the given ViewShellBase as
 113         disposed.  A following ReleaseInstance() call will destroy the
 114         FrameworkHelper object.
 115
 116         Do not call this method.  It is an internally used method that can
 117         not be made private.
 118     */
 119     static void DisposeInstance (ViewShellBase& rBase);
 120
 121     /** Destroy the FrameworkHelper object for the given ViewShellBase.
 122
 123         Do not call this method.  It is an internally used method that can
 124         not be made private.
 125     */
 126     static void ReleaseInstance (ViewShellBase& rBase);
 127
 128     /** Return an identifier for the given view URL.  This identifier can be
 129         used in a switch statement.  See GetViewURL() for a mapping in the
 130         opposite direction.
 131     */
 132     static ViewShell::ShellType GetViewId (const OUString& rsViewURL);
 133
 134     /** Return a view URL for the given identifier.  See GetViewId() for a
 135         mapping in the opposite direction.
 136     */
 137     static OUString GetViewURL (ViewShell::ShellType eType);
 138
 139     /** Return a ViewShell pointer for the given XView reference.  This
 140         assumes that the given reference is implemented by the
 141         ViewShellWrapper class that supports the XTunnel interface.
 142         @return
 143             When the ViewShell pointer can not be inferred from the given
 144             reference then an empty pointer is returned.
 145     */
 146     static ::boost::shared_ptr<ViewShell> GetViewShell (
 147         const css::uno::Reference<css::drawing::framework::XView>& rxView);
 148
 149     typedef ::boost::function<bool(const css::drawing::framework::ConfigurationChangeEvent&)>
 150         ConfigurationChangeEventFilter;
 151     typedef ::boost::function<void(bool bEventSeen)> Callback;
 152     typedef ::boost::function<
 153         void(
 154             const css::uno::Reference<
 155                 css::drawing::framework::XResourceId>&)
 156         > ResourceFunctor;
 157
 158     /** Test whether the called FrameworkHelper object is valid.
 159         @return
 160             When the object has already been disposed then <FALSE/> is returned.
 161     */
 162     bool IsValid();
 163
 164     /** Return a pointer to the view shell that is displayed in the
 165         specified pane.  See GetView() for a variant that returns a
 166         reference to XView instead of a ViewShell pointer.
 167         @return
 168             An empty pointer is returned when for example the specified pane
 169             does not exist or is not visible or does not show a view or one
 170             of the involved objects does not support XUnoTunnel (where
 171             necessary).
 172     */
 173     ::boost::shared_ptr<ViewShell> GetViewShell (const OUString& rsPaneURL);
 174
 175     /** Return a reference to the view that is displayed in the specified
 176         pane.  See GetViewShell () for a variant that returns a ViewShell
 177         pointer instead of a reference to XView.
 178         @param rxPaneOrViewId
 179             When this ResourceId specifies a view then that view is
 180             returned.  When it belongs to a pane then one view in that pane
 181             is returned.
 182         @return
 183             An empty reference is returned when for example the specified pane
 184             does not exist or is not visible or does not show a view or one
 185             of the involved objects does not support XTunnel (where
 186             necessary).
 187     */
 188     css::uno::Reference<css::drawing::framework::XView> GetView (
 189         const css::uno::Reference<css::drawing::framework::XResourceId>& rxPaneOrViewId);
 190
 191     /** Request the specified view to be displayed in the specified pane.
 192         When the pane is not visible its creation is also requested.  The
 193         update that creates the actual view object is done asynchronously.
 194         @param rsResourceURL
 195             The resource URL of the view to show.
 196         @param rsAnchorURL
 197             The URL of the pane in which to show the view.
 198         @return
 199             The resource id of the requested view is returned.  With that
 200             the caller can, for example, call RunOnResourceActivation() to
 201             do some initialization after the requested view becomes active.
 202     */
 203     css::uno::Reference<css::drawing::framework::XResourceId> RequestView (
 204         const OUString& rsResourceURL,
 205         const OUString& rsAnchorURL);
 206
 207     /** Process a slot call that requests a view shell change.
 208     */
 209     void HandleModeChangeSlot (
 210         sal_uLong nSlotId,
 211         SfxRequest& rRequest);
 212
 213     /** Run the given callback when the specified event is notified by the
 214         ConfigurationManager.  When there are no pending requests and
 215         therefore no events would be notified (in the foreseeable future)
 216         then the callback is called immediately.
 217         The callback is called with a flag that tells the callback whether
 218         the event it waits for has been sent.
 219     */
 220     void RunOnConfigurationEvent(
 221         const OUString& rsEventType,
 222         const Callback& rCallback);
 223
 224     /** Run the given callback when the specified resource has been
 225         activated.  When the resource is active already when this method is
 226         called then rCallback is called before this method returns.
 227         @param rxResourceId
 228             Wait for the activation of this resource before calling
 229             rCallback.
 230         @param rCallback
 231             The callback to be called when the resource is activated.
 232
 233     */
 234     void RunOnResourceActivation(
 235         const css::uno::Reference<css::drawing::framework::XResourceId>& rxResourceId,
 236         const Callback& rCallback);
 237
 238     /** Normally the requested changes of the configuration are executed
 239         asynchronously.  However, there is at least one situation (searching
 240         with the Outliner) where the surrounding code does not cope with
 241         this.  So, instead of calling Reschedule until the global event loop
 242         executes the configuration update, this method does (almost) the
 243         same without the reschedules.
 244
 245         Do not use this method until there is absolutely no other way.
 246     */
 247     void RequestSynchronousUpdate();
 248
 249     /** Block until the specified event is notified by the configuration
 250         controller.  When the configuration controller is not processing any
 251         requests the method returns immediately.
 252     */
 253     void WaitForEvent (const OUString& rsEventName) const;
 254
 255     /** This is a short cut for WaitForEvent(msConfigurationUpdateEndEvent).
 256         Call this method to execute the pending requests.
 257     */
 258     void WaitForUpdate() const;
 259
 260     /** Explicit request for an update of the current configuration.  Call
 261         this method when one of the resources managed by the sd framework
 262         has been activated or deactivated from the outside, i.e. not by the
 263         framework itself.  An example for this is a click on the closer
 264         button of one of the side panes.
 265     */
 266     void UpdateConfiguration();
 267
 268     /** Return a string representation of the given XResourceId object.
 269     */
 270     static OUString ResourceIdToString (
 271         const css::uno::Reference<
 272             css::drawing::framework::XResourceId>& rxResourceId);
 273
 274     /** Create a new XResourceId object for the given resource URL.
 275     */
 276     static css::uno::Reference<
 277         css::drawing::framework::XResourceId>
 278             CreateResourceId (
 279                 const OUString& rsResourceURL);
 280
 281     /** Create a new XResourceId object for the given resource URL and a
 282         single anchor URL.
 283     */
 284     static css::uno::Reference<
 285         css::drawing::framework::XResourceId>
 286             CreateResourceId (
 287                 const OUString& rsResourceURL,
 288                 const OUString& rsAnchorURL);
 289
 290     /** Create a new XResourceId object for the given resource URL.
 291     */
 292     static css::uno::Reference<
 293         css::drawing::framework::XResourceId>
 294             CreateResourceId (
 295                 const OUString& rsResourceURL,
 296                 const css::uno::Reference<
 297                     css::drawing::framework::XResourceId>& rxAnchor);
 298
 299     css::uno::Reference<css::drawing::framework::XConfigurationController>
 300         GetConfigurationController() const { return mxConfigurationController;}
 301
 302 private:
 303     typedef ::std::map<
 304         ViewShellBase*,
 305         ::boost::shared_ptr<FrameworkHelper> > InstanceMap;
 306     /** The instance map holds (at least) one FrameworkHelper instance for
 307         every ViewShellBase object.
 308     */
 309     static InstanceMap maInstanceMap;
 310     class ViewURLMap;
 311     static ::boost::scoped_ptr<ViewURLMap> mpViewURLMap;
 312
 313     ViewShellBase& mrBase;
 314     css::uno::Reference<css::drawing::framework::XConfigurationController>
 315         mxConfigurationController;
 316
 317     class DisposeListener;
 318     friend class DisposeListener;
 319     css::uno::Reference<css::lang::XComponent>
 320         mxDisposeListener;
 321
 322     FrameworkHelper (ViewShellBase& rBase);
 323     FrameworkHelper (const FrameworkHelper& rHelper) SAL_DELETED_FUNCTION;
 324     virtual ~FrameworkHelper();
 325     class Deleter; friend class Deleter;
 326     FrameworkHelper& operator= (const FrameworkHelper& rHelper) SAL_DELETED_FUNCTION;
 327
 328     void Initialize();
 329
 330     void Dispose();
 331
 332     /** Run the given callback when an event of the specified type is
 333         received from the ConfigurationController or when the
 334         ConfigurationController has no pending change requests.
 335         @param rsEventType
 336             Run rCallback only on this event.
 337         @param rFilter
 338             This filter has to return <TRUE/> in order for rCallback to be
 339             called.
 340         @param rCallback
 341             The callback functor to be called.
 342     */
 343     void RunOnEvent(
 344         const OUString& rsEventType,
 345         const ConfigurationChangeEventFilter& rFilter,
 346         const Callback& rCallback) const;
 347
 348     /** This disposing method is forwarded from the inner DisposeListener class.
 349     */
 350     void disposing (const css::lang::EventObject& rEventObject);
 351 };
 352
 353 } } // end of namespace sd::framework
 354
 355 #endif
 356
 357 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */