LINPUT +

This statement is an enhanced version of the LINPUT statement providing multiline entry, horizontal and vertical scrolling, word wrapping, and remote execution under Windows. The exact behaviour of the edit control is governed by a structure passed in the variable proplist$. This should be 64 bytes in length and initialised to HEX(00) and the appropriate entries filled in before the statement is executed. The first three fields do not have to be defined as they are set and returned by LINPUT+ to indicate how the LINPUT+ was terminated and how many characters were in the string retrieved from the edit control. Refer to the table below for a details of this structure.

When executed KCML will display the text using the specified attribute in the editable area defined by the width and depth properties. If the select on entry property is set on then all the text will be reversed to indicate selection. If the display only property is set on then it will return immediately leaving the text on the screen.

Editing follows Common User Access (CUA) rules popularised by all true Windows applications, not the rules used in console mode or original LINPUT statement. Note however that there is no overwrite mode.

If running under Microsoft Windows, either using KClient or the Windows DW terminal emulator, the mouse can be used to perform the tasks detailed below:

When editing is terminated by a function key (or HEX(0D) in the case of single line LINPUT+) then the first three fields are updated. Function keys '00 to '31, GL, Shift GL, TAB, SHIFT TAB are not used in editing and will terminate the LINPUT+. If a mouse is available, any attempt to click outside the editable area will also terminate the statement. The current text is redrawn in the original attribute if the attribute property is set to other than HEX(00).

In single line edit controls, depth zero or 1, then auto-horizontal scrolling is supported if the width field is less than the size of the alpha-receiver. If the width is zero then the size of the control will be set to the size of the alpha-receiver. If the width exceeds the size of the receiver then a X70 error occurs. RETURN or any non-editing function key will terminate the edit.

In multiline edit controls the text is formatted differently if the optional word wrap property is enabled. Without word wrap each line in the text, marked by a delimiter character which is specified in the delimiter property but which is normally HEX(0D), is put in a separate line of the control. With wrap the text is formatted to word wrap according to the control width with automatic vertical scrolling enabled if not all the text will fit in the depth available.

If the RemoteExec property is set while executing in Windows KCML or if using the WDW terminal emulator (version 3.00 or greater) then the editing will be delegated to Windows.

Horizontal and vertical scroll bars are optional for multiline controls and appear outside the defined area of the control. These can only be added if remotely executing under Windows.

When RETURN is pressed in a multiline control a delimiter character is embedded into the text at that point. When word wrap is enabled the control may break the text at the end of each row to fit the width but no record of this is embedded in the text. However it is possible to ask the control to mark the line ends when copying the text back to the alpha-receiver by setting the markrows property. Rows delimited this way can be separated into rows of an array variable for easy manipulation with $UNPACK e.g.

LOCAL DIM text$640, lines$(8)80
FLD(prop$.ed_delimiter)=HEX(0D)
FLD(prop$.ed_markrows)=1
LINPUT+text$,prop$
$UNPACK(D=HEX(010D))text$ to lines$()

The cursor state and the current attribute are preserved across a LINPUT+. If the interrupt key (Ctrl+BREAK) is pressed during a LINPUT+, there is no immediate effect until the LINPUT+ is terminated.

Properties marked IN should be set before the LINPUT+ and properties marked OUT are set by the LINPUT+ and can be inspected after it has terminated.

Bytes 21 and 25 store the index of the first visible character and the index of the current cursor character. This is information is useful if, for example, you need to trap a function key, insert some text at the current cursor position and re-enter the LINPUT + with the text scrolled to the same place. Generally they should be set to zero before the initial LINPUT+ and left unaltered if it is reexecuted.

Sample record:

DEFRECORD ed_linput
FLD ed_resultlen = "UINT(4)"                : REM Size of returned string. 
FLD ed_returnkey$1                          : REM Terminating key value e.g. HEX(0D) for return, HEX(7E) for TAB. 
FLD ed_returnpf = "UINT(1)"                 : REM Type of terminating key.
FLD ed_width = "UINT(1)"                    : REM Size of editable area.
FLD ed_depth = "UINT(1)"                    : REM Depth of the edit control.
FLD ed_attribute$1                          : REM Attribute to be used. 
FLD ed_color$1                              : REM Reserved. 
FLD ed_wordwrap = "UINT(1)"                 : REM Wordwrap.
FLD ed_vscrollbar = "UINT(1)"               : REM Vertical scrollbar.
FLD ed_hscrollbar = "UINT(1)"               : REM Horizontal scrollbar
FLD ed_delimiter$1                          : REM Character that ends paragraphs.
FLD ed_markrows = "UINT(1)"                 : REM End of line delimiter
FLD ed_displayonly = "UINT(1)"              : REM Display only
FLD ed_selectonentry = "UINT(1)"            : REM Select text on entry
FLD ed_remoteexec = "UINT(1)"               : REM Remote execution
FLD ed_paragraph$1                          : REM Paragraph symbol to use, HEX(00) for none.
FLD ed_passwd$1                             : REM Password character. If HEX(00) then display characters as entered.
FLD ed_startpos = "UINT(4)"
FLD ed_cursorpos = "UINT(4)"
FLD ed_arabic = "UINT(1)"                   : REM set to allow Arabic/Hebrew right to left style (R-to-L) input.
FLD ed_pg_term="UINT(1)"                    : REM set to 1 if PgUp and PgDown to terminate LINPUT +
END RECORD

Example:

The following example uses the above record and draws a 10x10 word wrapped edit box with a vertical scroll bar. In this example, the edit box is drawn by Windows therefore you must be using a Windows client. It uses the $UNPACK delimiter mode to break out the lines from the buffer into an array.

DIM text$640,line$(8)80,prop$_ed_linput

prop$ = ALL(HEX(00))

FLD(prop$.ed_delimiter$) = HEX(0D)

FLD(prop$.ed_markrows) = 1

FLD(prop$.ed_wordwrap) = 1

FLD(prop$.ed_width) = 10

FLD(prop$.ed_depth) = 10

FLD(prop$.ed_remoteexec) = 1

FLD(prop$.ed_vscrollbar) = 1

PRINT AT(10,10);

LINPUT+text$,prop$

$UNPACK(D=HEX(010D)) text$ TO line$()

See also:

INPUT,
LINPUT