framework/source/inc/accelerators/acceleratorcache.hxx

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