The Form Control
- Details
- Written by David Corrales
- Last Updated: 13 June 2016
- Created: 01 June 2011
- Hits: 30538
Form Control [System.Windows.Forms.Form]
The Form control represents the application window that contains the other controls.
- MSDN Page: System.Windows.Forms.Form
- Default Event: Load
Important properties of the Form object
- Text
- FormBorderStyle
- Icon
- StartPosition
- WindowState
- ControlBox
- MinimizeBox
- MaximizeBox
- AcceptButton
- CancelButton
- BackgroundImage
- BackgroundImageLayout
Important events of the Form object
Important methods of the Form object
Important Properties:
Text property: Sets the form title
Use the Text property to get or change the title of the form.
Value type: System.String
Default value: Form
For example, the value of the Text property of this form is “Form.”
To change the form title, in the Properties pane, change the value of the Text property of the form.
Or, set the value of the Text property of the form in the script.
Here’s the result.
Note: When you change the Text property value of a form (or other control), PowerShell Studio and PrimalScript automatically rename the variable that stores the form object. For example, if you set the Text property of the form to “Get Process,” the variable name is changed to $formGetProcess. To disable this feature, in Options/Designer, uncheck Sync control names with text.
FormBorderStyle property: Appearance of border and title bar
Use FormBorderStyle to determine whether the end-user can resize the form.
Value type: FormBorderStyle
Default value: Sizeable
Values (Default: Sizable):
None
No border or title bar. The end-user cannot drag or resize the form.
FixedSingle
A fixed, single-line border. The end-user cannot resize this form.
Fixed3D
A fixed, three-dimensional border. The end-user cannot resize this form.
FixedDialog
A thick, fixed dialog-style border. The end-user cannot resize this form.
Sizable (Default)
The end-user can resize this form.
FixedToolWindow
The end-user cannot resize this form.By design, a tool window does not appear in the taskbar or in the window thumbnail collection that appears when the user presses ALT+TAB. However, this does not appear to be true on Windows 10. When you use the FixedToolWindow value, you are supposed to set the ShowInTaskbar property to False; its default value is True.
SizableToolWindowThe end-user can resize this form.
By design, a tool window does not appear in the taskbar or in the window thumbnail collection that appears when the user presses ALT+TAB. However, this does not appear to be true on Windows 10. When you use the FixedToolWindow value, you are supposed to set the ShowInTaskbar property to False; its default value is True.
NOTE: Some borders, such as Fixed3D and FixedSingle, might be affected by the operating system and Windows theme.
Icon property: Gets and sets the form icon
The form icon is displayed in the system menu box and appears when the form is minimized. Use the Icon property to display a custom icon. The value of the FormBorderStyle and ShowIcon properties might hide the form icon.
Value type: System.Drawing.Icon
Default value: (Default icon). The default icon might be affected by the operating system and Windows theme.
To change the icon, in the Properties pane, in the Icon property value, click the ellipsis, then navigate to the icon file. You can set the Icon property value to any .ico file.
To reset the icon to its default value, in the Properties pane, click the current value, and then click Delete.
Default Icon:
Custom Icon:
StartPosition property: Determines where the form appears
Use the StartPosition property to determine where on the screen the form first appears. For example, you can place the form in center of the screen or the parent window.
Value type: System.Windows.Forms.FormStartPosition
Default value: WindowsDefaultLocation
Values (Default: WindowsDefaultLocation):
Manual
The position of the form is determined by the value of the Location property.
CenterScreen
The form is centered on the display and has the dimensions specified by the value of the Size property of the form.
WindowsDefaultLocation (Default)
The form is positioned at the default location for the current version of Windows. Its size is determined by the by the value of the Size property of the form.
WindowsDefaultBounds
The form is positioned at the Windows default location and has the bounds determined by Windows default.
CenterParent
The form is centered within the bounds of its parent form.
WindowState property: Opens the form minimized or maximized
Use the WindowState property to maximize or minimize when it is first displayed.
Value type: System.Windows.Forms.FormWindowState
Default value: WindowsDefaultLocation
Values (Default: Normal):
Normal (Default)
Opens at standard size.
Maximized
Opens maximized.
Minimized
Opens minimized.
ControlBox property: Show/hide system menu
Use the ControlBox property to show and hide the system menu that contains the Minimize, Maximize, and Close buttons. A value of False also hides the Windows icon on the top left corner of the window, if the operating system adds one.
Value type: System.Boolean
Default value: True
NOTES:
- The Form object also has MinimizeBox and MaximizeBox properties to show/hide each element on the system menu. If ControlBox is False, the system menu, including the CancelBox (X) does not appear, regardless of the value of the other properties.
- If you set the ControlBox property to False, be sure to add a way to close the form.
Values (Default: True):
True (Default):
False:
MaximizeBox property: Show/hide maximize button
Determines whether the form has a maximize button in the upper right corner of its title bar.
Value type: System.Boolean
Default value: True
When the value of ControlBox is False, the maximize button does not appear, regardless of the value of the MaximizeBox property.
MaximizeBox set to False:
MinimizeBox property: Show/hide minimize button
Determines whether a form has a minimize button in the upper right corner of its title bar.
Value type: System.Boolean
Default value: True
When the value of ControlBox is False, the maximize button does not appear, regardless of the value of the MaximizeBox property.
MinimizeBox set to False:
MaximizeBox and MinimizeBox set to False:
AcceptButton property: Button that is clicked on Enter
The AcceptButton property of the form determines which button’s Click event is raised when the user presses the ENTER key. Typically, the value of AcceptButton is the variable that contains the OK button object ($buttonOK), but you can use this property to change it to any button on the form, such as a Start button that performs the primary action of the form.
Value type: System.Windows.Forms.iButtonControl
Default value: (None)
When the end-user presses enter, the Click event of the AcceptButton is raised, and the event handler for the buttons Click event runs. You can also change and query the value of the AcceptButton in your script.
CancelButton property: The button that is clicked on ESC
The CancelButton property of the form determines which button’s Click event is raised when the user presses the ESC key. Typically, the value of CancelButton is the variable that contains the OK button object ($buttonOK), but you can use this property to change it to any button on the form, such as a Start button that performs the primary action of the form.
Value type: System.Windows.Forms.iButtonControl
Default value: (None)
BackgroundImage property: Sets a background image for the form
Use the BackgroundImage property to customize the form with a texture or graphic.
Value type: System.Drawing.Image
Default value: (None)
To set a background image, in the Properties pane, on the BackgroundImage row, click the ellipsis, and then navigate to an image file.
BackgroundImageLayout property: Layout of the background image
Use this property to change the default presentation of the background image.
Value type: System.Windows.Forms.ImageLayout
Default value: Tile
Values (Default: Tile)
None
The image is left-aligned at the top of the form.
Tile
Multiple instances of the image are arranged in the form rectangle.
Center
The image is centered in the form.
Stretch
The image is enlarged to occupy the entire form.
Zoom
The image is enlarged within the form.
Important Events:
Load event: Occurs before a form is displayed.
Use the Load event to initialize property values just before the form is displayed.
The values in the Properties pane of PowerShell Studio and PrimalScript are set when the objects are created (New-Object), which is shortly before the Load event is raised. You can use the Load event to get the initial values or set new values.
When you create a new form, PowerShell Studio and PrimalScript automatically an event handler for the Form_Load event.
$FormEvent_Load={ #TODO: Initialize Form Controls here }
FormClosing event: Occurs before the form is closed.
Use the FormClosing event to clean up and finalize before the form closes. You can also cancel the closing by setting the Cancel property to true:
$form1_FormClosing=[System.Windows.Forms.FormClosingEventHandler]{ #Event Argument: $_ = [System.Windows.Forms.FormClosingEventArgs] $_.Cancel = $true }
Important Methods:
Close method: Closes the form window
Typically, you use the Close method in the event handler for a Close button.
$buttonOK_Click={ $form1.Close() }
For licensed customers, use the forum associated with your product in our Product Support Forums for Registered Customers.
For users of trial versions, please post in our Former and Future Customers - Questions forum.