\section{KAccel\-Gen Namespace Reference}
\label{namespaceKAccelGen}\index{KAccelGen@{KAccelGen}}
Provides functions that, given a collection of QStrings, will automatically and intelligently assign menu accelerators to the QStrings in the collection.  


\subsection*{Classes}
\begin{CompactItemize}
\item 
class {\bf Deref}
\begin{CompactList}\small\item\em Static dereference class, for use as a template parameter. \item\end{CompactList}\item 
class {\bf Deref\_\-Key}
\begin{CompactList}\small\item\em Static dereference class that calls the key() method on its target; for use as a template parameter. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
bool {\bf is\-Legal\-Accelerator} (const  {\bf QString} \&str, uint index)
\begin{CompactList}\small\item\em Helper to determine if the given offset in the string could be a legal alphanumeric accelerator. \item\end{CompactList}\item 
template$<$class Iter, class Deref$>$ void {\bf load\-Predefined} (Iter begin, Iter end, {\bf QMap}$<$ {\bf QChar}, bool $>$ \&keys)
\begin{CompactList}\small\item\em Loads all legal predefined accelerators in the (implicitly specified) collection into the given {\bf QMap}. \item\end{CompactList}\item 
template$<$class Iter, class Iter\_\-Deref$>$ void {\bf generate} (Iter begin, Iter end, {\bf QString\-List} \&target)
\begin{CompactList}\small\item\em Main, maximally flexible template function that assigns accelerators to the elements of a collection of QStrings. \item\end{CompactList}\item 
template$<$class Iter$>$ void {\bf generate\-From\-Keys} (Iter begin, Iter end, {\bf QString\-List} \&target)
\begin{CompactList}\small\item\em Another convenience function; looks up the key instead of dereferencing directly for the given iterator. \item\end{CompactList}\item 
void {\bf generate} (const  {\bf QString\-List} \&source, {\bf QString\-List} \&target)
\begin{CompactList}\small\item\em Convenience function; generates accelerators for all the items in a {\bf QString\-List}. \item\end{CompactList}\item 
template$<$class Key$>$ void {\bf generate\-From\-Values} (const  {\bf QMap}$<$ Key, {\bf QString} $>$ \&source, {\bf QString\-List} \&target)
\begin{CompactList}\small\item\em Convenience function; generates accelerators for all the values in a QMap$<$T,QString$>$. \item\end{CompactList}\item 
template$<$class Data$>$ void {\bf generate\-From\-Keys} (const  {\bf QMap}$<$ {\bf QString}, Data $>$ \&source, {\bf QString\-List} \&target)
\begin{CompactList}\small\item\em Convenience function; generates an accelerator mapping from all the keys in a QMap$<$QString,T$>$. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
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 \char`\"{}accelerators\char`\"{}, we really mean accelerators as defined by the {\bf KDE} User Interface Guidelines. We do NOT mean \char`\"{}shortcuts\char`\"{}, which are what's handled by most other {\bf KDE} libraries with \char`\"{}accel\char`\"{} in the name.

In the {\bf 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 \char`\"{}target\char`\"{} {\bf QString\-List} 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 \char`\"{}user-specified\char`\"{} 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 \char`\"{}Load View Profile\char`\"{} 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 {\bf Deref}{\rm (p.\,\pageref{classKAccelGen_1_1Deref})} classes so that we can access a wider variety of collections. 



\subsection{Function Documentation}
\index{KAccelGen@{KAccel\-Gen}!isLegalAccelerator@{isLegalAccelerator}}
\index{isLegalAccelerator@{isLegalAccelerator}!KAccelGen@{KAccel\-Gen}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool is\-Legal\-Accelerator (const {\bf QString} \& {\em str}, uint {\em index})\hspace{0.3cm}{\tt  [inline]}}\label{namespaceKAccelGen_a0}


Helper to determine if the given offset in the string could be a legal alphanumeric accelerator. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em str}]base string \item[{\em index}]offset to check \end{description}
\end{Desc}


Definition at line 109 of file kaccelgen.h.

References QString::length().

Referenced by generate(), and load\-Predefined().\index{KAccelGen@{KAccel\-Gen}!loadPredefined@{loadPredefined}}
\index{loadPredefined@{loadPredefined}!KAccelGen@{KAccel\-Gen}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}template$<$class Iter, class Deref$>$ void load\-Predefined (Iter {\em begin}, Iter {\em end}, {\bf QMap}$<$ {\bf QChar}, bool $>$ \& {\em keys})\hspace{0.3cm}{\tt  [inline]}}\label{namespaceKAccelGen_a1}


Loads all legal predefined accelerators in the (implicitly specified) collection into the given {\bf QMap}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em begin}]start iterator \item[{\em end}](last+1) iterator \item[{\em keys}]map to store output \end{description}
\end{Desc}


Definition at line 125 of file kaccelgen.h.

References KStd\-Accel::end(), QString::find(), QMap::insert(), and is\-Legal\-Accelerator().\index{KAccelGen@{KAccel\-Gen}!generate@{generate}}
\index{generate@{generate}!KAccelGen@{KAccel\-Gen}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}template$<$class Iter, class Iter\_\-Deref$>$ void generate (Iter {\em begin}, Iter {\em end}, {\bf QString\-List} \& {\em target})}\label{namespaceKAccelGen_a2}


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 {\bf Deref}{\rm (p.\,\pageref{classKAccelGen_1_1Deref})} template parameter is a class containing a static dereferencing function, modeled after the comparison class C in Stroustrup 13.4.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em begin}](you know) \item[{\em end}](you know) \item[{\em target}]collection to store generated strings \end{description}
\end{Desc}


Definition at line 162 of file kaccelgen.h.

References QMap::contains(), KStd\-Accel::end(), QString::find(), QString::insert(), QMap::insert(), is\-Legal\-Accelerator(), and QString::length().\index{KAccelGen@{KAccel\-Gen}!generateFromKeys@{generateFromKeys}}
\index{generateFromKeys@{generateFromKeys}!KAccelGen@{KAccel\-Gen}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}template$<$class Iter$>$ void generate\-From\-Keys (Iter {\em begin}, Iter {\em end}, {\bf QString\-List} \& {\em target})\hspace{0.3cm}{\tt  [inline]}}\label{namespaceKAccelGen_a3}


Another convenience function; looks up the key instead of dereferencing directly for the given iterator. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em begin}]\item[{\em end}]\item[{\em target}]\end{description}
\end{Desc}


Definition at line 227 of file kaccelgen.h.

References KStd\-Accel::end().

Referenced by generate\-From\-Keys().\index{KAccelGen@{KAccel\-Gen}!generate@{generate}}
\index{generate@{generate}!KAccelGen@{KAccel\-Gen}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void generate (const {\bf QString\-List} \& {\em source}, {\bf QString\-List} \& {\em target})\hspace{0.3cm}{\tt  [inline]}}\label{namespaceKAccelGen_a4}


Convenience function; generates accelerators for all the items in a {\bf QString\-List}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em source}]Strings for which to generate accelerators \item[{\em target}]Output for accelerator-added strings \end{description}
\end{Desc}


Definition at line 240 of file kaccelgen.h.\index{KAccelGen@{KAccel\-Gen}!generateFromValues@{generateFromValues}}
\index{generateFromValues@{generateFromValues}!KAccelGen@{KAccel\-Gen}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}template$<$class Key$>$ void generate\-From\-Values (const {\bf QMap}$<$ Key, {\bf QString} $>$ \& {\em source}, {\bf QString\-List} \& {\em target})\hspace{0.3cm}{\tt  [inline]}}\label{namespaceKAccelGen_a5}


Convenience function; generates accelerators for all the values in a QMap$<$T,QString$>$. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em source}]Map with input strings as VALUES. \item[{\em target}]Output for accelerator-added strings \end{description}
\end{Desc}


Definition at line 253 of file kaccelgen.h.

References QMap::begin(), and QMap::end().\index{KAccelGen@{KAccel\-Gen}!generateFromKeys@{generateFromKeys}}
\index{generateFromKeys@{generateFromKeys}!KAccelGen@{KAccel\-Gen}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}template$<$class Data$>$ void generate\-From\-Keys (const {\bf QMap}$<$ {\bf QString}, Data $>$ \& {\em source}, {\bf QString\-List} \& {\em target})\hspace{0.3cm}{\tt  [inline]}}\label{namespaceKAccelGen_a6}


Convenience function; generates an accelerator mapping from all the keys in a QMap$<$QString,T$>$. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em source}]Map with input strings as KEYS. \item[{\em target}]Output for accelerator-added strings \end{description}
\end{Desc}


Definition at line 266 of file kaccelgen.h.

References QMap::begin(), QMap::end(), and generate\-From\-Keys().