Application Message Functions

The Application Message API lets you show messages, get user input, and select files in Automation1 Studio, Automation1 MachineApps, or a custom .NET application. These AeroScript functions run on the Automation1-iSMC (the Automation1 Intelligent Software-Based Machine Controller). But they are handled through a connected Automation1-MDK (the Automation1 Machine & Motion Development Kit) application, such as Automation1 Studio. Thus, you must connect Automation1 Studio or another application that registers for this callback to the controller before you use these functions.

Tip: By default, Automation1 Studio and Automation1 MachineApps try to register for Application Message and Application Frequency Response callbacks. The first application that registers will get the callbacks. The next application that tries to register will get an error. You can change the default behavior of Automation1 Studio in Settings. You can change the default behavior of a MachineApp in the MachineApps workspace in Automation1 Studio.

Message Notifications

Use the AppMessageDisplay() function to show a message. Each message shows a toast notification in the application toolbar. You can see all messages in the Notifications tab in the sidebar. Use the AppMessageDisplayDismiss() function to dismiss the messages from the sidebar.

You can show information, warning, or error notifications. If you do not specify the $severity argument to the AppMessageDisplay() function, you will show an information notification.

function AppMessageDisplay($message as string)

Displays the specified message.

Arguments

$message The message to display.

function AppMessageDisplay($message as string, $severity as MessageSeverity)

Displays the specified message with the given severity.

Arguments

$message The message to display.

$severity The severity of the message.

function AppMessageDisplayDismiss()

Clears all application message notifications.

function AppMessageDisplayDismiss($severity as MessageSeverity)

Clears all application message notifications with the given severity.

Arguments

$severity The severity of the messages to dismiss.

User Input

Message Box

Use the AppMessageBox() function to show a message and custom buttons in a message box. You can specify the title, the message, the number of buttons, and the text for each button. The function returns the index of the button that you click. If you click the ‘X’ in the title bar to cancel the message box, the return value is -1.

Use the $severity argument to show an information, warning, or error icon in the title bar of the message box. If the $takesFocus argument is 0, the message box shows in the Develop workspace. If the $takesFocus argument is 1, the message box shows in the active window.

function AppMessageBox($title as string, $message as string, $buttonNames[] as string, $severity as MessageSeverity, $takesFocus as integer) as integer

Displays a message box that shows the user information with a specified severity.

Arguments

$title The title to display for the message box.

$message The message to display for the message box.

$buttonNames An array of names to display on buttons in the message box.

$severity The severity of the message box.

$takesFocus Whether the message box takes focus.

Returns

The value of the button that was pressed.

Message Input

Use the AppMessageInputBox() function to show a message box that lets you enter an input value. You can specify the text for the title and the message that shows in the message box. You can also specify the default input value. When you press OK on the message box, the function returns the input value. When you click the ‘X’ in the title bar, the return value is always an empty string.

function AppMessageInputBox($title as string, $message as string, $defaultText as string, $severity as MessageSeverity, $takesFocus as integer) as string

Displays a message box that retrieves input data.

Arguments

$title The title of the message box.

$message The message to display for the message box.

$defaultText The input data that is shown by default.

$severity The severity of the message box.

$takesFocus Whether the message box takes focus.

Returns

The value of the input.

Message Menu

Use the AppMessageMenu() function to show a message box that lets you select from a list of items. You can specify the text for the title and the message that shows in the message box. You can also specify which item is selected by default. When you press OK on the message box, the function returns the index of the item you selected. When you click the ‘X’ in the title bar, the return value is always an empty string.

function AppMessageMenu($title as string, $message as string, $options[] as string, $defaultOption as integer, $severity as MessageSeverity, $takesFocus as integer) as integer

Displays a list of items that can be selected.

Arguments

$title The title of the message box.

$message The message to display for the message box.

$options An array of options to display.

$defaultOption The index of the option that is selected by default.

$severity The severity of the message box.

$takesFocus Whether the message box takes focus.

Returns

The value of the selected item.

File Selection

File Open

Use the AppMessageFileOpen() function to show the Open File dialog. This dialog lets you select the name of a file on the controller file system. The return value is the name of the file that you select. When you click the ‘X’ in the title bar, the return value is always an empty string.

You can specify the text for the dialog title. You can also specify a default directory and a default file. Use the ‘/’ separator to specify relative paths to a directory on the controller file system. Use the $filter argument to filter which file extensions show in the dialog. The filter string starts with the name of the filter followed by the ‘|’ separator and the filter pattern. You can also use the ‘|’ to separate multiple filter strings in the $filter argument. An example value for $filter argument is “Dat files|*.dat|Text files|*.txt”

If the $takesFocus argument is 0, the message box shows in the Develop workspace. If the $takesFocus argument is 1, the message box shows in the active window.

function AppMessageFileOpen($title as string, $directory as string, $defaultFile as string, $filter as string, $takesFocus as integer) as string

Displays a dialog box that is used to select a file to open.

Arguments

$title The title of the dialog box.

$directory The directory to show in the dialog box.

$defaultFile The default file to select.

$filter The file filter to use.

$takesFocus Whether the dialog box takes focus.

Returns

The full path of the selected file.

File Save

Use the AppMessageFileSave() function to show the Save File dialog. This dialog lets you select the name of a file on the controller file system. The return value is the name of the file that you select. When you click the ‘X’ in the title bar, the return value is always an empty string.

You can specify the text for the dialog title. You can also specify a default directory and a default file. Use the ‘/’ separator to specify relative paths to a directory on the controller file system. Use the $filter argument to filter which file extensions show in the dialog. The filter string starts with the name of the filter followed by the ‘|’ separator and the filter pattern. You can also use ‘|’ to separate more than one filter strings in the $filter argument. An example value for $filter argument is “Dat files|*.dat|Text files|*.txt”.

If the $takesFocus argument is 0, the message box shows in the Develop workspace. If the $takesFocus argument is 1, the message box shows in the active window.

See the File and Directory Functions topic for more information about working with files.

function AppMessageFileSave($title as string, $directory as string, $defaultFile as string, $filter as string, $takesFocus as integer) as string

Displays a dialog box that is used to select a file to save.

Arguments

$title The title of the dialog box.

$directory The directory to show in the dialog box.

$defaultFile The default file to select.

$filter The file filter to use.

$takesFocus Whether the dialog box takes focus.

Returns

The full path of the selected file.