svtools/inc/acceleratorexecute.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: acceleratorexecute.hxx,v $
  10  * $Revision: 1.13 $
  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 INCLUDED_SVTOOLS_ACCELERATOREXECUTE_HXX
  32 #define INCLUDED_SVTOOLS_ACCELERATOREXECUTE_HXX
  33
  34 //===============================================
  35 // includes
  36
  37 #include "svtools/svtdllapi.h"
  38
  39 #ifndef INCLUDED_VECTOR
  40 #include <vector>
  41 #define INCLUDED_VECTOR
  42 #endif
  43
  44 #ifndef __COM_SUN_STAR_LANG_XMULTISERVICEFACTORY_HPP_
  45 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  46 #endif
  47
  48 #ifndef __COM_SUN_STAR_FRAME_XFRAME_HPP_
  49 #include <com/sun/star/frame/XFrame.hpp>
  50 #endif
  51
  52 #ifndef __COM_SUN_STAR_FRAME_XDISPATCHPROVIDER_HPP_
  53 #include <com/sun/star/frame/XDispatchProvider.hpp>
  54 #endif
  55
  56 #ifndef __com_SUN_STAR_UI_XACCELERATORCONFIGURATION_HPP_
  57 #include <com/sun/star/ui/XAcceleratorConfiguration.hpp>
  58 #endif
  59
  60 #ifndef __COM_SUN_STAR_UTIL_XURLTRANSFORMER_HPP_
  61 #include <com/sun/star/util/XURLTransformer.hpp>
  62 #endif
  63 #include <com/sun/star/util/URL.hpp>
  64
  65 #ifndef __COM_SUN_STAR_AWT_KEYEVENT_HPP_
  66 #include <com/sun/star/awt/KeyEvent.hpp>
  67 #endif
  68 #include <vcl/keycod.hxx>
  69 #include <vcl/evntpost.hxx>
  70 #include <osl/mutex.h>
  71
  72 //===============================================
  73 // namespace
  74
  75 #ifdef css
  76     #error "Conflict on using css as namespace alias!"
  77 #else
  78     #define css ::com::sun::star
  79 #endif
  80
  81 namespace svt
  82 {
  83
  84 //===============================================
  85 // definitions
  86
  87 struct TMutexInit
  88 {
  89     ::osl::Mutex m_aLock;
  90 };
  91
  92 //===============================================
  93 /**
  94     @descr  implements a helper, which can be used to
  95             convert vcl key codes into awt key codes ...
  96             and reverse.
  97
  98             Further such key code can be triggered.
  99             Doing so different accelerator
 100             configurations are merged together; a suitable
 101             command registered for the given key code is searched
 102             and will be dispatched.
 103
 104     @attention
 105
 106             Because exceution of an accelerator command can be dangerous
 107             (in case it force an office shutdown for key "ALT+F4"!)
 108             all internal dispatches are done asynchronous.
 109             Menas that the trigger call doesnt wait till the dispatch
 110             is finished. You can call very often. All requests will be
 111             queued internal and dispatched ASAP.
 112
 113             Of course this queue will be stopped if the environment
 114             will be destructed ...
 115  */
 116 class SVT_DLLPUBLIC AcceleratorExecute : private TMutexInit
 117 {
 118     //-------------------------------------------
 119     // const, types
 120     private:
 121
 122         /** @deprecated
 123                 replaced by internal class AsyncAccelExec ...
 124                 remove this resource here if we go forwards to next major */
 125         typedef ::std::vector< ::std::pair< css::util::URL, css::uno::Reference< css::frame::XDispatch > > > TCommandQueue;
 126
 127     //-------------------------------------------
 128     // member
 129     private:
 130
 131         /** TODO document me */
 132         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
 133
 134         /** TODO document me */
 135         css::uno::Reference< css::util::XURLTransformer > m_xURLParser;
 136
 137         /** TODO document me */
 138         css::uno::Reference< css::frame::XDispatchProvider > m_xDispatcher;
 139
 140         /** TODO document me */
 141         css::uno::Reference< css::ui::XAcceleratorConfiguration > m_xGlobalCfg;
 142         css::uno::Reference< css::ui::XAcceleratorConfiguration > m_xModuleCfg;
 143         css::uno::Reference< css::ui::XAcceleratorConfiguration > m_xDocCfg;
 144
 145         /** @deprecated
 146                 replaced by internal class AsyncAccelExec ...
 147                 remove this resource here if we go forwards to next major */
 148         TCommandQueue m_lCommandQueue;
 149
 150         /** @deprecated
 151                 replaced by internal class AsyncAccelExec ...
 152                 remove this resource here if we go forwards to next major */
 153         ::vcl::EventPoster m_aAsyncCallback;
 154
 155     //-------------------------------------------
 156     // interface
 157     public:
 158
 159         //---------------------------------------
 160         /** @short  factory method to create new accelerator
 161                     helper instance.
 162
 163             @descr  Such helper instance must be initialized at first.
 164                     So it can know its environment (global/module or
 165                     document specific).
 166
 167                     Afterwards it can be used to execute incoming
 168                     accelerator requests.
 169
 170                     The "end of life" of such helper can be reached as follow:
 171
 172                     - delete the object
 173                       => If it stands currently in its execute method, they will
 174                          be finished. All further queued requests will be removed
 175                          and further not executed!
 176
 177                     - "let it stay alone"
 178                       => All currently queued events will be finished. The
 179                          helper kills itself afterwards. A shutdown of the
 180                          environment will be recognized ... The helper stop its
 181                          work immediatly then!
 182          */
 183         static AcceleratorExecute* createAcceleratorHelper();
 184
 185         //---------------------------------------
 186         /** @short  fight against inlining ... */
 187         virtual ~AcceleratorExecute();
 188
 189         //---------------------------------------
 190         /** @short  init this instance.
 191
 192             @descr  It must be called as first method after creation.
 193                     And further it can be called more then once ...
 194                     but at least its should be used one times only.
 195                     Otherwhise nobody can say, which asynchronous
 196                     executions will be used inside the old and which one
 197                     will be used inside the new environment.
 198
 199             @param  xSMGR
 200                     reference to an uno service manager.
 201
 202             @param  xEnv
 203                     if it points to a valid frame it will be used
 204                     to execute the dispatch there. Further the frame
 205                     is used to locate the right module configuration
 206                     and use it merged together with the document and
 207                     the global configuration.
 208
 209                     If this parameter is set to NULL, the global configuration
 210                     is used only. Further the global Desktop instance is
 211                     used for dispatch.
 212          */
 213         virtual void init(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR,
 214                           const css::uno::Reference< css::frame::XFrame >&              xEnv );
 215
 216         //---------------------------------------
 217         /** @short  trigger this accelerator.
 218
 219             @descr  The internal configuartions are used to find
 220                     as suitable command for this key code.
 221                     This command will be queued and executed later
 222                     asynchronous.
 223
 224             @param  aKey
 225                     specify the accelerator for execute.
 226
 227             @return [sal_Bool]
 228                     TRUE if this key is configured and match to a command.
 229                     Attention: This state does not mean the success state
 230                     of the corresponding execute. Because its done asynchronous!
 231          */
 232         virtual sal_Bool execute(const KeyCode&            aKey);
 233         virtual sal_Bool execute(const css::awt::KeyEvent& aKey);
 234
 235         /** search the command for the given key event.
 236         *
 237         * @param aKey The key event
 238         * @return The command or an empty string if the key event could not be found.
 239         */
 240         ::rtl::OUString  findCommand(const ::com::sun::star::awt::KeyEvent& aKey);
 241         //---------------------------------------
 242         /** TODO document me */
 243         static css::awt::KeyEvent st_VCLKey2AWTKey(const KeyCode&            aKey);
 244         static KeyCode            st_AWTKey2VCLKey(const css::awt::KeyEvent& aKey);
 245
 246         //---------------------------------------
 247         /** TODO document me */
 248         static css::uno::Reference< css::ui::XAcceleratorConfiguration > st_openGlobalConfig(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR);
 249
 250         //---------------------------------------
 251         /** TODO document me */
 252         static css::uno::Reference< css::ui::XAcceleratorConfiguration > st_openModuleConfig(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR ,
 253                                                                                               const css::uno::Reference< css::frame::XFrame >&              xFrame);
 254
 255         //---------------------------------------
 256         /** TODO document me */
 257         static css::uno::Reference< css::ui::XAcceleratorConfiguration > st_openDocConfig(const css::uno::Reference< css::frame::XModel >& xModel);
 258
 259     //-------------------------------------------
 260     // internal
 261     private:
 262
 263         //---------------------------------------
 264         /** @short  allow creation of instances of this class
 265                     by using our factory only!
 266          */
 267         SVT_DLLPRIVATE AcceleratorExecute();
 268
 269         AcceleratorExecute(const AcceleratorExecute& rCopy);
 270         void operator=(const AcceleratorExecute&) {};
 271         //---------------------------------------
 272         /** TODO document me */
 273         SVT_DLLPRIVATE ::rtl::OUString impl_ts_findCommand(const css::awt::KeyEvent& aKey);
 274
 275         //---------------------------------------
 276         /** TODO document me */
 277         SVT_DLLPRIVATE css::uno::Reference< css::util::XURLTransformer > impl_ts_getURLParser();
 278
 279         //---------------------------------------
 280         /** @deprecated
 281                 replaced by internal class AsyncAccelExec ...
 282                 remove this resource here if we go forwards to next major */
 283         DECL_DLLPRIVATE_LINK(impl_ts_asyncCallback, void*);
 284 };
 285
 286 } // namespace svt
 287
 288 #undef css
 289
 290 #endif // INCLUDED_SVTOOLS_ACCELERATOREXECUTE_HXX