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 #pragma once
  21
  22 #include <svtools/svtdllapi.h>
  23
  24 #include <memory>
  25 #include <mutex>
  26
  27 #include <com/sun/star/awt/KeyEvent.hpp>
  28 #include <vcl/keycod.hxx>
  29
  30 namespace com :: sun :: star :: frame { class XDispatchProvider; }
  31 namespace com :: sun :: star :: frame { class XFrame; }
  32 namespace com :: sun :: star :: frame { class XModel; }
  33 namespace com :: sun :: star :: ui { class XAcceleratorConfiguration; }
  34 namespace com :: sun :: star :: uno { class XComponentContext; }
  35 namespace com :: sun :: star :: util { class XURLTransformer; }
  36
  37
  38 namespace svt
  39 {
  40
  41
  42 /**
  43     @descr  implements a helper, which can be used to
  44             convert vcl key codes into awt key codes ...
  45             and reverse.
  46
  47             Further such key code can be triggered.
  48             Doing so different accelerator
  49             configurations are merged together; a suitable
  50             command registered for the given key code is searched
  51             and will be dispatched.
  52
  53     @attention
  54
  55             Because execution of an accelerator command can be dangerous
  56             (in case it force an office shutdown for key "ALT+F4"!)
  57             all internal dispatches are done asynchronous.
  58             Means that the trigger call doesn't wait till the dispatch
  59             is finished. You can call very often. All requests will be
  60             queued internal and dispatched ASAP.
  61
  62             Of course this queue will be stopped if the environment
  63             will be destructed...
  64  */
  65 class SVT_DLLPUBLIC AcceleratorExecute final
  66 {
  67     // member
  68     private:
  69         std::mutex m_aLock;
  70
  71         /** TODO document me */
  72         css::uno::Reference< css::uno::XComponentContext > m_xContext;
  73
  74         /** TODO document me */
  75         css::uno::Reference< css::util::XURLTransformer > m_xURLParser;
  76
  77         /** TODO document me */
  78         css::uno::Reference< css::frame::XDispatchProvider > m_xDispatcher;
  79
  80         /** TODO document me */
  81         css::uno::Reference< css::ui::XAcceleratorConfiguration > m_xGlobalCfg;
  82         css::uno::Reference< css::ui::XAcceleratorConfiguration > m_xModuleCfg;
  83         css::uno::Reference< css::ui::XAcceleratorConfiguration > m_xDocCfg;
  84     // interface
  85     public:
  86
  87
  88         /** @short  factory method to create new accelerator
  89                     helper instance.
  90
  91             @descr  Such helper instance must be initialized at first.
  92                     So it can know its environment (global/module or
  93                     document specific).
  94
  95                     Afterwards it can be used to execute incoming
  96                     accelerator requests.
  97
  98                     The "end of life" of such helper can be reached as follow:
  99
 100                     - delete the object
 101                       => If it stands currently in its execute method, they will
 102                          be finished. All further queued requests will be removed
 103                          and further not executed!
 104
 105                     - "let it stay alone"
 106                       => All currently queued events will be finished. The
 107                          helper kills itself afterwards. A shutdown of the
 108                          environment will be recognized ... The helper stop its
 109                          work immediately then!
 110          */
 111         static std::unique_ptr<AcceleratorExecute> createAcceleratorHelper();
 112
 113
 114         /** @short  fight against inlining ... */
 115         ~AcceleratorExecute();
 116
 117
 118         /** @short  init this instance.
 119
 120             @descr  It must be called as first method after creation.
 121                     And further it can be called more than once...
 122                     but at least it should be used one times only.
 123                     Otherwise nobody can say, which asynchronous
 124                     executions will be used inside the old and which one
 125                     will be used inside the new environment.
 126
 127             @param  rxContext
 128                     reference to a uno service manager.
 129
 130             @param  xEnv
 131                     if it points to a valid frame it will be used
 132                     to execute the dispatch there. Further the frame
 133                     is used to locate the right module configuration
 134                     and use it merged together with the document and
 135                     the global configuration.
 136
 137                     If this parameter is set to NULL, the global configuration
 138                     is used only. Further the global Desktop instance is
 139                     used for dispatch.
 140          */
 141         void init(const css::uno::Reference< css::uno::XComponentContext >& rxContext,
 142                           const css::uno::Reference< css::frame::XFrame >&              xEnv );
 143
 144
 145         /** @short  trigger this accelerator.
 146
 147             @descr  The internal configurations are used to find
 148                     as suitable command for this key code.
 149                     This command will be queued and executed later
 150                     asynchronous.
 151
 152             @param  aKey
 153                     specify the accelerator for execute.
 154
 155             @return [bool]
 156                     true if this key is configured and match to a command.
 157                     Attention: This state does not mean the success state
 158                     of the corresponding execute. Because it's done asynchronously!
 159          */
 160         bool execute(const vcl::KeyCode&       aKey);
 161         bool execute(const css::awt::KeyEvent& aKey);
 162
 163         /** search the command for the given key event.
 164         *
 165         * @param aKey The key event
 166         * @return The command or an empty string if the key event could not be found.
 167         */
 168         OUString  findCommand(const css::awt::KeyEvent& aKey);
 169
 170         /** TODO document me */
 171         static css::awt::KeyEvent st_VCLKey2AWTKey(const vcl::KeyCode&       aKey);
 172         static vcl::KeyCode       st_AWTKey2VCLKey(const css::awt::KeyEvent& aKey);
 173
 174
 175         /** TODO document me */
 176         static css::uno::Reference< css::ui::XAcceleratorConfiguration > st_openModuleConfig(const css::uno::Reference< css::uno::XComponentContext >& rxContext ,
 177                                                                                               const css::uno::Reference< css::frame::XFrame >&              xFrame);
 178
 179         static css::uno::Reference<css::ui::XAcceleratorConfiguration> lok_createNewAcceleratorConfiguration(const css::uno::Reference< css::uno::XComponentContext >& rxContext, OUString sModule);
 180         void lok_setModuleConfig(const css::uno::Reference<css::ui::XAcceleratorConfiguration>& acceleratorConfig);
 181
 182         /** TODO document me */
 183         static css::uno::Reference< css::ui::XAcceleratorConfiguration > st_openDocConfig(const css::uno::Reference< css::frame::XModel >& xModel);
 184
 185
 186     // internal
 187     private:
 188
 189
 190         /** @short  allow creation of instances of this class
 191                     by using our factory only!
 192          */
 193         SVT_DLLPRIVATE AcceleratorExecute();
 194
 195         AcceleratorExecute(const AcceleratorExecute& rCopy) = delete;
 196         void operator=(const AcceleratorExecute&)  = delete;
 197
 198         /** TODO document me */
 199         SVT_DLLPRIVATE OUString impl_ts_findCommand(const css::awt::KeyEvent& aKey);
 200
 201
 202         /** TODO document me */
 203         SVT_DLLPRIVATE css::uno::Reference< css::util::XURLTransformer > impl_ts_getURLParser();
 204 };
 205
 206 } // namespace svt
 207
 208 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */