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