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. But they are handled through a connected Automation1-MDK application, such as Automation1 Studio. Before you use these functions, you must connect Automation1 Studio or another application that registers for this callback to the controller.
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. Before you use these functions, you can use their related App*IsRegistered() functions to see if they are registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
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. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageDisplayIsRegistered() function.
Arguments
$message The message to display.
function AppMessageDisplay($message as string, $severity as MessageSeverity)
Displays the specified message with the given severity. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageDisplayIsRegistered() function.
Arguments
$message The message to display.
$severity The severity of the message.
enum MessageSeverity
| enum MessageSeverity
Information = 1 Warning = 2 Error = 3 end |
function AppMessageDisplayIsRegistered() as integer
Returns if the AppMessageDisplay() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
function AppMessageDisplayDismiss()
Clears all application message notifications. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageDisplayDismissIsRegistered() function.
function AppMessageDisplayDismiss($severity as MessageSeverity)
Clears all application message notifications with the given severity. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageDisplayDismissIsRegistered() function.
Arguments
$severity The severity of the messages to dismiss.
enum MessageSeverity
| enum MessageSeverity
Information = 1 Warning = 2 Error = 3 end |
function AppMessageDisplayDismissIsRegistered() as integer
Returns if the AppMessageDisplayDismiss() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
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. Before you use this function, you can use the AppMessageBoxIsRegistered() function to see if it is registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
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. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageBoxIsRegistered() function.
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.
enum MessageSeverity
| enum MessageSeverity
Information = 1 Warning = 2 Error = 3 end |
function AppMessageBoxIsRegistered() as integer
Returns if the AppMessageBox() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
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 click 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. Before you use this function, you can use the AppMessageInputBoxIsRegistered() function to see if it is registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
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 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. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageInputBoxIsRegistered() function.
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.
enum MessageSeverity
| enum MessageSeverity
Information = 1 Warning = 2 Error = 3 end |
function AppMessageInputBoxIsRegistered() as integer
Returns if the AppMessageInputBox() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
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 click 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. Before you use this function, you can use the AppMessageMenuIsRegistered() function to see if it is registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
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 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. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageMenuIsRegistered() function.
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.
enum MessageSeverity
| enum MessageSeverity
Information = 1 Warning = 2 Error = 3 end |
function AppMessageMenuIsRegistered() as integer
Returns if the AppMessageMenu() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
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. Before you use this function, you can use the AppMessageFileOpenIsRegistered() function to see if it is registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
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. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageFileOpenIsRegistered() function.
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.
function AppMessageFileOpenIsRegistered() as integer
Returns if the AppMessageFileOpen() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
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. Before you use this function, you can use the AppMessageFileSaveIsRegistered() function to see if it is registered with an Automation1 Studio, Automation1 MachineApps, or a custom .NET application.
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. This function must have a connected Automation1 Studio, Automation1 MachineApps, or a custom .NET application that registers to handle it. If there is not an application connected to your controller that can handle this function, an error will occur. If you need to do a check, call the AppMessageFileSaveIsRegistered() function.
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.
function AppMessageFileSaveIsRegistered() as integer
Returns if the AppMessageFileSave() function is registered by an application.
Returns
If the function is registered by an application, returns 1. Otherwise, returns 0.
