Branch data Line data Source code
1 : : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : : /*************************************************************************
3 : : *
4 : : * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 : : *
6 : : * Copyright 2000, 2010 Oracle and/or its affiliates.
7 : : *
8 : : * OpenOffice.org - a multi-platform office productivity suite
9 : : *
10 : : * This file is part of OpenOffice.org.
11 : : *
12 : : * OpenOffice.org is free software: you can redistribute it and/or modify
13 : : * it under the terms of the GNU Lesser General Public License version 3
14 : : * only, as published by the Free Software Foundation.
15 : : *
16 : : * OpenOffice.org is distributed in the hope that it will be useful,
17 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 : : * GNU Lesser General Public License version 3 for more details
20 : : * (a copy is included in the LICENSE file that accompanied this code).
21 : : *
22 : : * You should have received a copy of the GNU Lesser General Public License
23 : : * version 3 along with OpenOffice.org. If not, see
24 : : * <http://www.openoffice.org/license.html>
25 : : * for a copy of the LGPLv3 License.
26 : : *
27 : : ************************************************************************/
28 : :
29 : : #ifndef VCL_MNEMONICENGINE_HXX
30 : : #define VCL_MNEMONICENGINE_HXX
31 : :
32 : : #include "dllapi.h"
33 : :
34 : : #include <sal/config.h>
35 : : #include <sal/types.h>
36 : :
37 : : #include <memory>
38 : :
39 : : class String;
40 : : class KeyEvent;
41 : :
42 : : //........................................................................
43 : : namespace vcl
44 : : {
45 : : //........................................................................
46 : :
47 : : //====================================================================
48 : : //= IMnemonicEntryList
49 : : //====================================================================
50 : : /// callback for a MnemonicEngine
51 : 122 : class SAL_NO_VTABLE VCL_DLLPUBLIC IMnemonicEntryList
52 : : {
53 : : public:
54 : : /** returns the first list entry for the mnemonic search
55 : :
56 : : @return
57 : : a pointer which can be used to unuquely identify the entry.
58 : : The MenomonicEngine itself does not use this value, it
59 : : is only passed to other methods of this callback interface.
60 : :
61 : : If this value is <NULL/>, searching stops.
62 : : */
63 : : virtual const void* FirstSearchEntry( String& _rEntryText ) const = 0;
64 : :
65 : : /** returns the next list entry for the mnemonic search
66 : :
67 : : @return
68 : : a pointer which can be used to unuquely identify the entry.
69 : : The MenomonicEngine itself does not use this value, it
70 : : is only passed to other methods of this callback interface.
71 : :
72 : : If this value is <NULL/>, searching stops.
73 : :
74 : : If this value is the same as returned by the previous call
75 : : to <member>FirstSearchEntry</member> (i.e. you cycled
76 : : around), then searching stops, too.
77 : : */
78 : : virtual const void* NextSearchEntry( const void* _pCurrentSearchEntry, String& _rEntryText ) const = 0;
79 : :
80 : : /** "selects" a given entry.
81 : :
82 : : Note: The semantics of "select" depends on your implementation. You
83 : : might actually really select the entry (in the sense of a selected
84 : : list box entry, for example), you might make it the current entry,
85 : : if your implementation supports this - whatever.
86 : :
87 : : @param _pEntry
88 : : the entry to select. This is the return value of a previous call
89 : : to <member>FirstSearchEntry</member> or <member>NextSearchEntry</member>.
90 : : */
91 : : virtual void SelectSearchEntry( const void* _pEntry ) = 0;
92 : :
93 : : /** "executes" the current search entry, i.e. the one returned
94 : : in the previous <member>NextSearchEntry</member> call.
95 : :
96 : : Note: The semantics of "execute" depends on your implementation. You
97 : : might even have a list of entries which cannot be executed at all.
98 : :
99 : : This method is called after <member>SelectSearchEntry</member>,
100 : : if and only if the current entry's mnemonic is unambiguous.
101 : :
102 : : For instance, imagine a list which has two entries with the same mnemonic
103 : : character, say "c". Now if the user presses <code>Alt-C</code>, the MnemonicEngine
104 : : will call <member>SelectCurrentEntry</member> as soon as it encounters
105 : : the first entry, but it'll never call <member>ExecuteSearchEntry</member>.
106 : :
107 : : If, however, "c" is a unique mnemonic character in your entry list, then the
108 : : call of <member>SelectSearchEntry</member> will be followed by a
109 : : call to <member>ExecuteSearchEntry</member>.
110 : :
111 : : This way, you can implement cyclic selection of entries: In
112 : : <member>FirstSearchEntry</member>, return the entry which was previously
113 : : selected, and in <member>NextSearchEntry</member>, interlly cycle around
114 : : in your list. Then, multiple user inputs of <code>Alt-C</code> will
115 : : cycle through all entries with the mnemonic being "c".
116 : :
117 : : @param _pEntry
118 : : the entry to select. This is the return value of a previous call
119 : : to <member>FirstSearchEntry</member> or <member>NextSearchEntry</member>.
120 : : */
121 : : virtual void ExecuteSearchEntry( const void* _pEntry ) const = 0;
122 : :
123 : : protected:
124 : 122 : ~IMnemonicEntryList() {}
125 : : };
126 : :
127 : : //====================================================================
128 : : //= MnemonicEngine
129 : : //====================================================================
130 : : struct MnemonicEngine_Data;
131 : : class VCL_DLLPUBLIC MnemonicEngine
132 : : {
133 : : ::std::auto_ptr< MnemonicEngine_Data > m_pData;
134 : :
135 : : public:
136 : : MnemonicEngine( IMnemonicEntryList& _rEntryList );
137 : : ~MnemonicEngine();
138 : :
139 : : /** handles a key event
140 : :
141 : : If the key event denotes pressing an accelerator key, then the
142 : : entry list is searched for a matching entry. If such an entry is
143 : : found, <member>IMnemonicEntryList::SelectSearchEntry</member>
144 : : is called.
145 : :
146 : : If the entry is the only one with the given mnemonic character, then
147 : : also <member>IMnemonicEntryList::ExecuteSearchEntry</member>
148 : : is called.
149 : :
150 : : @return
151 : : if the key event has been handled, and should thus not be processed
152 : : further.
153 : : */
154 : : bool HandleKeyEvent( const KeyEvent& _rKEvt );
155 : : };
156 : :
157 : : //........................................................................
158 : : } // namespace vcl
159 : : //........................................................................
160 : :
161 : : #endif // VCL_MNEMONICENGINE_HXX
162 : :
163 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
