1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef VCL_MNEMONICENGINE_HXX 25 #define VCL_MNEMONICENGINE_HXX 26 27 #include "dllapi.h" 28 29 #include <sal/config.h> 30 #include <sal/types.h> 31 32 #include <memory> 33 34 class String; 35 class KeyEvent; 36 37 //........................................................................ 38 namespace vcl 39 { 40 //........................................................................ 41 42 //==================================================================== 43 //= IMnemonicEntryList 44 //==================================================================== 45 /// callback for a MnemonicEngine 46 class SAL_NO_VTABLE VCL_DLLPUBLIC IMnemonicEntryList 47 { 48 public: 49 /** returns the first list entry for the mnemonic search 50 51 @return 52 a pointer which can be used to unuquely identify the entry. 53 The MenomonicEngine itself does not use this value, it 54 is only passed to other methods of this callback interface. 55 56 If this value is <NULL/>, searching stops. 57 */ 58 virtual const void* FirstSearchEntry( String& _rEntryText ) const = 0; 59 60 /** returns the next list entry for the mnemonic search 61 62 @return 63 a pointer which can be used to unuquely identify the entry. 64 The MenomonicEngine itself does not use this value, it 65 is only passed to other methods of this callback interface. 66 67 If this value is <NULL/>, searching stops. 68 69 If this value is the same as returned by the previous call 70 to <member>FirstSearchEntry</member> (i.e. you cycled 71 around), then searching stops, too. 72 */ 73 virtual const void* NextSearchEntry( const void* _pCurrentSearchEntry, String& _rEntryText ) const = 0; 74 75 /** "selects" a given entry. 76 77 Note: The semantics of "select" depends on your implementation. You 78 might actually really select the entry (in the sense of a selected 79 list box entry, for example), you might make it the current entry, 80 if your implementation supports this - whatever. 81 82 @param _pEntry 83 the entry to select. This is the return value of a previous call 84 to <member>FirstSearchEntry</member> or <member>NextSearchEntry</member>. 85 */ 86 virtual void SelectSearchEntry( const void* _pEntry ) = 0; 87 88 /** "executes" the current search entry, i.e. the one returned 89 in the previous <member>NextSearchEntry</member> call. 90 91 Note: The semantics of "execute" depends on your implementation. You 92 might even have a list of entries which cannot be executed at all. 93 94 This method is called after <member>SelectSearchEntry</member>, 95 if and only if the current entry's mnemonic is unambiguous. 96 97 For instance, imagine a list which has two entries with the same mnemonic 98 character, say "c". Now if the user presses <code>Alt-C</code>, the MnemonicEngine 99 will call <member>SelectCurrentEntry</member> as soon as it encounters 100 the first entry, but it'll never call <member>ExecuteSearchEntry</member>. 101 102 If, however, "c" is a unique mnemonic character in your entry list, then the 103 call of <member>SelectSearchEntry</member> will be followed by a 104 call to <member>ExecuteSearchEntry</member>. 105 106 This way, you can implement cyclic selection of entries: In 107 <member>FirstSearchEntry</member>, return the entry which was previously 108 selected, and in <member>NextSearchEntry</member>, interlly cycle around 109 in your list. Then, multiple user inputs of <code>Alt-C</code> will 110 cycle through all entries with the mnemonic being "c". 111 112 @param _pEntry 113 the entry to select. This is the return value of a previous call 114 to <member>FirstSearchEntry</member> or <member>NextSearchEntry</member>. 115 */ 116 virtual void ExecuteSearchEntry( const void* _pEntry ) const = 0; 117 }; 118 119 //==================================================================== 120 //= MnemonicEngine 121 //==================================================================== 122 struct MnemonicEngine_Data; 123 class VCL_DLLPUBLIC MnemonicEngine 124 { 125 ::std::auto_ptr< MnemonicEngine_Data > m_pData; 126 127 public: 128 MnemonicEngine( IMnemonicEntryList& _rEntryList ); 129 ~MnemonicEngine(); 130 131 /** handles a key event 132 133 If the key event denotes pressing an accelerator key, then the 134 entry list is searched for a matching entry. If such an entry is 135 found, <member>IMnemonicEntryList::SelectSearchEntry</member> 136 is called. 137 138 If the entry is the only one with the given mnemonic character, then 139 also <member>IMnemonicEntryList::ExecuteSearchEntry</member> 140 is called. 141 142 @return 143 if the key event has been handled, and should thus not be processed 144 further. 145 */ 146 bool HandleKeyEvent( const KeyEvent& _rKEvt ); 147 }; 148 149 //........................................................................ 150 } // namespace vcl 151 //........................................................................ 152 153 #endif // VCL_MNEMONICENGINE_HXX 154 155