View source for Script:System/menu.js

The [[Script:system|system script]] [[Script:system/menu.js|menu.js]] provides a simple menu object.

__TOC__

==Usage==
{{usage|func=[[API:RequireSystemScript|RequireSystemScript]]|params="menu.js"}}

==Variables and functions of menu.js==
*	object constructor '''Menu()'''
**	properties of objects of Menu type:
***	'''font''' - a [[API:Font|font object]] used by the menu. Defaults to the [[API:GetSystemFont|system font]] if not specified.
***	'''window_style''' - a [[API:WindowStyle|window style object]] used as a menu background. Defaults to the [[API:GetSystemWindowStyle|system window style]] if not specified.
***	'''arrow''' - an [[API:Image|image object]] representing the menu arrow image. Defaults to the [[API:GetSystemArrow|system arrow]] if not specified.
***	'''up_arrow''' - an [[API:Image|image object]] to be used as an up arrow if the menu content exceeds the window. Defaults to the [[API:GetSystemUpArrow|system up arrow]] if not specified.
***	'''down_arrow''' - an [[API:Image|image object]] to be used as a down arrow if the menu content exceeds the window. Defaults to the [[API:GetSystemDownArrow|system down arrow]] if not specified.
***	'''escape_function''' - a function to be called when the escape key is pressed.
**	methods of objects of Menu type:
***	'''addItem(name, callback [, color])''' - adds an entry to the menu. The string 'name' specifies the menu text, 'callback' is a function to be called when the item is selected and 'color' is a [[API:Color|color object]] defining the color of the item. If the color remains unspecified it is set to white.
***	'''execute(x, y, width, height)''' - this displays and executes the menu. The arguments 'x', 'y', 'width' and 'height' define the size of the menu window. If the menu items don't fit into the window, the menu will be scrollable.

==Example==
<syntaxhighlight>
RequireSystemScript("menu.js");

var MainMenu = new Menu();
MainMenu.addItem("Items", ItemMenu);
MainMenu.addItem("Equip", EquipMenu);
MainMenu.addItem("Magic", MagicMenu);
MainMenu.addItem("Stats", StatsMenu);
MainMenu.addItem("Quit", Exit);

MainMenu.execute(20, 20, 50, 60);
</syntaxhighlight>

The following functions are called if their respective menu item is selected. They have to be defined for the above to work. [[API:Exit|Exit]](), which is called by the last menu item, doesn't need to be defined, because it is a function of the [[API:Functions|Sphere API]].
<syntaxhighlight>
function ItemMenu() {
  //...
}

function EquipMenu() {
  //...
}

function MagicMenu() {
  //...
}
 
function StatsMenu() {
  //...
}
</syntaxhighlight>

==Notes==
*	The menu arrow is moved using the up and down directional keys. A selection is always confirmed with enter. Joystick input is not supported.
*	If necessary the up and down arrows will be displayed near the right border of the menu window.
*	To specify a function as an <var>escape_function</var> or <var>callback</var> function you may ''not'' use brackets.<br/><pre>/* This won't work:     */&#10;MyMenu.escape_function = DoSomething();&#10;MyMenu.addItem("New Game", NewGame());</pre><pre>/* This will work fine: */&#10;MyMenu.escape_function = DoSomething;&#10;MyMenu.addItem("New Game", NewGame);</pre>
*	Menu.js automatically includes the [[Script:System/colors.js|system script colors.js]].
*	A tutorial can be found in the {{dir|docs/system_scripts/}} directory of Sphere.
*	The famous [[Script:flik_menu.js|flik_menu.js]] is not a system script, but works similar to menu.js. It allows you to do much more though.

==External links==
*	[http://sphere.sourceforge.net/flik/docs/sphere-menu.html Flik's Sphere Central &rarr; Docs : How to use Sphere's default menu object].

[[Category:Scripts]]