Modula-2 || Compiler & Tools || Library || Search Engine

Ulm's Modula-2 Library:
EditWindow

NAME

SYNOPSIS

TYPE 
   FunctionKeyReaction =
      PROCEDURE (Window, VAR FunctionKey, VAR BOOLEAN);



CONST 
   LocalMoves = 
      FunctionKeySet {up,down,left,right,home,backspace};



(* editing *)
PROCEDURE EditWindow(win : Window; predefined : BOOLEAN;
                     VAR exitkey : FunctionKey );
PROCEDURE EnableLocalMoves (directions : FunctionKeySet);
PROCEDURE MapChar(char : CHAR; key : FunctionKey);
PROCEDURE DefineReaction(key : FunctionKey;
                         reactproc : FunctionKeyReaction);
PROCEDURE EnableSingleCharFK (recognize : BOOLEAN);
PROCEDURE CallOnce(proc : PROC);



(* other useful procedures *)
PROCEDURE ReadOneChar(win : Window; echo : BOOLEAN) : CHAR;
PROCEDURE Wait(w : Window);
PROCEDURE Beep();
PROCEDURE GetWindowLine(win : Window; line : CARDINAL;
                        VAR text : ARRAY OF CHAR;
                        clearleadingspace, clearfillupspace : BOOLEAN);



(* prototype procedures with type 'FunctionKeyReaction' *)
PROCEDURE Ignore (win : Window; VAR exitkey : FunctionKey;
                  VAR return : BOOLEAN);
PROCEDURE Return (win : Window; VAR exitkey : FunctionKey;
                  VAR return : BOOLEAN);
PROCEDURE Default (win : Window; VAR exitkey : FunctionKey;
                   VAR return : BOOLEAN);

DESCRIPTION

Any window win can be edited by EditWindow and no precondition concerning current window attributes and current cursor position are required. Initial attribute set and cursor position of win are restored after editing.

EditWindow supports three modes: escape, insert, and replace. Refer to section EDITING for description. Editing always starts at the upper left corner of win, any typeahead of input (before EditWindow was called) is ignored. If predefined is TRUE EditWindow displays the old contents of win and switches to mode escape. If predefined FALSE, win is cleared and insert becomes the starting mode.

EditWindow returns with exitkey set to nokey if either return is entered on the last window line or an explicit quit command is issued (see below). By default any function key will also finish editing. In this case the terminating key is assigned to exitkey (values to be imported from FunctionKeys). Arrows and home key on keyboard are made available for editing by EnableLocalMoves (directions should be a subset of LocalMoves). Single character function keys are not recognized by EditWindow unless EnableSingleCharFK was called before with recognize set to TRUE (default can be restored calling EnableSingleCharFK(\c FALSE)). When enabling single function keys, backspace must be defined as a local move, otherwise EditWindow will react rather unconventionally to backspace editing.

EditWindow has a large variety of applications, since the exit key returned can be interpreted as the result of editing which decides about what to do next (f.i. positioning within screen masks where single input field are represented as windows edited by means of EditWindow). MapChar, DefineReaction, and EnableLocalMoves extend the capabilities of this feature.

DefineReaction defines a procedure reactproc that is called by EditWindow whenever the function key key is read. During this call reactproc may update the currently edited window which is received as the first parameter. By means of the boolean VAR parameter set by reactproc, EditWindow decides whether to terminate editing or not. If reactproc yields TRUE EditWindow returns with exitkey set the value defined by reactproc for its second parameter.

Default, Return, and Ignore are prototype procedures of type FunctionKeyReaction. If used as arguments to DefineReaction, Return causes EditWindow to return with exitkey = nokey Ignore outputs a acoustic signal and continues editing and Default resets the default reaction for key.

MapChar allows mapping of any character char into a function key key. During subsequent calls of EditWindow input of char will have the same effect than key Thus, if function keys are needed for certain applications but not supported by input terminals, control characters can be defined instead.

Note that EditWindow will neither recognize function keys nor map characters during uncompleted editing commands in escape mode.

CallOnce defines a procedure proc that is called by EditWindow having read the first input character. proc is executed exactly one time. CallOnce does not affect more than one call of EditWindow.

Some more useful procedures independent from editing window are provided by this module as well.

GetWindowLine copies line line of window win into string text. Blanks before first or following last non space character on line are ignored if clearleadingspace respectively clearfillupspace equals TRUE. GetWindowLine will return an empty string, if illegal parameters are received or output does not fit into text.

Beep outputs an acoustic signal to the device associated with StdIO.stderr.

Wait suspends program execution until any key is hit (typeahead of input is ignored). win is used as an argument to Windows.WindowRead but remains unaffected.

ReadOneChar returns the first character read from the current cursor position of win (typeahead not recognized). If echo is TRUE input will be echoed. Initial window attributes and cursor position are restored.

EDITING COMMANDS

<CR>	carriage return (15C)
<LF>	line feed (12C)
<BS>	backspace (10C)
<ESC>	escape (33C)
<DEL>	delete (177C)
<SP>	a space/blank (40C)
{vis}	any visible character (40C-176C)

By default EditWindow follows UNIX-Conventions and reacts in the same way to <CR> and <LF>. Nevertheless both input keys are distinguished. This allows mapping of <LF> without altering the conventional behavior of the return key on the keyboard.

Insert Mode

{vis}

inserted at the current cursor position

<ESC>

switch to escape mode

<BS> <DEL>

erase character before current cursor position (restricted to characters inserted on current line since last switch to insert mode)

<CR> <LF>

break line at current cursor position and terminate editing if on last window line

Replace Mode

{vis}

replace character at the current cursor position

<ESC>

switch to escape mode

<BS> <DEL>

move left

<CR> <LF>

move to beginning of next line or terminate editing if on the last one

Escape Mode

i

switch to insert mode

I

move to first non space character on line and switch to insert mode

a

move right and switch to insert mode (append)

A

move beyond last non space character on line and switch to insert mode

o

insert an empty line after the current one and switch to insert mode

O

insert an empty line at the current one and switch to insert mode

R

switch to replace mode

r{vis}

replace character at current position by vis

J

join current line with the next one

h <BS> <DEL>

move left

l <SP>

move right

k --

move up (same column)

j +

move down (same column, editing is not terminated if on last line)

0

move to beginning of current line

^

move to first non space character of current line

$

move to last non space character of current line

G

move to last line

[1-9][0-9]+G

move to the specified line

w

move to next word begin (word is a sequence of non space characters)

e

move to next word end

b

move to last word begin

W E B

as lower case letters, but words are now coherent sequences of either alpha numeric or punctation characters

x

delete character at current cursor position

dd

delete current line

d0 d^ d$ dw dW de dE db dB

delete to the position specified by second character of command (deletion always restricted to current line)

<CR> <LF>

move to beginning of next line or terminate editing if on the last one

ZZ

terminate editing (exitkey = nokey)

Local Moves (if supported)

The following function keys are recognized by EditWindow only if they have been enabled by EnableLocalMoves before. None of them will switch the current editing mode.

up

move up (same column)

down

move down (same column, no termination on last line)

right

move right (same as <SP> in insert mode)

left backspace

as <BS> (reaction depends on current editing mode)

home

move to upper left corner of window

DIAGNOSTICS

SEE ALSO

AUTHOR

BUGS

Modula-2 || Compiler & Tools || Library || Search Engine