XJTAG logo
Open search box button
Close search button

INPUTBOX

The INPUTBOX function prompts the user for input.

In XJRunner a modal dialog is displayed to collect the input.

Example message box in XJRunner

When multiple XJLinks are in use, XJRunner will direct the user's attention to any tab that is trying to display an input dialog box, but will not display the dialog until the tab is selected. The behaviour is very similar to the ALERT statement.

In XJRun a simple prompt is displayed:

Example message box in XJRunner

INPUTBOX was added in XJTAG v2.4.

Syntax

There are two forms of the INPUTBOX function, depending on whether it is used in an expression or whether it is used as a statement. The statement form has two return parameters: the string entered and a boolean value that indicates if the Cancel button was pressed. If the function is used in an expression, there is no second return parameter and so there is no explicit way of determining that Cancel was pressed; an empty string is returned in this case. If you need to distinguish between Cancel and an empty string being entered, then use the statement version.

INPUTBOX( STRING prompt, STRING title, STRING default [ , STRING imageFilename ])
INPUTBOX( STRING prompt, STRING title, STRING default [ , STRING imageFilename ])( STRING input, INT cancelled );

Parameters

prompt
The text to display as a prompt in the dialog box.
title
The text to display as the title of the dialog box.
default
The default text to put in the input box.
input
Returns the text that the user entered, or an empty string if the Cancel button was pressed.
cancelled
A boolean value indicating whether the input box was cancelled or not.
imageFilename

This parameter is optional.

The filename of an image which is to be displayed in the dialog. When running from an XJPack file, this will first look the in XJPack file for the image and then on file system. See how files are located for more information on how the path is resolved. If the parameter is omitted or is an empty string, then no image will be displayed. Supported file types are:

  • BMP
  • GIF
  • JPEG
  • PNG
  • TIFF

Note that if a relative path is used, then images may need to added as additional files when creating the XJPack file for them to be accessible when running from the XJPack file.

Return value

In the first case, when INPUTBOX is used in an expression, the function returns a STRING value containing the text that the user entered. If the user cancels the input, then an empty string is returned.

Example

// Used as an expression
STRING input;
input := INPUTBOX("Please enter a serial number:", "Serial Number", "");
IF input = "" THEN
  PRINT("No valid serial number entered\n");
ELSE
  PRINT("The serial number is ", input, "\n");
END;

// Used as a statement
STRING input;
INT cancelled;
INPUTBOX("Please enter a serial number:", "Serial Number", "")(input, cancelled);
IF cancelled THEN
  PRINT("The input box was cancelled\n");
ELSE
  PRINT("The serial number is ", input, "\n");
END;

See Also