en-US/TerminalUI-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>Get-UserChoice</command:name> <command:verb>Get</command:verb> <command:noun>UserChoice</command:noun> <maml:description> <maml:para>Prompts the user to choose one of multiple options. Similar to $Host.UI.PromptForChoice, but with a different UI and more options.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Prompts the user to choose one of multiple options. Similar to $Host.UI.PromptForChoice, but with a different UI and more options.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-UserChoice</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Items</maml:name> <maml:Description> <maml:para>A list of options the user can pick from. The user will be shown these, and can choose one (or more, if -Multi is set). Items can be a list of strings, or a list of `[UserChoiceItem]` if you want more control over how they are presented to the user.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</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>Multi</maml:name> <maml:Description> <maml:para>If set, users can pick more than one option. They must choose at least one. The return value will change to a list of the chosen values (or an empty list, if the user cancels)</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>NoHelp</maml:name> <maml:Description> <maml:para>If set, don't show the user how to use the prompt (e.g. '[↑↓] Move [Enter] Submit [Esc] Cancel').</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Items</maml:name> <maml:Description> <maml:para>A list of options the user can pick from. The user will be shown these, and can choose one (or more, if -Multi is set). Items can be a list of strings, or a list of `[UserChoiceItem]` if you want more control over how they are presented to the user.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</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>Multi</maml:name> <maml:Description> <maml:para>If set, users can pick more than one option. They must choose at least one. The return value will change to a list of the chosen values (or an empty list, if the user cancels)</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>NoHelp</maml:name> <maml:Description> <maml:para>If set, don't show the user how to use the prompt (e.g. '[↑↓] Move [Enter] Submit [Esc] Cancel').</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:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>The value the user picked, or a list of values if -Multi is set.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>If the user cancels, `$null` will be returned (or `@()` if -Multi is set).</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-UserChoice 'Foo','Bar','Baz' $ User is shown a list of options ('Foo', 'Bar' and 'Baz'), of which they can pick one $ Return value will be the one they choose</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-UserChoice 'Foo','Bar','Baz' -Multi $ User is shown a list of options ('Foo', 'Bar' and 'Baz'), of which they can pick multiple $ Return value will be a list of the ones they choose</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <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>Get-UserInput</command:name> <command:verb>Get</command:verb> <command:noun>UserInput</command:noun> <maml:description> <maml:para>Prompts the user for text input. Similar to Read-Host, but with suggestions support.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Prompts the user for text input on the CLI. Supports all parameters from the built-in Read-Host (except -AsSecureString), as well as suggestions.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-UserInput</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Prompt</maml:name> <maml:Description> <maml:para>An optional text for the prompt. The function appends a colon (`:`) to the text you enter, and displays it in bold to differentiate it from the users input.</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="2" aliases="none"> <maml:name>Suggestions</maml:name> <maml:Description> <maml:para>A list of strings to use as suggestions to the user. The user will be shown these, and can autocomplete them, but is also free to enter their own values. Suggestions can be a list of strings, or a list of `[UserInputSuggestion]` if you want more control over how they are presented to the user.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>@()</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>MaxSuggestions</maml:name> <maml:Description> <maml:para>The maximum number of suggestions to show at a time.</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>3</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoHelp</maml:name> <maml:Description> <maml:para>If set, don't show the user how to use the prompt (i.e. '[↑↓] Change suggestion [Tab] Pick suggestion [Enter] Submit [Esc] Cancel'). Only relevant if `-Suggestions` is set, as the help won't be shown without suggestions.</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>MaskInput</maml:name> <maml:Description> <maml:para>If set, replace the input with '*'. This is similar to -MaskInput for the built-in Read-Host. The returned value will still be what the user entered.</maml:para> </maml:Description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Prompt</maml:name> <maml:Description> <maml:para>An optional text for the prompt. The function appends a colon (`:`) to the text you enter, and displays it in bold to differentiate it from the users input.</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="2" aliases="none"> <maml:name>Suggestions</maml:name> <maml:Description> <maml:para>A list of strings to use as suggestions to the user. The user will be shown these, and can autocomplete them, but is also free to enter their own values. Suggestions can be a list of strings, or a list of `[UserInputSuggestion]` if you want more control over how they are presented to the user.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>@()</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>MaxSuggestions</maml:name> <maml:Description> <maml:para>The maximum number of suggestions to show at a time.</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>3</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoHelp</maml:name> <maml:Description> <maml:para>If set, don't show the user how to use the prompt (i.e. '[↑↓] Change suggestion [Tab] Pick suggestion [Enter] Submit [Esc] Cancel'). Only relevant if `-Suggestions` is set, as the help won't be shown without suggestions.</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>MaskInput</maml:name> <maml:Description> <maml:para>If set, replace the input with '*'. This is similar to -MaskInput for the built-in Read-Host. The returned value will still be what the user entered.</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:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>The string the user entered.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-UserInput $ User is shown an empty line. Whatever they write will be returned after they press enter</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-UserInput -Prompt 'Test' $ User is shown a line containing 'Test: '. Whatever they write will be returned after they press enter</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-UserInput -Prompt 'Password' -MaskInput $ Whatever the user writes will be shown as a list of '*'. The returned value will be what the user entered</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Get-UserInput -Prompt 'Choose a color' -Suggestions 'Blue','Red','Green' $ The user is free to write whatever they want, but will be shown suggestions as they type</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <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-UserChoiceItem</command:name> <command:verb>New</command:verb> <command:noun>UserChoiceItem</command:noun> <maml:description> <maml:para>Creates a new item for use with Get-UserChoice. Should only be used if you need to display something other than the value the item represents.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates a new item for use with Get-UserChoice. Normally you'd simply pass a string to Get-UserChoice, but in some cases you want to display something other than the item value. In those cases you can create an item using New-UserChoiceItem that has a display string and a value.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-UserChoiceItem</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Value</maml:name> <maml:Description> <maml:para>The value to return when the item is chosen.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Display</maml:name> <maml:Description> <maml:para>The string to display in the item list.</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>$Value</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Value</maml:name> <maml:Description> <maml:para>The value to return when the item is chosen.</maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Display</maml:name> <maml:Description> <maml:para>The string to display in the item list.</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>$Value</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>An instance of the internal `[UserChoiceItem]` class.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-UserChoice @(New-UserChoiceItem 'Foo') $ Will display the item as 'Foo', when chosen will return 'Foo'</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-UserChoice @(New-UserChoiceItem -Value 'Foo' -Display 'Metasyntactic variable') $ Will display the item as 'Metasyntactic variable', when chosen will enter 'Foo'</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-UserInput @(New-UserChoiceItem 'Foo' 'Metasyntactic variable') $ Will display the item as 'Metasyntactic variable', when chosen will enter 'Foo'</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <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-UserInputSuggestion</command:name> <command:verb>New</command:verb> <command:noun>UserInputSuggestion</command:noun> <maml:description> <maml:para>Creates a new suggestion for use with Get-UserInput. Should only be used if you need to display something other than the value the suggestion represents.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates a new suggestion for use with Get-UserInput. Normally you'd simply pass a string to Get-UserInput, but in some cases you want to display something other than the suggestion value. In those cases you can create a suggestion using New-UserInputSuggestion that has a display string and a value.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-UserInputSuggestion</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Value</maml:name> <maml:Description> <maml:para>The value to enter when the suggestion is chosen.</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="2" aliases="none"> <maml:name>Display</maml:name> <maml:Description> <maml:para>The string to display in the suggestions list.</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>$Value</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Value</maml:name> <maml:Description> <maml:para>The value to enter when the suggestion is chosen.</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="2" aliases="none"> <maml:name>Display</maml:name> <maml:Description> <maml:para>The string to display in the suggestions list.</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>$Value</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>An instance of the internal `[UserInputSuggestion]` class.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-UserInput -Suggestions @(New-UserInputSuggestion 'Foo') $ Will display the suggestion as 'Foo', when chosen will enter 'Foo'</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-UserInput -Suggestions @(New-UserInputSuggestion -Value 'Foo' -Display 'Metasyntactic variable') $ Will display the suggestion as 'Metasyntactic variable', when chosen will enter 'Foo'</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-UserInput -Suggestions @(New-UserInputSuggestion 'Foo' 'Metasyntactic variable') $ Will display the suggestion as 'Metasyntactic variable', when chosen will enter 'Foo'</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> </helpItems> |