AlliedModders Wiki - User contributions [en]

Menus Step By Step (SourceMod Scripting)

2017-01-18T16:09:39Z

Mitchell: removed incorrect information

The SourceMod [[Menu API (SourceMod)|Menu API]] is fairly useful for displaying an information panel, a menu, or a vote to users. This document talks specifically about menus and how to create one.

== The working menu example ==

This is the working code example that we'll be talking about in the upcoming sections. If you need to, you can come back and look at it as you read the rest of this page.

We will be using PrintToServer to print text to the server console as we run through the events.

Usage of the [[Translations (SourceMod Scripting)|Translations]] system is highly recommended and will be used in this example.

<pawn>#define CHOICE1 "#choice1"
#define CHOICE2 "#choice2"
#define CHOICE3 "#choice3"

public void OnPluginStart()
{
LoadTranslations("menu_test.phrases");
RegConsoleCmd("menu_test1", Menu_Test1);
}

public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)
{
switch(action)
{
case MenuAction_Start:
{
PrintToServer("Displaying menu");
}

case MenuAction_Display:
{
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Vote Nextmap", param1);

Panel panel = view_as<Panel>(param2);
panel.SetTitle(buffer);
PrintToServer("Client %d was sent menu with panel %x", param1, param2);
}

case MenuAction_Select:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));
if (StrEqual(info, CHOICE3))
{
PrintToServer("Client %d somehow selected %s despite it being disabled", param1, info);
}
else
{
PrintToServer("Client %d selected %s", param1, info);
}
}

case MenuAction_Cancel:
{
PrintToServer("Client %d's menu was cancelled for reason %d", param1, param2);
}

case MenuAction_End:
{
delete menu;
}

case MenuAction_DrawItem:
{
int style;
char info[32];
menu.GetItem(param2, info, sizeof(info), style);

if (StrEqual(info, CHOICE3))
{
return ITEMDRAW_DISABLED;
}
else
{
return style;
}
}

case MenuAction_DisplayItem:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));

char display[64];

if (StrEqual(info, CHOICE3))
{
Format(display, sizeof(display), "%T", "Choice 3", param1);
return RedrawMenuItem(display);
}
}
}

return 0;
}

public Action Menu_Test1(int client, int args)
{
Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);
menu.SetTitle("%T", "Menu Title", LANG_SERVER);
menu.AddItem(CHOICE1, "Choice 1");
menu.AddItem(CHOICE2, "Choice 2");
menu.AddItem(CHOICE3, "Choice 3");
menu.ExitButton = false;
menu.Display(client, 20);

return Plugin_Handled;
}</pawn>

The translation file that goes with it... addons/sourcemod/translations/menu_test.phrases.txt

<pre>"Phrases"
{
"Choice 3"
{
"en" "Choice Translated"
}

"Menu Title"
{
"en" "Menu Title Translated"
}
}</pre>

== Step by Step ==

=== OnPluginStart ===

<pawn>public void OnPluginStart()
{
LoadTranslations("menu_test.phrases");
RegConsoleCmd("menu_test1", Menu_Test1);
}</pawn>

This block is here to register the command /menu_test1 so that this menu can be tested.

This block is beyond the scope of this page. See: [[Introduction to SourceMod Plugins#Plugin Structure|Plugin Structure]] for OnPluginStart, [[Translations (SourceMod Scripting)|Translations]] for LoadTranslations, and [[Commands_(SourceMod_Scripting)|Commands]] for RegConsoleCmd.

=== Menu_Test1 ===

Menu_Test1 is a ConCmd, which is beyond the scope of this page. See: [[Commands (SourceMod Scripting)|Commands]] for more details on that. We're going to be talking about what's in it.

==== Menu ====

<pawn> Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);</pawn>

Menu takes two arguments.

The first is a function that matches the [https://sm.alliedmods.net/new-api/menus/MenuHandler MenuHandler] callback signature.

The second is a bitmask of which MenuAction events we are going to handle in our MenuHandler. There are 7 that apply to standard menus:
* MenuAction_Start - Called once when a menu is displayed
* MenuAction_Display - Called once for each client a menu is displayed to
* MenuAction_Select - Called when a client makes a selection from the menu that isn't Previous, Next, Back, or Exit.
* MenuAction_Cancel - Called when a client closes a menu or it is closed on them
* MenuAction_End - Called once when all clients have closed the menu
* MenuAction_DrawItem - Called once for each item for each user a menu is displayed to. Can change the menu item style.
* MenuAction_DisplayIitem. - Called once for each item for each user a menu is displayed to. Can change the menu item text.

These will be discussed in more detail in the MenuHandler1 section.

Of those 7, 3 are called whether you specify them or not: MenuAction_Select, MenuAction_Cancel, and MenuAction_End.

MENU_ACTIONS_DEFAULT sets just the 3 required fields, while MENU_ACTIONS_ALL specifies all 10 actions (including the 3 vote actions).

To specify just a few of them, you can do this:

<pawn> Menu menu = new Menu(MenuHandler1, MenuAction_Start|MenuAction_Select|MenuAction_Cancel|MenuAction_End);</pawn>

==== menu.SetTitle ====
<pawn> menu.SetTitle("%T", "Menu Title", LANG_SERVER);</pawn>

Sets the menu's title. This example uses the translation system and the server's default language. This isn't strictly necessary as we will set the menu title again later.

==== menu.AddItem ====

<pawn> menu.AddItem(CHOICE1, "Choice 1");
menu.AddItem(CHOICE2, "Choice 2");
menu.AddItem(CHOICE3, "Choice 3");</pawn>

A menu isn't useful without something in it!
menu.AddItem has 2 required arguments and one optional argument.

The 3 required arguments are:

The Info string, and the Display string.

The Info String is a string that is used to uniquely identify this menu item. It is never displayed to the user, but is used in various callbacks.

The Display String is the default text to be used for this item on the menu. It can be changed via the menu's MenuAction_DisplayItem callback.

The optional argument is the menu's item draw style. It can be one of these values:
* ITEMDRAW_DEFAULT - Displays text as normal.
* ITEMDRAW_DISABLED - Item is displayed and has a number, but can't be selected.
* ITEMDRAW_RAWLINE - Item is displayed, but doesn't have a number assigned to it and thus can't be selected
* ITEMDRAW_NOTEXT - Draws an item with no text. Not very useful.
* ITEMDRAW_SPACER - Item is blank, but has a number. Can't be selected.
* ITEMDRAW_IGNORE - Item is blank with no number. Can't be selected.
* ITEMDRAW_CONTROL - Don't use this one. It's used for the items SourceMod automatically adds.

Be aware that if your CreateMenu second argument includes MenuAction_DrawItem or MENU_ACTIONS_ALL and you don't actually implement the MenuAction_DrawItem callback (or implement it and don't return the current item's style if you don't change it), your style here will be completely ignored.

==== menu.ExitButton ====
<pawn> menu.ExitButton = false;</pawn>

Defaults to true.

It set to false, the menu won't have an exit button.

==== menu.ExitBackButton ====
<pawn> menu.ExitBackButton = false;</pawn>

(This isn't in the code above, but it should be mentioned)

Defaults to false.

Should only be used if the menu is a submenu, with the menu set up to check the cancel reason to see if the ExitBack action was used.

If set to true, replaces the Exit item with the Back item. The Back item still cancels the menu, but has a separate cancel reason.

This can be used to dynamically set if a menu is being called as its own menu or as a submenu.

==== menu.Display ====
<pawn> menu.Display(client, 20);</pawn>

DisplayMenu takes 2 arguments:

A Menu handle, a client index, and the amount of time in seconds to show the menu.

If you want the menu to show forever, pass MENU_TIME_FOREVER as the third argument.

=== MenuHandler1 ===
<pawn>public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)</pawn>

MenuHandler1 is a function whose signature matches the MenuHandler callback. It can be named something other than MenuHandler1. It must always be public and it will always have these arguments: Handle, MenuAction, cell, and cell in that order.

The Handle argument is always the menu that called the handler.

The MenuAction argument is always one of 7 actions for a standard menu. They are: MenuAction_Start, MenuAction_Display, MenuAction_Select, MenuAction_Cancel, MenuAction_End, MenuAction_DrawItem, and MenuAction_DisplayIitem. We will discuss each of these as we reach their code.

The two cell arguments meaning depend on the MenuAction argument. '''A common mistake is to assume param1 is the client.''' This is incorrect for MenuAction_Start, MenuAction_End, MenuAction_VoteEnd, MenuAction_VoteStart, and MenuAction_VoteCancel.

==== MenuAction_Start ====

<pawn> case MenuAction_Start:
{
PrintToServer("Displaying menu");
}</pawn>

* param1: not set
* param2: not set
* return: 0 (or don't return)

MenuAction_Start doesn't set param1 and param2. It is fired when the menu is displayed to one or more users using DisplayMenu, DisplayMenuAtItem, VoteMenu, or VoteMenuToAll.

==== MenuAction_Display ====

<pawn> case MenuAction_Display:
{
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Vote Nextmap", param1);

Panel panel = view_as<Panel>(param2);
panel.SetTitle(buffer);
PrintToServer("Client %d was sent menu with panel %x", param1, param2);
}</pawn>

* param1: client index
* param2: MenuPanel Handle
* return: 0 (or don't return)

MenuAction_Display is called once for each user a menu is displayed to. param1 is the client, param2 is the MenuPanel handle.

SetPanelTitle is used to change the menu's title based on the language of the user viewing it using the Translations system. Previous versions of this guide suggested using SetMenuTitle. This is a ''bad'' idea, as it changes the title globally.

==== MenuAction_Select ====
<pawn> case MenuAction_Select:
{
char info[32];
menu.GetInfo(param2, info, sizeof(info));
if (StrEqual(info, CHOICE3))
{
PrintToServer("Client %d somehow selected %s despite it being disabled", param1, info);
}
else
{
PrintToServer("Client %d selected %s", param1, info);
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: 0 (or don't return)

MenuAction_Select is called when a user selects a non-control item on the menu (something added using AddMenuItem). param1 is the client, param2 is the menu position of the item the client selected.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string.

==== MenuAction_Cancel ====

case MenuAction_Cancel:
{
PrintToServer("Client %d's menu was cancelled for reason %d", param1, param2);
}

* param1: client index
* param2: MenuCancel reason
* return: 0 (or don't return)

MenuAction_Cancel is called whenever a user closes a menu or it is closed for them for another reason. param1 is the client, param2 is the close reason.

The close reasons you can receive are:

* MenuCancel_Disconnected - The client got disconnected from the server.
* MenuCancel_Interrupted - Another menu opened, automatically closing our menu.
* MenuCancel_Exit - The client selected Exit. Not called if SetMenuExitBack was set to true. Not called if SetMenuExit was set to false.
* MenuCancel_NoDisplay - Our menu never displayed to the client for whatever reason.
* MenuCancel_Timeout - The menu timed out. Not called if the menu time was MENU_TIME_FOREVER.
* MenuCancel_ExitBack - The client selected Back. Only called if SetMenuExitBack has been called and set to true before the menu was sent. Not called if SetMenuExit was set to false.

==== MenuAction_End ====
<pawn> case MenuAction_End:
{
delete menu;
}</pawn>

* param1: MenuEnd reason
* param2: If param1 is MenuEnd_Cancelled, the MenuCancel reason
* return: 0 (or don't return)

MenuAction_End is called when ''all'' clients have closed a menu or vote. For menus that are not going to be redisplayed, it is required that you call CloseHandle on the menu here.

The parameters are rarely used in MenuAction_End. param1 is the menu end reason. param2 depends on param1.

The end reasons you can receive for normal menus are:

* MenuEnd_Selected - The menu closed because an item was selected (MenuAction_Select was fired)
* MenuEnd_Cancelled - The menu was cancelled (MenuAction_Cancel was fired), cancel reason is in param2; cancel reason can be any of the ones listed in MenuAction_Cancel except MenuCancel_Exit or MenuCancel_ExitBack
* MenuEnd_Exit - The menu was exited via the Exit item (MenuAction_Cancel was fired with param2 set to MenuCancel_Exit)
* MenuEnd_ExitBack - The menu was exited via the ExitBack item (MenuAction_Cancel was fired with param 2 set to MenuCancel_ExitBack)

Note: You do '''not''' have the client index during this callback, so it's far too late to do anything useful with this information.

==== MenuAction_DrawItem ====
<pawn> case MenuAction_DrawItem:
{
int style;
char info[32];
menu.GetItem(param2, info, sizeof(info), style);

if (StrEqual(info, CHOICE3))
{
return ITEMDRAW_DISABLED;
}
else
{
return style;
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: new ITEMDRAW properties or style from GetMenuItem. Since 0 is ITEMDRAW_DEFAULT, returning 0 clears all styles for this item.

MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its draw style here. param1 is the client, param2 is the menu position.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string and menu style.

You should return the style you want the menu item to have. In our example, if client 1 is viewing the menu, we want CHOICE3 to be disabled.

the return value is a bitfield, so to apply multiple styles, you do something like this:

return ITEMDRAW_NOTEXT | ITEMDRAW_SPACER;

'''Failing to return the current item's style if you don't change the style is a programmer error.'''

==== MenuAction_DisplayItem ====

<pawn> case MenuAction_DisplayItem:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));

char display[64];

if (StrEqual(info, CHOICE3))
{
Format(display, sizeof(display), "%T", "Choice 3", param1);
return RedrawMenuItem(display);
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: return value from RedrawMenuItem or 0 for no change

MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its text here. param1 is the client, param2 is the menu position.

This callback is intended for use with the Translation system.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string.

Once we have the info string, we compare our item to it and apply the appropriate translation string.

If we change an item, we have to call RedrawMenuItem and return the value it returns. If we do not change an item, we must return 0.

==== return ====
<pawn> return 0;</pawn>

If you handle MenuAction_DrawItem or MenuAction_DisplayItem, you will get the following warning if you fail to return 0 after the switch block:

<code>warning 209: function "MenuHandler1" should return a value</code>

This is because MenuAction_DrawItem and MenuAction_DisplayItem have return values, while the other actions only return 0.

== The End ==
Hopefully this walk through a simple menu helped you understand why each call is being made where. Menus have some options that we didn't explore here, such as disabling pagination (which is enabled by default). You may want to refer to the main Menu documentation for more details.

User:Mitchell

2017-01-04T21:35:59Z

Mitchell:

''~lick~''

[[File:Mitchell.gif]]

User:Mitchell

2017-01-04T21:35:14Z

Mitchell: Created page with "''~lick~'' File:Mitchell.gif"

''~lick~''
[[File:Mitchell.gif]]

File:Mitchell.gif

2017-01-04T21:34:47Z

Mitchell:

Menu API (SourceMod)

2017-01-04T21:31:11Z

Mitchell: Changed INVALID_HANDLE to null (1.7)

SourceMod has an extensive API for building and displaying menus to clients. Unlike AMX Mod X, this API is highly state driven. Menus are based on callbacks which are guaranteed to be fired.

For C++, the Menu API can be found in <tt>public/IMenuManager.h</tt>. For SourcePawn, it is in <tt>scripting/include/menus.inc</tt>.

=Objects=
The SourceMod Menu System is based on an object oriented hierarchy. Understanding this hierarchy, even for scripting, is critical to using menus effectively.

==Styles==
The top level object is a ''MenuStyle'' (<tt>IMenuStyle</tt> in C++). Styles describe a unique menu system. There are two such styles built into SourceMod:
*Valve Style, also called "ESC" menus; 8 items per page, no raw/disabled text can be rendered
*Radio Style, also called "AMX" menus; 10 items per page, raw/disabled text can be rendered

Each MenuStyle has its own rules and properties. You can think of them as existing on separate "channels." For example, two different menus can exist on a player's screen as both a Valve menu and a Radio menu at the same time, and SourceMod will be able to manage both without any problems. This is because each style keeps track of its own menus separately.

==Panels==
Menu displays are drawn with a lower level interface called ''Panels'' (<tt>IMenuPanel</tt> in C++). Panels describe exactly one chunk of display text. Both selectable items and raw text can be added to a panel as long as its parent style supports the contents you're trying to draw. For example, the Valve style does not support drawing raw text or disabled items. But with a Radio-style Panel, you can display a large amount of on-screen data in your own format.

Panels are considered temporary objects. They are created, rendered, displayed, and destroyed. Although they can be saved indefinitely, it is not necessary to do so.

Valve Style drawing rules/limitations:
*Max items per page is 8.
*Disabled items cannot be drawn.
*Raw text cannot be drawn.
*Spacers do not add a space/newline, giving a "cramped" feel.
*Users must press "ESC" or be at their console to view the menu.

Radio Style drawing rules/limitations:
*Max items per page is 10.
*Titles appear white; items appear yellow, unless disabled, in which case they are white.
*The 0th item is always white. For consistency, this means navigational controls explained in the next section are always white, and simply not drawn if disabled.

==Menus==
Lastly, there are plain ''Menus'' (<tt>IBaseMenu</tt> in C++). These are helper objects designed for storing a menu based on selectable items. Unlike low-level panels, menus are containers for '''items''', and can only contain items which are selectable (i.e., do not contain raw text). They fall into two categories:
*Non-paginated: The menu can only have a certain number of items on it, and no control/navigation options will be added, except for an "Exit" button which will always be in the last position supported by the style.
**Valve Style maximum items: 8
**Radio Style maximum items: 10
*Paginated: The menu can have any number of items. When displayed, only a certain number of items will be drawn at a time. Automatic navigation controls are added so players can easily move back and forth to different "pages" of items in the menu.
**"Previous" is always drawn as the first navigation item, third from the last supported position. This will not be drawn if the menu only contains one page. If there are no previous pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 6
***Radio Style position: 8
**"Next" is always drawn as the second navigation item, second from the last supported position. This will not be drawn if the menu only contains one page. If there are no further pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 7
***Radio Style position: 9
**"Exit" is drawn if the menu has the exit button property set. It is always the last supported item position.
***Valve Style position: 8
***Radio Style position: 10

The purpose of Menus is to simplify the procedure of storing, drawing, and calculating the selection of items. Thus, menus do not allow for adding raw text, as that would considerably complicate the drawing algorithm. ''Note: The C++ API supports hooking <tt>IBaseMenu</tt> drawing procedures and adding raw text; this will be added to the scripting API soon.''

Internally, Menus are drawn via a ''RenderMenu'' algorithm. This algorithm creates a temporary panel and fills it with items from menus. This panel is then displayed to a client. The algorithm attempts to create a consistent feel across all menus, and across all styles. Thus any menu displayed via the <tt>IBaseMenu</tt> class, or <tt>Menu</tt> Handles, will look and act the same, and the Menu API is based off the Panel API.

=Callbacks=
==Overview==
Menus are a callback based system. Each callback represents an action that occurs during a ''menu display cycle''. A cycle consists of a number of notifications:
*Start notification.
**Display notification if the menu can be displayed to the client.
**Either an item select or menu cancel notification.
*End notification.

Since ''End'' signifies the end of a full display cycle, it is usually used to destroy temporary menus.

==Specification==
A detailed explanation of these events is below. For C++, an <tt>IBaseMenu</tt> pointer is always available. For SourcePawn, a <tt>Menu</tt> Handle and a <tt>MenuAction</tt> are always set in the <tt>MenuHandler</tt> callback. Unlike C++, the SourcePawn API allows certain actions to only be called if they are requested at menu creation time. This is an optimization. However, certain actions cannot be prevented from being called.

*'''Start'''. The menu has been acknowledged. This does not mean it will be displayed; however, it guarantees that "OnMenuEnd" will be called.
**<tt>OnMenuStart()</tt> in C++.
**<tt>MenuAction_Start</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: Ignored (always 0).
***<tt>param2</tt>: Ignored (always 0).
*'''Display'''. The menu is being displayed to a client.
**<tt>OnMenuDisplay()</tt> in C++. An <tt>IMenuPanel</tt> pointer and client index are available.
**<tt>MenuAction_Display</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A Handle to a menu panel.
*'''Select'''. An item on the menu has been selected. The item position given will be the position in the menu, rather than the key pressed (unless the menu is a raw panel).
**<tt>OnMenuSelect()</tt> in C++. A client index and item position are passed.
**<tt>MenuAction_Select</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: An item position.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.
*'''End'''. The menu's display cycle has finished; this means that the "Start" action has occurred, and either "Select" or "Cancel" has occurred thereafter. This is typically where menu resources are removed/deleted.
**<tt>OnMenuEnd()</tt> in C++.
**<tt>MenuAction_End</tt> in SourcePawn. This action is always triggered, whether requested or not.
***<tt>param1</tt>: A menu end reason code.
***<tt>param2</tt>: If param1 was MenuEnd_Cancelled, this contains a menu cancellation reason code.

==Panels==
For panels, the callback rules change. Panels only receive two of the above callbacks, and it is guaranteed that only one of them will be called for a given display cycle. For C++, the <tt>IBaseMenu</tt> pointer will always be <tt>NULL</tt>. For SourcePawn, the menu Handle will always be <tt>INVALID_HANDLE</tt> or <tt>null</tt>.

*'''Select'''. A key has been pressed. This can be any number and should not be considered as reliably in bounds. For example, even if you only had 2 items in your panel, a client could trigger a key press of "43."
**<tt>OnMenuSelect()</tt> in C++. A client index and key number pressed are passed.
**<tt>MenuAction_Select</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: Number of the key pressed.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.

=Examples=
First, let's start off with a very basic menu. We want the menu to look like this:

<pre>Do you like apples?
1. Yes
2. No</pre>

We'll draw this menu with both a basic Menu and a Panel to show the API differences.

==Basic Menu==
First, let's write our example using the Menu building API. For a more in-depth guide, see [[Menus Step By Step (SourceMod Scripting)]].

<pawn>public void OnPluginStart()
{
RegConsoleCmd("menu_test1", Menu_Test1);
}

public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)
{
/* If an option was selected, tell the client about the item. */
if (action == MenuAction_Select)
{
char info[32];
bool found = menu.GetItem(param2, info, sizeof(info));
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);
}
/* If the menu was cancelled, print a message to the server about it. */
else if (action == MenuAction_Cancel)
{
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
/* If the menu has ended, destroy it */
else if (action == MenuAction_End)
{
delete menu;
}
}

public Action Menu_Test1(int client, int args)
{
Menu menu = new Menu(MenuHandler1);
menu.SetTitle("Do you like apples?");
menu.AddItem("yes", "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.Display(client, 20);

return Plugin_Handled;
}</pawn>

Note a few very important points from this example:
*One of either <tt>Select</tt> or <tt>Cancel</tt> will always be sent to the action handler.
*<tt>End</tt> will always be sent to the action handler.
*We destroy our Menu in the <tt>End</tt> action, because our Handle is no longer needed. If we had destroyed the Menu after <tt>DisplayMenu</tt>, it would have canceled the menu's display to the client.
*Menus, by default, have an exit button. We disabled this in our example.
*Our menu is set to display for 20 seconds. That means that if the client does not select an item within 20 seconds, the menu will be canceled. This is usually desired for menus that are for voting. Note that unlike AMX Mod X, you do not need to set a timer to make sure the menu will be ended.
*Although we created and destroyed a new Menu Handle, we didn't need to. It is perfectly acceptable to create the Handle once for the lifetime of the plugin.

Our finished menu and attached console output looks like this (I selected "Yes"):

[[Image:Basic_menu_1.PNG]]

==Basic Panel==
Now, let's rewrite our example to use Panels instead.

<pawn>public void OnPluginStart()
{
RegConsoleCmd("panel_test1", Panel_Test1);
}

public int PanelHandler1(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_Select)
{
PrintToConsole(param1, "You selected item: %d", param2);
} else if (action == MenuAction_Cancel) {
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
}

public Action Panel_Test1(int client, intargs)
{
Panel panel = new Panel();
panel.SetTitle("Do you like apples?");
panel.DrawItem("Yes");
panel.DrawItem("No");

panel.Send(client, PanelHandler1, 20);

delete panel;

return Plugin_Handled;
}</pawn>

As you can see, Panels are significantly different.
*We can destroy the Panel as soon as we're done displaying it. We can create the Panel once and keep re-using it, but we can destroy it at any time without interrupting client menus.
*The Handler function gets much less data. Since panels are designed as a raw display, no "item" information is saved internally. Thus, the handler function only knows whether the display was canceled or whether (and what) numerical key was pressed.
*There is no automation. You cannot add more than a certain amount of selectable items to a Panel and get pagination. Automated control functionality requires using the heftier Menu object API.

Our finished display and console output looks like this (I selected "Yes"):

[[Image:Basic_panel_1.PNG]]

==Basic Paginated Menu==
Now, let's take a more advanced example -- pagination. Let's say we want to build a menu for changing the map. An easy way to do this is to read the <tt>maplist.txt</tt> file at the start of a plugin and build a menu out of it.

Since reading and parsing a file is an expensive operation, we only want to do this once per map. Thus we'll build the menu in <tt>OnMapStart</tt>, and we won't call <tt>CloseHandle</tt> until <tt>OnMapEnd</tt>.

Source code:
<pawn>Menu g_MapMenu = null;

public void OnPluginStart()
{
RegConsoleCmd("menu_changemap", Command_ChangeMap);
}

public void OnMapStart()
{
g_MapMenu = BuildMapMenu();
}

public void OnMapEnd()
{
if (g_MapMenu != null)
{
delete(g_MapMenu);
g_MapMenu = null;
}
}

Menu BuildMapMenu()
{
/* Open the file */
File file = OpenFile("maplist.txt", "rt");
if (file == null)
{
return null;
}

/* Create the menu Handle */
Menu menu = new Menu(Menu_ChangeMap);
char mapname[255];
while (!file.EndOfFile() && file.ReadLine(mapname, sizeof(mapname)))
{
if (mapname[0] == ';' || !IsCharAlpha(mapname[0]))
{
continue;
}
/* Cut off the name at any whitespace */
int len = strlen(mapname);
for (int i=0; i<len; i++)
{
if (IsCharSpace(mapname[i]))
{
mapname[i] = '\0';
break;
}
}
/* Check if the map is valid */
if (!IsMapValid(mapname))
{
continue;
}
/* Add it to the menu */
menu.AddItem(mapname, mapname);
}
/* Make sure we close the file! */
file.Close();

/* Finally, set the title */
menu.SetTitle("Please select a map:");

return menu;
}

public int Menu_ChangeMap(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_Select)
{
char info[32];

/* Get item info */
bool found = menu.GetItem(param2, info, sizeof(info));

/* Tell the client */
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);

/* Change the map */
ServerCommand("changelevel %s", info);
}
}

public Action Command_ChangeMap(int client, int args)
{
if (g_MapMenu == null)
{
PrintToConsole(client, "The maplist.txt file was not found!");
return Plugin_Handled;
}

g_MapMenu.Display(client, MENU_TIME_FOREVER);

return Plugin_Handled;
}</pawn>

This menu results in many selections (my <tt>maplist.txt</tt> file had around 18 maps). So, our final menu has 3 pages, which side by side, look like:

[[Image:Basic_menu_2_page1.PNG]]
[[Image:Basic_menu_2_page2.PNG]]
[[Image:Basic_menu_2_page3.PNG]]

Finally, the console output printed this before the map changed to my selection, <tt>cs_office</tt>:
<pre>You selected item: 8 (found? 1 info: cs_office)</pre>

Displaying and designing this Menu with a raw <tt>ShowMenu</tt> message or <tt>Panel</tt> API would be very time consuming and difficult. We would have to keep track of all the items in an array of hardcoded size, pages which the user is viewing, and write a function which calculated item selection based on current page and key press. The Menu system, thankfully, handles all of this for you.

'''Notes:'''
*Control options which are not available are not drawn. For example, in the first page, you cannot go "back," and in the last page, you cannot go "next." Despite this, the menu API tries to keep each the interface as consistent as possible. Thus, visually, each navigational control is always in the same position.
*Although we specified no time out for our menu, if we had placed a timeout, flipping through pages does not affect the overall time. For example, if we had a timeout of 20, each successive page flip would continue to detract from the overall display time, rather than restart the allowed hold time back to 20.
*If we had disabled the Exit button, options 8 and 9 would still be "Back" and "Next," respectively.
*Again, we did not free the Menu Handle in <tt>MenuAction_End</tt>. This is because our menu is global/static, and we don't want to rebuild it every time.
*These images show "Back." In SourceMod revisions 1011 and higher, "Back" is changed to "Previous," and "Back" is reserved for the special "ExitBack" functionality.

=Voting=
SourceMod also has API for displaying menus as votable choices to more than one client. SourceMod automatically handles selecting an item and randomly picking a tie-breaker. The voting API adds two new <tt>MenuAction</tt> values, which for vote displays, are '''always''' passed:

*<tt>MenuAction_VoteStart</tt>: Fired after <tt>MenuAction_Start</tt> when the voting has officially started.
*<tt>MenuAction_VoteEnd</tt>: Fired when all clients have either voted or cancelled their vote menu. The chosen item is passed through <tt>param1</tt>. This is fired '''before''' <tt>MenuAction_End</tt>. It is important to note that it does not supercede <tt>MenuAction_End</tt>, nor is it the same thing. Menus should never be destroyed in <tt>MenuAction_VoteEnd</tt>. '''Note:''' This is not called if <tt>SetVoteResultCallback</tt>() is used.
*<tt>MenuAction_VoteCancel</tt>: Fired if the menu is cancelled while the vote is in progress. If this is called, <tt>MenuAction_VoteEnd</tt> or the result callback will not be called, but <tt>MenuAction_End</tt> will be afterwards. A vote cancellation reason is passed in <tt>param1</tt>.

The voting system extends overall menus with two additional properties:
*Only one vote can be active at a time. You must call <tt>IsVoteInProgress</tt>() or else <tt>VoteMenu</tt>() will fail.
*If a client votes and then disconnects while the vote is still active, the client's vote will be invalidated.

The example below shows has to create a function called <tt>DoVoteMenu()</tt> which will ask all clients whether or not they would like to change to the given map.

==Simple Vote==
<pawn>public int Handle_VoteMenu(Menu menu, MenuAction action, int param1,int param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
delete menu;
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
char map[64];
menu.GetItem(param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
}
}

void DoVoteMenu(const char[] map)
{
if (IsVoteInProgress())
{
return;
}

Menu menu = new Menu(Handle_VoteMenu);
menu.SetTitle("Change map to: %s?", map);
menu.AddItem(map, "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.DisplayVoteToAll(20);
}</pawn>

==Advanced Voting==
If you need more information about voting results than <tt>MenuAction_VoteEnd</tt> gives you, you can choose to have a different callback invoked. The new callback will provide much more information, but at a price: <tt>MenuAction_VoteEnd</tt> will not be called, and you will have to decide how to interpret the results. This is done via <tt>SetVoteResultCallback</tt>().

Example:
<pawn>public int Handle_VoteMenu(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
delete menu;
}
}

public void Handle_VoteResults(Menu menu,
int num_votes,
int num_clients,
const int[][] client_info,
int num_items,
const int[][] item_info)
{
/* See if there were multiple winners */
int winner = 0;
if (num_items > 1
&& (item_info[0][VOTEINFO_ITEM_VOTES] == item_info[1][VOTEINFO_ITEM_VOTES]))
{
winner = GetRandomInt(0, 1);
}

char map[64];
menu.GetItem(item_info[winner][VOTEINFO_ITEM_INDEX], map, sizeof(map));
ServerCommand("changelevel %s", map);
}

void DoVoteMenu(const char[] map)
{
if (IsVoteInProgress())
{
return;
}

Menu menu = new Menu(Handle_VoteMenu);
menu.VoteResultCallback = Handle_VoteResults;
menu.SetTitle("Change map to: %s?", map);
menu.AddItem(map, "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.DisplayVoteToAll(20);
}</pawn>

=ExitBack=
ExitBack is a special term to refer to the "ExitBack Button." This button is disabled by default. Normally, paginated menus have no "Previous" item for the first page. If the "ExitBack" button is enabled, the "Previous" item will show up as "Back."

Selecting the "ExitBack" option will exit the menu with <tt>MenuCancel_ExitBack</tt> and <tt>MenuEnd_ExitBack</tt>. The functionality of this is the same as a normal menu exit internally; extra functionality must be defined through the callbacks.

=Closing Menu Handles=
It is only necessary to close a menu handle on <tt>MenuAction_End</tt>. The <tt>MenuAction_End</tt> is done every time a menu is closed and no longer needed.

=Translations=
It is possible to dynamically translate menus to each player through the <tt>MenuAction_DisplayItem</tt> callback. A special native, <tt>RedrawMenuItem</tt>, is used to transform the text while inside the callback. Let's redo the vote example from earlier to be translated:

<pawn>public int Handle_VoteMenu(Menu menu, MenuAction action, int param1, int param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
delete menu;
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
char map[64];
menu.GetItem(param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
} else if (action == MenuAction_DisplayItem) {
/* Get the display string, we'll use it as a translation phrase */
char display[64];
menu.GetItem(param2, "", 0, _, display, sizeof(display));

/* Translate the string to the client's language */
char buffer[255];
Format(buffer, sizeof(buffer), "%T", display, param1);

/* Override the text */
return RedrawMenuItem(buffer);
} else if (action == MenuAction_Display) {
/* Panel Handle is the second parameter */
Panel panel = view_as<Panel>(param2);

/* Get the map name we're changing to from the first item */
char map[64];
menu.GetItem(0, map, sizeof(map));

/* Translate to our phrase */
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Change map to?", client, map);

panel.SetTitle(buffer);
}
}

void DoVoteMenu(const char[] map)
{
if (IsVoteInProgress())
{
return;
}

Menu menu = new Menu(Handle_VoteMenu,MenuAction_DisplayItem|MenuAction_Display);
menu.SetTitle("Change map to: %s?", map);
menu.AddItem(map, "Yes");
menu.AddItem("no", "No");
menu.ExitButton = false;
menu.DisplayVoteToAll(20);
}</pawn>

[[Category:SourceMod Development]]
[[Category:SourceMod Scripting]]

{{LanguageSwitch}}