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 than once ...
187                     but at least it should be used one time only.
188                     Otherwise 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);
operator =(const AcceleratorExecute &)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