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