Class lwk

Object
   |
   +--lwk

class lwk

Defines the most important keyboard and menu functions. These are mainly drivers to low level routines, or "lwk macros" calling lower level lwk routines.

The following functions are local functions for block oriented mainframe terminal families IBM 3270, IBM 5250 and FSC 9750. Only some of them are supported or emulated for character based Unix terminals as well:

• Basic functions
  • hideSelect() - supported as local function for Unix terminals as well
  • incrChar()
  • incrField()
  • incrSelect()
  • inputCheck()
  • hostLocked()
  • modifyScreen()
  • pos()
• Functions for inputting and inserting text
  • ignoreKey() - supported as local function for Unix terminals as well
  • inputCheck()
  • inputField() - supported as local function for Unix terminals as well
  • inputScreen()
  • insert()
  • paste() - supported as local function for Unix terminals as well
• Functions for deleting text
  • cut()
  • deleteBackspace()
  • deleteChar()
  • deleteField()
  • deleteFieldEnd()
  • deleteFields()
  • deleteSelection()
• Functions for sending the screen contents to the host system
  • send() - supported as local function for Unix terminals as well
• Functions for cursor movement by character
  • incrChar()
  • goCharDown()
  • goCharFirst()
  • goCharLast()
  • goCharLeft()
  • goCharRight()
  • goCharUp()
• Functions for cursor movement by word
  • goWordLeft()
  • goWordRight()
• Functions for cursor movement by field
  • incrField()
  • goFieldFirst()
  • goFieldLast()
  • goFieldLeft()
  • goFieldRight()
• Functions for cursor movement by line
  • goLineFirst()
  • goLineNext()
  • goLinePrev()
• Functions for creating text selections
  • incrSelect()
  • selectAll() - supported as local function for Unix terminals as well
  • selectCharDown()
  • selectCharFirst()
  • selectCharLast()
  • selectCharLeft()
  • selectCharRight()
  • selectCharUp()
  • selectField()
  • selectWord()
  • selectWordLeft()
  • selectWordRight()
• Functions on text selections
  • copy() - supported as local function for Unix terminals as well
  • cut()
  • hideSelect() - supported as local function for Unix terminals as well
  • deleteSelection()
• Functions for accessing the clipboard
  • copy() - supported as local function for Unix terminals as well
  • cut()
  • paste() - supported as local function for Unix terminals as well

• Mouse event functions
  • menuMouse()
  • posMouse()
  • selectMouse()
• GUI related functions are collected in lwk.gui
  • lwk.gui.admin()
  • lwk.gui.color()
  • lwk.gui.connectionMonitor()
  • lwk.gui.connectionTest()
  • lwk.gui.help()
  • lwk.gui.keyboard()
  • lwk.gui.keyboardLayout()
  • lwk.gui.macro()
  • lwk.gui.makeSessions()
  • lwk.gui.menu()
  • lwk.gui.showUrl()
  • lwk.gui.toolbar()
• Special functions
  • bean()
  • eval()
  • logLevel()
  • BEL()
  • message()
  • messageBEL()
  • wait()
• Deprecated functions
  • keyboard
  • inputChar()

• 2006-03-10 / optimize inputField
• 2006-03-12 / masked input string; paste
• 2007-02-27 / JF add goWord
• 2007-02-27 / JF add selection handling via lwh.select (no more browser selection)
• 2007-02-27 / JF add text selection via keyboard
• 2007-02-28 / JF rename lwk.inputChar to lwk.inputField
• 2007-02-28 / JF rename lwk.input to lwk.modifyScreen (common worker for lwk.inputScreen, lwk.deleteSelection)
• 2007-02-28 / JF add lwk.inputScreen as driver to lwk.modifyScreen
• 2007-03-05 / JF renamed lwKeyboardSettings() to lwk.keyboard()
• 2007-03-13 / JF added mouse event functions: menuMouse, posMouse
• 2007-05-10 / JF COPY/PASTE for VT
• 2007-05-12 / JF strict host mode for delete current char (9750) / insert 1 char (3270/5250); see lwh.Field.del/insert
• 2007-07-03 / JF paste option: "always block mode" (do not auto-detect)
• 2007-07-03 / JF handle host states "locked" and "error (5250 preHelp)"
• 2008-02-08 / JF lwk.bean(): general V3 menu bean
• 2008-04-09 / JF lwk.gui(): access V3 GUI parts

Field Detail

invalidChars

<static> {Array} invalidChars

The user supplied array of invalid characters for IBM 5250.

userkeys

<static> {Object} userkeys

The user supplied keyboard mapping table for IBM 5250. Contains key name and associated function (String).

lwk

lwk()

Defines the most important keyboard and menu functions.

Version:
• 2006-03-10 / optimize inputField
• 2006-03-12 / masked input string; paste
• 2007-02-27 / JF add goWord
• 2007-02-27 / JF add selection handling via lwh.select (no more browser selection)
• 2007-02-27 / JF add text selection via keyboard
• 2007-02-28 / JF rename lwk.inputChar to lwk.inputField
• 2007-02-28 / JF rename lwk.input to lwk.modifyScreen (common worker for lwk.inputScreen, lwk.deleteSelection)
• 2007-02-28 / JF add lwk.inputScreen as driver to lwk.modifyScreen
• 2007-03-05 / JF renamed lwKeyboardSettings() to lwk.keyboard()
• 2007-03-13 / JF added mouse event functions: menuMouse, posMouse
• 2007-05-10 / JF COPY/PASTE for VT
• 2007-05-12 / JF strict host mode for delete current char (9750) / insert 1 char (3270/5250); see lwh.Field.del/insert
• 2007-07-03 / JF paste option: "always block mode" (do not auto-detect)
• 2007-07-03 / JF handle host states "locked" and "error (5250 preHelp)"
• 2008-02-08 / JF lwk.bean(): general V3 menu bean
• 2008-04-09 / JF lwk.gui(): access V3 GUI parts


Author: j.fellner@logics.de

bean

<static> Object bean(nam, val)

Bean wrapper for the specified variable.
Supported as local function for Unix terminals as well.

Parameters:
String - ) nam required: the variable name (String!).
Object - ) val optional: the value to be assigned.

Returns:
the current value of the variable.

BEL

<static> void BEL()

Output BEL. Note: The file specified in lwk.BEL.file will be played, if any (and if supported by browser).
Supported as local function for Unix terminals as well.

copy

<static> void copy(<boolean> always)

Copies the currently selected text to the Clipboard.
supports VT: 2007-05-10/jf
• Does nothing if no selected text is available.
• Does nothing if selection is not visible (except: argument always is true))
• Does not cancel the selected text.
• Does not modify cursor position.
• For password fields, copies SPACES instead of the password.
• Supported as local function for Unix terminals as well.

Parameters:
always - : if true: copies invisible selection as well

See:
- cut()
- paste()

cut

<static> void cut()

Cuts currently selected text to Clipboard.

See:
- copy()
- deleteSelection()

deleteBackspace

<static> void deleteBackspace()

If possible: Deletes the previous char and positions back. Current Field must be input. Positions cursor back one character, then deletes this character. If already at start of field: goto end of previous field first (might be same field). Note: does not delete all selected chars (if any)

Version: 2006-11-14/JF: do no longer stop at start of current field

See:
- deleteChar()
- deleteChar()
- incrChar()
- inputCheck()
- incrField()
- pos()

deleteChar

<static> void deleteChar()

Deletes the current character, or the current selection. If no selection exists: Current Field must be input; cursor position is not modified.

See:
- deleteSelection()
- deleteBackspace()
- deleteField()
- inputCheck()

deleteField

<static> void deleteField()

Deletes all chars of the current Field starting with first char. Current Field must be input. Positions to first char of Field.

See:
- deleteFieldEnd()
- deleteFields()
- deleteChar()
- inputCheck()

deleteFieldEnd

<static> void deleteFieldEnd()

Deletes all chars from current position in field up to the end of field. Current Field must be input. Does not modify cursor position.

See:
- deleteFields()
- deleteField()
- deleteChar()
- inputCheck()

deleteFields

<static> void deleteFields()

Deletes all input Fields. Positions cursor to first char of first Field.

See:
- deleteField()
- deleteFieldEnd()
- deleteChar()

deleteSelection

<static> void deleteSelection()

Deletes contents of input fields contained in current selection.

See:
- cut()
- deleteField()
- deleteChar()

eval

<static> void eval()

Prompts for JS source and evaluates it. Alerts and logs the result. Saves last (correct) input value for next prompt.
Supported as local function for Unix terminals as well.

goCharDown

<static> void goCharDown()

Positions the cursor one char down. Depending on host, cursor may not reach protected fields.

See:
- incrChar()

goCharFirst

<static> void goCharFirst()

Positions the cursor to the first char of the current Field. Current Field must be input.

See:
- inputCheck()
- pos()

goCharLast

<static> void goCharLast()

Positions the cursor to the last char of the current field. Current Field must be input. Host NIL chars are not considered chars.

See:
- inputCheck()
- pos()

goCharLeft

<static> void goCharLeft()

Positions the cursor one char left. Depending on host, cursor may not reach protected fields.

See:
- incrChar()

goCharRight

<static> void goCharRight()

Positions the cursor one char right. Depending on host, cursor may not reach protected fields.

See:
- incrChar()

goCharUp

<static> void goCharUp()

Position the cursor one char up. Depending on host, cursor may not reach protected fields.

See:
- incrChar()

goFieldFirst

<static> void goFieldFirst()

Positions the cursor the start of the first input Field. If not exist: does not change cursor position.

See:
- pos()

goFieldLast

<static> void goFieldLast()

Positions the cursor the start of the last input Field. If not exist: does not change cursor position.

See:
- pos()

goFieldLeft

<static> void goFieldLeft()

Positions the cursor to the start of this or of the previous input field. If cursor is in input field and not at first position: positions to first char of this input field.

See:
- incrField()
- goCharFirst()

goFieldRight

<static> void goFieldRight()

Positions the cursor to the start of the next input field.

See:
- incrField()

goLineFirst

<static> void goLineFirst()

Positions the cursor to the start of the first input Field in current line. If there is no such input Field, the cursor position is not changed.

See:
- pos()

goLineNext

<static> void goLineNext()

Positions the cursor to the start of the first input Field below the current line. If there is no such input Field, positions to the first input Field in the screen.

See:
- pos()

goLinePrev

<static> void goLinePrev()

Positions the cursor to the start of the first input Field above the current line. If there is no such input Field, positions to the first input Field of the last line that contains at least one input Field.

See:
- pos()

goWordLeft

<static> void goWordLeft()

Positions the cursor one char left. Depending on host, cursor may not reach protected fields.

See:
- incrChar()

goWordRight

<static> void goWordRight()

Positions the cursor one word to right. Depending on host, cursor may not reach protected fields.

See:
- incrChar()

hideSelect

<static> void hideSelect()

Hides selected text, if any. Just in case: hides browser selection as well.
Supported as local function for Unix terminals as well.

See:
- copy()

hostLocked

<static> boolean hostLocked()

Checks if host status is locked. If host mode is error (5250 preHelp) or locked: shows message.

Returns:
true if host state is error (5250 preHelp) or locked

ignoreKey

<static> void ignoreKey()

Ignores this key.
Supported as local function for Unix terminals as well.

incrChar

<static> void incrChar(<int> row, <int> col)

Increments the current position by specified row and col values.
• Increments may be negative, 0, or positive.
• Position wraps rows and columns.
• Depending on host, cursor may not reach protected fields.
• Cancels selected text, if any.

Parameters:
row - the row increment
col - the column increment

See:
- incrField()
- pos()

incrField

<static> lwh.Field incrField(<int> incr)

Sets cursor to the start of the next/previous input field. Increment may be negative, 0, or positive. If no input field exists: positions the cursor to (0,0). Cancels selected text, if any.

Parameters:
incr - the field increment (negative, 0, positive)

Returns:
the new input Field

See:
- incrChar()
- pos()

incrSelect

<static> void incrSelect(<int> row, <int> col, <boolean> isBlock)

Worker: Selects text by specified row and col values.
• If no selection is visible: starts a new selection in specified mode from current position to specified end point
• If selection is already visible: extends current selection to specified end point and keeps selection mode (ignores specified mode).
• Select ending col number is exclusive.
• Increments may be negative, 0, or positive.
• Position wraps rows and columns.

Parameters:
row - the row increment
col - the column increment
isBlock - if true: starts a new block selection; else: starts a new lines selection. Evaluated only when a new selection is initiated (else: selection mode is not changed).

See:
- incrField()
- pos()

inputChar

<static> void inputChar(<char> str)

Enters the specified character(s) into the current input field.

Parameters:
str - the input character

Deprecated renamed to lwk.inputField()

See:
- inputField()

inputCheck

<static> lwh.Field inputCheck(<boolean> keep)

Checks if current field is input. Hides selected text, if any. If Current Field not input: alerts user.

Parameters:
keep - : if true, keeps the current selection (if any)

Returns:
the current field, or null if not input

inputField

<static> void inputField(<char> str)

Enters the specified character(s) into the current input field. This is an optimized version of lwk.inputScreen for fast keyboard entry (will be called from lwh.onkey keyboard input routine).
• Current Field must be input.
• Respects insert mode
  Single char input: respects strict host defined insert mode (consums NUL, checks "field full")
  Multi char input: relaxt "windows style" insert mode
• Respects host monocase, numeric
• Positions the cursor to next char
• At end of field, skips rest of input chars, and respects host autotab.
• Multi char input: Beyond end of field, does not process the rest of the specified String
• Emulated as "local function" for Unix terminals as well

Parameters:
str - the input character; relaxed mode for multi character input

See:
- insert()
- inputCheck()
- inputScreen()

inputScreen

<static> void inputScreen(<String> text, <boolean> masked, <boolean> nl, <boolean> block)

Enters the specified text starting at the current field. There are different modes, depending on arguments masked and nl:
• Not masked (default mode): enters text in input fields only.
  • Current Field must be input
  • Checks insert mode
  • Checks host Field attributes monocase, numeric
  • Positions the cursor to following char
  • At end of host Field, advances to next host InputField and continues
• Masked mode: Enters text in host InputFields while skipping text falling in host ProtectedFields.
  • For host ProtectedFields, skips the corresponding number of chars from text. Simply advances cursor in the host ProtectedFields.
  • For host InputFields, enters text chars like in unmasked mode.
    Checks insert mode, and host attributes monocase and numeric.
  • Positions the cursor to following char of host Field.
  • At end of host Field (input or protected), advances cursor to next host Field (input or protected) and continues.
• Not newline mode (default): Ignores NL ("newline") control characters in text.
  • Treats text as "character stream".
  • Simply enters specified text character by character.
  • Advances to next line depending on host Field position only.
• Newline mode: Requires NL ("newline") control characters in text to advance cursor to next line.
  • Treats text as "lines stream".
  • Skips all text characters beyond current line up to next NL control character.
  • Advances to next line only when a NL control character is detected in text.
  • Requires masked mode to work properly.
  • Automatically detects "block mode" or "lines mode" data entry.
    • Switches to block mode, if all text lines have same length. (last text line may be empty: "trailing NL").
    • In block mode: On NL control character, advances to next line at initial starting column position.
    • In lines mode (default): On NL control character, advances to next line at first column.
• Block mode input: Requires Newine mode and masked mode to work properly.
  • May be set explicitly, or auto-detect in newline mode
  • Skips all text characters beyond current line up to next NL control character.
  • Advances to next line at initial starting column position when a NL control character is detected in text.
  • On NL control character, advances to next line at initial starting column position.
• Control characters CR and TAB in text are always ignored. Control character NL is ignored, except for newline mode.

Parameters:
text - the input String
masked - if true, performs masked input
nl - if true, respects NL char, and auto-detects block mode.
block - if true, always forces block mode (requires nl as well)

See:
- paste()
- inputField()
- insert()
- inputCheck()
- incrField()
- modifyScreen()

insert

<static> boolean insert(<boolean_null> val)

Toggles or sets insert mode. Does not insert any specified characters.

Parameters:
val - optional: sets or resets insert mode; if null: toggles insert mode; if missing: returns current insert mode only.

Returns:
if true: insert mode is on

Version: 2007-02-28/jf toggle requires null; no param is getter

See:
- inputField()

logLevel

<static> int logLevel(<int> value)

int getter/setter for the lw logLeveL.
Supported as local function for Unix terminals as well.

Parameters:
value - optional: the new value; if missing: simply returns the current value

Returns:
the (new) current value

menuMouse

<static> void menuMouse(menu)

Shows context Menu at current mouse position. Mouse event function, usually assigned to ONCLICKRIGHT:
• Works for Unix terminals as well.
• Works for input or output fields.
• Hides selected text, if any.

Parameters:
optional - : menu the menu to show; default is emulation menu bar menu "lwh.menu.bar"

See:
- lw.Menu

message

<static> void message(<String> text)

Shows a user message to the user.
Supported as local function for Unix terminals as well.

Parameters:
text - the message text; if empty or null: clears the async message immediatelly

messageBEL

<static> void messageBEL()

Output host generated BEL. Note: Browsers so not always support BEL directly, so we show an additional message text as well.
Supported as local function for Unix terminals as well.

See:
- BEL()

paste

<static> void paste(<boolean> masked, <boolean> nl, <boolean> block)

Paste from Clipboard. Enters the clipboard text into the input field(s).
supports VT: 2007-05-10/jf
• Unix terminals, VT: sends all chars as data
• Mainframe only
  • If masked input is true: skips all character that fall into protected fields.
  • If nl is true: advances to next line only if NL char is detected in text; auto-detects block mode
  • if block is true: always forces block mode (on NL moves to soriginal starting column on next line; requires nl and masked as well)

Parameters:
masked - if true, performs masked input
nl - if true, respects NL char, and auto-detects block mode.
block - if true, always forces block mode (requires nl as well)

See:
- inputScreen()
- copy()
- cut()

pos

<static> void pos(<int_Field> row, <int> col)

Sets cursor to specified host position (row, col) or to host Field. Hides selected text, if any.

Parameters:
row - the host row number (0..lwh.host.rows-1); if 2nd argument col is missing: specifies the host field instead, or per index into lwh.host.fields[], or per host Field Object
col - optional: the host column number, 0..lwh.host.cols-1; if missing: 1st argument (row) specifies the field

posMouse

<static> void posMouse(<int> opt)

Mouse event function: Sets cursor to current mouse position.
• Works for Unix terminals as well.
• Works for input or output fields.
• Hides selected text, if any.

Parameters:
opt - optional, for VT only: 1 = use cursor upd/down (default), 2 = use tab/cbt

selectAll

<static> void selectAll()

Selects whole screen.
Supported as local function for Unix terminals as well.

See:
- selectField()

selectCharDown

<static> void selectCharDown(<boolean> isBlock)

Select text one row down.

Parameters:
isBlock - optional; if true: starts a new block selection; else: starts a new lines selection. Evaluated only when a new selection is initiated (else: selection mode is not changed).

selectCharFirst

<static> void selectCharFirst()

Select text up to first char. If start of selection: first char of field; else: first char of line.

selectCharLast

<static> void selectCharLast()

Select text up to (inclusive) last char. If start of selection: last char of field; else: last char of line.

selectCharLeft

<static> void selectCharLeft(<boolean> isBlock)

Select text one char to the left.

Parameters:
isBlock - optional; if true: starts a new block selection; else: starts a new lines selection. Evaluated only when a new selection is initiated (else: selection mode is not changed).

selectCharRight

<static> void selectCharRight(<boolean> isBlock)

Select text one char to the right.

Parameters:
isBlock - optional; if true: starts a new block selection; else: starts a new lines selection. Evaluated only when a new selection is initiated (else: selection mode is not changed).

selectCharUp

<static> void selectCharUp(<boolean> isBlock)

Select text one row up.

Parameters:
isBlock - optional; if true: starts a new block selection; else: starts a new lines selection. Evaluated only when a new selection is initiated (else: selection mode is not changed).

selectField

<static> void selectField()

Selects current host Field.

See:
- selectAll()

selectMouse

<static> void selectMouse(<boolean> isBlock)

Starts text selection via mouse dragging. Event processing function, must be called on mouse drag.
Supported as local function for Unix terminals as well.

Parameters:
isBlock - if true, selects a text block; else, selects lines of text

selectWord

<static> void selectWord(<boolean> isBack, <boolean> isBlock)

Worker: Selects text by word left or right. Selects up to next/previous word. Does not select beyond input field, except when current selection is already larger than input field.

Parameters:
isBack - if true, selects backwards (to the left), else: selects forewards (to the right).
isBlock - if true, starts a block selection; else: starts a line selection. Note: if selection is extended, isBlock is ignored.

See:
- selectWordLeft()
- selectWordRight()

selectWordLeft

<static> void selectWordLeft(isBlock)

Selects text up to (including) previous word left.

See:
- selectWord()

selectWordRight

<static> void selectWordRight(isBlock)

Selects text up to (excluding) next word right.

See:
- selectWord()

send

<static> void send(<String> hostkey)

transmits the current screen contents with the specified host function key. The name of the host function key depends on the host system. It must be enclosed in brackets < and >, e.g. <F1>.
Does not cancel the selected text (if any).
Supported as function for Unix terminals as well.

Parameters:
hostkey - the host function key.

wait

<static> void wait(<Function> fnc, <int> to)

on host response, calls specified function.
Supported as local function for Unix terminals as well.

Parameters:
fnc - required: the function to call
to - optional: the time to wait after receipt of (last) host response before calling fnc; if missing: 0 **NOT IMPLEMENTED**