{"id":6569,"date":"2013-10-01T09:14:00","date_gmt":"2013-10-01T17:14:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=6569"},"modified":"2013-10-01T09:14:33","modified_gmt":"2013-10-01T17:14:33","slug":"powershell-studio-passing-and-returning-values-using-forms","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2013\/10\/01\/powershell-studio-passing-and-returning-values-using-forms\/","title":{"rendered":"PowerShell Studio – Passing and Returning Values using Forms"},"content":{"rendered":"

Two frequent questions we get on the forums are:<\/p>\n

\n

How do I pass a value to another form?<\/em><\/p>\n<\/blockquote>\n

\n

How do I get the results from a form?<\/em> <\/p>\n<\/blockquote>\n

In this article, we will answer these common questions in order to give you a better understanding about how to use projects with multiple forms.<\/p>\n

 <\/p>\n

Getting Started<\/strong><\/p>\n

You will need to create a project with multiple forms in order to proceed. The Multi-Form Project template is a good starting point. At the end of this article there is a link to download a sample project that demonstrates how to use these techniques.<\/p>\n

 <\/p>\n

Calling Forms in a Project (Reference Functions)<\/strong><\/p>\n

Once you have a project with a form, you can call the form from the Startup.pfs or from another form. To do this, you must use the Form\u2019s Reference Function. A file\u2019s Reference Function uses the following naming convention:<\/p>\n

Call-<File Name>_<Extension><\/span><\/pre>\n<\/p>\n
For example, to call the AddExtension.pff file in the sample project, you would use the following reference function:<\/p>\n
Call-AddEmployeeForm_pff<\/span><\/pre>\n
<\/span> <\/pre>\n
Calling PS1 Files<\/strong><\/p>\n
If you need to call a ps1 file you will have to set the following project file\u2019s properties in the Project Panel as follows:<\/p>\n\n\n\n\n\n
Property<\/strong><\/td>\nValue<\/strong><\/td>\n<\/tr>\n
Build<\/td>\nInclude<\/em><\/td>\n<\/tr>\n
CommandExtension<\/td>\nFalse<\/em><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n
By setting the CommandExtension property to False,<\/em> you are telling the project to treat the ps1 file as a function. This allows you use the file\u2019s reference function to execute it:<\/p>\n
Call-MyScript_ps1
<\/span><\/pre>\n
Note: You can still dot source ps1 files; but if you do you must set the ps1 file\u2019s Build setting to Content<\/em> so that it isn\u2019t merged into the final project script.<\/p>\n
If you are unsure of the Reference Function name, you can look at the Reference Name property of the project file:<\/p>\n
\"Reference<\/a>  <\/p>\n
In addition, PowerShell Studio\u2019s PrimalSense will display a list of Reference Functions when you type \u201cCall-\u201d :<\/p>\n
 \"Reference <\/p>\n
 <\/p>\n
Passing Parameters<\/strong><\/p>\n
There are times when you need to pass information to a child form. In these situations, you can use a parameter block in the same manor you would with a traditional ps1 script. To do this, go to the form file\u2019s  script section and insert a Parameter block at the very top of the script. It is very important that nothing but comments appear before the parameter block.<\/p>\n
 <\/p>\n
\"Parameter <\/p>\n
 <\/p>\n
Once you add the parameter block, PowerShell Studio will color the parameters accordingly:<\/p>\n
\"ReferenceFunction <\/p>\n
Note: Script scope variables can also be used as an alternative to parameters.<\/p>\n
Returning Values<\/strong><\/p>\n
Now that you know how to pass values to a form, how do you get values back? Returning values depends on what you are referencing. For example, Form files are handled differently the ps1 files.<\/p>\n
Form Return Values<\/em><\/p>\n
The Form\u2019s Reference Function returns the DialogResult of the Form when it is closed. How do you handle return values?<\/p>\n
Luckily PowerShell Studio auto generates variable values with the values of controls in the form. The return variables name convention is as follows:<\/p>\n
$<Form Name>_<Control Name><\/span><\/pre>\n<\/p>\n
For example, if AddEmployeeForm.pff has a TextBox named textBoxFirstName, PowerShell Studio will generate the following return variable:<\/p>\n
$AddEmployeeForm_textboxFirstName<\/span><\/pre>\n
When you use a Reference Function, PowerShell Studio\u2019s PrimalSense will automatically include the return variables when you type $.<\/p>\n
\"ReturnVariables\" <\/p>\n
 <\/p>\n
The value contained in the variable depends on the control. The following is a list of controls that generate return values:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Control<\/strong><\/td>\nReturns<\/strong><\/td>\n<\/tr>\n
TextBox<\/td>\nstring<\/td>\n<\/tr>\n
CheckBox<\/td>\nbool<\/td>\n<\/tr>\n
ComboBox<\/td>\nstring<\/td>\n<\/tr>\n
MonthCalendar<\/td>\nDateTime<\/td>\n<\/tr>\n
DateTimePicker<\/td>\nDateTime<\/td>\n<\/tr>\n
ListView<\/td>\nCollection<\/td>\n<\/tr>\n
ListBox<\/td>\nCollection<\/td>\n<\/tr>\n
NumericUpDown<\/td>\nDecimal<\/td>\n<\/tr>\n
RichTextBox<\/td>\nstring<\/td>\n<\/tr>\n
TreeView<\/td>\nstring<\/td>\n<\/tr>\n
RadioButton<\/td>\nbool<\/td>\n<\/tr>\n
CheckedListBox<\/td>\nCollection<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n
Returning Custom Values in Forms<\/em><\/em><\/p>\n
In the case where the control doesn\u2019t return a value or you want to return a custom value \/ object, you can create a variable using the script scope:<\/p>\n
$script:MyReturnValue<\/span> <\/span>=<\/span> <\/span>..<\/span>.<\/span><\/pre>\n
Then you can reference the variable in the file that called the form.<\/p>\n
if<\/span>(<\/span>Call-AddEmployeeForm_pff<\/span>) \u2013eq <\/span>'OK'<\/span>)\n{\n    <\/span>Out-Default<\/span> <\/span>$script:MyReturnValue<\/span>\n}<\/span><\/pre>\n
<\/em>In the sample project, the amount of time the user took to complete the Add Employee form is saved in a script variable. The main form then displays a message if the user took longer than the allotted time.<\/p>\n
 
Script Return Values<\/em><\/p>\n
Script (ps1) files simply return the objects via the pipeline as there is no form to return a DialogResult<\/em>.<\/p>\n
Call-MyScript_ps1<\/span> <\/span>|<\/span> <\/span>Out-Default<\/span><\/pre>\n
Hopefully now you have the tools to create complex GUIs that utilize multiple forms. The sample project below utilizes the techniques covered by this article. <\/p>\n
Sample Project \u2013 Employee Roster<\/strong><\/p>\n
The Employee Roster is a sample project that uses a grid to display a list of employees. When you press a button, a second form is displayed to collect employee information and the results are in turn loaded into the grid of the first form.<\/p>\n
\"Employee<\/a> <\/p>\n
\"DOWNLOAD2\"<\/a> <\/p>\n<\/p>\n
– Employee Roster Sample Project<\/p>\n","protected":false},"excerpt":{"rendered":"
Two frequent questions we get on the forums are: How do I pass a value to another form? How do I get the results from a form? In this article, we will answer these common questions in order to give you a better understanding about how to use projects with multiple forms.   Getting Started […]<\/p>\n","protected":false},"author":10,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[705,25],"tags":[41,850,28,1016,767,312],"class_list":["post-6569","post","type-post","status-publish","format-standard","hentry","category-powershell-studio-2012","category-windows-powershell","tag-gui","tag-parameters","tag-powershell","tag-powershell-studio","tag-projects","tag-winforms"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/6569","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/10"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=6569"}],"version-history":[{"count":6,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/6569\/revisions"}],"predecessor-version":[{"id":6578,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/6569\/revisions\/6578"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=6569"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=6569"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=6569"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}