The Prompt for Text statement is used to interact with a running action. The entered text will be saved in a track or named variable.
The supplied text strings may contain any of the escape sequences described in Escape Sequences. The prompt is a multi line scrolling area.
You can choose to pre-fill the text value with the contents of a specified field or named variable.
You can provide simple markup for the text specifying colours, bold and italic. The markup sequences are described in the Common Prompt Markup Functionality topic. Note that when using markup sequences the colour specified in the colour control is ignored.
You can elect to issue a beep with the prompt.
You can configure up to four buttons. See Configuring Buttons on Prompt Statements for more information. Which button was pressed can be determined from the Prompt Chosen Button named variable. The default button, if any, is effectively pressed if the Return key is pressed.
The statement supports additional configurability which is documented in Advanced Prompt Statement Functionality. These settings can be configured by clicking on the small button with the gear icon.
You can optionally display the step information. The step information displays the statement, the name of the file which was being processed and the name of the action and line number which contains the statement.
The statement can perform validation on the value entered by the user. If the specified requirements are not met, the panel will not be closed. Other configuration requirements can also be imposed. The requirements are specified in the named variable Prompt for Text Formatting. The format codes are documented in the Prompt Text Format Codes topic. Note that these codes can be configured when clicking on the button with the gear icon.
You can force the display of a picker button used to display a menu whose items can be inserted in the text field. The menu is defined in the Prompt for Text List named variable. The menu formatting is defined in the Prompt Menu Formatting topic.
At runtime when a button configured to be a Menu is hit the following holds:
When the panel is closed the Prompt Menu Item Reference named variable will be -1 if the panel was not closed by a menu item. If the panel is closed by a menu item, it will describe which menu item was selected. See the Prompt Menu Formatting topic for more information.
You can force the use of the picker menu by setting the R (Read only) format code. When this is set you will not be able to edit the text field directly.
When the text field is read only and a picker menu is displayed, the appropriate reference to the last selected picker menu item is stored to named variable Prompt for Text RO Menu Reference. If no picker menu item was selected the named variable will be empty. Depending as to how the selected menu item was configured, the value may be a duplicate of the value in Prompt Menu Item Reference. Note that menus associated with buttons do not change the value of this named variable.
How selected menu items get added to the text field is controlled by the R (Read only), X (Menu item insertion mode - Overwrite) and A (Menu item insertion mode - Insert/Append) format codes.
At runtime, you can switch to a multi line editor if there is a Multi Line Editor button displayed. You can also use the Multi line setting to immediately display a multi line editor at runtime. When the Multi line option is enabled, the following holds:
The prompt is only issued once per set of files when executed stepwise.
The statement is valid in all execution contexts.
Note: it is possible to design a Prompt for Text statement which cannot be closed due to the specified formatting requirements and the content of the picker control's menu. If this happens the Action Pending Window can always be cancelled via Yate>Cancel or the associated toolbar button. Whan batch processing, you can cancel the batch process to force the dismissal of the window.