Macro Events

> Macro Events

Macro Events

A Macro represents a series of commands that are processed sequentially.

Events in SYSPRO are triggers embedded within programs that fire when the program performs a specific task (e.g. refreshing a form). When these events fire they run the macro that is linked to the event (i.e. macro events).

Events are associated with every form, data grid, listview, and customized pane within SYSPRO. In addition, every field on a form has its own list of events (e.g. a field on a form can be assigned text for a menu option. Once this is available - enabled programmatically using script - the menu option is available via the SmartLink Information icon).

In SYSPRO, macros are typically written using VBScript and each program component can have its own VBScript file which contains functions.

The content and behavior of objects in a customized pane is controlled via VBScript using various events.

These events are displayed when you load the Admin VBScript Editor program. Only the events associated with the current field, form or object you selected are displayed.

To create an event against a form, right-click any caption within the form and select Macro.

To create an event against a specific field, right-click the field and select Macro.

FORM Events

Event	Description
OnLoad	This event is invoked only once per run of the program - after the program loads the form and populates it with data. An `OnLoad` event is typically used to invoke things that must remain for the whole run of the program, or to set an initial state. For example, if a field on the form needs a button, the definition of this button would appear against this event. Or, if the initial state of a field on an entry form must be read only, this would be set against this event.
OnRefresh	This event is invoked each time the contents of the whole form needs to be refreshed. The first time a form is used the `OnLoad` event is invoked followed immediately by the `OnRefresh` event. This event is typically used to change the state of a field, or cause a change on another form, when the form refreshes. For example if you wanted to change the background color of a field to highlight that its value has fallen outside of a target range.
OnStartEdit	This event is invoked as you start editing the first field on a form, or when the cursor is placed on the form, for the first time. This is considered a legacy event provided for backward-compatibility and should be used sparingly (check that it fires at the appropriate times under all circumstances).
OnStopEdit	This event is invoked after you have finished editing the fields on the form. The exact point at which the event is invoked is program-specific. This is considered a legacy event provided for backward-compatibility and should be used sparingly (check that it fires at the appropriate times under all circumstances).
OnSubmit	This event is only available for an entry form and is invoked each time the form data is saved (i.e. when the operator attempts to save the data entered, like when a sales order is successfully ended). This event can be used to validate data (e.g. to ensure that all the required data was entered on the form).
OnAfterSubmit	This event has limited application in the software (e.g. from the Stocked line pane of the SO Entry program). Whereas the `OnSubmit` event is invoked while the entered data is still displayed on the form and before the data is saved on the server, the `OnAfterSubmit` event is invoked after the data is saved on the server, but before the form is cleared. The sequence of events is as follows: The `OnSubmit` event is invoked. A check is performed to ensure all custom form fields are valid The business logic verifies the validity of the fields. The data is saved. The `OnAfterSubmit` event is invoked. The form is cleared.

FIELD Events

Event	Description
OnMenuSelect	This event requires a menu to be defined for the field first. This is normally defined against the form's `OnLoad` or `OnRefresh` functions. Once defined, the menu becomes available when you select the Smartlink Information icon against the field. This event is invoked when you select the displayed menu item.
OnGainFocus	This event is invoked when focus is set on the value portion of the specified field. This is invoked each time that focus is gained/set (i.e. after it has been lost and regained).
OnLostFocus	This event is invoked when focus was set on the field and the operator clicks somewhere else (e.g. on the caption portion of the field) on another field on the form, on another form on the window or even another window altogether. It is possible that a change to a value may be overwritten by data returned by the call to the server.
OnBeforeChange	This event is invoked when the operator changes the value of a field and moves off the field (i.e. before the data has been committed). This allows a script to validate that the entered value is acceptable and prevents data from being changed if it does not match this requirement. This event is invoked before the `OnLostFocus` event.
OnAfterChange	This event is invoked after the data has been changed in memory. It is invoked after the `OnLostFocus` event. It is possible that a change to a value may be overwritten by data returned by the call to the server. This event only applies when the change is done by the operator and not when it is triggered by the system. For example, if Job complete is triggered by the system when an operator enters the quantity outstanding on the job, the system automatically ticks the job complete which does not trigger the VBScript.
OnButtonClick	This event is only available if you created a button for the field on the form. The event is invoked when the button is selected. This does not relate to a browse button which appears automatically against a key field or a browse button added to a form.
OnLinkClicked	This event is invoked when you select a predefined hyperlink on an entry form. This event relates to fields that are hyperlinked automatically by the program and is not available on display form types.

Global Login Logout VBScript

Event Description

OnLogin

Event	Description
OnLogin	The OnLogin event fires just as you complete the login process, but before the main menu is loaded. Therefore this is executed before any customized panes or any other windows appear, giving you an opportunity to create a script to check settings or mapped drives before SYSPRO fully loads. If these checks fail, the operator can be prevented from logging in by setting: `MainMenu_OnLogin = False` For example, the following script for the `OnLogin` event checks if you are accessing company 0 and, if true, then SYSPRO will exit: Function MainMenu_OnLogin() if SystemVariables.CodeObject.Company = "0" then Msgbox "You are not permitted to login to this company",0, "Access Denied" MainMenu_OnLogin = False exit function end if End Function Setting the `MainMenu_OnLogin` variable to `False` logs the operator out. And as they have not completed the login process, the `MainMenu_OnLogout` event does not fire.
OnLogout	This event is invoked either when the operator logs out of SYSPRO or when the operator changes SYSPRO company. Although most of the System Variables are available at this point, you cannot use ones such as `SYSPROProgramToRun` as it will not load the program. If you wanted to keep an external copy of who logged in/out you would probably implement the logout part here.

The OnLogin event fires just as you complete the login process, but before the main menu is loaded.

Therefore this is executed before any customized panes or any other windows appear, giving you an opportunity to create a script to check settings or mapped drives before SYSPRO fully loads.

If these checks fail, the operator can be prevented from logging in by setting:

MainMenu_OnLogin = False

For example, the following script for the OnLogin event checks if you are accessing company 0 and, if true, then SYSPRO will exit:

Function MainMenu_OnLogin()
if SystemVariables.CodeObject.Company = "0" 
then Msgbox "You are not permitted to login to this company",0, "Access Denied" 
MainMenu_OnLogin = False 
exit function 
end if 
End Function

Setting the MainMenu_OnLogin variable to False logs the operator out. And as they have not completed the login process, the MainMenu_OnLogout event does not fire.

OnLogout

This event is invoked either when the operator logs out of SYSPRO or when the operator changes SYSPRO company.

Although most of the System Variables are available at this point, you cannot use ones such as SYSPROProgramToRun as it will not load the program.

If you wanted to keep an external copy of who logged in/out you would probably implement the logout part here.

Toolbar VBScript Events

You can configure user-defined VBScript functions against toolbar buttons so that the code runs when the toolbar button is clicked.

Application Builder Events

Event Description

OnClose

Event	Description
OnClose	This event enables you to define the VBScript code to execute when closing out of the Application Builder (see Application Builder 1). This can be used to perform tasks once the operator closes this application, such as: Write a log of what the operator has done. Write the information contained in a listview to a SQL Server table. Prevent an operator from exiting the program until a certain task has been performed, or some other criteria has been met. For example: You may want to prevent the Application Builder window from closing when a field has not yet been entered on a form. To do this, set the `AppBuilder_OnClose` event to be 'false' (e.g. `AppBuilder_OnClose = false`) Scripts for the `OnClose` event can be defined at system-wide level, or by role, or by industry. Each application in the Application Builder menu has its own `OnClose` script, so each can perform a different set of tasks. The name of the script that is created is as follows: Standard operator: The script is saved in `\Work\vbscripts\IMPDH?XX` Role applied operator: The script is saved in `\Base\settings\Role_name\IMPDH?XX` Industry layout: The script is saved in `\Base\settings\Role_industry\IMPDH?XX` System-wide layout: The script is saved in `\Base\settings\Role_SYS\IMPDHKXX`

This event enables you to define the VBScript code to execute when closing out of the Application Builder (see Application Builder 1).

This can be used to perform tasks once the operator closes this application, such as:

Write a log of what the operator has done.
Write the information contained in a listview to a SQL Server table.
Prevent an operator from exiting the program until a certain task has been performed, or some other criteria has been met.
For example: You may want to prevent the Application Builder window from closing when a field has not yet been entered on a form.
To do this, set the AppBuilder_OnClose event to be 'false' (e.g. AppBuilder_OnClose = false)

Scripts for the OnClose event can be defined at system-wide level, or by role, or by industry.

Each application in the Application Builder menu has its own OnClose script, so each can perform a different set of tasks.

The name of the script that is created is as follows:

Standard operator: The script is saved in \Work\vbscripts\IMPDH?XX
Role applied operator: The script is saved in \Base\settings\Role_name\IMPDH?XX
Industry layout: The script is saved in \Base\settings\Role_industry\IMPDH?XX
System-wide layout: The script is saved in \Base\settings\Role_SYS\IMPDHKXX

OBJECT Events

Event	Description
OnLoad	This event fires once when the object is initially instantiated. Typically in this event you would create Graph properties or Listview column headings.
OnRefresh	This event fires each time the object is asked to be refreshed (either by selecting the Refresh button or when automatically refreshed using the timer (see Customized Pane Editor). Typically in this event you would refresh the contents of the object in the pane, such as populating the listview or the graph.
OnToolbarButton1Clicked / OnToolbarButton2Clicked	These events enable you to dynamically access and/or modify all the rows in a listview using the `CustomizedPane.Codeobject.Array` and `CustomizedPane_OUT.CodeObject.Array` variables.
OnSave	(Rich text notepad object)
OnAfterExecuteMethod	(.NET User Control object)
OnPopulate	(Listview object) This event fires after a listview has been populated with new data. You can use this event to iterate through the listview rows and modify the cell attributes for exception purposes. For example, you might want to highlight in red if a warehouse's quantity on hand is negative. If you are changing a checkbox using the `OnPopulate` event and you want to change the value of the checkbox as well as the caption next to the checkbox, then you can use the following syntax: "<Field Value='1New Caption' > </Field>" to make the checkbox checked and change the caption. "<Field Value='0New Caption' > </Field>" to make the checkbox unchecked and change the caption.
OnClick	(Graph object) This event fires when clicking on a graph bar. The information about the item selected is returned in the VBScript variables `BarLabelClicked`, `BarPointClicked`, and `BarSeriesClicked`.
OnDblClick	(Graph and Listview objects) This event fires when double-clicking either on a graph bar or on any row in a listview. The information about the graph bar is returned (for a single click event) and for a listview the contents of each cell in the listview row are returned in the variable `ListviewRowReturned`; each cell is separated by a TAB character.
OnLinkClicked	(Listview object) This event fires when you click on a hyperlink in a cell. The contents of each cell in the listview row are returned in the variable `ListviewRowReturned`; each cell is separated by a TAB character. The column in which the cell was clicked can be identified using the variable `ColumnClicked`.
OnAfterChange	(Listview object) This event fires after the contents of a cell have been changed by an operator (e.g. when changing the existing content of a row in maintenance mode, or when adding a row to a data grid). Each cell that is changed will cause this event to fire. The system variable `CancelStandardAction` can be used to prevent SYSPRO from executing it's built-in function after the `OnAfterChange` event in a form. If, within the `OnAfterChange` function, you insert the line: SystemVariables.CodeObject.CancelStandardAction = true then this indicates that the application must not execute any standard action built into the application. This is useful when you want to override the default behaviour of the SYSPRO application.
OnChecked	(Listview object) This event fires when a checkbox within a listview customized pane is either checked or unchecked. The row containing this checkbox is available using the `ListviewRowReturned` variable, the column number containing the checkbox is available using the `ColumnClicked` variable and the `BeforeChangeValue` variable contains the value of the checkbox before the operator checked/unchecked it.
OnRowSelected	(Listview object) This event is fired when you select a row in any standard listview. This is useful if you want to refresh another customized pane with details of the row just selected. This calls the `OnRowSelected` VBScript event in which you can pick up the current row's cell values using the listview Columns listed in the VBScript variables. The difference between the `OnPopulate` event and the `OnRowSelected` event is that the `OnPopulate` event creates an array equal to the number of records in the listview, whereas the `OnRowSelected` event creates an array of column values for the currently selected row only.
OnDELPressed	(Listview object) If the Columns element contains the AllowDEL attribute set to True, operators are allowed to delete rows from the listview by highlighting the row and pressing the DEL key. If the `OnDELPressed` function exists the event will be fired at this time. The following customized pane variables can be used: ListviewRowReturned Returns the content of the row selected to be deleted in a one dimensional array. SelectedRow Returns the array row number (the first row number is zero) of the row selected to be deleted. Array name The content of the whole array (before the DEL key was pressed) is available. You can prevent the row from being deleted by setting the OnDELPressed function to False.

CustomizedPane Variables

Variable Description

ButtonValue1 ButtonValue2

These variables return the current value of the two available toolbar controls (if configured) if defined as a checkbox or edit control. For an edit control, the value returned will be whatever was entered in the edit control by the operator. For a checkbox, the value returned will be the current status of the checkbox (i.e. 1 for checked, and 0 for unchecked).

DesktopAlert

This displays a message on the operator's screen when a certain condition is met. Double-clicking this variable displays the Desktop Alert Settings windowm from which you can configure the content of the alert.

Field	Description
Duration	This indicates how long the alert will stay on the screen until you interact with it.
Animation style	This indicates how you want the alert to appear or disappear.
Heading line/Subject line/Notes line	These options enables you to add a title for the alert against the text prompt and an icon to appear against the title. The When clicked prompt allows you to specify what must happen if the operator clicks on the alert's heading (i.e. Do nothing, Launch SYSPRO program, or Run executable).

GlobalVariable

This variable and its value remains available until the customized pane is closed.

Normally, as each function within a customized pane VBScript runs in isolation, setting a variable in one function means that the variable (and its content) expires when the function finishes running (e.g. you could not create and set a variable in the customized pane's OnLoad function and access it from the customized pane's OnRefresh function).

RefreshValue This variable enables a customized pane 's OnRefresh function to be fired by other panes within the same SYSPRO program (or within the SYSPRO Main Menu, if that is where the customized pane resides).

Sample usage

Message box statements

The simplest way to confirm when a macro event fires is by using message box statements against the functions within the VBScript.

Although adding message box statements against each event is simple to do, you need to ensure that the name of the function is included in the message box. Otherwise you will know that an event has fired, but not necessarily which one. As you add message box statements to more functions, this becomes more important.

The following is a simple example that appears against the Asset Details pane in the Asset Query program, where both the OnLoad and OnRefresh functions use a message box statement to display the name of the function:
```
Option Explicit 
Function AssetDetails_OnLoad() 
msgbox "AssetDetails_OnLoad" 
End Function 
Function AssetDetails_OnRefresh() 
msgbox "AssetDetails_OnRefresh" 
End Function
```