include/svtools/acceleratorexecute.hxx

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