Set-FormControl

In PowerShell it is quiet common to use Windows Forms to build a User Interface for small cmdlets but the syntaxis required for this are far from DRY (don’t repeat yourself) programming.

In a lot of cases it not required to created any functions to make your code less verbose, take e.g. the lengthy WinForms PowerShell script here. Code pieces like this:

Can easily be simplified in WinForms to a single line:

$Tab1.Padding = 3

And if the padding would be different for each side, PowerShell will automatically convert:

$Tab1.Padding = "4, 6, 4, 6"

Note that PowerShell does not convert $Tab1.Padding = "3" or $Tab1.Padding = "4, 6"

Nevertheless, the native way to create a windows form control is quiet lengthy and although (multiple) properties can be added at creation (using: New-Object System.Windows.Forms.Button -Property @{Location = "75, 120"; Size = "75, 23"}) , multiple properties can’t be set right away at a later state. Above that, there isn’t a quick and easy way to add events*1, child controls and container properties (as e.g. RowSpan), or any combination, intermediately at creation of a windows form control.

Bottom line, you have to reference the windows form control over and over again to set its properties and more with e.g. $OKButton.<property> = ... as in this example :

That’s why I have created a reusable PowerShell Form Control wrapper that let’s you minimize Windows Forms (WinForms) code to it’s essence.

*1 unless you use On<event> methods, see also: addEventListener vs onclick

Cmdlet

Syntax

Creating a control

<System.Windows.Forms.Control> = New-FormControl [-Control <String>] [-Member <HashTable>]

Modifying a control

<Void> = Set-FormControl [-Control <System.Windows.Forms.Control>] [-Member <HashTable>]

Adding a (new) control to a container

<System.Windows.Forms.Control> = Set-FormControl [-Control <String>|<System.Windows.Forms.Control>] [-Member <HashTable>] [-Add <System.Windows.Forms.Control[]>]

Piping a container to a (new) control

<System.Windows.Forms.Control> = <System.Windows.Forms.Control> | New-FormControl [-Control <String>|<System.Windows.Forms.Control>] [-Member <HashTable>] [-Set <HashTable>] [-PassParent]

Note that Set-FormControl is simply an alias for New-FormControl, there is no functional difference between the commands. Whether a new form control is created or update, depends object type supplied to the -Control parameter.

Parameters

-Control <String>|<System.Windows.Forms.Control> (position 0, default: Form)

The -Control parameter accepts either a Windows form control type name ([String]) or an existing form control ([System.Windows.Forms.Control] ). Windows form control type names are like Form, Label, TextBox, Button, Panel, etc. If a Windows form control type name ([String]) is supplied, the wrapper will create and return a new Windows form control with properties and settings as defined by the rest of the parameters.
If an existing Windows form control ([System.Windows.Forms.Control] ) is supplied, the wrapper will update the existing Windows form control using the properties and settings as defined by the rest of the parameters.

-Member <HashTable> (position 1)

Sets property values, invokes methods and add events on a new or existing object.

  • If the hash name represents property on the control, e.g. Size = "50, 50", the value will be assigned to the control property value.
  • If the hash name represents method on the control, e.g. Scale = {1.5, 1.5}, the control method will be invoked using the value for arguments .
  • If the hash name represents event on the control, take e.g. Click = {$Form.Close()}, the value ( [ScriptBlock]) will be added to the control events.

Two collection properties, ColumnStyles and RowStyles, are simplified especially for the TableLayoutPanel control which is considered a general substitute for the WPF Grid control: – The ColumnStyles property, clears all column widths and reset them with the ColumnStyle array supplied by the hash value. The RowStyles property, clears all row Heigths and reset them with the RowStyle array supplied by the hash value.

Note: If needto add or insert a single specific ColumnStyle or RowStyle item, you need to fallback on the native statement, as e.g.: [Void]$Control.Control.ColumnStyles.Add((New-Object Windows.Forms.ColumnStyle("Percent", 100)).

-Add <Array>

The -Addparameter adds one or more child controls to the current control.

Note: the -add parameter cannot be used if container is piped to the control.

-Container <System.Windows.Forms.Control> (from pipeline)

The parent container is usually provided from the pipeline: $ParentContainer | Form $ChildControl and attached a (new) child control to the concerned container.

-Set <HashTable>

The -Set parameter sets (SetCellPosition, SetColumn, SetColumnSpan, SetRow, SetRowSpan and SetStyle) the specific child control properties related its parent panel container, e.g. -Set RowSpan = 2.

Note: the -set column – and row parameters can only be used if a container is piped to the control.

-GetParent

By default the (child) control will be returned by the Set-FormControl function unless the -GetParent switch is supplied which will return the parent container instead.

Note: the -GetParentparameter can only be used if a container is piped to the control.

Examples

There are two way to setup the Windows Forms hierarchy:

  1. Adding a (new) control to a container
  2. Piping a container to a (new) control

Adding a (new) control to a container

For this example I have reworked the Creating a Custom Input Box at docs.microsoft.com for using the PowerShell Form Control wrapper:

Piping a container to a (new) control

For this I have created a small for to test the docking behavior:

(See StackOverflow for an example with two docked items)

The Set-ControlForm cmdlet was originally published at StackOverflow

Leave a Reply