summaryrefslogtreecommitdiffstats
path: root/kdeui/kaccelgen.h
blob: 8f0c50bed764d29a1b0870531bb48374cbb30719 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
/*  This file is part of the KDE project
    Copyright (C) 2000 Keunwoo Lee <klee@cs.washington.edu>

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB. If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA  02110-1301, USA.
*/

#ifndef KACCELGEN_H
#define KACCELGEN_H

#include <tqmap.h>
#include <tqstring.h>
#include <tqstringlist.h>

#include <kdelibs_export.h>

/**
 * Provides functions that, given a collection of QStrings, will
 * automatically and intelligently assign menu accelerators to the
 * QStrings in the collection.
 *
 * NOTE: When this file speaks of "accelerators", we really mean
 * accelerators as defined by the KDE User Interface Guidelines.  We
 * do NOT mean "shortcuts", which are what's handled by most other KDE
 * libraries with "accel" in the name.
 *
 * In the Qt library, the mechanism for adding a keyboard accelerator
 * to a menu item is to insert an '&' before the letter. Since we
 * usually don't want to disturb the original collection, the idiom in
 * these functions is to populate a "target" TQStringList parameter
 * with the input collectin's QStrings, plus possibly some added '&'
 * characters.
 *
 * That is the mechanism. Here is the policy, in order of decreasing
 * importance (it may seem like these are implementation details, but
 * IMHO the policy is an important part of the interface):
 *
 * 1. If the string already contains an '&' character, skip this
 * string, because we consider such strings to be "user-specified"
 * accelerators.
 *
 * 2. No accelerator may clash with a previously defined accelerator,
 * including any legal (alphanumeric) user-specified accelerator
 * anywhere in the collection
 *
 * 3. Prefer alphanumerics at the start of the string.
 *
 * 4. Otherwise, prefer alphanumerics at the start of a word.
 *
 * 5. Otherwise, choose any alphanumeric character not already
 * taken. If no such character is available, give up & skip this
 * string.
 *
 * A typical use of these functions would be to automatically assign
 * accelerators to a dynamically populated popup menu.  For example,
 * the core code was written to automatically set accelerators for the
 * "Load View Profile" popup menu for Konqueror.  We quickly realized
 * that it would be useful to make this facility more generally
 * available, so I abstracted it out into a set of templates.
 *
 * TODO:
 *
 * + Add sugar functions for more collections.
 *
 * + Add more Deref classes so that we can access a wider variety of
 * collections.
 * */
namespace KAccelGen
{

// HELPERS

/**
 * Static dereference class, for use as a template parameter.
 */
template <class Iter>
class Deref
{
public:
    static TQString deref(Iter i) { return *i; }
};

/**
 * Static dereference class that calls the key() method on its
 * target; for use as a template parameter.
 */
template <class Iter>
class Deref_Key
{
public:
    static TQString deref(Iter i) { return i.key(); }
};

/**
 * Helper to determine if the given offset in the string could be a
 * legal alphanumeric accelerator.
 *
 * @param str   base string
 * @param index offset to check
 */
inline bool
isLegalAccelerator(const TQString& str, uint index)
{
    return index < str.length()
        && str[index].isLetterOrNumber();
}

/**
 * Loads all legal predefined accelerators in the (implicitly
 * specified) collection into the given TQMap.
 *
 * @param begin start iterator
 * @param end   (last+1) iterator
 * @param keys map to store output
 */
template <class Iter, class Deref>
inline void
loadPredefined(Iter begin, Iter end, TQMap<TQChar,bool>& keys)
{
    for (Iter i = begin; i != end; ++i) {
        TQString item = Deref::deref(i);
        int user_ampersand = item.find(TQChar('&'));
        if( user_ampersand >= 0 ) {
            // Sanity check.  Note that we don't try to find an
            // accelerator if the user shoots him/herself in the foot
            // by adding a bad '&'.
            if( isLegalAccelerator(item, user_ampersand+1) ) {
                keys.insert(item[user_ampersand+1], true);
            }
        }
    }
}


// ///////////////////////////////////////////////////////////////////
// MAIN USER FUNCTIONS


/**
 * Main, maximally flexible template function that assigns
 * accelerators to the elements of a collection of QStrings. Clients
 * will seldom use this directly, as it's usually easier to use one of
 * the wrapper functions that simply takes a collection (see below).
 *
 * The Deref template parameter is a class containing a static
 * dereferencing function, modeled after the comparison class C in
 * Stroustrup 13.4.
 *
 * @param begin  (you know)
 * @param end    (you know)
 * @param target collection to store generated strings
 */
template <class Iter, class Iter_Deref >
void
generate(Iter begin, Iter end, TQStringList& target)
{
    // Will keep track of used accelerator chars
    TQMap<TQChar,bool> used_accels;

    // Prepass to detect manually user-coded accelerators
    loadPredefined<Iter,Iter_Deref>(begin, end, used_accels);

    // Main pass
    for (Iter i = begin; i != end; ++i) {
        TQString item = Iter_Deref::deref(i);

        // Attempt to find a good accelerator, but only if the user
        // has not manually hardcoded one.
        int user_ampersand = item.find(TQChar('&'));
        if( user_ampersand < 0 || item[user_ampersand+1] == '&') {
            bool found = false;
            uint found_idx;
            uint j;

            // Check word-starting letters first.
            for( j=0; j < item.length(); ++j ) {
                if( isLegalAccelerator(item, j)
                    && !used_accels.contains(item[j])
                    && (0 == j || (j > 0 && item[j-1].isSpace())) ) {
                    found = true;
                    found_idx = j;
                    break;
                }
            }

            if( !found ) {
                // No word-starting letter; search for any letter.
                for( j=0; j < item.length(); ++j ) {
                    if( isLegalAccelerator(item, j)
                        && !used_accels.contains(item[j]) ) {
                        found = true;
                        found_idx = j;
                        break;
                    }
                }
            }

            if( found ) {
                // Both upper and lower case marked as used
                used_accels.insert(item[j].upper(),true);
                used_accels.insert(item[j].lower(),true);
                item.insert(j,TQChar('&'));
            }
        }

        target.append( item );
    }
}

/**
 * Another convenience function; looks up the key instead of
 * dereferencing directly for the given iterator.
 *
 * @param begin
 * @param end
 * @param target
 */
template <class Iter>
inline void
generateFromKeys(Iter begin, Iter end, TQStringList& target)
{
    generate< Iter, Deref_Key<Iter> >(begin, end, target);
}


/**
 * Convenience function; generates accelerators for all the items in
 * a TQStringList.
 *
 * @param source Strings for which to generate accelerators
 * @param target Output for accelerator-added strings */
inline void
generate(const TQStringList& source, TQStringList& target)
{
    generate<TQStringList::ConstIterator, Deref<TQStringList::ConstIterator> >(source.begin(), source.end(), target);
}

/**
 * Convenience function; generates accelerators for all the values in
 * a TQMap<T,TQString>.
 *
 * @param source Map with input strings as VALUES.
 * @param target Output for accelerator-added strings */
template <class Key>
inline void
generateFromValues(const TQMap<Key,TQString>& source, TQStringList& target)
{
    generate<TQMapConstIterator<Key,TQString>, Deref_Key<TQMapConstIterator<Key,TQString> > >(source.begin(), source.end(), target);
}

/**
 * Convenience function; generates an accelerator mapping from all the
 * keys in a TQMap<TQString,T>
 *
 * @param source Map with input strings as KEYS.
 * @param target Output for accelerator-added strings */
template <class Data>
inline void
generateFromKeys(const TQMap<TQString,Data>& source, TQStringList& target)
{
    generateFromKeys(source.begin(), source.end(), target);
}


} // end namespace KAccelGen

#endif