====== Add menu item ======

===== Synopsis =====

    item [--menu <menu>] [--key <key>] [--default] [<label>|--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

===== Description =====

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

The label will not be displayed.  It will be used by the ''[[:cmd:choose]]'' command to indicate the selection made by the user.

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 item was successfully added          |
^ Failure   | The menu item was not successfully added      |

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

  * ''[[:cmd:menu]]''
  * ''[[:cmd:choose]]''
  * 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 <label>%%'' option when displaying the menu with the ''[[:cmd:choose]]'' command.

If you want your menu 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 ----------------