Form Action Helper Function

When performing an action with a ScriptoForm, typically with an Event Handler, it is generally best practice for usablitity purposes to set the state of the Form and Controls before, during, and after the processing of that action. This may include:

• Disabling controls to prevent user interaction
• Setting status messages
• Setting the mouse cursor
• Re-enabling controls
• Clearing control values
• Setting focus to a specific control

To facilitate these state changes for most common scenarios, the Invoke-FormAction function is provided that can be called from your Event Handler.

Functions Region

function Invoke-FormAction
{
    param
    (
        [Parameter(Mandatory, Position = 0)] [ScriptBlock]$Action,
        [Parameter(Position = 1)] [ScriptBlock]$Reset = $null,
        [Parameter(Position = 2)] [String]$StatusText = "Working...please wait"
    )

    try
    {
        $ToolStripStatusLabelMain.Text = $StatusText
        $FormMain.Controls | Where-Object {$PSItem -isnot [System.Windows.Forms.StatusStrip]} | ForEach-Object {$PSItem.Enabled = $false}
        $FormMain.Cursor = [System.Windows.Forms.Cursors]::WaitCursor
        [System.Windows.Forms.Application]::DoEvents()
        Invoke-Command -ScriptBlock $Action
    }

    finally
    {
        $FormMain.Controls | ForEach-Object {$PSItem.Enabled = $true}
        $FormMain.ResetCursor()
        if ($Reset) {Invoke-Command -ScriptBlock $Reset}
        $ToolStripStatusLabelMain.Text = "Ready"
        $StatusStripMain.Update()
    }
}

The overall flow of this function is as follows:

1. The $ToolStripStatusLabelMain.Text value is set to a default value of: Working...please wait. This value can be adjusted with the StatusText parameter if needed. This text provides visible feedback to the user that the action steps have begun.
2. All controls on the Form, with the exception of the $StatusStripMain control, are disabled. This prevents the user from interacting with the Form while the action steps are running. The $StatusStripMain control is left enabled to allow status messages via the $ToolStripStatusLabelMain.Text value to be updated as needed while the action steps are running.
3. The Form mouse cursor is set to the WaitCursor value. This provides visiable feedback to the user that the action steps are running.
4. The action steps are executed via the Action parameter script block.
5. The action steps finish and exceptions are handled if needed.
6. All Form controls are enabled.
7. The Form mouse cursor is reset to the default value.
8. The Form controls are reset to a desired state via the Reset parameter script block. For example, an Input control text value can be cleared. Additionally, focus to a specific control can be set via this script block as well. This, in effect, resets the Form to it’s original state.
9. The $ToolStripStatusLabelMain.Text value of the Form is reset to the default value of Ready.

Example

Handlers Region

$ButtonRun_Click =
{
  Invoke-FormAction -Action {
    try
      {
        Start-Sleep -Seconds 2
        [void][System.Windows.Forms.MessageBox]::Show(
          "Action complete.",
          "Results",
          [System.Windows.Forms.MessageBoxButtons]::OK,
          [System.Windows.Forms.MessageBoxIcon]::Information
        )
      }
      catch
      {
        [void][System.Windows.Forms.MessageBox]::Show(
          $PSItem.Exception.Message + "`n`nPlease contact $SUPPORT_CONTACT for technical support.",
          "Exception",
          [System.Windows.Forms.MessageBoxButtons]::OK,
          [System.Windows.Forms.MessageBoxIcon]::Warning
        )
      }
  } -Reset {
    $TextBoxServerName.Clear()
    $TextBoxServerName.Focus()
  }
}