MULTI_LINE Create/Control Multi-Line Input

Property

Description

Auto

When set, the control will generate a 'Change' event whenever its value changes as opposed to the default Off state where the control will only generate the change event when losing focus.

Possible values are:

AutoComplete$

Controls the automatic completion of user entries: For parameters, see Auto Complete as described in the MULTI_LINE directive.

AutoCtl

Ctl_id to be generated by a multi-line to signal that the list of entries for the Auto Complete drop box is to be loaded via the AutoValue$ property.

AutoValue$

List of entries to load into Auto Complete drop box. See AutoCtl property.

BackColor$
BackColour$

Background color. When a multi-line control is disabled, it retains the background color that has been set instead of showing the standard disabled color.

For information on valid color names and color specifications, see Color Properties. (Default: "DEFAULT")

Border

Add border: 1 - Border; 0 - No border (Default: 1)

Note:
Applicable only when using Windows XP or Windows 7 style controls.

BringToTop

This property, when set to any value, will cause the control to be moved to the top of the display order. Once at the top of the display order, the control will appear visually on top of any other control on the window. (Default: Not Applicable - Always returns 0)

Calendar$

Invoke month calendar control. For parameters, see Calendar Feature as described in the MULTI_LINE directive.

Col

Screen position (column) of control.

Cols

Width of control in column units.

CtlName$

Control type ("MULTI_LINE"). See MULTI_LINE directive.

DisableBackColor$
DisableBackColour$

Background color when the control is disabled. For information on valid color names and color specifications, see Color Properties.

(Multi-Line support was added in PxPlus 2019.)

DisableTextColor$

Foreground text color when the control is disabled. For information on valid color names and color specifications, see Color Properties.

(Multi-Line support was added in PxPlus 2019.)

Enabled

Enabled indicator: 1 = True; 0 = False (Default: 1)

Encrypt$

The 'Encrypt$ property for multi-lines can be set on fields that are to be kept confidential by the user (such as a password) and that the system only needs to verify that the user has entered the same value as opposed to knowing what the user entered. When the 'Encrypt$ property is set, the control will return the SHA1 hash key of the value set in 'Encrypt$ followed by the value in the field. This is an industry standard hashing algorithm that is generally acceptable for security purposes.

Example:

If the input field contains the value "MyPassword", then setting the 'Encrypt$ property to "Hide the Password:" -- When you read the field, it will return the value of HSH ("Hide the Password:MyPassword",-1), which is its SHA1 value. This is a one-way encrypt into a 40 byte (20 Hex characters or 160 bit) value -- see http://en.wikipedia.org/wiki/SHA-1.

Note:
When the Encrypt$ property is set, you cannot load a value into the multi-line; you can only clear it. Any attempt to set a value in the multi-line is ignored (since a write back would be trying to write back the SHA1 value).

This feature allows the system to store a user input such as a password and validate against the SHA1 of a prior entry without ever knowing what the password is. For increased security, you cannot read back the 'Encrypt property. If you do read, this property will return the following string:

     D:n,L:n,U:n,S:n

Where:

Each of the 'n' values indicates the number of Digits, Lowercase, Uppercase and Special characters in the field. This can be used to determine general password characteristics so the developer can impose restrictions on the password such as must be > 6 characters, contain a number and at least one special character.

'SelectText$ will be disabled while 'Encrypt$ has a value, and this property is only valid on regular multi-lines -- not Rich Text multi-lines. Once set, this will allow for secure interaction for password fields with a WindX connection without having to resort to using SSL for communications.

EnterMode

This property is used to define how the ENTER key will be processed with the control. For the multi-line, the EnterMode property defines whether the ENTER key is to be allowed within the control or considered a TAB to exit the control.

When 0 (zero), it indicates that the ENTER key will not be considered as a TAB; thus, depending on the type of multi-line, it will signal the input complete for a 1-line field or insert a line feed on a control with multiple input lines.

(Default for Multi-line: The default setting reflects the '+E' mnemonic setting.)

Eom$

Last change terminator. See also MULTI_LINE directive.

Fmt$

Control format definition. Refer to the FMT= option as described in the MULTI_LINE directive.

Focus

Focus indicator: 1 = Control has focus (Default: 0)

FocusBackColor$
FocusBackColour$

Background color when the control has focus. For information on valid color names and color specifications, see Color Properties.

(Multi-Line support was added in PxPlus 2018.)

FocusTextColor$
FocusTextColour$

Foreground text color when the control has focus. For information on valid color names and color specifications, see Color Properties.

(Multi-Line support was added in PxPlus 2018.)

Font$

This property is used to reference the font for a control. It will contain (or can be set to) a string containing three comma-separated fields of the font name, size and attributes. See 'FONT' mnemonic.

Example:

To set the font to Arial, 1.5 times normal size, and Bold, the format would be xxx'Font$="Arial,1.5,B".

Height

Height of control in pixels.

hWnd

Windows handle for control.

ImpliedDecimal

Controls implied decimal input.

Key$

Hot key to jump to control.

Left

Left margin for control in pixels.

Len

Input length of line.

Line

Screen position of control.

Lines

Height of control in number of lines.

Lock

Lock status: Possible values are:

(The Lock status of 2 was added in PxPlus 2019.)

LookAndFeel

Defines how a control will look. Possible values are:

MenuCtl

This property reports/sets the CTL value to generate when an object is selected on a right-click of the mouse.

Msg$

Message line text for the control.

Nul$

String text to display when the value of the multi-line field is empty. If a numeric format string has been assigned, then the text is displayed when the value is 0 (zero).

ObjectID

User object method. (Default: 0 - No object specified)

The 'ObjectID property allows applications to intercept property values and add methods to controls. When set to a valid ObjectID by the application, you can add methods and add/override property logic for any control in the system. When set in the system, it allows the application to logically request methods against the control that, in turn, will be performed by the related Object ID. It will also first check the object for any property requests and, if the property is defined in the object, set or get that property instead of the controls.

To allow the specified object to get true access to the control, while executing within the object identified by the 'ObjectID property, the system will direct any property requests directly to the control.

Note:
When a control is deleted from the system, any object identified by an 'ObjectID property will be automatically dropped.

OnDoubleClick

This multi-line property controls the generation of a CTL event when the control is double clicked. The value is ignored if the control is disabled, but will be generated if the control is locked.

It can be set to a non-zero CTL value, which will be generated if the user double clicks the control.

(The OnDoubleClick property was added in PxPlus 2022 Update 1.)

OnFocusCols

On focus, resize columns: Returns to defined size when focus leaves. Assign 0 to reset.

OnFocusCtl

On Focus CTL event: 0 is returned if no On Focus CTL value is set up for the control.

OnFocusLines

On focus, resize lines: Returns to defined size when focus leaves. Assign 0 to reset.

OnTipCtl

This property controls the CTL event that will be fired prior to the system displaying the Tip for any control. If the value of this property is non-zero, the system will use its value of a CTL event to fire and will defer the display of the tip until the application changes the value in 'Tip$. If the value in 'Tip$ is not changed, no tip will be displayed.

Setting this to zero (Default) disables the event from being sent and the current 'Tip$ will be displayed.

Parent

Parent window handle.

Password

Password mask data.

If this property is set to 1, the multi-line will have its contents replaced with the PxPlus defined password character (default $). Setting this property to 0 (zero) removes the masking.

(Read/Write support for the Password property was added in PxPlus 2023.)

PasteFilter

Strip non-printing characters from pasted data. When this property is set to On, the filter strips leading/trailing non-printing characters, such as line feeds or tabs, from data that is copied/pasted into a multi-line control and replaces any internal sequence of non-printing characters with a single space. (Default: 1 (On), except for multi-lines that are >1 line high and accept multiple lines of input, which default to 0 (Off))

Example:

Data that is copied as …

123 Main Street
Markham
Ontario

… will be pasted as:

123 Main Street Markham Ontario

The Clipboard will reflect the actual data pasted in case the user wants to paste the data elsewhere.

(The PasteFilter property was added in PxPlus 2020 Update 1.)

PriorValue$

This property contains the value last returned when the multi-line was read.

(The PriorValue$ property was added in PxPlus 2018.)

QryButton

Contains the CTL value for a query button that is to be placed within an input multi-line control. Button position, size and visibility are controlled by the multi-line. Transparency fills the button with multi-line background color.

Scroll

Set scrollbar types. Possible values are:

ScrollWheel

Set scroll wheel increment. This property is used to define how many lines each click of the scroll wheel will move a list box or grid.

Possible values are:

SelectLength

Length of selected item: This reports the number of characters currently highlighted. This allows for cut, copy and paste within a GUI input region.

SelectOffset

This property indicates where the highlight begins within the data or, if nothing is highlighted, the current cursor location. This allows for cut, copy and paste within a GUI input region.

SelectText$

Text contained within the highlight: This allows for cut, copy and paste within a GUI input region. See Multiple Selections.

Sep$

Separator character between each field, column or data point.

SepLoad$

Separator character for each row or data set.

SignalOnExit

Controls whether a 'Change' signal will be generated when the control (or region of a grid control) is exited regardless of whether the control's value changes. Normally, controls only signal changes when the control loses focus and the contents have changed. Setting 'SignalOnExit allows a change signal to also be generated whenever focus leaves the control (or region for grid).

SpellCheck

Enable spell checking. For a multi-line and grid cell, set this property to non-zero to enable spell checking on the input field. Reading this property will determine whether spell checking is enabled. (Default: 0)

(The SpellCheck property was added in PxPlus 2019.)

TextColor$
TextColour$

Foreground text color. For information on valid color names and color specifications, see Color Properties. (Default: "DEFAULT")

Tip$

Tip message for control.

Top

Top of control in pixels.

Uppercase

Force text to uppercase: 1 = On; 0 = Off (Default: 0)

Value$

Current item value.

ValueNoSignal$

Change control's value without generating OnChange event: Same as 'Value$; however, when used to change the value in the control, no OnChange event will occur.

Normally, on list style or input controls which have Signal All Changes enabled, changing the control value under either program control or by user input will generate an OnChange event. Changing the value of a control using the ValueNoSignal$ property allows the control's value to change without generating the OnChange event.

Visible

Control visible flag: 1 = Yes; 0 = No (Default: 1)

Width

Width of control in pixels.

_PropList$

Controls the list of properties to be returned in '_PropValues$. Each value is separated by the value in '_PropSep$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.

_PropSep$

Controls the separator used between each of the values of the properties returned in '_PropValues$ as defined by '_PropList$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.

_PropValues$

Accesses the values of the properties defined in '_PropList$. Each value is separated by the value in '_PropSep$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.