initial commit

LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 mlot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

PSGUIFunctions.ps1

@@ -0,0 +1,210 @@
+#Requires -Version 5
+
+# Collection of cobbled together Powershell functions for GUI based message and user input prompts.
+
+function Select-Folder {
+    <#
+    .SYNOPSIS
+     Opens a folder selection dialog and returns full path to the folder.
+
+    .EXAMPLE
+     $selectedFolder = Select-Folder
+    #>
+    Add-Type -AssemblyName System.Windows.Forms
+    $FolderSelect = New-Object System.Windows.Forms.FolderBrowserDialog
+    $null = $FolderSelect.ShowDialog()
+    $SelectedFolder = $FolderSelect.SelectedPath
+    return $SelectedFolder
+}
+
+
+function Select-File {
+    <#
+    .SYNOPSIS
+     Opens a file selection dialog and returns full path to the file.
+
+    .PARAMETER InitialDialogDir
+    Specifies the inital directory to start in the dialog. If unspecified it defaults to the root of the home drive.
+
+    .EXAMPLE
+    $selectedFile = Select-File -InitialDialogDir "C:\Users\Public\Documents"
+    #>
+    param (
+        [Parameter(Mandatory=$false)]
+        [String] $InitialDialogDir = "$env:HOMEDRIVE"
+    )
+    Add-Type -AssemblyName System.Windows.Forms
+    $FileSelect = New-Object System.Windows.Forms.OpenFileDialog -Property @{
+        InitialDirectory = $InitialDialogDir
+        filter = "All files (*.*)| *.*"
+    }
+    $null = $FileSelect.ShowDialog()
+    $SelectedFile = $FileSelect.FileName
+    return $SelectedFile
+}
+
+
+function Save-File {
+    <#
+    .SYNOPSIS
+    Creates a save file dialog and returns the path and name of the file to save.
+
+    .PARAMETER InitialDialogDir
+    Specifies the initial directory to start in the dialog. If unspecified it defaults to the root of the home drive.
+
+    .EXAMPLE
+    $saveFile = Save-File -InitialDialogDir "C:\Users\Public\Documents"
+    #>
+    param (
+        [Parameter(Mandatory=$false)]
+        [String]
+        $InitialDialogDir = "$env:HOMEDRIVE"
+    )
+    Add-Type -AssemblyName System.Windows.Forms
+    $FileSelect = New-Object System.Windows.Forms.SaveFileDialog -Property @{
+        InitialDirectory = $InitialDialogDir
+        filter = "All files (*.*)| *.*"
+    }
+    $null = $FileSelect.ShowDialog()
+    $SelectedFile = $FileSelect.FileName
+    return $SelectedFile
+}
+
+
+function Show-MessageBox {
+    <#
+    .SYNOPSIS
+    Displays a message box and returns the button pressed in response.
+
+    .PARAMETER MessageText
+    Specifies the main text of the message to display.
+
+    .PARAMETER MessageTitle
+    Specifies the title of the message box.
+
+    .PARAMETER ButtonOptions
+    Specifies the button types shown for response to the message box. Default is 'OKCancel'.
+
+    .PARAMETER MessageBoxIcon
+    Specifies the icon displayed on the message box to indicate it's type. Default is 'Information'.
+
+    .PARAMETER MessageBoxDefaultButton
+    Specifies the default button to be activated on the message box. Default is 'Button1'.
+
+    .EXAMPLE
+    $returnedMessageBoxButton = Show-MessageBox -MessageText "Hello, World" -MessageTitle "Hello World"
+    #>
+    param (
+        [Parameter(Mandatory=$true)]
+        [String]
+        $MessageText,
+        [Parameter(Mandatory=$false)]
+        [String]
+        $MessageTitle = "Message",
+        [Parameter(Mandatory=$false)]
+        [String]
+        $ButtonOptions = "OKCancel",  # YesNoCancel, AbortRetryIgnore, YesNo, RetryCancel
+        [Parameter(Mandatory=$false)]
+        [String]
+        $MessageBoxIcon = "Information",  # Error, Question, Warning, Stop, Hand
+        [Parameter(Mandatory=$false)]
+        [String]
+        $MessageBoxDefaultButton = "Button1"  # Button2, Button3
+    )
+    Add-Type -AssemblyName System.Windows.Forms
+    $ButtonReturn=[System.Windows.Forms.MessageBox]::Show("$MessageText","$MessageTitle", +
+    [System.Windows.Forms.MessageBoxButtons]::$ButtonOptions,[System.Windows.Forms.MessageBoxIcon]::$MessageBoxIcon, +
+    [System.Windows.Forms.MessageBoxDefaultButton]::$MessageBoxDefaultButton)
+    return $ButtonReturn
+}
+
+
+function Get-UserInput {
+    <#
+    .SYNOPSIS
+    Displays a user input box and returns the user's input as a string (default) or integer (see parameter).
+
+    .PARAMETER InputMessage
+    Specifies the main text of the input box message to display.
+
+    .PARAMETER InputTitle
+    Specifies the title of the input box.
+
+    .PARAMETER DefaultInput
+    Allows you to set an initial default input value for the user.
+
+    .PARAMETER ReturnAsInteger
+    Default is set to '$false'. Set to '$true' to convert input from string to integer (if conversion is possible).
+
+    .EXAMPLE
+    $userInput = Get-UserInput -InputMessage "What is your name?" -InputTitle "Your Information"
+    $userInput = Get-UserInput -InputMessage "How old are you?" -ReturnAsInteger $true
+    #>
+    param (
+        [Parameter(Mandatory=$true)]
+        [String]
+        $InputMessage,
+        [Parameter(Mandatory=$false)]
+        [String]
+        $InputTitle = "Input Request",
+        [Parameter(Mandatory=$false)]
+        [String]
+        $DefaultInput,
+        [Parameter(Mandatory=$false)]
+        [bool]
+        $ReturnAsInteger = $false  # Set to "$true" if you want a numeric string converted to an integer
+    )
+    [void][System.Reflection.Assembly]::LoadWithPartialName('Microsoft.VisualBasic')
+    $UsersInput = [Microsoft.VisualBasic.Interaction]::InputBox($InputMessage, $InputTitle, $DefaultInput)
+    if ($ReturnAsInteger -eq $true -and $UsersInput -match "^\d+$") {
+        return [int]$UsersInput
+    } else {
+        return $UsersInput
+    }
+}
+
+
+# Display Listbox Input Selection
+function Show-ListBox {
+    <#
+    .SYNOPSIS
+    Displays a listbox and returns single or multiple choices from the list of items. (Uses Powershell's Out-GridView.)
+
+    .PARAMETER ItemsForList
+    List items must be passed in from a Powershell array. 
+
+    .PARAMETER ChoiceMode
+    Allows you to set for 'Single' item only or 'Multiple' item selections by user. Default is 'Single'.
+    Single items are returned as System.String type, multiple items are returned as a System.Object[] type.
+
+    .PARAMETER BoxTitle
+    Specifies the title of the list box and can be used to ask for selection.
+
+    .PARAMETER SortListItems
+    Allows you to specify if list item are sorted (e.g. alphabetically). Default is '$false'.
+
+    .EXAMPLE
+    $listItems = @('Jack','John','Jill','Jane')
+    $userInput = Show-ListBox -ItemsForList $listItems -BoxTitle "Please choose a name:" -ChoiceMode "Single" -SortListItems $true
+    #>
+    param (
+        [Parameter(Mandatory=$true)]
+        [array]
+        $ItemsForList,  # List items passed in as an array
+        [Parameter(Mandatory=$false)]
+        [String]
+        $ChoiceMode = "Single",  # "Single" (default) or "Multiple" item selection
+        [Parameter(Mandatory=$false)]
+        [String]
+        $BoxTitle = "Choose item below and press OK:",
+        [Parameter(Mandatory=$false)]
+        [bool]
+        $SortListItems = $false  # Set to "$true" if you want to sort the list items alphanumerically
+    )
+    if ($SortListItems) {
+        $SelectedBoxItems = $ItemsForList | Sort-Object | Out-GridView -OutputMode $ChoiceMode -Title $BoxTitle
+    } else {
+        $SelectedBoxItems = $ItemsForList | Out-GridView -OutputMode $ChoiceMode -Title $BoxTitle
+    }
+    return $SelectedBoxItems
+}

README.md

@@ -0,0 +1,70 @@
+[![Language](https://img.shields.io/badge/language-powershell-blue.svg)](https://docs.microsoft.com/en-us/powershell/) 
+
+# PSGUIFunctions
+A small collection of cobbled together Powershell functions for GUI messages and user input.
+
+## Purpose and Background
+I just needed a simple and easy way to display information, warnings, get input, select a file or directory, or ask a simple response question in a GUI format for my Powershell scripts. Sure there are many great modules I could use that are much more sophisticated, but I just found it fun to make my own and only needed some basic options. That's why I pieced together PSGUIFunction's examples for input and dialog boxes. Hopefully, you can get some use from them too.
+
+**The message boxes available are:**
+* Information
+* Warning
+* Error
+* Question
+* Yes/No
+* Ok/Cancel
+* Retry/Cancel
+* Abort/Retry/Ignore
+
+**The input boxes available are:**
+* String/Integer Input Box (returns a string or integer if entered)
+* Listbox Input (returns the selection(s) from a given array)
+
+**The dialog boxes available are:**
+* Select Filename (returns full path to file selected)
+* Save As Filename (returns full path to file and name for saving)
+* Select Directory (returns full path to directory selected)
+
+![Example Image](https://tildeforge.dev/mlot/PSGUIFunctions/raw/branch/main/Hello_World.png "Example Image")
+
+## Requirements
+* [ ] Windows Powershell 5.1 and/or Powershell Core 7
+
+Tested with Windows 11 x64 Version 23H2
+
+## Installation
+No install required. Just copy and paste the examples from within the PSGUIFunctions.ps1 file directly into your own script and modify as needed.
+
+Downloading PSGUIFunctions.ps1 using [cURL](https://curl.haxx.se/):
+
+```
+curl -o PSGUIFunctions.ps1 https://tildeforge.dev/mlot/PSGUIFunctions/raw/branch/main/PSGUIFunctions.ps1
+```
+
+## Example Use
+
+Copy and paste the function examples from within the PSGUIFunctions.ps1 file directly into your own script and call the function passing the required or optional arguments:
+```powershell
+function Select-Folder {
+    <#
+    .SYNOPSIS
+     Opens a folder selection dialog and returns full path to the folder.
+
+    .EXAMPLE
+     $selectedFolder = Select-Folder
+    #>
+    Add-Type -AssemblyName System.Windows.Forms
+    $FolderSelect = New-Object System.Windows.Forms.FolderBrowserDialog
+    $null = $FolderSelect.ShowDialog()
+    $SelectedFolder = $FolderSelect.SelectedPath
+    return $SelectedFolder
+}
+
+$selectedFolder = Select-Folder  # Returns the full path to the selected folder assigning it to the $selectedFolder variable
+```
+
+## Contributing
+If you want to contribute new functions or improve the exisiting ones, feel free to clone the repo and submit a pull request. And thanks for any time and help!
+
+## License
+[MIT License](https://opensource.org/licenses/MIT) for PSGUIFunctions