====== Add menu item or form item ======

===== Synopsis =====

    item [--menu <menu>] [--key <key>] [--default] [<name>|--gap [<text>]]

    item [--form <form>] [--key <key>] [--default] [--secret] [<name>|--gap [<text>]]

===== 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
    
=== Add a menu item with a shortcut key ===

    item --key f fedora   Fedora Linux

=== Add a dynamic menu item ===

    item san      Boot from ${root-path}

=== Add a menu separator ===

    item --gap Operating systems:

=== Add a blank menu separator ===

    item

=== Create and display a simple form ===

    form                IPv4 networking
    item netX/ip        IPv4 address
    item netX/netmask   Subnet mask
    item netX/gateway   Gateway address
    present

=== Create and display a form with a secret field ===

    form                    Login credentials
    item          email     Email address
    item --secret password  Password
    present

===== Description =====

Add a menu item or form item with the specified name and display text.  If no menu or form is specified, the default menu or form will be used.  If a key is specified, it will be used as the shortcut key for the item.  If the ''%%--default%%'' option is specified, the item will become the default selection.  If no name is provided or if the ''%%--gap%%'' option is specified, the item will function as a separator (which cannot be selected by the user).

The name will not be displayed.  For menu items, it will be used by the ''[[:cmd:choose]]'' command to indicate the selection made by the user.  For form items, it will be used by the ''[[:cmd:present]]'' command to determine the [[:settings|setting]] into which the value will be stored.

The shortcut key can be specified as a character literal (such as ''f'') or as an extended ASCII character value.  The values for special keys such as ''Ctrl-B'' and ''F12'' are defined in [[http://git.ipxe.org/ipxe.git/blob/HEAD:/src/include/ipxe/keys.h|include/ipxe/keys.h]] within the iPXE source code.  Some useful values are:

^ Key      ^ Keycode   |
| Ctrl-A   | 0x01      |
| Ctrl-B   | 0x02      |
| Ctrl-C   | 0x03      |
| ...                 ||
| Ctrl-Z   | 0x1a      |
| F5       | 0x107e    |
| F6       | 0x127e    |
| F7       | 0x137e    |
| F8       | 0x147e    |
| F9       | 0x157e    |
| F10      | 0x167e    |
| F11      | 0x187e    |
| F12      | 0x197e    |

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

^ Success   | The menu or form item was successfully added          |
^ Failure   | The menu or form item was not successfully added      |

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

  * ''[[:cmd:menu]]''
  * ''[[:cmd:form]]''
  * ''[[:cmd:choose]]''
  * ''[[:cmd:present]]''
  * iPXE [[:scripting|scripting]] guide
  * [[:cmd|List of all iPXE commands]]

===== Notes =====

The display text will be truncated if necessary to fit within the available width.

Shortcut keys are not automatically displayed.  You may wish to include an indication of the shortcut key within the display text.  For example:

    item --key f   fedora   Boot (F)edora
    item --key x   winxp    Boot Windows (X)P

You can specify a menu's default item either by using the ''%%--default%%'' option when creating the menu item with the ''item'' command, or by using the ''%%--default <name>%%'' option when displaying the menu with the ''[[:cmd:choose]]'' command.

If you want your separator text to start with dashes, then you must use ''%%--%%'' to prevent iPXE from attempting to interpret your separator text as an option.  For example:

    item --gap -- ---------------- Advanced configuration ----------------