A "hot-key" means that a key pressed by the user invokes a function call.
Creating hot-keys may be done in following four ways:
- By marking a single character (by preceding it with the
tilde '~' character) in the label text of a visible object. This
character will then be the hot-key for clicking that object.
- Implicitly when the system automatically generates a hot-key for an
newly created labelled object (DisplayWin does this). These hot-keys
will always be selected from, so far, unused keys.
- Explicitly assigning a hot-key to an object (or extending the object
with yet one). This will be done by use of the "#scan,ascii;"
command in the label string.
- Explicitly creating a "hot key" for any purpose (not associated with
any visible object) by call to SetHotKey.
Hot-keys associated with an existing object will be automatically removed
when the object is removed (which normally will be done when closing the
window).
Hot-keys created with SetHotKey will be removed when the node which it is
associated with, are removed. Such hot-keys may also be removed
selectively by just calling Remove and pass the id received from
`SetHotKey'.
When assigning hot-keys explicitly there is no check if the key is
already used. If the same hot-key is assigned to multiple objects, it is
not defined which one will be selected when the user presses the key.
You may use the function IsHotKey to avoid ambiguous
hot-keys.
The scope of hot-keys is normally a window. An exception from this are
menus which have their own scope...or to be correct: this is no exception
since menus are implemented as windows... Tab windows are not independent
windows, and the objects in "hidden tab-windows" does not exist, so there
will be no conflict if same keys are used in different
tab-windows.
A special hot-key feature is the tab-chain. Any number of objects may be
linked together in the tab-chain. There is one tab-chain in each window
(possibly empty). Selectable objects (i.e. such objects that are used
for user input) will automatically join the tab-chain when they are
created.
The tab and back-tab keys are reserved for the tab-chain. One of the
objects within the chain are pre-set to be in
"tab-focus" when the window is created (by default this will be set to
the first one in the chain). When the user presses the tab or back-tab
key the "tab-focus" will move to the next or previous object in the
chain.
The "tab-focus" means that the object is highlighted, and that it will
catch subsequent ENTER and/or CRTL-ENTER key presses. The ENTER-key
matches left mouse-button and CTRL-ENTER right mouse-button, so the later
requires the object to be pre-set to receive right mouse clicks.
The chain is circular. An object in the tab-chain that is currently
deactivated will not get the tab-focus, it will be by-passed if reached
by a tab key-press.
The order in which the object joins the tab-chain controls their position
in the chain. By default the joining is their creation order.
Containers may also join the tab-chain (optionally). The effect is that
the container itself will take one position in the chain. While the
container is in "tab-focus" any object within it may be in "sub-focus",
which in this case is the real focus notified by the user and sensible for
enter/ctrl-enter. The user can move the sub-focus only by using the
arrow-keys. This requires that the objects within the container are
grouped and positioned in a tabular manner (the sub-focus will go the
object next to left/right/below/above following the x/y-coordinate of
the current sub-focused object. This implies that it will not work
properly if there are containers nested within the one joining the
chain, only one level is possible.
If an object within the tab-chain is selected by use of the mouse (e.g.
if it is clicked), then the focus is moved to it.
There are functions to re-arrange the default order in the tab-chain,
to force the focus to some object and to achieve info about which object
that is currently in focus.
Possible modes: 0 or 1 (off or on)
In default mode CGUI will automatically try to generate short-cuts
for text-labelled visual objects. If the combination of labels in a
window happens to have a first solution of unique short-cuts that takes
a long time to find (this will occur if there are lots of objects and
the total usege of characters is large and they occur in a random
order and there is only a few or none possible solutions).
To avoid long (or infinite!) processor time for finding a solution before
displaying a window, hot-keys for labelled object may be explicitly
stated, or you may except a sequence of objects from the automatic
generation and maybe put them into the tab-chain instead.
When objects like buttons, check-boxes, list-boxes etc are created they
will automatically be linked into a `tab-chain' (strict sequential and
flat in the tree-formed window). The tab-chain defines
which objects that may be set in focus by the user (using the
tab/backtab keys) and it also defines the order between these objects.
The order of the automatic joining will be the order in which the objects
were created.
You can use `JoinTabChain' to add objects that do not join the chain
automatically (e.g. canvas-objects) or to customise the order between
them by re-joining.
Not only simple objects like buttons can join the tab chain, but also
containers (e.g. radio-containers, list-boxes etc.). If the user tabs to
a container the selection of a certain object within the container can be
done by use of the arrow-keys. It is not meaningful to join a container
in which there are more containers (i.e. recursive constructs), since
there is no way for the user to control the focus movement within the
sub-sub-container.
`JoinTabChain' will first remove the object `id' from the chain if it is
already there, and then insert it after the currently focused object.
The focus is not changed.
Returns 1 on success and 0 if it fails. The parameter `id' shall be the
id-key of an object (returned by the creating function).
See also:
SetFocusOn.
When a window is created the first created object within the window that
joins the tab-chain will be in focus. The meaning of "beeing in focus" is
that it will be drawn highlighted in some manner and it is ready for
input. For simple objects like buttons, check-boxes etc. this means that
a subsequent enter key-press will have the same effect as a click. For
edit-boxes it means that it is ready to let the user type in text (the
text-cursor is blinking). For nodes like menu-bars, radio-containers,
list-boxes etc it means that the user may make a sub-selection of an
object with use of the arrow-keys.
This function explicitly sets the focus on the object `id'. It must be
a selectable object (i.e. it must be in the tab-chain).
You can call `SetFocusOn' immediately after you finnished the window
building process by a call to `DisplayWin', or later to e.g. highlight a
newly performed action by the user.
`SetFocusOn' updates the view of both the previus and new focus.
There are some different cases of the object `id':
- `id' is a simple object: The focus is moved to it (and the
previously focused will be unfocused).
- `id' is a node (container) that has joined the chain: The
the main focus is moved to the node (which normally has no special
view) and the simple object within the node that was last in
"sub-focus" will now be highlighed as `focused'.
- `id' is an object within a node (container), and the node itself
is the one that has joined the chain: The
`tab-focus' will be moved to the node and `id' will be highlighted.
- `id' is a window: The window will get the focus in case
there are no modal windows above it (highligted in the header).
Returns 1 on success and 0 if it fails.
The parameter `id' can be the id-key of any type of object (returned by
the creating function).
See also:
JoinTabChain,
BrowseTo.
Returns the id-key of the object that is currently in focus.
If `id' is 0 the id-key of the window currently beeing in focus will be
returned.
If `id' referes to a window then the focused object within the tab-chain
of that window will be returned.
If `id' referes to a container that has joined the tab-chain, the focused
(simple) object within that container will be returned.
See also:
SetFocusOn,
JoinTabChain.
int SetHotKey(int id, void (*CallBack)(void*), void *data, int scan,
int ascii);
Installs an application-specific handler which will be called with "data"
when the "hot-key"-will be pressed.
This "hot-key" will be hooked to any node, and it will be removed with
the node.
Parameters:
- id: the id-key to the node (window, tab-window, list, container etc)
To get a hot-key that is global (and permanent) for all windows,
just enter 0.
- CallBack: a function written by you. It will be called when a
key-press matches scan/ascii.
- data: passed to CallBack
- scan, ascii: specifies the hotkey. NOTE!: For "ordnary keys"
(alphanumeric, esc, carrage return, backspace, shifted digits, and
other "normal" keys on the main part like '.' etc) you must
pass 0 for scan-key.
Case of letters are ignored
See also:
IsHotKey.
Checks if the specified scan/ascii already has been used in the
operating window.
Returns 0 if not, otherwise 1
See also:
SetHotKey.
This function calls for the system's handler of hot-keys, which is
by default the receiver of keys (if no editbox is in focus), and does not
normally need to be called by the application program.
SimulateHotKeys will have the same effect as if the user pressed the
specified keys. This function may possibly be useful to call in
special cases in some other keyboard-handler (to bypass the let the
key-presses bypass the current keyboard- handler (and all other) and
go directly to the hot-key handler. Another way of doing this is to
call Allegro's `simulate_keypress'. This will however lead to a new
entry in the event queue.
Specifies which characters in the labeltexts that shall be used by the
system when the automatic generation of hot-keys is in progress. Default
is the english alphabet. If you wants national characters or special keys
like %-/ etc to be candidates for hotkeys then use this function. `hkset'
will replace the previous set.
See also:
Labels.
Back to contents