Draw a Text Box screen object to create a way to input and/or output text, including multiple lines.

1. Open a screen for editing.
2. On the Graphics tab of the ribbon, in the Active Objects group, click Text Box. The mouse cursor changes to a crosshair for drawing.
3. Draw the object where you want it on the screen, and then further move or resize it if necessary.
4. Double-click the object. The Object Properties dialog box is displayed.
   Figure 1. Text Box object properties
   

   

5. In the Hint box, type a hint or tooltip that you want to have displayed during run time when the mouse hovers over the object.
6. In the Tag/Expression box, type the name of a project tag or an expression to associate it with the object.
   Tip: Click the browse button (…) on the right to use the Object Finder to form the tag/expression.

   A project tag can be used for either input or output. An expression can be used only for output.

   If you want to input or output multiple lines of text — that is, if you select Multi-line, which is described below — then type the name of a String array with an index of 0 (e.g., MyStringArray[0]). If you try to start at any other position, then you may see unexpected behavior during run time. For example, if you type MyStringArray[4], then the first line of the object will display index 4 of the array but the second line will start over at index 0.

   You should not use any other type of array (i.e., Boolean, Integer, or Real) with the Multi-line option.

7. In the Format list, select how the numerical value (if any) of the specified tag/expression will be formatted and displayed on-screen. Available options include Decimal, Hexadecimal, Binary and Auto. If you select Auto, then the value will be formatted according to the virtual table created by the SetDecimalPoints function. This option does not actually change the specified tag/expression in any way. For example, Tag/Expression is set to an Integer tag, Input Enabled is selected, and Format is set to Hexadecimal. You may input a new value in hexadecimal format, but it is saved in your project database as an integer.
8. By default, Input Enabled is selected. If you do not want to allow input, clear this option.
9. In the Mask/Count box, type a value that will restrict the input:
   • To mask a numerical value so that it matches a specific format, type one or more # characters. Each # represents one character of input/output. You can also combine # characters with regular text: $###.##
     It is important to remember that the project runtime will always display the most significant digits of a numerical value, regardless of the number or placement of # characters in the text. That means if you do not have sufficient # characters to display the value, then it will be transformed in some way depending on the format of the value (as set by the Format option described below):

     • In Decimal format, the number of decimal places is determined by the position of the decimal separator in the ### text. However, if you do not have enough # characters to the left of the decimal separator to display the whole value, then the whole value will overrun the fractional value. For example, if you try to display a value of 112.64 in #.##, you will see 112.
     • In Hexadecimal and Binary formats, if you have more # characters than you need to display the value, then the runtime project will fill in with leading zeroes. If you have less characters than you need, then the value will simply be truncated.
     • In Auto format, the runtime project will ignore the number of # characters and display the entire numeric or string value. Numeric values will be displayed in decimal format with their complete whole and fractional values, regardless of the placement of the decimal separator in the ### text. Given an exceptionally large value or long string, this may disrupt the layout of your screens.
   • To limit a string to specific character count, type a value between 0 and 1024. 1024 is the maximum limit because it is the maximum size of the String data type. If you enter more than 1024 characters, then the string will be truncated and the remaining characters will be discarded.

     Please note that this character count limit is per line, so if you configure the object to have multiple lines (i.e., if you select Multi-line) and associate it with a String array, then each line of text / array element may be up to the limit.

10. In the Minimum Value and Maximum Value fields, type the minimum and maximum numerical values (if any) that will be accepted from the user. This is optional.
11. In the Disable box, type the name of project tag or an expression. This is optional. When the value of the tag/expression is TRUE (1), the object is disabled.
12. To make the object accept/display multiple lines of text, select Multi-line . When Multi-line is selected, the Scroll Bar and Word Wrap options also become available and the Password option becomes unavailable.
13. To make the object obfuscate text input (e.g., ********), select Password.