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