CD Shell Development: Hotkey Services

Hotkey Services

Hotkey Services List

Modules are able to present a list of hotkey services to the core. The list is a linear array made up of individual hotkey service definitions, each of which define a single hotkey supported by the module. These hotkeys are then used to intercept keystrokes from the console, and perform various actions when triggered. A good example of this is the history module, which intercepts the up arrow, down arrow, and enter keys to maintain and bowse the command history.

A 2-byte (16-bit) zero value terminates the list.

Hotkey Service Definition

Offset	Size	Description
0	2 bytes	service routine pointer
2	2 bytes	flags
4	2 bytes	name pointer
6	2 bytes	description text pointer
8	2 bytes	key code

Service Routine Pointer

This is the offset into the module segment of the handler routine that processes this hotkey.

Flags

This field is a set of flags that determine how the hotkey is handled. To determine whether or not to invoke a hotkey service, the key code of the pressed key is compared with that in the hotkey service definition. If they match, then the modifier keys (ctrl, alt, left/right shift) are polled, masked to determine which ones to test, and then tested if necessary to check for a match. If all conditions match, then the service routine will be called by the core to handle the keypress.

The flag bitfields are defined as follows:

Bit	Field	Description
[0]	Ignore	pretend this hotkey is not in the list
[1]	Hide	don't display info about this hotkey
[10:2]	Reserved	these flags are reserved for future use
[11:8]	Modifier Key Mask	indicate which modifier keys to test
[15:12]	Modifier Key Test	tests modifier keys to determine match

Note: Modifier key mask and test bitfields are defined in cdshell.inc.

Name Pointer

This is the offset into the module segment of the hotkey name, a null-terminated string.

Description Text Pointer

This is the offset into the module segment of the hotkey description, a short string presented to the user in the master hotkey list. If no description is provided, this field should be zeroed out.

Key Code

This is the BIOS key code of the keypress that this hotkey will intercept (see flags description above).

Service Routine Environment

Call Context

The hotkey service routine is called by the core with the following context:

Register	Contents
ah	modifier keys state (see below)
si	offset of input line buffer (located in core segment)
cs	module segment
ds	segment of input line buffer (core segment)
es	module segment
gs	Core Services Table segment
ss:sp	global stack, far return pointer on top

Modifier Keys State Bitfield

Bit	Description
[0]	right shift pressed
[1]	left shift pressed
[2]	ctrl pressed
[3]	alt pressed
[4]	scroll-lock active
[5]	num-lock active
[6]	cap-lock active
[7]	insert active

Return Context

The core expects the following context upon return from the service routine:

Register	Contents
al	return action
ss:sp	global stack, far return pointer popped

Return Actions

When the hotkey handler returns, it informs the core of what action to perform next. The possible actions are described below.

Value	Action Performed Upon Return
Hotkey.Continue	continue using the current input buffer, and continue processing the keystroke
Hotkey.Execute	execute the contents of the current input buffer
Hotkey.Forget	continue using the current input buffer, but end processing the keystroke
Hotkey.New	begin a new command line

Note: Action values are defined in cdshell.inc.

- Previous -

- Next -