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