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