framework/inc/dispatch/closedispatcher.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: closedispatcher.hxx,v $
  10  * $Revision: 1.14 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __FRAMEWORK_DISPATCH_CLOSEDISPATCHER_HXX_
  32 #define __FRAMEWORK_DISPATCH_CLOSEDISPATCHER_HXX_
  33
  34 //_______________________________________________
  35 // my own includes
  36
  37 #include <threadhelp/threadhelpbase.hxx>
  38 #include <macros/xinterface.hxx>
  39 #include <macros/xtypeprovider.hxx>
  40 #include <macros/debug.hxx>
  41 #include <macros/generic.hxx>
  42 #include <stdtypes.h>
  43 #include <general.h>
  44
  45 //_______________________________________________
  46 // interface includes
  47 #include <com/sun/star/lang/XTypeProvider.hpp>
  48 #include <com/sun/star/frame/XFrame.hpp>
  49 #include <com/sun/star/frame/XStatusListener.hpp>
  50 #include <com/sun/star/frame/XNotifyingDispatch.hpp>
  51 #include <com/sun/star/frame/XDispatchInformationProvider.hpp>
  52 #include <com/sun/star/util/URL.hpp>
  53 #include <com/sun/star/frame/XDispatchResultListener.hpp>
  54 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  55 #include <com/sun/star/frame/DispatchResultState.hpp>
  56
  57 //_______________________________________________
  58 // other includes
  59 #include <cppuhelper/weak.hxx>
  60 #include <vcl/evntpost.hxx>
  61
  62 //_______________________________________________
  63 // namespace
  64
  65 namespace framework{
  66
  67 //-----------------------------------------------
  68 /**
  69     @short          helper to dispatch the URLs ".uno:CloseDoc"/".uno:CloseWin"/".uno:CloseFrame"
  70                     to close a frame/document or the whole application implicitly in case it was the last frame
  71
  72     @descr          These URLs implements a special functionality to close a document or the whole frame ...
  73                     and handle the state, it was the last frame or document. Then we create the
  74                     default backing document which can be used to open new ones using the file open dialog
  75                     or some other menu entries. Or we terminate the whole application in case this backing mode shouldnt
  76                     be used.
  77  */
  78 class CloseDispatcher : public css::lang::XTypeProvider
  79                       , public css::frame::XNotifyingDispatch             // => XDispatch
  80                       , public css::frame::XDispatchInformationProvider
  81                         // baseclasses ... order is neccessary for right initialization!
  82                       , private ThreadHelpBase
  83                       , public  ::cppu::OWeakObject
  84 {
  85     //-------------------------------------------
  86     // types
  87
  88     private:
  89
  90         //---------------------------------------
  91         /** @short  describe, which request must be done here.
  92         @descr      The incoming URLs {.uno:CloseDoc/CloseWin and CloseFrame
  93                     can be classified so and checked later performant.}*/
  94         enum EOperation
  95         {
  96             E_CLOSE_DOC,
  97             E_CLOSE_FRAME,
  98             E_CLOSE_WIN
  99         };
 100
 101     //-------------------------------------------
 102     // member
 103
 104     private:
 105
 106         //---------------------------------------
 107         /** @short reference to an uno service manager,
 108                    which can be used to create own needed
 109                    uno resources. */
 110         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
 111
 112         //---------------------------------------
 113         /** @short  reference to the target frame, which should be
 114                     closed by this dispatch. */
 115         css::uno::WeakReference< css::frame::XFrame > m_xCloseFrame;
 116
 117         //---------------------------------------
 118         /** @short  used for asynchronous callbacks within the main thread.
 119             @descr  Internaly we work asynchronous. Because our callis
 120                     are not aware, that her request can kill its own environment ... */
 121         ::vcl::EventPoster m_aAsyncCallback;
 122
 123         //---------------------------------------
 124         /** @short  used inside asyncronous callback to decide,
 125                     which operation must be executed. */
 126         EOperation m_eOperation;
 127
 128         //---------------------------------------
 129         /** @short  for asynchronous operations we must hold us self alive! */
 130         css::uno::Reference< css::uno::XInterface > m_xSelfHold;
 131
 132         //---------------------------------------
 133         /** @short  list of registered status listener */
 134         ListenerHash m_lStatusListener;
 135
 136         //---------------------------------------
 137         /** @short  holded alive for internaly asynchronous operations! */
 138         css::uno::Reference< css::frame::XDispatchResultListener > m_xResultListener;
 139
 140     //-------------------------------------------
 141     // native interface
 142
 143     public:
 144
 145         //---------------------------------------
 146         /** @short  connect a new CloseDispatcher instance to its frame.
 147             @descr  One CloseDispatcher instance is bound to onw frame only.
 148                     That makes an implementation (e.g. of listener support)
 149                     much more easier .-)
 150
 151             @param  xSMGR
 152                     an un oservice manager, which is needed to create uno resource
 153                     internaly.
 154
 155             @param  xFrame
 156                     the frame where the corresponding dispatch was started.
 157
 158             @param  sTarget
 159                     help us to find the right target for this close operation.
 160          */
 161         CloseDispatcher(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
 162                         const css::uno::Reference< css::frame::XFrame >&              xFrame ,
 163                         const ::rtl::OUString&                                        sTarget);
 164
 165         //---------------------------------------
 166         /** @short  does nothing real. */
 167         virtual ~CloseDispatcher();
 168
 169     //-------------------------------------------
 170     // uno interface
 171
 172     public:
 173
 174         //---------------------------------------
 175         FWK_DECLARE_XINTERFACE
 176         FWK_DECLARE_XTYPEPROVIDER
 177
 178         //---------------------------------------
 179         // XNotifyingDispatch
 180         virtual void SAL_CALL dispatchWithNotification( const css::util::URL&                                             aURL      ,
 181                                                         const css::uno::Sequence< css::beans::PropertyValue >&            lArguments,
 182                                                         const css::uno::Reference< css::frame::XDispatchResultListener >& xListener ) throw(css::uno::RuntimeException);
 183
 184         //---------------------------------------
 185         // XDispatch
 186         virtual void SAL_CALL dispatch            ( const css::util::URL&                                     aURL      ,
 187                                                     const css::uno::Sequence< css::beans::PropertyValue >&    lArguments) throw(css::uno::RuntimeException);
 188         virtual void SAL_CALL addStatusListener   ( const css::uno::Reference< css::frame::XStatusListener >& xListener ,
 189                                                     const css::util::URL&                                     aURL      ) throw(css::uno::RuntimeException);
 190         virtual void SAL_CALL removeStatusListener( const css::uno::Reference< css::frame::XStatusListener >& xListener ,
 191                                                     const css::util::URL&                                     aURL      ) throw(css::uno::RuntimeException);
 192
 193         //---------------------------------------
 194         // XDispatchInformationProvider
 195         virtual css::uno::Sequence< sal_Int16 >                       SAL_CALL getSupportedCommandGroups         (                         ) throw (css::uno::RuntimeException);
 196         virtual css::uno::Sequence< css::frame::DispatchInformation > SAL_CALL getConfigurableDispatchInformation( sal_Int16 nCommandGroup ) throw (css::uno::RuntimeException);
 197
 198     //-------------------------------------------
 199     // internal helper
 200
 201     private:
 202
 203         //---------------------------------------
 204         /** @short  a callback for asynchronous started operations.
 205
 206             @descr  As already mentione, we make internaly all operations
 207                     asynchronous. Otherwhise our callis kill its own environment
 208                     during they call us ...
 209         */
 210         DECL_LINK( impl_asyncCallback, void* );
 211
 212         //---------------------------------------
 213         /** @short  prepare m_xCloseFrame so it should be closeable without problems.
 214
 215             @descr  Thats needed to be shure, that the document cant disagree
 216                     later with e.g. an office termination.
 217                     The problem: Closing of documents can show UI. If the user
 218                     ignores it and open/close other documents, we cant know
 219                     which state the office has after closing of this frame.
 220
 221             @param  bAllowSuspend
 222                     force calling of XController->suspend().
 223
 224             @param  bCloseAllOtherViewsToo
 225                     if there are other top level frames, which
 226                     contains views to the same document then our m_xCloseFrame,
 227                     they are forced to be closed too.
 228                     We need it to implement the CLOSE_DOC semantic.
 229
 230             @return [boolean]
 231                     TRUE if closing was successfully.
 232          */
 233         sal_Bool implts_prepareFrameForClosing(const css::uno::Reference< css::frame::XFrame >& xFrame                ,
 234                                                      sal_Bool                                   bAllowSuspend         ,
 235                                                      sal_Bool                                   bCloseAllOtherViewsToo,
 236                                                      sal_Bool&                                  bControllerSuspended  );
 237
 238         //---------------------------------------
 239         /** @short  close the member m_xCloseFrame.
 240
 241             @descr  This method does not look for any document
 242                     inside this frame. Such views must be cleared
 243                     before (e.g. by calling implts_closeView()!
 244
 245                     Otherwhise e.g. the XController->suspend()
 246                     call isnt made and no UI warn the user about
 247                     loosing document changes. Because the
 248                     frame is closed ....
 249
 250             @return [bool]
 251                     TRUE if closing was successfully.
 252          */
 253         sal_Bool implts_closeFrame();
 254
 255         //---------------------------------------
 256         /** @short  set the special BackingComponent (now StartModule)
 257                     as new component of our m_xCloseFrame.
 258
 259             @return [bool]
 260                     TRUE if operation was successfully.
 261          */
 262         sal_Bool implts_establishBackingMode();
 263
 264         //---------------------------------------
 265         /** @short  calls XDesktop->terminate().
 266
 267             @descr  No office code has to be called
 268                     afterwards! Because the process is dieing ...
 269                     The only exception is a might be registered
 270                     listener at this instance here.
 271                     Because he should know, that such things will happen :-)
 272
 273             @return [bool]
 274                     TRUE if termination of the application was started ...
 275          */
 276         sal_Bool implts_terminateApplication();
 277
 278         //---------------------------------------
 279         /** @short  notify a DispatchResultListener.
 280
 281             @descr  We check the listener reference before we use it.
 282                     So this method can be called everytimes!
 283
 284             @parama xListener
 285                     the listener, which should be notified.
 286                     Can be null!
 287
 288             @param  nState
 289                     directly used as css::frame::DispatchResultState value.
 290
 291             @param  aResult
 292                     not used yet realy ...
 293          */
 294         void implts_notifyResultListener(const css::uno::Reference< css::frame::XDispatchResultListener >& xListener,
 295                                                sal_Int16                                                   nState   ,
 296                                          const css::uno::Any&                                              aResult  );
 297
 298         //---------------------------------------
 299         /** @short  try to find the right target frame where this close request
 300                     must be realy done.
 301
 302             @descr  The problem behind: closing some resources depends sometimes from the
 303                     context where its dispatched. Sometimes the start frame of the dispatch
 304                     has to be closed itself (target=_self) ... sometimes it's parent frame
 305                     has to be closed - BUT(!) it means a parent frame containing a top level
 306                     window. _top cant be used then for dispatch - because it adress TopFrames
 307                     not frames containg top level windows. So normaly _magic (which btw does not
 308                     exists at the moment .-) ) should be used. So we interpret target=<empty>
 309                     as _magic !
 310
 311             @param  xFrame
 312                     start point for search of right dispatch frame.
 313
 314             @param  sTarget
 315                     give us an idea how this target frame must be searched.
 316         */
 317
 318         static css::uno::Reference< css::frame::XFrame > static_impl_searchRightTargetFrame(const css::uno::Reference< css::frame::XFrame >& xFrame ,
 319                                                                                             const ::rtl::OUString&                           sTarget);
 320
 321 }; // class CloseDispatcher
 322
 323 } // namespace framework
 324
 325 #endif // #ifndef __FRAMEWORK_DISPATCH_CLOSEDISPATCHER_HXX_