Qtrac Ltd.
Software
Courses
Books
Game
All Writing & Software
Privacy
Copyright © 2006 Qtrac Ltd.
All Rights Reserved.
The Alt_Key Library Documentation
The Alt_Key library is a
Qt 4 library for automatically and instantly inserting
keyboard accelerators into actions, dialogs, and menus. It is very fast
because it uses the Kuhn-Munkres
algorithm, easily outperforming all the naive
algorithms.
This library is no longer being developed or maintained.
Introduction
The Alt_Key library consists of four files: alt_key.hpp,
alt_key.cpp, kuhn_munkres.hpp, and
kuhn_munkres.cpp. The
public API is in alt_key.hpp and uses the AQP namespace.
The library is supplied along with the examples for the book Advanced Qt Programming. Many of the book's
examples use the library. The library is also used by the Alt_Key GUI application.
Example
Here is a list of menu options before and after Alt_Key has added
accelerators:
Before | After |
Calculate | &Calculate |
New | &New |
Load... | &Load... |
Save | &Save |
Save &As... | Save &As... |
Copy to Clipboard | Copy &to Clipboard |
Set Options... | Set &Options... |
Help | &Help |
About | A&bout |
Quit | &Quit |
Notice that the "Save &As" option already had an accelerator: The
Alt_Key library respects manually inserted accelerators.
API
Include
- #include "alt_key.hpp"
-
This includes the kuhn_munkres.hpp file. Either copy the four
files into your project or soft link them or add them to your include
path.
Constant
- QString AQP::Alphabet
-
This string holds the characters that are eligible to be used as
accelerators: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ. All the
functions that take an alphabet argument use this as their default
value. If you choose to use a different alphabet you may only use
uppercase letters (or no-case letters for languages that don't
distinguish case).
(Actually this is now an instance of the private AQP::_Alphabet
class; the class provides a single method which is a QString
conversion function, so in most cases it can be used wherever a
QString is expected. The reason for this change is to make the
alphabet string translatable.)
Main Functions
These are the most commonly used functions provided by the
Alt_Key library.
- void AQP::accelerateActions(QList<QAction*> actions, const
QString &alphabet=Alphabet)
-
This function takes a list of actions and optionally an alphabet. It
adds keyboard accelerators to every action's text wherever possible.
Existing accelerators are respected as are plain ampersands (which
are represented by "&&" in strings).
- void AQP::accelerateMenu(QWidget *menuOrMenuBar, const QString
&alphabet=Alphabet)
-
This function takes a menu (including context menus) or a main
window's menu bar and optionally an alphabet. It adds keyboard
accelerators to every menu item's text wherever possible. The
function works recursively, adding accelerators to submenus and
subsubmenus. Existing accelerators are respected as are plain
ampersands (which are represented by "&&" in strings).
- void AQP::accelerateWidget(QWidget *widget, const QString
&alphabet=Alphabet)
-
This function takes a widget (such as a QDialog subclass) and
optionally an alphabet. It adds keyboard accelerators to every buddy
label, button (i.e., all QAbstractButton subclasses apart from
QToolButton), checkbox, checkable group box, and radio button,
that is a child of the widget (or grandchild, recursively), wherever
possible. Existing accelerators are respected as are plain ampersands
(which are represented by "&&" in strings).
- void AQP::accelerateWidgets(QList<QWidget*> widgets, const QString
&alphabet=Alphabet)
-
This function takes a list of widgets (for example, all the widgets
on a particular tab widget page) and optionally an alphabet. It
adds keyboard accelerators to every suitable widget, (i.e., to every
buddy label and button), wherever possible. Existing accelerators
are respected as are plain ampersands (which are represented by
"&&" in strings).
Auxiliary Functions
These functions are occassionally useful.
- QStringList AQP::accelerated(const QStringList &strings, const
QString &alphabet=Alphabet)
-
This function takes a list of strings and optionally an alphabet. It
returns a new string list with a keyboard accelerator added to every
string wherever possible. Existing accelerators are respected as are
plain ampersands (which are represented by "&&" in
strings).
- bool AQP::isValid(const QStringList &strings, QPair<int,
int> *where=0, const QString &alphabet=Alphabet)
-
This function returns true if the given list of strings has
valid accelerators. Valid includes no accelerators, but does not
include duplicate accelerators. If the where pair is passed and
the function returns false the pair's ints are set to
the index of the first string in the list and the index of the character
within the string where a problem (e.g., duplicate accelerators)
occurred.
- int AQP::numberAccelerated(const QStringList
&strings)
-
This function returns the number of strings in the string list that
have accelerators.
- double AQP::quality(const QStringList &strings)
-
This function returns a rough guide to accelerator quality. For each
string the best quality is when the string has an accelerator for its
first character, second best is an accelerator for the start of a word,
third best is any accelerator at all, and worst is no accelerator. The
quality computation accounts for the overall quality of all the strings
in the list and returns a value that ranges from 0.0 (worst) to 1.0
(best).
Top