Editing EDF menu reference

New to EDF 1.6, dynamic menus allow the Eternity Engine's menu system to be customized in various ways, including through the definition of the custom user menu and via overriding of specific menus within the native menu heirarchy. 

Remember that all fields are optional and may be provided in any order. Note that the order of item sections within a menu is important, however. 
{{backto|EDF}}
==Syntax==
 menu <unique mnemonic>
 {
   # one or more item sections can exist; the items appear on the menu in the
   # order they are defined within their parent menu section
   item
   {
      type  = <menu item type name>
      text  = <string>
      cmd   = <string>
      patch = <string>
      flags = <menu item flags string>
   }
   
   prevpage = <menu mnemonic>
   nextpage = <menu mnemonic>
   x        = <number>
   y        = <number>
   first    = <number>
   flags    = <menu flags string>
 }
==Explanation of Fields==
*item
:Default = No default
:One or more items must be defined in every menu. There is no upper limit on the number of item sections. The items will appear in the menu in the same order in which they were defined in EDF.
:Explanation of menu item fields:
:*type
::Default = info
::One of the following values with the given meanings: 
::*info - The item is an informational string. It cannot be selected or execute a command, even if one is provided. This type of item is used as a section title. It is usual for the text to be given gold coloration, but this is up to the user. 
::*gap - The item is a gap of blank space. It cannot be selected or execute a command. The amount of space is determined by the font used by the menu. 
::*runcmd - This item type executes a command when the key bound to menu_confirm is pressed while it is selected. Only the text description is displayed; there is no value or other graphic to the right. If the command provided to this item is invalid, this item will be disabled. 
::*variable - This item type allows editing of a console variable's value directly. The value editing must be done by typing in the new value. The value will appear to the right of the text description of this item at a distance determined by the layout of the menu. If the variable provided to this item is invalid, it will be disabled. 
::*toggle - This item allows editing of a console variable's value using the menu_left or menu_right actions to scroll through its possible set of values. This type of item is only appropriate for console variables which are of "yes/no", "on/off", or "named value" types. The value of the variable will appear to the right of the text description of this item at a distance determined by the layout of the menu. If the variable provided to this item is invalid, it will be disabled. 
::*title - This item type is appropriate only for use as the main title of the menu. Titles are drawn using the gamemode's "Big" font if no graphic patch is available for them. In Heretic, menu title text is also shadowed by default. This type of item has no value, is not selectable, and cannot execute a command. 
::*slider - This item type allows editing of a console variable's value using a slider. The slider will appear to the right of the text description at a distance determined by the menu's layout. If the variable assigned to this item is invalid, the slider will be disabled. Sliders are only appropriate for use with ranged integer console variables. 
::*automap - This item is an automap color selector. 
::*binding - This item is a keybinding. The value provided to the cmd field must be a key action name instead of a console command. The keys currently bound to the action will appear to the right of text description at a distance determined by the menu's layout. 
::*bigslider - This item is a giant slider for emulated menus. Otherwise, it works similar to the normal slider. 
*text
::Default = ""
::This is the textual description of the menu item, which is drawn for all item types unless a valid patch graphic is specified, in which case it will be drawn instead. The height of the menu item is determined by the text or graphic used by the item, and item spacing is performed automatically by the menu engine. 
:*cmd
::Default = No default
::This is the console command, console variable, or other special value which this item will execute or set a value to when it is activated. This field only has meaning for item types which are selectable. Non-selectable types will ignore it entirely. If a runcmd, variable, toggle, slider, automap, or binding item type is given an invalid console command or variable, the item will be disabled by the menu engine. 
:*patch
::Default = No default
::If specified, this field will override the text description with a patch graphic of the given name. If the patch named doesn't exist amongst all loaded WAD files, the text description will appear instead. If the graphic named exists but is not a valid patch graphic lump, behavior is undefined. 
:*flags
::A BEX-format flags field which can accept any combination of the following values. All values are off by default. 
         Flag name       Effect
        --------------------------------------------------------------------
         BIGFONT         Item uses the gamemode's "big" font
         CENTERED        Menu item is centered. Useful only for info items.
         LALIGNED        Menu item is aligned to the left.
        --------------------------------------------------------------------
        
::Example: 
        menu foo
        {
           item { type = info; text = "Hello EDF!"; flags = BIGFONT|CENTERED }
        }
        
::As with all other BEX-format flag fields, if the field's value contains whitespace, commas, or other characters disallowed in unquoted strings, you must surround the entire field value in single or double quotation marks. 
*prevpage
:Default = No default
:This field specifies the previous page of this menu. Menus may be attached to each other in a circular chain of pages, which can be perused either by pressing Ctrl plus the keys bound to menu_left or menu_right, or by pressing the keys bound to menu_pageup or menu_pagedown. The default value means that there is no previous page. If the menu named by this field does not exist, there will also be no previous page. Table of contents functionality is not available for dynamic menus. 
*nextpage
:Default = No default
:This field specifies the next page of this menu. It is otherwise identical to the prevpage field above. 
*x
:Default = 200
:Specifies the x offset of the menu starting from the upper lefthand corner of the screen. Menu coordinates are relative to a 320x200 screen and are scaled at runtime by the game engine. All patches are clipped to the screen, so it is not harmful if a menu or any items on it extend off the framebuffer. Note that this value specifies the right end of description strings for normal menu items. Item values will be drawn further to the right of this. 
*y
:Default = 15
:Specifies the y offset of the menu starting from the upper lefthand corner of the screen. Menu coordinates are relative to a 320x200 screen and are scaled at runtime by the game engine. 
first
*Default = 0
:Zero-based index of the first item that should be selected on the menu. If this value is out of range or is set to a normally unselectable item, the selection pointer will not appear until the user moves to a new item, at which point it will appear to jump to the proper item. On most native menus, the first selectable item is at index 3. This is due to a title, gap, and info item usually being the first three items on the menu. 
*flags
:A BEX-format flags field which can accept any combination of the following values. All values are off by default. 
      Flag name       Effect
     ------------------------------------------------------------------------
      skullmenu       This menu uses the large skull pointer.
      background      This menu has a background and uses the small pointer.
      leftaligned     This menu is aligned to the left. Does not work with
                      all item types.
      centeraligned   All items on this menu are centered. Not useful for
                      menus that contain anything other than title, gap,
                      info, or command items.
      emulated        This menu is an emulated original DOOM menu. All items
                      are spaced at 16-pixel intervals.
     ------------------------------------------------------------------------
     
:Example: 
     menu foo
     {
        item { type = info; text = "Hello EDF!"; flags = BIGFONT }
        
        flags = skullmenu|leftaligned
     }
     
:As with all other BEX-format flag fields, if the field's value contains whitespace, commas, or other characters disallowed in unquoted strings, you must surround the entire field value in single or double quotation marks. 
==Restrictions and Caveats==
*All menus must have a unique mnemonic no longer than 32 characters. They should only contain alphanumeric characters and underscores. Length will be verified, but format will not (non-unique mnemonics will overwrite previous definitions). 
==Replacing Existing Menus==

To replace the values of an existing EDF menu definition, simply define a new menu with the exact same mnemonic value (as stated above, all menus need a unique mnemonic, so duplicate mnemonics serve to indicate that an existing menu should be replaced). 

==Example==
 /*

  Define the reserved _MN_Custom menu, which is automatically made available on
  the second page of Eternity's main options menu when it is defined.
  This is a great use for the new optional "user.edf" file. Note that by using
  the new "mn_dynamenu" command, it is possible to create your own inter-menu
  links and form a complete heirarchy of custom menus. See the console reference
  for full information.
  
 */ 
 menu _MN_Custom
 {
   item { type = title;  text = "my custom menu" }
   item { type = gap }
   item { type = info;   text = "\Hitems here" }
   item { type = runcmd; text = "get outta here!"; cmd = "mn_prevmenu" }
   
   first = 3
   flags = background
 }
==Overriding Native Menus==

Eternity allows specific native menus to be overridden by menus you define in EDF. Currently the following menus can be overridden: 
*Episode selection menu 
To override a specific menu, you set a global variable in either the root EDF or in an EMENUS lump to the mnemonic of the menu you have provided. A table of variables and the menus they replace follows: 
   EDF Variable                   Menu Overridden
  -------------------------------------------------------
   mn_episode                     Episode selection menu
  -------------------------------------------------------
Example
 /*
   This could be placed at global scope anywhere within the root chain of EDF
   files/lumps or within an EMENUS lump along with the menu it names.
 */
 mn_episode = MyEpisodeMenu
[[category:EDF]]