Hotkeys

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: 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.


void AutoHotKeys(int mode);

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.


int JoinTabChain(int id);

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.
int SetFocusOn(int id);

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': 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.
int GetCurrentFocus(int id);

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:
See also: IsHotKey.
int IsHotKey(int scan, int ascii);

Checks if the specified scan/ascii already has been used in the operating window.
Returns 0 if not, otherwise 1
See also: SetHotKey.
void SimulateHotKeys(int scan, int ascii);

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.


void UseHotKeys(char *hkset);

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