diff options
Diffstat (limited to 'tdeui/kaccelgen.h')
| -rw-r--r-- | tdeui/kaccelgen.h | 280 |
1 files changed, 0 insertions, 280 deletions
diff --git a/tdeui/kaccelgen.h b/tdeui/kaccelgen.h deleted file mode 100644 index d1e761876..000000000 --- a/tdeui/kaccelgen.h +++ /dev/null @@ -1,280 +0,0 @@ -/* 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 <tdelibs_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 TDEAccelGen -{ - -// 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 TDEAccelGen - -#endif - |