$ Functions: WebPages HMI

The HMI $ functions provide flexibility and additional functionality compared to using a tag and binding association, and are designed to interact with a project during deployed mode, via JavaScript code in a Button element's OnClicked script point, for example. WebPage Right-Click Menu eliminate the need to create a script on a UI control to call a single $ function.

The WebPages HMI $ functions are "static" HMI functions, and are used to programmatically interact with the entire WebPages infrastructure, versus being associated with a single element or WebPage.

Most of these functions are not asynchronous (that is, they are evaluated in the web browser not in the product), however, the functions associated with the WebPage (such as GetPageTitle, GetPageWidth, etc.) should be treated as though they are asynchronous to handle their return values.

Several functions return a Promise object because JavaScript is asynchronous, and callbacks (that is, Promises) must be used to use the returned value.

All functions act on a per web session basis. In other words, they don’t affect other web sessions, or the WPF HMI.

HMI.CloseDialogPage() : Void
Returns	Void
Arguments	N/A
Description	Closes the active dialog page.

$HMI.GetControlProperty(controlname,propertyname : String) : Any
Returns	Any
Arguments	controlname: String, specifying the name of the control element. propertyname: String, specifying the name of the property.
Description	Fetches the specified property of the specified control element. Note: Cognex recommends only using this function when an element does not have a published property tag. For a complete list of the published element property tags, see the WebPages Element Property Tags topic. Use this function to access an element property that is not published as a tag. All element properties (for Web Page User Input Controls, Graphics) can be accessed via the $HMI.SetControlProperty() and $HMI.GetControlProperty() functions. The properties of the elements are the same as those exposed in the Web Page Editor, minus the white space between the names (so instead of Border Color, it is BorderColor, for example).

$HMI.Login(username,password : String) : Void
Returns	Void
Arguments	username: String, specifying the name of the user used for login. password: String, specifying the password of the user used for login.
Description	Logs in to the HMI webpage with the specified username and password. Note: This function does not return whether the login and/or logout has been successful. To evaluate the result, use a Data Change Scripts (WebHMI) script referencing the CurrentUser tag.

$HMI.Logout() : Void
Returns	Void
Arguments	N/A
Description	Logs out of the HMI webpage. Note: This function does not return whether the login and/or logout has been successful. To evaluate the result, use a Data Change Scripts (WebHMI) script referencing the CurrentUser tag.

$HMI.SetControlProperty(controlName,propertyName : String, newValue : Integer, double, Boolean, String) : Boolean
Returns	Boolean
Arguments	controlName: String, specifying the name of the control element. propertyName: String, specifying the name of the property to set. newValue: Integer, double, boolean or string, specifying the new value of the property to set.
Description	Sets the property (specified with the propertyName argument) of the control element (specified with the controlName argument) to a new value (provided with the newValue argument). Note: Cognex recommends only using this function when an element does not have a published property tag. For a complete list of the published element property tags, see the WebPages Element Property Tags topic. Use this function to access an element property that is not published as a tag. All element properties (for Web Page User Input Controls, Graphics) can be accessed via the $HMI.SetControlProperty() and $HMI.GetControlProperty() functions. The properties of the elements are the same as those exposed in the Web Page Editor, minus the white space between the names (so instead of Border Color, it is BorderColor, for example). The function will return true if the property setting is successful, otherwise it will return false.

$HMI.SetFocusOn(controlName : String) : Void
Returns	Void
Arguments	controlName: String, specifying the name of the control element to focus.
Description	Sets the focus on the control element specified with the controlName argument. Note: This function should be used with a specific control element; the specified element will have focus when the function is called.

$HMI.ShowError(message,title : String) : Promise
Returns	Promise
Arguments	message: String, specifying the text of the error to show. title: String, specifying the title of the error to show.
Description	Shows the error specified with the message and title arguments.

$HMI.ShowInformation(message,title : String) : Promise
Returns	Promise
Arguments	message: String, specifying the text of the message to show. title: String, specifying the title of the message to show.
Description	Shows the information message specified with the message and title arguments.

$HMI.ShowLogin() : Boolean
Returns	Boolean
Arguments	N/A
Description	Shows the login process. Note: This function does not return whether the login and/or logout has been successful. To evaluate the result, use a Data Change Scripts (WebHMI) script referencing the CurrentUser tag.

$HMI.ShowMessage(message : String): Promise
Returns	Promise
Arguments	message: String, specifying the message to show.
Description	Shows the message specified with the message argument.

$HMI.ShowPage(pageName : String): Void
Returns	Void
Arguments	pageName: String, specifying the name of the web page to show.
Description	Shows the page specified with the pageName argument.

$HMI.ShowQuestion(message,title : String): Promise
Returns	Promise
Arguments	message: String, specifying the text of the question to show. title: String, specifying the title of the question to show.
Description	Shows the question specified with the message and title arguments.