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