Keyboard Primitives

int assign_to_key( [string key], [string macro] )

Assign command to key or key sequence.

Description

The assign_to_key primitive assigns a key or key sequence to a function.

The key is defined by the string parameter key, which if omitted shall be prompted. key may be specified as either an internal key code, or may be specified by a portable abbreviation, see below.

A key is “unassigned” by assigning the function nothing to the key.

If key evaluates to more than one keystroke, this shall define a multikey sequence, that is more than one key must be pressed to execute the macro.  In this case, an internal key code is assigned for the key.  This internal key code is returned as the value of this macro.  Multikey sequences do not time out between key presses unlike the other internal keys when there is an ambiguity.

Parameters

Key Sequences

Generally keys are defined using their associated mnemonic possiblity prefixed with one or modifiers enclosed within a set of “<>” brackets, examples.

• <F1>
• <Ctrl-F1>
• <Alt-Ctrl-Up>.

The following are the set of supported modifiers

• Shift - Key Shift, for example a to Z.
• Ctrl - Control Key.
• Alt - Alt Key.
• Meta - Alias for Alt.
• Keypad - Keypad key variate.

In the case of simple ASCII keys their character value can be used, for example “a”.

In addition to a mnemonic “<xxx>” or ASCII “x” syntax additional alternative forms and special characters are supported.

When it is required to state any of the special characters “<, >, %, # or ^” these can be referenced using their escaped form, example “\\<”.

The following table details the supported key sequence encoding and suitable modifiers; all names are matched case insensitive.

For examples review current supplied macro code.

Returns

The assign_to_key returns the key value assigned to sequence, otherwise -1 if the key sequence is invalid or the operation aborted.

Portability

n/a

See Also

key_to_int

int copy_keyboard( int  kbdid,     [string cmd ...] )

Copy a keyboard.

Description

The copy_keyboard() primitive copies the key bindings associated with the keyboard identifier kbdid.  The keyboard is either copied in its entirety or optionally the subset of key bindings associated with the specified list of commands cmd.

The primary use of this primitive is to obtain an explicit subset of a full keyboard for a specific use; for example a keyboard to be used by an popup for a special editing window.  Another way of thinking, it a macro can inherit a keyboard, modify and then utilise locally without knowledge of the callers keyboard bindings.

Parameters

Returns

The copy_keyboard() primitive returns the Keyboard identifier of the new keyboard.  On error 0 is returned if the commands given are not found.

Portability

n/a

See Also

keyboard_push, keyboard_pop, assign_to_key

void get_mouse_pos(   [int &x], [int &y], [int &winnum],   [int &line], [int &col],   [int &where], [int &region], [int &event] )

Retrieve last mouse action.

Description

The get_mouse_pos() primitive retrieves the details of the last mouse action.

Parameters

Where

Region

Returns

Returns the time since the previous mouse event.

Portability

n/a

See Also

process_mouse, translate_pos

int input_mode( int  char, int  flag )

Effect of certain system keys.

Description

The input_mode() primitive controls the effect of certain characters when typed, setting the actions of character char to the desired state.

Normally the keyboard driver acts internal on specific characters which perform the control actions of XON/XOFF and the Job control stop; specifically Ctrl-S (0x13), Ctrl-Q (0x11) and Ctrl-Z (0x1a).

Parameters

Returns

The input_mode() primitive returns 1 if character previously enabled; zero otherwise.

Portability

n/a

See Also

inq_keyboard

string inq_assignment( int|string  val,   [int tokey = FALSE] )

Get key assignment for function.

Description

The inq_assignment() primitive either retrieves the command that is assigned to the particular key val or the key sequence(s) that will invoke a specific command.

Parameters

Returns

The inq_assignment() primitive returns a string containing the desired conversion.

For key sequence to command: the name of the command; OR “nothing” if no command is assigned; OR “ambiguous” if there is more than key sequence starting with the val.

For command to key sequence enabled when tokey is non-zero

a list of the valid key sequences for the command.  The list elements are formatted with the following separators:

Portability

n/a

See Also

assign_to_key

int inq_kbd_char()

Peek at the keyboard.

Description

The inq_kbd_char() primitive determines whether a character is available to be retrieved from the keyboard using read_char.

Parameters

none

Returns

The inq_kbd_char() primitive returns non-zero if one or more characters are available, otherwise 0 if the keyboard buffer is empty.

Portability

n/a

See Also

read_char

int inq_kbd_flags()

Get keyboard key flags.

Description

The inq_kbd_flags() primitive returns the state of the special keyboard keys.

Parameters

none

Returns

Always returns 0.

Portability

Provided only for BRIEF compatibility.

See Also

inq_kbd_char

string inq_kbd_name( [int kbdid] )

Retrieve the assigned keyboard name.

Description

The inq_kbd_name() primitive retrieves the name assigned to the keyboard kbdid using <set_kdb_name>.

Parameters

Returns

The inq_kbd_name() primitive retrieves the keyboard name otherwise an empty string is none has been assigned.

Portability

n/a

See Also

set_kbd_name

int inq_keyboard()

Retrieve the keyboard identifier.

Description

The inq_keyboard() primitive retrieves the identifier associated with the current keyboard.

Parameters

none

Returns

The inq_keyboard() primitive returns the current keyboard identifier.

Portability

n/a

See Also

keyboard_pop, keyboard_push

string inq_keystroke_macro( [int macroid], [int &bufnum] )

Retrieve the current keystroke macro.

Description

The inq_keystroke_macro() primitive retrieves a string containing the definition of the current keyboard macro, which may then be saved in a file and reloaded.

The returned definition may edited and/or saved for future use; see load_keystroke_macro.

Parameters

Returns

nothing

Portability

Under BRIEF this primitive behaved like the functionality available via inq_keystroke_status.

See Also

remember, load_keystroke_macro

int inq_keystroke_macro( [int &macroid] )

Determine keystroke macro status.

Description

The inq_keystroke_macro() primitive determines whether keystroke macro record or playback is active.

Parameters

Returns

The inq_keystroke_macro() primitive returns greater than zero if a keystroke macro is being recorded or played back.

Portability

Under BRIEF this primitive is named inq_keystroke_macro.

See Also

remember, playback

int inq_local_keyboard()

Retrieve local keyboard identifier.

Description

The inq_local_keyboard() primitive retrieves the identifier associated with current local keyboard.

Parameters

none

Returns

The inq_local_keyboard() primitive returns the associated keyboard identifier, otherwise 0 if none is available.

Portability

n/a

See Also

use_local_keyboard

string inq_mouse_action()

Retrieve the keyboard mouse handler.

Description

The inq_mouse_button() primitive is reserved for future BRIEF compatibility.

The inq_mouse_action() primitive retrieves the name of the current mouse action handler.  This function can be used to save the current mouse handle prior to pushing a new keyboard.

Parameters

none

Returns

Returns the current mouse action.

Portability

n/a

See Also

set_mouse_action

int inq_mouse_type()

Retrieve the button type.

Description

The inq_mouse_type() primitive retrieves the current mouse type.

Parameters

none

Returns

Returns the current mouse type.

Portability

n/a

See Also

string inq_remember_buffer( [int macroid] )

Determine the keystroke buffer name.

Description

The inq_remember_buffer() primitive derives the buffer name associated with the keyboard macro macro.

Unlike BRIEF multiple keystroke macros can be maintained.  Each remember execution shall create a buffer named KBD-MACRO-# where # is the associated keyboard macro identifier.  This buffer maybe then edited and/or saved to later use.

Parameters

Returns

The inq_remember_buffer() primitive returns the buffer name associated with the remember buffer.

Portability

n/a

See Also

remember

string int_to_key( int  key )

Convert an keycode to mnemonic key string.

Description

The int_to_key() primitive generates the corresponding mnemonic representation for the specified keycode key; which can be used by assign_to_key

Parameters

Returns

The int_to_key() primitive returns the key mnemonic string associated with the specified keycode, for example “<Ctrl-D>”; see assign_to_key for full description of key mnemonics.

Portability

n/a

See Also

assign_to_key

list key_list( int  kbdid,     [int self_inserts = 0],   [int bufnum] )

Retrieve keyboard bindings.

Description

The key_list() primitive retrieves the key bindings associated with the keyboard kbdid.  The definitions are returned as a list of string pairs, the first element being the key name with the second being assigned macro.

Up to two keyboards can be specified.  If bufnum is specified, then the local keyboard assigned to that buffer is used.  If not specified then the local keyboard map of the current buffer is used.  The returned list is a union of the set keyboards.

This primitive is designed to display a list of all valid keys currently mapped in both the current local and global keyboard maps.  For an example see the key_map macro.

Parameters

Returns

The key_list() primitive returns a list of key binding, as a set of string pairs, the first element is the key name and second being assigned macro to that key.  Otherwise on error a null list.

Portability

n/a

See Also

keyboard_pop, keyboard_push

int key_to_int( string  key, int  raw )

Convert key name to a code.

Description

The key_to_int() primitive converts a mnemonic key string to an integer.

The following scheme is utilised for encoding internal key-codes, allowing for simple conversion of ASCII character code to the internal codes and vice-versa.

Firstly key-codes are divided into several ranges.

These ranges can be OR’ed with one or more of the following bits to indicate a modifier key, for example a Shift-F1 key or Ctrl-Shift-F2.

To further simplify key handling, the follow special key manifest constants are predefined.

switch (keycode) {
case key_to_int("<F1>"):
    f1();
    break;
case key_to_int("<Ctrl-A>"):
    ctrla();
    break;
case key_to_int("<Ctrl-B>"):
    ctrlb();
    break;
:

Parameters

Returns

The key_to_int() primitive returns an integer representing the internal key code assigned to the specified key sequence, or -1 if the sequence does not correspond to an valid key.

Portability

n/a

See Also

assign_to_key, int_to_key

void keyboard_flush()

Flush the keyboard buffer.

Description

The keyboard_flush() primitive flushs the keyboard input buffer, consuming any pending input, permanently removing the keystrokes.

Parameters

none

Returns

nothing

Portability

n/a

See Also

inq_kbd_char, read_char

void keyboard_pop( [int save = FALSE] )

Pop a keyboard from the keyboard stack.

Description

The keyboard_pop() primitive removes the top keyboard, from the last-in/first-out (LIFO) keyboard stack.

Each invocation of keyboard_push must have a corresponding invocation of keyboard_pop.

The keyboard resource and associated identifier shall only remain valid if the save argument is non-zero, otherwise the keyboard definition is deleted and its memory reclaimed.

If the current buffer is the same as it was when the keyboard was pushed, the current local keyboard is also restored to its former value.

Parameters

Returns

nothing

Portability

n/a

See Also

keyboard_push, inq_keyboard

void keyboard_push( [int kbdid] )

Push a keyboard onto the keyboard stack.

Description

The keyboard_push() primitive pushes a keyboard, either an existing or new, onto the last-in/first-out (LIFO) keyboard stack.  Being a stack each invocation of keyboard_push must have a corresponding invocation of keyboard_push; otherwise the keyboard objects shall never to released, resulting in a resource/memory leak.

Either the specified keyboard kbdid or if omitted a new empty keyboard object shall be pushed onto the stack and become the current keyboard (See: inq_keyboard).  When a new keyboard is created, it is empty and the current local keyboard is temporarily unassigned.

A keyboard resource is a table of key bindings, that is keys mapped against the macro which should be executed when encountered.  During initialisation the default keyboard resource binds the usual editing keys, keyboard_push() permits the creation of macro specific keyboards, supporting temporarily bind macros to keys for their operation.

Defaults

The default key bindings along with keyboard_typeables includes -

Parameters

Returns

The keyboard_push() primitive returns the identifier of the referenced keyboard, otherwise -1 on error.

Example

The following example creates a new keyboard with only typeable key binds active.

keyboard_pop();
keyboard_push();
keyboad_typeables();

The following example shows how to create a temporary keyboard mapping for use within a macro.

keyboard_push();
assign_to_key("<Alt-H>", "help");
    // additional key bindings
                 ::
process();
keyboard_pop();

Portability

n/a

See Also

inq_keyboard, keyboard_pop, keyboard_typeables, process

int keyboard_typeables()

Assign self_insert to all typeable keys.

Description

The keyboard_typeables() primitive populates the keyboard with all of the standard keys, example include ASCII keys (for example A-Z and 0-9), Backspace, Tab, and Enter are bound to self_insert.

Parameters

none

Returns

nothing

Portability

n/a

See Also

inq_keyboard

int load_keystroke_macro( string  def )

Load a recorded macro from a file.

Description

The load_keystroke_macro() primitive loads the specified keystroke macro macro, being a string in a similar format returned by inq_keystroke_macro.  This primitive is designed to allow user macros to load macros from external files.

Parameters

Returns

The load_keystroke_macro() primitive returns the newly associated macro identifier, otherwise -1 on error.

Portability

n/a

See Also

inq_keystroke_macro

void pause()

Pause keystroke definition.

Description

The pause() primitive pauses a keyboard macro definition.

Usually all keyboard input typed during a remember sequence is saved in the keyboard macro buffer.  Pressing a key assigned to pause causes the remember sequence to suspend saving the characters.

Parameters

none

Returns

nothing

Portability

n/a

See Also

remember

int playback( [int macroid] )

Replay a keystroke macro.

Description

The playback() primitive replays the previously saved keyboard macro macro.

Parameters

Returns

The playback() primitive returns greater than or equal to zero if playback was successful, otherwise less than zero on error.

Portability

n/a

See Also

remember

void process()

Invoke a Grief engine.

Description

The process() primitive invokes an instance of the Grief command-loop recursively by accepting keystrokes and calling the functions assigned thru the associated key bindings (See: assign_to_key).

process is usually invoked after building the required environment including buffers and/or windows with an associated keyboard.  Process nesting may occur to any depth, within the bounds of Griefs maximum nesting level.  The

current command loop executes until the session is terminated by an exit command.

Parameters

none

Returns

nothing

Portability

n/a

See Also

exit, suspend

void push_back( int  key,     [int front],   [int x],   [int y] )

Push back a character into the keyboard.

Description

The push_back() primitive pushes the specified key code key into the keyboard input buffer.

The front is zero or omitted the key shall pushed to the back of the keyboard buffer, otherwise to the front.

Parameters

Returns

nothing

Portability

Mouse support is a GriefEdit extension.

See Also

inq_kbd_char, key_to_int, read_char

void read_char( [int timeout = 0], [int mode = 0] )

Read next key from the keyboard.

Description

The read_char() primitive attempts to retrieve the next character from the keyboard.

The timeout argument specifies the handling of non key conditions, is other words when no keys are available.  If a positive value the timeout argument specifies the interval in milliseconds read_char() should block waiting for a key to become ready.  If the time limit expires before any key events read_char returns -1.  If omitted or zero read_char shall block unconditionally until a key is available.  A negative (-1) timeout shall not block returning immediately effectively polling the keyboard.

The mode parameter controls the type of keyboard event to be returned.  Supported modes are as follows.

Parameters

Returns

The read_char() primitive returns the key-code, otherwise -1 on a timeout.

Portability

Use of a ‘-’1 timeout value is required to emulate BRIEF.

See Also

int_to_key, inq_kbd_char, inq_kbd_flags

int remember( [string|int overwrite], [int macroid] )

Start remembering keystrokes.

Description

The remember() primitive control macro recording, starts remembering keystrokes, which can be later replayed with the playback function.

Recording is stopped by a second call to the remember macro.

The remember() primitive is not usually called as part of a macro but is usually bound to a keyboard key, for example (<F7>).

Unlike BRIEF multiple keystroke macros can be maintained.  Each remember execution shall create a buffer named KBD-MACRO-# where # is the associated keyboard macro identifier.  This buffer maybe then edited and/or saved for later use.  The inq_remember_buffer primitive shall derive the buffer name.

Parameters

Returns

The remember() primitive returns the positive identifier assigned to the keystroke macro on completion, 0 if the remember was cancelled, otherwise -1 on error or the recording began.

Portability

n/a

See Also

pause

int save_keystroke_macro( string  filename )

Save the current keystroke macro.

Description

The save_keystroke_macro() primitive saves the current remembered keystrokes macro to the specified file filename.

Parameters

Returns

The save_keystroke_macro() primitive returns greater than zero on success, otherwise -1 on error.

See Also

playback, remember

void set_kbd_name( string  name,   [int kbdid] )

Set the keyboard name.

Description

The set_kbd_name() primitive assigned the label name as the name of the keyboard kbdid, allowing primitives to assign a descriptive or meaningful definition to a keyboard.  These names or descriptions may then be utilised by macros.

Parameters

Returns

nothing

Portability

n/a

See Also

inq_kbd_name

int set_mouse_action( string  mouse_handler )

Set keyboard mouse handler.

Description

The set_mouse_button() primitive is reserved for future BRIEF compatibility.

The set_mouse_action() primitive sets the function mouse_handler as the mouse action handler within the current keyboard.

void
mouse_handler(
        int event,      // event code; see below
        int modifier,   // modifier keys
        int parm2,      // either line or scrollbar position
        int parm3       // either column or thumb position
        )
{
    switch(event) {
    case BTN1_MOVE:
        break;
    case BTN2_MOVE:
        break;
    case BTN3_MOVE:
        break;

    case BTN1_DOWN:
        break;
    case BTN2_DOWN:
        break;
    case BTN3_DOWN:
        break;

    case BTN1_UP:
        break;
    case BTN2_UP:
        break;
    case BTN3_UP:
        break;

    case BTN1_CLICK:
        break;
    case BTN2_CLICK:
        break;
    case BTN3_CLICK:
        break;

    case BTN1_DBLCLK:
        break;
    case BTN2_DBLCLK:
        break;
    case BTN3_DBLCLK:
        break;
    }
}

Parameters

Returns

Returns the previous mouse action.

Portability

n/a

See Also

inq_mouse_action, inq_keyboard

int set_mouse_type()

Sets the mouse type.

Description

The set_mouse_type() primitive sets the mouse type.

Parameters

Returns

none

Portability

n/a

See Also

inq_mouse_type

int undo( [int move], [int pastwrite = -1], [int redo = FALSE] )

Undo previous edit operations.

Description

The undo() primitive undoes buffer modifications on the current buffer.

Executing without arguments undoes the last operation performed on the buffer, including cursor movement, any text modification and marked region modification.  If the previous operation on the buffer was a macro, or a complex operation, e.g. global translate, then all the buffer modifications performed are undone in one step.

The move option limits the undo operation to the last buffer modification, restoring the cursor to the its location where the buffer was actually modified.

Each buffer maintains their own undo stack, unless disabled (See: set_buffer_flags).  Under BRIEF the undo stack for a particular buffer was cleared when the buffer is written to disk, as such it was not possible to undo any operations performed on the buffer before the last write_buffer.

Under GriefEdit the undo stack is retained for the duration of the editor lifetime.  If pastwrite is specified as positive value, the undo shall perform undo’s beyond the last write_buffer; by default the user is prompted as follows

Undo past saved file mark?

Parameters

Returns

The undo() primitive returns the number of operations undo; this is GriefEdit extension.

Portability

n/a

See Also

redo

int use_local_keyboard( int  kbdid )

Associate a keyboard with a buffer.

Description

The use_local_keyboard() primitive cause the current keyboard to be associated with the current buffer.

Parameters

Returns

The use_local_keyboard primitive return 0 on success otherwise -1 on error.

Portability

n/a

See Also

inq_local_keyboard, keyboard_pop, keyboard_push

$Id: $