Where:

@(col,ln, wth,ht )	Position and size of the multi-line region. Numeric expressions. Column and line coordinates for top left corner, width in number of columns and height in number of lines. Note that width and height are for the total area (box plus text/description). Use line value -1 to display the check box on the tool bar.
alt_ctl	CTL value to generate when the list box gains focus.
contents$	Text / contents of the multi-line input field. String expression.
ctl_id	Unique logical identifier for multi-line input (any integer -32000 to +32000). Avoid integers that conflict with keyboard definitions (e.g., 4 cancels CTL=4 for the F4 key) or Negative CTL Definitions. Use this value with the apostrophe operator to access various Multi-Line Properties.
ctrlopt	Control options. Supported options for MULTI_LINE include: ERR=stmtref Error transfer FMT=mask$ For valid options, see Data Format Masks. FMT="!" can be used to indicate that the field should be displayed as blank if the value is 0 (zero); however, do not use FMT="!" if you wish to display a 0 (zero) being entered, or if the value being entered can have 0 as its integral component; e.g., - 0.99 or .12. FNT="font,size[,attr]" Font name, size, optional properties Refer to the 'FONT' Mnemonic for details. KEY=char$ Hot key LEN=num Maximum input characters. You can use the LEN= option in conjunction with the FMT= option to limit the number of characters allowed for a MULTI_LINE WRITE that violates the format mask. MNU=ctl CTL value associated with right-click menu event. MSG=text$ Message line OPT=char$ Single character parameter/option.See MULTI_LINE OPT= Settings. TBL=char$ Translation characters TIP=text$ Mouse pointer message. To change the colour, refer to the 'TC'= System Parameter.
mode$	String variable. ProvideX returns a single-character hex value in this variable to report the last method / keystroke the user chose to terminate the multi-line input field, e.g., $0D$for Enter as the EOM character for a 1-line multi-line input field, or $09$ for Tab to exit a multi-line input field.
stmtref	Program line number or statement label to which to transfer control.
var$	String variable to receive the text/contents of the multi-line input field.

MULTI_LINE OPT= Settings

The valid parameters for OPT=char$ are listed below:

"$"	Password entry displays dollar sign as substitute for each character entered.
">"	Include a horizontal scrollbar.
"!"	Support for Arabic characters (right to left entry).
"A"	Auto. Generates a CTL value signal for every character entered.
"B"	No border. The multi-line input region will not have a border.
"C"	Centre the input.
"d"	Permanently disabled.
"D"	Disabled. Multi-line region is is grayed out and is not accessible to the user.
"E"	Edit Mode. Append to end of existing text (default=Insert)
"F"	Full. Generate a signal upon maximum input length.
"h"	Permanently hidden.
"H"	Hide. Mult-line is not displayed but is accessible programmatically.
"i"	Disable Implied decimal point input for this control (overrides the '+I' mnemonic setting)
"I"	Activate Implied decimal point input for this control (overrides the '+I' mnemonic setting)
"L"	Lock. User can set focus, but cannot change the multi-line input region.
"R"	Right Justify.
"r"	Rich Text Editor. Multi-line provides Rich Text Editor capabilities (see Rich Text Editor below)
"s"	Scroll. Allows the multi-line input region to scroll in a resizable/scrollable dialogue box.
"t"	Supports the use of the Tab key in the multi-line input region.
"T"	Strips trailing spaces.
"U"	Upper case: converts lower case to upper case automatically.
"X"	Signal on exit. Generates a control when focus leaves the multi-line input region.
"Z"	Cursor changes to resize pointer if within 4 pixels from the edge of the control.
"^"	The mutli-line background will be transparent when the control is locked. This will allow background images and textures to bleed through. +PxPlus Exclusive (build 9200)

The Apostrophe Operator can be used with the unique logical identifier (ctl_id) to dynamically read and alter a wide variety of control attributes (properties) directly from the programming language. The list of properties available for manipulating a multi-line object are described in Control Object Properties,

When the AutoComplete feature is applied to a multi-line control, it will predict text as the user is entering it. When the control is accessed, users are prompted with the previously-entered words/phrases or entries already in a data file as soon as they start to type. This is a particularly useful tool for applications that require repetitive data entry. The AutoComplete feature will be disabled when MUTLI_LINE is used for a password field.

AutoComplete may be set up using the HLP= option as follows:

MULTI_LINE ctl_id, @(col,ln,wth,ht)),HLP="[AutoComplete]parameters$"

The paramater list (parameters$) can consist of any of the following options separated by semicolons:

AutoComplete$="DataFile=ProvideX.dat;Readonly=NO".

Existing parameters will not be reset unless they are set specifically when the AutoComplete$ property is set. If you need to reset all parameters in the list, set the AutoComplete$ property to a null string.

If the key is case sensitive, all lower case keys will be ignored.

Client-Server Behaviour (WindX/Javx)

In this scenario, the file used by the auto-complete logic to store and/or retrieve data must be on the client machine by default. If you wish to retrieve data from a rea-only fiile on the server, you must use additional program logic to accomplish this. First, set the AutoCTL property of the MULTI_LINE with a ctl_id to be generated when content is needed for loading values in the auto-complete dropbox. The final character of the list is used as the list item delimiter. Assign the list to the MULTI_LINE's AutoValue$ property. This will cause the dropbox to be loaded for selection.

It is also possible to create a list with tab-separated display/return value pairs that displays the first item of the pair in the drop box, but uses the second item to load the multi-line when selected.

For example, a list consisting of

"12345 - Barry's Bargain Bistro"+$09$+"12345"+$0A$+"12121 -ABC Company"+$09$+"12121"+$0A"

... would display the following:

12345 - Barry's Bargain Bistro
12121 - ABC Company

... but would load 12345 or 12121 into the multi-line depending on the selection

Calendar feature

The CALENDAR feature provides a user-friendly way to enter date information into a multi-line input area. When it is applied to a MULTI_LINE, a button will be added to the control that can be clicked to invoke a month calendar popup. This will allow users to pick a date to be inserted automatically into the multi-line input area.

The format of the date inserted is based on the formatting rules of the DTE( ) Function.

The CALENDAR feature may be set up using the HLP= option as follows:

MULTI_LINE ctl_id, @(col,ln,wth,ht)),HLP="[Calendar]parameters$"

The paramater list (parameters$) can consist of any of the following options separated by semicolons:

The ’Calendar$ property can also be used (with the above parameter list); e.g.,

ML_Ctl'Calendar$="CALENDAR=YES;DTE=%Y%M%D;Contents={!Stop}Stop;Width=10".

When invoked, the top left corner of the calendar button will be aligned with the top right corner of the multi-line input area. If parameters are not specified, the default button contents will be {!DATE} and the width and height of the button equal to the height of the control itself.

The following methods can be used to invoke the calendar:

• When the multi-line input area or the calendar button has focus, press Shift-F2 . In this case CTL=-6 is suppressed.
• When button control has focus, press SPACEBAR or ENTER.
• Use the mouse or touchpad to click on the calendar button.

The calendar will disappear automatically when:

• A date is selected and placed in the multi-line input area.
• An ESC is pressed.
• The user clicks anywhere outside the button or calendar.

When the button is clicked, no EOM value will be generated, as the button is considered part of the MULTI_LINE directive and is handled internally. When a date is inserted into the multi-line input area, no EOM value will be generated unless OPT="A" has been set and and focus is on the MUTLI_LINE control.

When the MULTI_LINE is hidden or disabled, the calendar button should also be hidden or disabled, and SHIFT-F2 will not display the calendar control.

Example:

The following code sample invokes the CALENDAR feature using both methods .. the HLP= string and the Calendar$ property.

0010 PRINT 'DIALOGUE'(0,0,100,50,"test",OPT="*Z")
0020 PRINT '4D','CS'
0030 LET A=1000
0040 MULTI_LINE A,@(10,10,30,1),HLP="[CALENDAR]CALENDAR=YES"
0050 LET B=1001
0060 MULTI_LINE B,@(10,20,30,1)
0070 LET B'CALENDAR$="CALENDAR=YES;DTE=%Y %Ml %D;Contents=Enter Date;Width=10"
0080 PRINT "A: ",A'CALENDAR$
0090 PRINT "B: ",B'CALENDAR$
0100 OBTAIN (0,SIZ=1)'ME',A$,'MN',; LET C=CTL; LET E$=HTA(EOM); PRINT "CTL=",C," EOM=",E$
0110 IF C=4 THEN ESCAPE
0120 GOTO 0100

MULTI_LINE ctl_id, @(col,ln,wth,ht)[,ctrlopt]

Use this format to define or create a multi-line input field. The FNT= option establishes the font for multi-line input. If you omit this option, ProvideX uses the "System" default font. If you specify FNT="*", standard text mode fixed font is used.

If you define a multi-line input field as occupying more than one line, ProvideX adds scrollbars and automatic word wrapping. If you define the input area as only one line high, the multi-line input region will not have a vertical scrollbar, but will scroll horizontally as required; e.g.,

0010 MULTI_LINE 100,@(2,14,12,6)
0020 MULTI_LINE WRITE 100,"Now is the time for all"
0030 OBTAIN *
0040 IF CTL=100 THEN MULTI_LINE READ 100,X$

This creates a multi-line input field that generates a CTL=100when its value changes and the user exits the multi-line input region.

MULTI_LINE REMOVE ctl_id[,ERR=stmtref]

This format to deletes a multi-line input field.

MULTI_LINE {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

Use the MULTI_LINE DISABLE format to gray out a multi-line input region so that it will be visible but inaccessible to users. To reactivate it, use MULTI_LINE ENABLE.

MULTI_LINE GOTO ctl_id[,ERR=stmtref]

Use the MULTI_LINE GOTO format to set the focus on the multi-line input field, ready for the user's next action.

MULTI_LINE READ ctl_id,var$[,mode$][,ERR=stmtref]

If the user enters more than one line of text, ProvideX will delimit each line, either using the system SEP character or the character you specify in the SEP= option of a directive. By default, multi-line input fields auto-wrap text, so the SEP character will only be returned on the READ if the user inserts a carriage return.

On the READ, the mode$ variable will identify the method use to end multi-line input. It will contain:

• $09$ for Tab used to exit or
• $0D$for Enter used to end a 1-line multi-line input field.

Once this value is read, it is reset to $00$.

Use the MULTI-LINE READ format to read the contents of the multi-line input field.

MULTI_LINE WRITE ctl_id,contents$[,ERR=stmtref]

When you write string expressions into the multi-line input, you must use a delimiter set by either the SEP= or the DLM= option.

MULTI_LINE SET_FOCUS ctl_id,ctl_val[,ERR=stmtref]

This format generates a CTL value whenever focus shifts to the multi-line input region.

MULTI_LINE AUTO ctl_id[,ERR=stmtref]

Use the MULTI_LINE AUTO format to generate a control automatically whenever there is a change.

MULTI_LINE {LOCK | UNLOCK} ctl_id[,ERR=stmtref]

Use the MULTI_LINE LOCK or UNLOCK formats to prevent or allow access to the multi-line input field. Use a LOCK to limit the user's permissions to "view only" for data such as notes and instructions.

MULTI_LINE {HIDE | SHOW} ctl_id[,ERR=stmtref]

With the MULTI_LINE HIDE format, the multi-line remains active, but is not displayed. It is still accessible programmatically. Use the SHOW format to restore the display and user access.