Event Handlers

The main function of a ScriptoForm is to display a Microsoft Windows Forms application which is event-driven and executes code in response to events. Typically, these events are initiated by the user of your ScriptoForm such as clicking a button or typing text into an input field. To respond to these events at run-time, you need to provide Event Handlers to each specific event. In a ScriptoForm, these event handlers are implemented as PowerShell script blocks.

As an example, when a user clicks a Button control, an OnClick event is raised which you can listen for, by associating an event (known as “subscribing”) with its handler name, and perform an action with that handler script block. The action that is performed in response to the event depends on the purpose of your ScriptoForm and how you wish to handle it.

In PowerShell, all event handler subscriptions for Microsoft Windows Forms controls follow the pattern Add_<EventName>. This method allows you to associate a specific event with a corresponding event handler script block. For example, to handle the “Click” event of a button control, you would use the Add_Click method to subscribe to the event.

An event handler is assigned to a control using the following covention:
$ControlName.Add_EventName($ControlName_EventName)

• $ControlName: The name of the control.
  Example: $ButtonReloadUserList
• Add_EventName: The name of the event subscription.
  Example: Add_Click
• ($ControlName_EventName): The name of the script block used to handle the event.
  Example: $ButtonReloadUserList_Click

Using the above examples would result in the following:
$ButtonReloadUserList.Add_Click($ButtonReloadUserList_Click)

Example

1. In the $ShowFormMain script block of the Forms region, assign the name of the script block to be used to handle the specific event type to the control.

   Forms Region | $ShowMainForm

   $ButtonReloadUserList.Location = New-Object -TypeName System.Drawing.Point(($FormWidth - 175),($FormHeight - 60))
   $ButtonReloadUserList.Size = New-Object -TypeName System.Drawing.Size(75,25)
   $ButtonReloadUserList.TabIndex = 100
   $ButtonReloadUserList.Enabled = $false
   $ButtonReloadUserList.Text = "Reload User List"
   $ButtonReloadUserList.Add_Click($ButtonReloadUserList_Click)
   $FormMain.Controls.Add($ButtonReloadUserList)

2. In the Handlers region, create a matching script block for the handler.

   Handlers Region

   #region Handlers
   $ButtonReloadUserList_Click =
   {
       # Add your custom code here...
   }
   #endregion

Tip

For a comprehensive list of control events please see the official .NET documentation: System.Windows.Forms Namespace

Predefined Event Handlers

A newly provisioned ScriptoForm predefines the following event handlers automatically, which can be customized as needed:

• $FormMain_Shown: This event handler is used to provide initial setup and configuration of the main Form, and controls, prior to displaying it. By default, it sets the text property of the $ToolStripStatusLabelMain control and then activates the Form.
• $ButtonRun_Click: This event handler is used to perform the primary action(s) of the ScriptoForm. By default, it closes the Form which then exits the script.

References

Events overview (Windows Forms .NET) | Microsoft Learn