en-US/PsUi.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-UiWindow</command:name> <command:verb>New</command:verb> <command:noun>UiWindow</command:noun> <maml:description> <maml:para>Creates the main application window from a scriptblock of PsUi controls and waits until it's closed.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Builds a themed window from the controls declared in -Content and displays it. The call blocks the terminal until the window closes. The window itself runs on its own thread with its own session (control registry and captured values) so a second window opened from another console can't see the first one's controls. The theme is set for the whole process.</maml:para> <maml:para>Variables and functions from the calling scope are captured at creation and injected where actions run, which is why a button can read $server from your script without any plumbing. Functions are copied across as text and redeclared. Values are not: runspaces are in process so a hashtable an action mutates is the same hashtable your script holds. The full model lives on the Threading and Variable Hydration page.</maml:para> <maml:para>Without -Width or -Height the window sizes itself to its content, capped by -MaxWidth and -MaxHeight. -Width alone keeps the self-sizing for height.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-UiWindow</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Titlebar text.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>PowerShell GUI</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Content</maml:name> <maml:description> <maml:para>A scriptblock of PsUi controls laid out in the order declared. Layout containers (New-UiPanel, New-UiGrid, New-UiTab) nest freely. An empty block is a terminating error, caught before any window appears.</maml:para> <maml:para>When a command in the block writes a non-terminating error such as Get-ChildItem on a missing folder, New-UiWindow writes it out with the file and line in front of it and the window opens anyway. PsUi's own commands stop the window when they fail since a window missing a control is worse than no window, and so does a throw or a command run with -ErrorAction Stop. A failed expression such as 1 / 0 stops it too and so does a .NET method that throws. Passing -ErrorAction Continue to that PsUi command writes its error and opens the window without the control.</maml:para> <maml:para>The block starts from New-UiWindow's own error action which is -ErrorAction when it is passed and the calling script's $ErrorActionPreference when it isn't. Under Stop the first error of any kind ends the block on that line and the window never opens. New-UiWindow then fails the way any command run with -ErrorAction Stop fails. Under SilentlyContinue or Ignore the errors stay hidden, and a PsUi control that fails to build, such as New-UiImage on a missing file, is left out while the rest of the block builds. Setting $ErrorActionPreference inside the block, or passing -ErrorAction to a single command, decides what happens to the errors a command writes, the way it does in any script. New-UiWindow's -ErrorVariable collects every error it writes.</maml:para> <maml:para>A PsUi command given a parameter it rejects, such as New-UiProgress with -Maximum below -Minimum or New-UiLabel with a -Style outside its set, stops the window under any preference since the script called it wrong. When the calling script itself runs under SilentlyContinue, a window that stops that way prints no error, like any command that fails under that preference, and the error is waiting in $Error. -ErrorAction on a container such as New-UiPanel doesn't reach the commands inside its block, the same as -ErrorAction on ForEach-Object. 5.1 doesn't accept Ignore as $ErrorActionPreference, and a PsUi control given -ErrorAction Ignore sets that preference inside itself, so on 5.1 use SilentlyContinue in both places. -ErrorAction Ignore on New-UiWindow itself works on 5.1 and 7 alike.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Width in pixels, 200 to 2000. Leave out both -Width and -Height and the window sizes itself to its content instead.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Height</maml:name> <maml:description> <maml:para>Height in pixels, 150 to 1500. Giving -Width without -Height keeps the self-sizing behavior for height alone.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxWidth</maml:name> <maml:description> <maml:para>Ceiling for the self-sized width, 300 to 2000. Only matters when the window is sizing itself to content.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>800</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxHeight</maml:name> <maml:description> <maml:para>Ceiling for the self-sized height, 200 to 1500.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>900</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Theme</maml:name> <maml:description> <maml:para>The theme name, any of the built-in ones or one registered with Register-UiTheme. Auto, the default, follows the OS light or dark setting.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Auto</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ThemePath</maml:name> <maml:description> <maml:para>Path to a theme JSON file (the key set Get-UiThemeTemplate prints). The theme registers under the file's base name and this window opens in it.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IconFont</maml:name> <maml:description> <maml:para>Icon font for this window: Inherit (default, keeps whatever Set-PsUiIconFont last established), Auto (re-detects), SegoeMDL2, or SegoeFluentIcons. The previous active font comes back when the window closes.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Inherit</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Auto</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SegoeMDL2</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SegoeFluentIcons</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Inherit</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoIconFontFallback</maml:name> <maml:description> <maml:para>Pins the chosen icon font without a fallback chain so glyphs missing from it render as tofu instead of borrowing from the other Segoe font. On a Windows 10 box with only MDL2 installed there is no secondary font anyway. The remaining effect is tighter IntelliSense for -Icon names.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoResize</maml:name> <maml:description> <maml:para>Locks the window size without a resize grip or edge dragging.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Icon</maml:name> <maml:description> <maml:para>Accepted for scripts written against an earlier build and currently unused. The titlebar icon comes from -Logo or from a generated icon in the theme colors when there is none.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>LayoutMode</maml:name> <maml:description> <maml:para>Stack (default) lays controls out in a single column. Responsive wraps them side by side as the width allows, up to -MaxColumns across.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Responsive</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Stack</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Stack</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxColumns</maml:name> <maml:description> <maml:para>Column ceiling for -LayoutMode Responsive, 1 to 4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>2</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TabAlignment</maml:name> <maml:description> <maml:para>Left or Center placement for the tab headers when the content declares New-UiTab blocks.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Left</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Center</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Left</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MinimizeConsole</maml:name> <maml:description> <maml:para>Minimizes the console window while the window is open and restores it on close.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WPFProperties</maml:name> <maml:description> <maml:para>Hashtable of extra WPF properties to set on the window, for anything not exposed as a parameter. Similar to every control's -WPFProperties. Dot notation reaches attached properties, and string values convert to the target type, so `Cursor = 'Hand'` and `ResizeMode = 'NoResize'` work as written. Tag is reserved (it holds the window chrome) and gets stripped with a warning. If a value won't convert, a [PsUi] Warning line prints on the console, and if a name doesn't resolve it's skipped silently.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HideThemeButton</maml:name> <maml:description> <maml:para>Removes the titlebar palette button when you'd rather users not restyle your tool.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsyncApartment</maml:name> <maml:description> <maml:para>Which thread waits on each async action. MTA, the default, uses a thread pool thread. STA starts a new STA thread for every run, which is slower. The action itself runs on an STA thread in both modes so Windows Forms dialogs and COM objects that need one work under the default. The parameter stays for scripts that already pass it.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">STA</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">MTA</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>MTA</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="NoCapture"> <maml:name>NoImplicitCapture</maml:name> <maml:description> <maml:para>Skips capturing the calling scope's variables and functions at window creation. Startup gets faster in a console holding a large session, at a price: neither -Content nor the actions see your script's variables or functions. Control values still hydrate.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the Window object as soon as the window is up instead of blocking until it closes. The console stays usable while the window runs on its own thread.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ExportOnClose</maml:name> <maml:description> <maml:para>Writes the window's captured values back into the calling scope when the window closes. That covers what -Capture on a button or Invoke-UiAsync collected and anything stored with Set-UiCapturedVariable. Control values aren't collected at close. Ignored with -PassThru which returns before there is anything to export.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Loading"> <maml:name>Splash</maml:name> <maml:description> <maml:para>Shows a small themed splash with an indeterminate progress bar while the window builds. Use it for a window that takes a moment to construct.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Logo</maml:name> <maml:description> <maml:para>Path to an image used as the titlebar and taskbar icon, and as the splash centerpiece under -Splash. Without one, PsUi generates an icon from the theme colors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Titlebar text.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>PowerShell GUI</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Content</maml:name> <maml:description> <maml:para>A scriptblock of PsUi controls laid out in the order declared. Layout containers (New-UiPanel, New-UiGrid, New-UiTab) nest freely. An empty block is a terminating error, caught before any window appears.</maml:para> <maml:para>When a command in the block writes a non-terminating error such as Get-ChildItem on a missing folder, New-UiWindow writes it out with the file and line in front of it and the window opens anyway. PsUi's own commands stop the window when they fail since a window missing a control is worse than no window, and so does a throw or a command run with -ErrorAction Stop. A failed expression such as 1 / 0 stops it too and so does a .NET method that throws. Passing -ErrorAction Continue to that PsUi command writes its error and opens the window without the control.</maml:para> <maml:para>The block starts from New-UiWindow's own error action which is -ErrorAction when it is passed and the calling script's $ErrorActionPreference when it isn't. Under Stop the first error of any kind ends the block on that line and the window never opens. New-UiWindow then fails the way any command run with -ErrorAction Stop fails. Under SilentlyContinue or Ignore the errors stay hidden, and a PsUi control that fails to build, such as New-UiImage on a missing file, is left out while the rest of the block builds. Setting $ErrorActionPreference inside the block, or passing -ErrorAction to a single command, decides what happens to the errors a command writes, the way it does in any script. New-UiWindow's -ErrorVariable collects every error it writes.</maml:para> <maml:para>A PsUi command given a parameter it rejects, such as New-UiProgress with -Maximum below -Minimum or New-UiLabel with a -Style outside its set, stops the window under any preference since the script called it wrong. When the calling script itself runs under SilentlyContinue, a window that stops that way prints no error, like any command that fails under that preference, and the error is waiting in $Error. -ErrorAction on a container such as New-UiPanel doesn't reach the commands inside its block, the same as -ErrorAction on ForEach-Object. 5.1 doesn't accept Ignore as $ErrorActionPreference, and a PsUi control given -ErrorAction Ignore sets that preference inside itself, so on 5.1 use SilentlyContinue in both places. -ErrorAction Ignore on New-UiWindow itself works on 5.1 and 7 alike.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Width in pixels, 200 to 2000. Leave out both -Width and -Height and the window sizes itself to its content instead.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Height</maml:name> <maml:description> <maml:para>Height in pixels, 150 to 1500. Giving -Width without -Height keeps the self-sizing behavior for height alone.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxWidth</maml:name> <maml:description> <maml:para>Ceiling for the self-sized width, 300 to 2000. Only matters when the window is sizing itself to content.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>800</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxHeight</maml:name> <maml:description> <maml:para>Ceiling for the self-sized height, 200 to 1500.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>900</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Theme</maml:name> <maml:description> <maml:para>The theme name, any of the built-in ones or one registered with Register-UiTheme. Auto, the default, follows the OS light or dark setting.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Auto</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ThemePath</maml:name> <maml:description> <maml:para>Path to a theme JSON file (the key set Get-UiThemeTemplate prints). The theme registers under the file's base name and this window opens in it.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IconFont</maml:name> <maml:description> <maml:para>Icon font for this window: Inherit (default, keeps whatever Set-PsUiIconFont last established), Auto (re-detects), SegoeMDL2, or SegoeFluentIcons. The previous active font comes back when the window closes.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Inherit</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoIconFontFallback</maml:name> <maml:description> <maml:para>Pins the chosen icon font without a fallback chain so glyphs missing from it render as tofu instead of borrowing from the other Segoe font. On a Windows 10 box with only MDL2 installed there is no secondary font anyway. The remaining effect is tighter IntelliSense for -Icon names.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoResize</maml:name> <maml:description> <maml:para>Locks the window size without a resize grip or edge dragging.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Icon</maml:name> <maml:description> <maml:para>Accepted for scripts written against an earlier build and currently unused. The titlebar icon comes from -Logo or from a generated icon in the theme colors when there is none.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>LayoutMode</maml:name> <maml:description> <maml:para>Stack (default) lays controls out in a single column. Responsive wraps them side by side as the width allows, up to -MaxColumns across.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Stack</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxColumns</maml:name> <maml:description> <maml:para>Column ceiling for -LayoutMode Responsive, 1 to 4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>2</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TabAlignment</maml:name> <maml:description> <maml:para>Left or Center placement for the tab headers when the content declares New-UiTab blocks.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Left</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MinimizeConsole</maml:name> <maml:description> <maml:para>Minimizes the console window while the window is open and restores it on close.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WPFProperties</maml:name> <maml:description> <maml:para>Hashtable of extra WPF properties to set on the window, for anything not exposed as a parameter. Similar to every control's -WPFProperties. Dot notation reaches attached properties, and string values convert to the target type, so `Cursor = 'Hand'` and `ResizeMode = 'NoResize'` work as written. Tag is reserved (it holds the window chrome) and gets stripped with a warning. If a value won't convert, a [PsUi] Warning line prints on the console, and if a name doesn't resolve it's skipped silently.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HideThemeButton</maml:name> <maml:description> <maml:para>Removes the titlebar palette button when you'd rather users not restyle your tool.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsyncApartment</maml:name> <maml:description> <maml:para>Which thread waits on each async action. MTA, the default, uses a thread pool thread. STA starts a new STA thread for every run, which is slower. The action itself runs on an STA thread in both modes so Windows Forms dialogs and COM objects that need one work under the default. The parameter stays for scripts that already pass it.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>MTA</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="NoCapture"> <maml:name>NoImplicitCapture</maml:name> <maml:description> <maml:para>Skips capturing the calling scope's variables and functions at window creation. Startup gets faster in a console holding a large session, at a price: neither -Content nor the actions see your script's variables or functions. Control values still hydrate.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the Window object as soon as the window is up instead of blocking until it closes. The console stays usable while the window runs on its own thread.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ExportOnClose</maml:name> <maml:description> <maml:para>Writes the window's captured values back into the calling scope when the window closes. That covers what -Capture on a button or Invoke-UiAsync collected and anything stored with Set-UiCapturedVariable. Control values aren't collected at close. Ignored with -PassThru which returns before there is anything to export.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Loading"> <maml:name>Splash</maml:name> <maml:description> <maml:para>Shows a small themed splash with an indeterminate progress bar while the window builds. Use it for a window that takes a moment to construct.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Logo</maml:name> <maml:description> <maml:para>Path to an image used as the titlebar and taskbar icon, and as the splash centerpiece under -Splash. Without one, PsUi generates an icon from the theme colors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Windows.Window</maml:name> </dev:type> <maml:description> <maml:para>Only with -PassThru. Without it, the call has no output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>-Debug flips on PsUi's internal diagnostic stream for everything the window runs. -Verbose does the same for verbose output. Both are the first thing to reach for when a window misbehaves.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code># The smallest useful tool. Blocks here until the window is closed. New-UiWindow -Title 'My First Tool' -Content { New-UiInput -Label 'Name' -Variable 'userName' New-UiButton -Text 'Greet' -Action { Write-Host "Hello, $userName!" } }</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code># Fixed size, dark theme, and no palette button so users can't restyle it New-UiWindow -Title 'Settings' -Width 500 -Height 400 -Theme Dark -HideThemeButton -Content { New-UiToggle -Label 'Enable dark mode' -Variable 'darkMode' New-UiSlider -Label 'Volume' -Variable 'volume' -Minimum 0 -Maximum 100 -Default 50 }</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code># A splash with the company logo while a heavy window builds; the logo doubles as the window icon New-UiWindow -Title 'Inventory' -Splash -Logo 'C:\Tools\logo.png' -Content { Get-HotFix | New-UiDataGrid -Variable 'hotfixes' -Fill }</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code># -PassThru hands back the Window object immediately instead of blocking the console $window = New-UiWindow -Title 'Monitor' -PassThru -Content { New-UiLabel -Text 'Watching...' }</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code># Click Save, close the window, and the captured values come back to the console New-UiWindow -Title 'New User' -ExportOnClose -Content { New-UiInput -Label 'Username' -Variable 'user' New-UiToggle -Label 'Admin' -Variable 'isAdmin' New-UiButton -Text 'Save' -Capture 'savedUser', 'savedAdmin' -Action { $savedUser = $user $savedAdmin = $isAdmin Write-Host "Saved $user" } } Write-Host "Creating $savedUser (admin: $savedAdmin)"</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/jlabon2/PsUi/wiki/New-UiWindow</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Getting Started</maml:linkText> <maml:uri>https://github.com/jlabon2/PsUi/wiki/Getting-Started</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Threading and Variable Hydration</maml:linkText> <maml:uri>https://github.com/jlabon2/PsUi/wiki/Threading-and-Variable-Hydration</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Sessions and Window Isolation</maml:linkText> <maml:uri>https://github.com/jlabon2/PsUi/wiki/Sessions-and-Window-Isolation</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Theming and Custom Themes</maml:linkText> <maml:uri>https://github.com/jlabon2/PsUi/wiki/Theming-and-Custom-Themes</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-UiChildWindow</maml:linkText> <maml:uri>https://github.com/jlabon2/PsUi/wiki/New-UiChildWindow</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Close-UiWindow</maml:linkText> <maml:uri>https://github.com/jlabon2/PsUi/wiki/Close-UiWindow</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |