Functions/New-Popup.ps1
|
function New-PopUp { <# .SYNOPSIS New-Popup will display a popup message .DESCRIPTION The New-Popup command uses the Wscript.Shell PopUp method to display a graphical message box. You can customize its appearance of icons and buttons. By default the user must click a button to dismiss but you can set a timeout value in seconds to automatically dismiss the popup. The command will write the return value of the clicked button to the pipeline: OK = 1 Cancel = 2 Abort = 3 Retry = 4 Ignore = 5 Yes = 6 No = 7 If no button is clicked, the return value is -1. .EXAMPLE new-popup -message "The update script has completed" -title "Finished" -time 5 This will display a popup message using the default OK button and default Information icon. The popup will automatically dismiss after 5 seconds. .EXAMPLE $answer = new-popup -Message "Please pick" -Title "form" -buttons "OKCancel" -icon "information" If the user clicks "OK" the $answer variable will be equal to 1. If the user clicks "Cancel" the $answer variable will be equal to 2. .NOTES Last Updated: 6/17/2018 .PARAMETER Message The message you want displayed .PARAMETER Title The text to appear in title bar of dialog box .PARAMETER Time The time to display the message. Defaults to 0 (zero) which will keep dialog open until a button is clicked .PARAMETER Buttons Valid values for -Buttons include: "OK" "OKCancel" "AbortRetryIgnore" "YesNo" "YesNoCancel" "RetryCancel" .PARAMETER Icon Valid values for -Icon include: "Stop" "Question" "Exclamation" "Information" "None" .PARAMETER ShowOnTop Switch which will force the popup window to appear on top of all other windows. .PARAMETER AsString Will return a human readable representation of which button was pressed as opposed to an integer value. .INPUTS None .OUTPUTS An integer with the following value depending upon the button pushed. Timeout = -1 # Value when timer finishes countdown. OK = 1 Cancel = 2 Abort = 3 Retry = 4 Ignore = 5 Yes = 6 No = 7 .LINK Wscript.Shell #> #region Parameters [CmdletBinding()] [OutputType('int')] Param ( [Parameter(Position=0,Mandatory,HelpMessage='Enter a message for the popup')] [ValidateNotNullorEmpty()] [string] $Message, [Parameter(Position=1,Mandatory,HelpMessage='Enter a title for the popup')] [ValidateNotNullorEmpty()] [string] $Title, [Parameter(Position=2)] [ValidateScript({$_ -ge 0})] [int] $Time=0, [Parameter(Position=3)] [ValidateNotNullorEmpty()] [ValidateSet('OK','OKCancel','AbortRetryIgnore','YesNo','YesNoCancel','RetryCancel')] [string] $Buttons='OK', [Parameter(Position=4)] [ValidateNotNullorEmpty()] [ValidateSet('Stop','Question','Exclamation','Information','None' )] [string] $Icon='None', [Parameter(Position=5)] [switch] $ShowOnTop, [Parameter(Position=6)] [switch] $AsString ) #endregion Parameters Begin { Write-Verbose -Message "Starting $($MyInvocation.Mycommand)" } process { # set $ShowOnTopValue based on switch if ($ShowOnTop) { $ShowOnTopValue = 4096 } else { $ShowOnTopValue = 0 } #lookup key to convert buttons to their integer equivalents $ButtonsKey = @{ 'OK' = 0 'OKCancel' = 1 'AbortRetryIgnore' = 2 'YesNo' = 4 'YesNoCancel' = 3 'RetryCancel' = 5 } #lookup key to convert icon to their integer equivalents $IconKey = @{ 'Stop' = 16 'Question' = 32 'Exclamation' = 48 'Information' = 64 'None' = 0 } #lookup key to convert return value to human readable button press $ReturnKey = @{ -1 = 'Timeout' 1 = 'OK' 2 = 'Cancel' 3 = 'Abort' 4 = 'Retry' 5 = 'Ignore' 6 = 'Yes' 7 = 'No' } #create the COM Object Try { $wshell = New-Object -ComObject Wscript.Shell -ErrorAction Stop #Button and icon type values are added together to create an integer value $return = $wshell.Popup($Message,$Time,$Title,$ButtonsKey[$Buttons] + $Iconkey[$Icon] + $ShowOnTopValue) if ($return -eq -1) { write-verbose -Message "User timedout [$($returnkey[$return])] after [$time] seconds" } else { write-verbose -Message "User pressed [$($returnkey[$return])]" } if ($AsString) { $ReturnKey[$return] } else { $return } } Catch { #You should never really run into an exception in normal usage Write-Warning -Message 'Failed to create Wscript.Shell COM object' Write-Warning -Message ($_.exception.message) } } End { Write-Verbose -Message "Ending $($MyInvocation.Mycommand)" } } # EndFunction New-PopUp |