PowerShell Studio Projects: Form and Multi-Form Projects

The last article in our PowerShell Studio Project Series follows Forms and Multi-Form Projects.

Form

Form projects allow for objects or connections to be created before the initialization of the form; with a standalone form, you cannot initialize anything before the form.

After entering the project name, you will be prompted to select the template for the form in the project:

The selected template will be used to create the MainForm.psf file.

The project will be created with a Globals.ps1, Startup.pss, and the previously mentioned MainForm.psf. From the project toolbar, you can add a new or existing file. Adding a new file will open the Add File dialog to choose a template:

As for project settings, there are no unique Form or Multi-form project settings:

For more information on the properties shown for the project file, reference PowerShell Studio Projects: Introduction. Since the release of the first article in this series, a new Project setting has been added: Remember PowerShell Version. When this property is enabled, the next time the project is opened, it will remember the most recent PowerShell version (v5 or v7) set from the ribbon.

Multi-Form

A multi-form or multi-page app is a GUI application with more than one window.

It’s worth noting that a single Form project can become a Multi-Form project as you add more PSF files to your project. A Multi-Form project gives you a starting point of interaction between the main form of the project and a child form.

When you create a PowerShell Studio Multi-Form project, you start with Globals.ps1, Startup.pss,  MainForm.psf, and ChildForm.psf files. If you add forms to the project, PowerShell Studio creates each form in a separate .psf file.

In Multi-Form projects with modal windows, one form opens another form (and, possibly, another and another). The starting form is called the main formparent form, or owner; any window that’s opened is called the child form. The child form can then open other forms so that it becomes the parent of another child form.

Reference Function

All form-related code exists in a function called a reference function. When a PSF file is exported, this reference function is created with the following name:

Show_FileName_psf

Calling this function will open the form. This function can be called from all files in the project with the Build Setting set to Include. For the default files of a Form project, the reference function for MainForm.psf is called Show-MainForm_psf. The call to this reference function is in Startup.pss.

For more information on single PSF files, please refer to Basics: Working with a PSF file in PowerShell Studio – SAPIEN Blog.

Calling a Child Form

As mentioned, in a Form project, all form code is encased in a function called Show-MainForm_psf.

The reference functions make it very easy to open a form from another form. For example, this form project has MainForm.psf, ChildForm.psf, MiddleChildForm.psf, and ThirdChildForm.psf files:

Each form in the project can call the reference functions for all other forms. No dot-sourcing is required, because all of the functions are in the same script.

When you open a child form in a modal window structure, its parent form is temporarily disabled because the ‘control’ has passed to the child form. Then, when the child form closes, control is automatically passed to its parent form, which is reenabled. You do not need to add any code to reopen the parent form. 

All reference functions use a method called ShowDialog() to show the form at the end of the function.

When you close the child form, the ShowDialog() method will return the DialogResult value of the child form to the parent form. The DialogResult indicates which button was used to close the child form; this is an enumerated value returned by dialogs after closing.

For more information on working with DialogResult values, the following articles may be helpful:

Besides the DialogResult, you may want additional information from your child form. For some commonly used control properties, PowerShell Studio creates a script-scoped variable for you.

This table lists the supported controls and properties:

Control Property Type
CheckBox Checked System.Boolean
CheckedListBox SelectedItems System.Windows.Forms.ListBox.SelectedObjectCollection
ComboBox Text and SelectedItem System.String
DateTimePicker Value System.DateTime
ListBox SelectedItems System.Windows.Forms.ListBox.SelectedObjectCollection
ListView SelectedItems System.Windows.Forms.ListView.SelectedListViewItemCollection
MonthCalendar SelectionStart System.DateTime
NumericUpDown Value System.Decimal
RadioButton Checked System.Boolean
RichTextBox Text System.String
TextBox Text System.String
TreeView SelectedNode.Text System.String

All supported controls and properties will be saved in a generated form closing event:

For controls not supported, the same principle can still be applied. On the Closing event of the form, save the desired properties or information to a script-scoped variable.

Building and Running a Form or Multi-Form Project

When running a project, the project files are built based on their build setting and build order. All files set to Include will be combined into one file called ProjectName.Run.ps1.

When you run or debug the form or project, PowerShell Studio combines the code in all of those files into a single .ps1 script file. That script file—created in memory—runs when you click Run or Debug. It is also the script that is packaged into an executable file (.exe) or a Microsoft installer file (.ms1) when you use the SAPIEN Script Packager features of PowerShell Studio.

When creating the reference function, the form is broken into sections:

  • Assemblies – All references to assemblies.
  • Generated Form Objects – All Forms’ controls and associated objects being initialized.
  • User Generated Script – All code from the Script tab.
  • Generated Events – Event handlers for loading the window state of the form and for cleanup when the form closes.
  • Generated Form Code – All properties and events of the Forms’ controls and objects being set.

In a form project, the generated PS1 file will add the files according to the build order. From the default build order, the generated PS1 file will contain regions in this order:

Startup.pss
Globals.ps1
MainForm.psf

If you open the exported file, it should look something like this:

Depending on your recovery settings, each file region will have recovery data as well as recovery data for the project file (.PSPROJ) itself. A Multi-Form project would look similar to this except with the additional child form region.

Related

Feedback

All information provided in this article is based on the functionality available in PowerShell Studio 2022 build 5.8.209.

As always, any feedback is appreciated. If you have a particular type of blog article or product feature request you would like to see, please submit your suggestions on the Wish List and Feature Requests forum or the Feature Requests page.