framework/inc/dispatch/closedispatcher.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 <com/sun/star/frame/XFrame.hpp>
  23 #include <com/sun/star/frame/XStatusListener.hpp>
  24 #include <com/sun/star/frame/XNotifyingDispatch.hpp>
  25 #include <com/sun/star/frame/XDispatchInformationProvider.hpp>
  26 #include <com/sun/star/util/URL.hpp>
  27 #include <com/sun/star/frame/XDispatchResultListener.hpp>
  28 #include <com/sun/star/uno/XComponentContext.hpp>
  29
  30 #include <memory>
  31 #include <cppuhelper/implbase.hxx>
  32 #include <cppuhelper/weakref.hxx>
  33 #include <vcl/evntpost.hxx>
  34 #include <vcl/vclptr.hxx>
  35
  36 class SystemWindow;
  37
  38 namespace framework{
  39
  40 /**
  41     @short          helper to dispatch the URLs ".uno:CloseDoc"/".uno:CloseWin"/".uno:CloseFrame"
  42                     to close a frame/document or the whole application implicitly in case it was the last frame
  43
  44     @descr          These URLs implements a special functionality to close a document or the whole frame ...
  45                     and handle the state, it was the last frame or document. Then we create the
  46                     default backing document which can be used to open new ones using the file open dialog
  47                     or some other menu entries. Or we terminate the whole application in case this backing mode should not
  48                     be used.
  49  */
  50 class CloseDispatcher final : public  ::cppu::WeakImplHelper<
  51                                     css::frame::XNotifyingDispatch,             // => XDispatch
  52                                     css::frame::XDispatchInformationProvider >
  53 {
  54
  55     // types
  56
  57     private:
  58
  59         /** @short  describe, which request must be done here.
  60         @descr      The incoming URLs {.uno:CloseDoc/CloseWin and CloseFrame
  61                     can be classified so and checked later performant.}*/
  62         enum EOperation
  63         {
  64             E_CLOSE_DOC,
  65             E_CLOSE_FRAME,
  66             E_CLOSE_WIN
  67         };
  68
  69     // member
  70
  71     private:
  72
  73         /** @short reference to a uno service manager,
  74                    which can be used to create own needed
  75                    uno resources. */
  76         css::uno::Reference< css::uno::XComponentContext > m_xContext;
  77
  78         /** @short  reference to the target frame, which should be
  79                     closed by this dispatch. */
  80         css::uno::WeakReference< css::frame::XFrame > m_xCloseFrame;
  81
  82         /** @short  used for asynchronous callbacks within the main thread.
  83             @descr  Internally we work asynchronously. Because our callees
  84                     are not aware that their request can kill its own environment... */
  85         std::unique_ptr<vcl::EventPoster> m_aAsyncCallback;
  86
  87         /** @short  used inside asynchronous callback to decide,
  88                     which operation must be executed. */
  89         EOperation m_eOperation;
  90
  91         /** @short  for asynchronous operations we must hold us self alive! */
  92         css::uno::Reference< css::uno::XInterface > m_xSelfHold;
  93
  94         /** @short  holded alive for internally asynchronous operations! */
  95         css::uno::Reference< css::frame::XDispatchResultListener > m_xResultListener;
  96
  97         VclPtr<SystemWindow> m_pSysWindow;
  98
  99     // native interface
 100
 101     public:
 102
 103         /** @short  connect a new CloseDispatcher instance to its frame.
 104             @descr  One CloseDispatcher instance is bound to own frame only.
 105                     That makes an implementation (e.g. of listener support)
 106                     much more easier .-)
 107
 108             @param  rxContext
 109                     an un oservice manager, which is needed to create uno resource
 110                     internally.
 111
 112             @param  xFrame
 113                     the frame where the corresponding dispatch was started.
 114
 115             @param  sTarget
 116                     help us to find the right target for this close operation.
 117          */
 118         CloseDispatcher(css::uno::Reference< css::uno::XComponentContext >        xContext  ,
 119                         const css::uno::Reference< css::frame::XFrame >&          xFrame ,
 120                         std::u16string_view                                       sTarget);
 121
 122         /** @short  does nothing real. */
 123         virtual ~CloseDispatcher() override;
 124
 125     // uno interface
 126
 127     public:
 128
 129         // XNotifyingDispatch
 130         virtual void SAL_CALL dispatchWithNotification( const css::util::URL&                                             aURL      ,
 131                                                         const css::uno::Sequence< css::beans::PropertyValue >&            lArguments,
 132                                                         const css::uno::Reference< css::frame::XDispatchResultListener >& xListener ) override;
 133
 134         // XDispatch
 135         virtual void SAL_CALL dispatch            ( const css::util::URL&                                     aURL      ,
 136                                                     const css::uno::Sequence< css::beans::PropertyValue >&    lArguments) override;
 137         virtual void SAL_CALL addStatusListener   ( const css::uno::Reference< css::frame::XStatusListener >& xListener ,
 138                                                     const css::util::URL&                                     aURL      ) override;
 139         virtual void SAL_CALL removeStatusListener( const css::uno::Reference< css::frame::XStatusListener >& xListener ,
 140                                                     const css::util::URL&                                     aURL      ) override;
 141
 142         // XDispatchInformationProvider
 143         virtual css::uno::Sequence< sal_Int16 >                       SAL_CALL getSupportedCommandGroups         (                         ) override;
 144         virtual css::uno::Sequence< css::frame::DispatchInformation > SAL_CALL getConfigurableDispatchInformation( sal_Int16 nCommandGroup ) override;
 145
 146     // internal helper
 147
 148     private:
 149
 150         /** @short  a callback for asynchronous started operations.
 151
 152             @descr  As already mentioned, we make internally all operations
 153                     asynchronous. Otherwise our callis kill its own environment
 154                     during they call us...
 155         */
 156         DECL_LINK( impl_asyncCallback, LinkParamNone*, void );
 157
 158         /** @short  prepare m_xCloseFrame so it should be closeable without problems.
 159
 160             @descr  That's needed to be sure, that the document can't disagree
 161                     later with e.g. an office termination.
 162                     The problem: Closing of documents can show UI. If the user
 163                     ignores it and open/close other documents, we can't know
 164                     which state the office has after closing of this frame.
 165
 166             @param  bCloseAllOtherViewsToo
 167                     if there are other top level frames, which
 168                     contains views to the same document then our m_xCloseFrame,
 169                     they are forced to be closed too.
 170                     We need it to implement the CLOSE_DOC semantic.
 171
 172             @return [boolean]
 173                     sal_True if closing was successful.
 174          */
 175         bool implts_prepareFrameForClosing(const css::uno::Reference< css::frame::XFrame >& xFrame,
 176                                            bool                                   bCloseAllOtherViewsToo,
 177                                            bool&                                  bControllerSuspended  );
 178
 179         /** @short  close the member m_xCloseFrame.
 180
 181             @descr  This method does not look for any document
 182                     inside this frame. Such views must be cleared
 183                     before (e.g. by calling implts_closeView()!
 184
 185                     Otherwise e.g. the XController->suspend()
 186                     call is not made and no UI warn the user about
 187                     losing document changes. Because the
 188                     frame is closed...
 189
 190             @return [bool]
 191                     sal_True if closing was successful.
 192          */
 193         bool implts_closeFrame();
 194
 195         /** @short  set the special BackingComponent (now StartModule)
 196                     as new component of our m_xCloseFrame.
 197
 198             @return [bool]
 199                     sal_True if operation was successful.
 200          */
 201         bool implts_establishBackingMode();
 202
 203         /** @short  calls XDesktop->terminate().
 204
 205             @descr  No office code has to be called
 206                     afterwards! Because the process is dying...
 207                     The only exception is a might be registered
 208                     listener at this instance here.
 209                     Because he should know, that such things will happen :-)
 210
 211             @return [bool]
 212                     sal_True if termination of the application was started ...
 213          */
 214         bool implts_terminateApplication();
 215
 216         /** @short  notify a DispatchResultListener.
 217
 218             @descr  We check the listener reference before we use it.
 219                     So this method can be called every time!
 220
 221             @parama xListener
 222                     the listener, which should be notified.
 223                     Can be null!
 224
 225             @param  nState
 226                     directly used as css::frame::DispatchResultState value.
 227
 228             @param  aResult
 229                     not used yet really ...
 230          */
 231         void implts_notifyResultListener(const css::uno::Reference< css::frame::XDispatchResultListener >& xListener,
 232                                                sal_Int16                                                   nState   ,
 233                                          const css::uno::Any&                                              aResult  );
 234
 235         /** @short  try to find the right target frame where this close request
 236                     must be really done.
 237
 238             @descr  The problem behind: closing some resources depends sometimes from the
 239                     context where its dispatched. Sometimes the start frame of the dispatch
 240                     has to be closed itself (target=_self) ... sometimes its parent frame
 241                     has to be closed - BUT(!) it means a parent frame containing a top level
 242                     window. _top can't be used then for dispatch - because it address TopFrames
 243                     not frames containing top level windows. So normally _magic (which btw does not
 244                     exists at the moment .-) ) should be used. So we interpret target=<empty>
 245                     as _magic !
 246
 247             @param  xFrame
 248                     start point for search of right dispatch frame.
 249
 250             @param  sTarget
 251                     give us an idea how this target frame must be searched.
 252         */
 253
 254         static css::uno::Reference< css::frame::XFrame > static_impl_searchRightTargetFrame(const css::uno::Reference< css::frame::XFrame >& xFrame ,
 255                                                                                             std::u16string_view                        sTarget);
 256
 257 }; // class CloseDispatcher
 258
 259 } // namespace framework
 260
 261 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */