framework/source/inc/accelerators/acceleratorcache.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 #ifndef __FRAMEWORK_ACCELERATORS_ACCELERATORCACHE_HXX_
  29 #define __FRAMEWORK_ACCELERATORS_ACCELERATORCACHE_HXX_
  30
  31 //__________________________________________
  32 // own includes
  33
  34 #include <threadhelp/threadhelpbase.hxx>
  35 #include <general.h>
  36 #include <stdtypes.h>
  37
  38 //__________________________________________
  39 // interface includes
  40
  41 #ifndef __COM_SUN_STAR_AWT_KEYEVENT_HPP_
  42 #include <com/sun/star/awt/KeyEvent.hpp>
  43 #endif
  44
  45 //__________________________________________
  46 // other includes
  47 #include <comphelper/sequenceasvector.hxx>
  48
  49 //__________________________________________
  50 // definition
  51
  52 namespace framework
  53 {
  54
  55 //__________________________________________
  56 /**
  57     @short  implements a cache for any accelerator configuration.
  58
  59     @descr  Its implemented threadsafe, supports copy-on-write pattern
  60             and a flush mechansim to support concurrent access to the same
  61             configuration.
  62
  63             copy-on-write ... How? Do the following:
  64  */
  65 class AcceleratorCache : public ThreadHelpBase // attention! Must be the first base class to guarentee right initialize lock ...
  66 {
  67     //______________________________________
  68     // const, types
  69
  70     public:
  71
  72         //---------------------------------------
  73         /** TODO document me
  74             commands -> keys
  75         */
  76         typedef ::comphelper::SequenceAsVector< css::awt::KeyEvent > TKeyList;
  77         typedef BaseHash< TKeyList > TCommand2Keys;
  78
  79         //---------------------------------------
  80         /** TODO document me
  81             keys -> commands
  82         */
  83         typedef ::std::hash_map< css::awt::KeyEvent ,
  84                                  ::rtl::OUString    ,
  85                                  KeyEventHashCode   ,
  86                                  KeyEventEqualsFunc > TKey2Commands;
  87
  88     //______________________________________
  89     // member
  90
  91     private:
  92
  93         //---------------------------------------
  94         /** map commands to keys in relation 1:n.
  95             First key is interpreted as preferred one! */
  96         TCommand2Keys m_lCommand2Keys;
  97
  98         //---------------------------------------
  99         /** map keys to commands in relation 1:1. */
 100         TKey2Commands m_lKey2Commands;
 101
 102     //______________________________________
 103     // interface
 104
 105     public:
 106
 107         //---------------------------------------
 108         /** @short  creates a new - but empty - cache instance. */
 109         AcceleratorCache();
 110
 111         //---------------------------------------
 112         /** @short  make a copy of this cache.
 113             @descr  Used for the copy-on-write feature.
 114         */
 115         AcceleratorCache(const AcceleratorCache& rCopy);
 116
 117         //---------------------------------------
 118         /** @short  does nothing real. */
 119         virtual ~AcceleratorCache();
 120
 121         //---------------------------------------
 122         /** @short  write changes back to the original container.
 123
 124             @param  rCopy
 125                     the (changed!) copy, which should be written
 126                     back to this original container.
 127           */
 128         virtual void takeOver(const AcceleratorCache& rCopy);
 129
 130         //---------------------------------------
 131         /** TODO document me */
 132         virtual AcceleratorCache& operator=(const AcceleratorCache& rCopy);
 133
 134         //---------------------------------------
 135         /** @short  checks if the specified key exists.
 136
 137             @param  aKey
 138                     the key, which should be checked.
 139
 140             @return [bool]
 141                     TRUE if the speicfied key exists inside this container.
 142          */
 143         virtual sal_Bool hasKey(const css::awt::KeyEvent& aKey) const;
 144         virtual sal_Bool hasCommand(const ::rtl::OUString& sCommand) const;
 145
 146         //---------------------------------------
 147         /** TODO document me */
 148         virtual TKeyList getAllKeys() const;
 149
 150         //---------------------------------------
 151         /** @short  add a new or change an existing key-command pair
 152                     of this container.
 153
 154             @param  aKey
 155                     describe the key.
 156
 157             @param  sCommand
 158                     describe the command.
 159           */
 160         virtual void setKeyCommandPair(const css::awt::KeyEvent& aKey    ,
 161                                        const ::rtl::OUString&    sCommand);
 162
 163         //---------------------------------------
 164         /** @short  returns the list of keys, which are registered
 165                     for this command.
 166
 167             @param  sCommand
 168                     describe the command.
 169
 170             @return [TKeyList]
 171                     the list of registered keys. Can be empty!
 172           */
 173         virtual TKeyList getKeysByCommand(const ::rtl::OUString& sCommand) const;
 174
 175         //---------------------------------------
 176         /** TODO */
 177         virtual ::rtl::OUString getCommandByKey(const css::awt::KeyEvent& aKey) const;
 178
 179         //---------------------------------------
 180         /** TODO */
 181         virtual void removeKey(const css::awt::KeyEvent& aKey);
 182         virtual void removeCommand(const ::rtl::OUString& sCommand);
 183 };
 184
 185 } // namespace framework
 186
 187 #endif // __FRAMEWORK_ACCELERATORS_ACCELERATORCACHE_HXX_