====== Choose menu item ======

===== Synopsis =====

    choose [--menu <menu>] [--default <label>] [--timeout <timeout>]
           [--keep] <setting>

===== Examples =====

=== Create and display a simple menu ===

    menu Please choose an operating system to boot
    item fedora   Fedora Linux
    item win7     Windows 7
    choose os

=== Choose from a menu and go to the chosen script label ===

    choose target && goto ${target}

=== Choose from menu with a default and a three-second timeout ===

    menu
    item linux    Boot Linux
    item shell    Enter iPXE shell
    item exit     Exit to BIOS
    choose --default exit --timeout 3000 target && goto ${target}

===== Description =====

Choose an item from a menu and store the result in the specified [[:settings|setting]], defaulting to the specified item after the specified timeout (in milliseconds).  If no timeout is explicitly specified, or if a zero timeout is specified, then iPXE will wait indefinitely.

{{ :screenshots:menu_graphic.png?400x300 |A sample menu}}

If no default item is explicitly specified, then the menu's pre-existing default item (if any) will be used.  If no menu is specified, the default (unnamed) menu will be used.  The menu will be automatically deleted unless the ''%%--keep%%'' option is specified.

===== Command status =====

^ Success   | A choice was stored successfully            |
^ Failure   | A choice was not stored successfully        |

===== See also =====

  * ''[[:cmd:menu]]''
  * ''[[:cmd:item]]''
  * iPXE [[:scripting|scripting]] guide
  * [[:cmd|List of all iPXE commands]]

===== Notes =====

The user is able to use Ctrl-C (or Escape) to exit the menu without making a selection.  You may therefore wish to always handle failures of the ''choose'' command.  For example:

    choose os || goto cancelled

The ''%%--default%%'' option for the ''choose'' command overrides any default item specified using the ''[[:cmd:item]]'' command.

You can use any valid setting name, including a scope and type.  For example:

    menu Select a DNS server
    item ${netX/dns}    Current DNS server (${netX}/dns)
    item 8.8.8.8        Google public DNS
    choose dns:ipv4

You can add a background picture to enhance the appearance of your menu using the ''[[:cmd:console]]'' command.