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