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