text

Type: String

Availability: Read or write at any time for text box, edit mask, and rich text controls, read or write at run time only for tables, list boxes, and combo boxes with the style property set to 0 (dropdown) or 1 (simple), read or write at run time only for text edit controls that have the readOnly property set to true, read-only at run time for all other combo boxes, read or write at run time only for text editor controls

The text property contains the text in the edit area of ComboBox controls that have the style property set to Style_DropDown (0) or to Style_Simple (1), and the TextBox control. For other styles of the ComboBox control, this property returns the text of the selected item in the combo box list. The property is read-only in this context.

The text property of the JadeRichText control contains the text in the control in plain text format.

In the JadeEditMask and TextBox classes, this property can be translated when the value of the Schema class formsManagement property is FormsMngmt_Single_Multi (2).

For a ListBox control, this property contains the text of the selected item in the list box. This property is equivalent to accessing the itemText property with an index of listIndex. Changing the text of an item in the list box can change its position because of sorting. When the text of an item is altered from the text property, the newIndex method can be used to obtain its new index value.

For the Table control, the property accesses the current cell on the current sheet. The current cell is defined by the row and column properties. The code fragment in the following example uses concatenation with the Tab character to store text in cells to the right of the specified cell.

// Set up the column headings
table.row := 1;
table.column := 1;
table.text := "Name" & Tab & "Address" & Tab & "Phone";

For a TextBox or a ComboBox control that has the style property set to Style_DropDown (0) or to Style_Simple (1), this property returns the text contained in the edit area of the control.

A numeric text box expects the numeric string to be formatted according to the locale under which the user application is running. Setting the TextBox control text property validates the numeric value on the basis of that locale definition format. Retrieving the text returns the same string (that is, no locale conversion is performed).

For a ListBox control or a combo box control with other settings of the style property, you can use the text property to obtain the text of the currently selected item. For a list box, if no entry is selected (listIndex = -1), a null string ("") is returned.

The text property of the JadeEditMask class contains the concatenated text of the text box fields of the control, including any literal text. When setting the text value of the control, that text must be valid according to the mask property rules. Any prompt characters contained in the text are not treated as prompt characters.

Accessing the text property value returns a value consisting of the concatenated text of each of the text box fields, with each prompt character replaced by a space. For example, the text 21/10/2001 returns '21/10/2001' and the text 21/__/__ returns '21/ / '. Setting the text of the control to the returned value is always accepted. Setting the text to null ("") clears all characters that can be entered, leaving only any literals in the text and the prompt characters.

As dates are in locale order and abbreviated months are in locale format, you must convert them by using locale-aware routines. (For details, see "Date Type", in Chapter 1 of the JADE Encyclopaedia of Primitive Types, and "Converting Primitive Types", in Chapter 1 of the JADE Developer’s Reference.) Similarly, locale-equivalent characters are expected and returned for decimal places, thousand separators, negative signs, currency symbols, date delimiters, and time delimiters. Conversion must therefore use locale-aware routines.

Setting the text value with text that has a length less than the expected field length pads that text with an empty version of the expected text field. For example, setting a date field of dd/MM/yyyy to '21' results in the displayed text field of 21/__/____.

The text property of the JadeTextEdit control can be set when the readOnly property of the JadeTextEdit control is set to true. When the text property is set, the undo buffer is cleared and the modified property is set to false. No end-of-line conversion is performed when the text is set or retrieved. You can call the convertEndOfLines method to force all line endings to a required value.

The following example shows the use of the text property.

userNotify(eventType: Integer;
           theObject: Object;
           eventTag:  Integer;
           userInfo:  Any) updating;
begin
    // The userNotify method is executed when a notification that was
    // registered for a user event is received.  The notification is
    // identified using the eventType parameter and an appropriate
    // message is displayed in a text box.
    if eventType = 16 then
        textBox2.text := "User Class Notification Received";
        textBox7.text := userInfo.String;
    elseif eventType = 17 then
        textBox4.text := "User Notification Received";
        textBox8.text := userInfo.String;
    endif;
end;