dvander@790: /**
dvander@790:  * vim: set ts=4 :
dvander@790:  * ===============================================================
dvander@790:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
dvander@790:  * ===============================================================
dvander@790:  *
dvander@790:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
dvander@790:  * or modified under the Terms and Conditions of its License Agreement, which is found 
dvander@790:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
dvander@790:  * may change at any time.  To view the latest information, see:
dvander@790:  *   http://www.sourcemod.net/license.php
dvander@790:  *
dvander@790:  * Version: $Id$
dvander@790:  */
dvander@790:  
dvander@790: #if defined _menus_included
dvander@790:  #endinput
dvander@790: #endif
dvander@790: #define _menus_included
dvander@790: 
dvander@790: /**
dvander@790:  * Low-level drawing style of the menu.
dvander@790:  */
dvander@790: enum MenuStyle
dvander@790: {
dvander@790: 	MenuStyle_Default = 0,		/**< The "default" menu style for the mod */
dvander@790: 	MenuStyle_Valve = 1,		/**< The Valve provided menu style (Used on HL2DM) */
dvander@790: 	MenuStyle_Radio = 2,		/**< The simpler menu style commonly used on CS:S */
dvander@790: };
dvander@790: 
dvander@790: /**
dvander@790:  * Different actions for the menu "pump" callback
dvander@790:  */
dvander@790: enum MenuAction
dvander@790: {
dvander@790: 	MenuAction_Start = (1<<0),		/**< A menu has been started (nothing passed) */
dvander@790: 	MenuAction_Display = (1<<1),	/**< A menu is about to be displayed (param1=client, param2=MenuPanel Handle) */
dvander@790: 	MenuAction_Select = (1<<2),		/**< An item was selected (param1=client, param2=item) */
dvander@796: 	MenuAction_Cancel = (1<<3),		/**< The menu was cancelled (param1=client, param2=reason) */
dvander@1005: 	MenuAction_End = (1<<4),		/**< A menu display has fully ended (param1=reason, param2=cancel reason) */
dvander@885: 	MenuAction_VoteEnd = (1<<5),	/**< (VOTE ONLY): A vote sequence has succeeded (param1=chosen item) */
dvander@885: 	MenuAction_VoteStart = (1<<6), 	/**< (VOTE ONLY): A vote sequence has started (nothing passed) */
dvander@885: 	MenuAction_VoteCancel = (1<<7),	/**< (VOTE ONLY): A vote sequence has been cancelled (nothing passed) */
dvander@1007: 	MenuAction_DrawItem = (1<<8),	/**< An item is being drawn; return the new style (param1=client, param2=item) */
dvander@1163: 	MenuAction_DisplayItem = (1<<9) /**< Item text is being drawn to the display (param1=client, param2=item)
dvander@1163: 										  To change the text, use RedrawMenuItem().
dvander@1163: 										  If you do so, return its return value.  Otherwise, return 0.
dvander@1163: 										  */
dvander@790: };
dvander@790: 
dvander@790: /** Default menu actions */
dvander@790: #define MENU_ACTIONS_DEFAULT	MenuAction_Select|MenuAction_Cancel|MenuAction_End
dvander@790: /** All menu actions */
dvander@790: #define MENU_ACTIONS_ALL		-1
dvander@790: 
dvander@790: #define MENU_NO_PAGINATION		0		/**< Menu should not be paginated (10 items max) */
dvander@790: #define MENU_TIME_FOREVER		0		/**< Menu should be displayed as long as possible */
dvander@790: 
dvander@790: #define ITEMDRAW_DEFAULT		(0)		/**< Item should be drawn normally */
dvander@790: #define ITEMDRAW_DISABLED		(1<<0)	/**< Item is drawn but not selectable */
dvander@790: #define ITEMDRAW_RAWLINE		(1<<1)	/**< Item should be a raw line, without a slot */
dvander@790: #define ITEMDRAW_NOTEXT			(1<<2)	/**< No text should be drawn */
dvander@790: #define ITEMDRAW_SPACER			(1<<3)	/**< Item should be drawn as a spacer, if possible */
dvander@790: #define ITEMDRAW_IGNORE	((1<<1)|(1<<2))	/**< Item should be completely ignored (rawline + notext) */
dvander@790: #define ITEMDRAW_CONTROL		(1<<4)	/**< Item is control text (back/next/exit) */
dvander@790: 
dvander@1259: #define MENUFLAG_BUTTON_EXIT		(1<<0)	/**< Menu has an "exit" button */
dvander@1259: #define MENUFLAG_BUTTON_EXITBACK	(1<<1)	/**< Menu has an "exit back" button */
dvander@1259: #define MENUFLAG_NO_SOUND			(1<<2)	/**< Menu will not have any select sounds */
dvander@1259: 
dvander@790: /**
dvander@790:  * Reasons a menu can be cancelled.
dvander@790:  */
dvander@790: enum
dvander@790: {
dvander@1005: 	MenuCancel_Disconnected = -1,	/**< Client dropped from the server */
dvander@1005: 	MenuCancel_Interrupted = -2,	/**< Client was interrupted with another menu */
dvander@1005: 	MenuCancel_Exit = -3,			/**< Client exited via "exit" */
dvander@1005: 	MenuCancel_NoDisplay = -4,		/**< Menu could not be displayed to the client */
dvander@1005: 	MenuCancel_Timeout = -5,		/**< Menu timed out */
dvander@1005: 	MenuCancel_ExitBack = -6,		/**< Client selected "exit back" on a paginated menu */
dvander@790: };
dvander@790: 
dvander@790: /**
dvander@997:  * Reasons a menu ended.
dvander@997:  */
dvander@1010: enum
dvander@997: {
dvander@1005: 	MenuEnd_Selected = 0,			/**< Menu item was selected */
dvander@1005: 	MenuEnd_VotingDone = -1,		/**< Voting finished */
dvander@1005: 	MenuEnd_VotingCancelled = -2,	/**< Voting was cancelled */
dvander@1005: 	MenuEnd_Cancelled = -3,			/**< Menu was cancelled (reason in param2) */
dvander@1005: 	MenuEnd_Exit = -4,				/**< Menu was cleanly exited via "exit" */
dvander@1005: 	MenuEnd_ExitBack = -5,			/**< Menu was cleanly exited via "back" */
dvander@997: };
dvander@997: 
dvander@997: /**
dvander@790:  * Describes a menu's source
dvander@790:  */
dvander@790: enum MenuSource
dvander@790: {
dvander@790: 	MenuSource_None = 0,			/**< No menu is being displayed */	
dvander@790: 	MenuSource_External = 1,		/**< External menu */
dvander@790: 	MenuSource_Normal = 2,			/**< A basic menu is being displayed */
dvander@790: 	MenuSource_RawPanel = 3,		/**< A display is active, but it is not tied to a menu */
dvander@790: };
dvander@790: 
dvander@790: /**
dvander@790:  * Called when a menu action is completed.
dvander@790:  *
dvander@790:  * @param menu				The menu being acted upon.
dvander@790:  * @param action			The action of the menu.
dvander@790:  * @param param1			First action parameter (usually the client).
dvander@790:  * @param param2			Second action parameter (usually the item).
dvander@790:  * @noreturn
dvander@790:  */
dvander@790: functag MenuHandler public(Handle:menu, MenuAction:action, param1, param2);
dvander@790: 
dvander@790: /**
dvander@790:  * Creates a new, empty menu using the default style.
dvander@790:  * 
dvander@790:  * @param handler			Function which will receive menu actions.
dvander@790:  * @param actions			Optionally set which actions to receive.  Select, 
dvander@790:  *							Cancel, and End will always be received regardless
dvander@790:  *							of whether they are set or not.  They are also
dvander@790:  *							the only default actions.
dvander@790:  * @return					A new menu Handle.
dvander@790:  */
dvander@790: native Handle:CreateMenu(MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
dvander@790: 
dvander@790: /**
dvander@790:  * Displays a menu to a client.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param client			Client index.
dvander@790:  * @param time				Maximum time to leave menu on the screen.
dvander@790:  * @return					True on success, false on failure.
dvander@790:  * @error					Invalid Handle or client not in game.
dvander@790:  */
dvander@790: native bool:DisplayMenu(Handle:menu, client, time);
dvander@790: 
dvander@790: /**
dvander@790:  * Appends a new item to the end of a menu.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param info				Item information string.
dvander@790:  * @param display			Default item display string.
dvander@1136:  * @param style				Drawing style flags.  Anything other than DEFAULT or 
dvander@1136:  *							DISABLED will be completely ignored when paginating.
dvander@790:  * @return					True on success, false on failure.
dvander@790:  * @error					Invalid Handle or item limit reached.
dvander@790:  */
dvander@790: native AddMenuItem(Handle:menu, 
dvander@790: 					const String:info[], 
dvander@790: 					const String:display[], 
dvander@790: 					style=ITEMDRAW_DEFAULT);
dvander@790: 
dvander@790: /**
dvander@790:  * Inserts an item into the menu before a certain position; the new item will
dvander@790:  * be at the given position and all next items pushed forward.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param position			Position, starting from 0.
dvander@790:  * @param info				Item information string.
dvander@790:  * @param display			Default item display string.
dvander@1136:  * @param style				Drawing style flags.  Anything other than DEFAULT or 
dvander@1136:  *							DISABLED will be completely ignored when paginating.
dvander@790:  * @return					True on success, false on failure.
dvander@790:  * @error					Invalid Handle or menu position.
dvander@790:  */
dvander@790: native bool:InsertMenuItem(Handle:menu,
dvander@790: 						position, 
dvander@790: 						const String:info[], 
dvander@790: 						const String:display[], 
dvander@790: 						style=ITEMDRAW_DEFAULT);
dvander@790: 
dvander@790: /**
dvander@790:  * Removes an item from the menu.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param position			Position, starting from 0.
dvander@790:  * @return					True on success, false on failure.
dvander@790:  * @error					Invalid Handle or menu position.
dvander@790:  */
dvander@790: native bool:RemoveMenuItem(Handle:menu, position);
dvander@790: 
dvander@790: /**
dvander@790:  * Removes all items from a menu.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @noreturn
dvander@790:  * @error					Invalid Handle or menu position.
dvander@790:  */
dvander@790: native RemoveAllMenuItems(Handle:menu);
dvander@790: 
dvander@790: /**
dvander@790:  * Retrieves information about a menu item.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param position			Position, starting from 0.
dvander@790:  * @param infoBuf			Info buffer.
dvander@790:  * @param infoBufLen		Maximum length of the info buffer.
dvander@790:  * @param style				By-reference variable to store drawing flags.
dvander@790:  * @param dispBuf			Display buffer.
dvander@790:  * @param dispBufLen		Maximum length of the display buffer.
dvander@790:  * @return					True on success, false if position is invalid.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native bool:GetMenuItem(Handle:menu, position, String:infoBuf[], infoBufLen, &style=0, String:dispBuf[]="", dispBufLen=0);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns the number of items in a menu.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @return					Number of items in the menu.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native GetMenuItemCount(Handle:menu);
dvander@790: 
dvander@790: /**
dvander@790:  * Sets whether the menu should be paginated or not.
dvander@790:  *
dvander@790:  * @param menu				Handle to the menu.
dvander@790:  * @param itemsPerPage		Number of items per page, or MENU_NO_PAGINATION.
dvander@790:  * @return					True on success, false if pagination is too high or low.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native bool:SetMenuPagination(Handle:menu, itemsPerPage);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns a menu's pagination setting.
dvander@790:  *
dvander@790:  * @param menu				Handle to the menu.
dvander@790:  * @return					Pagination setting.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native GetMenuPagination(Handle:menu);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns a menu's MenuStyle Handle.  The Handle
dvander@790:  * is global and cannot be freed.
dvander@790:  *
dvander@790:  * @param menu				Handle to the menu.
dvander@790:  * @return 					Handle to the menu's draw style.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native Handle:GetMenuStyle(Handle:menu);
dvander@790: 
dvander@790: /**
dvander@790:  * Sets the menu's default title/instruction message.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param fmt				Message string format
dvander@790:  * @param ...				Message string arguments.
dvander@790:  * @noreturn
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native SetMenuTitle(Handle:menu, const String:fmt[], any:...);
dvander@790: 
dvander@790: /**
dvander@790:  * Creates a raw MenuPanel based off the menu's style.
dvander@790:  * The Handle must be freed with CloseHandle().
dvander@790:  *
dvander@790:  * @return					A new MenuPanel Handle.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native Handle:CreatePanelFromMenu(Handle:menu);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns whether or not the menu has an exit button.
dvander@790:  * By default, menus have an exit button.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @return 					True if the menu has an exit button; false otherwise.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native bool:GetMenuExitButton(Handle:menu);
dvander@790: 
dvander@790: /**
dvander@790:  * Sets whether or not the menu has an exit button.
dvander@790:  * By default, menus have an exit button.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param button			True to enable the button, false to remove it.
dvander@790:  * @return 					True if allowed; false on failure.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native bool:SetMenuExitButton(Handle:menu, bool:button);
dvander@790: 
dvander@790: /**
dvander@1005:  * Returns whether or not the menu has an "exit back" button.
dvander@1005:  * By default, menus do not have an exit back button.
dvander@1005:  * Exit Back buttons appear as "Back" on page 1 of paginated menus and
dvander@1005:  * have functionality defined by the user in MenuEnd_ExitBack.
dvander@1005:  *
dvander@1005:  * @param menu				Menu Handle.
dvander@1005:  * @return 					True if the menu has an exit back button; false otherwise.
dvander@1005:  * @error					Invalid Handle.
dvander@1005:  */
dvander@1005: native bool:GetMenuExitBackButton(Handle:menu);
dvander@1005: 
dvander@1005: /**
dvander@1005:  * Sets whether or not the menu has an "exit back" button.
dvander@1005:  * By default, menus do not have an exit back button.
dvander@1005:  * Exit Back buttons appear as "Back" on page 1 of paginated menus and
dvander@1005:  * have functionality defined by the user in MenuEnd_ExitBack.
dvander@1005:  *
dvander@1005:  * @param menu				Menu Handle.
dvander@1005:  * @param button			True to enable the button, false to remove it.
dvander@1005:  * @error					Invalid Handle.
dvander@1005:  */
dvander@1005: native SetMenuExitBackButton(Handle:menu, bool:button);
dvander@1005: 
dvander@1005: 
dvander@1005: /**
dvander@790:  * Cancels a menu from displaying on all clients.  While the
dvander@790:  * cancellation is in progress, this menu cannot be re-displayed
dvander@790:  * to any clients.
dvander@790:  *
dvander@790:  * The menu may still exist on the client's screen after this command.
dvander@790:  * This simply verifies that the menu is not being used anywhere.
dvander@790:  *
dvander@885:  * If any vote is in progress on a menu, it will be cancelled.
dvander@885:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @noreturn
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@790: native CancelMenu(Handle:menu);
dvander@790: 
dvander@790: /**
dvander@1259:  * Retrieves a menu's option flags.
dvander@1259:  *
dvander@1259:  * @param menu				Menu Handle.
dvander@1259:  * @return					A bitstring of MENUFLAG bits.
dvander@1259:  * @error					Invalid Handle.
dvander@1259:  */
dvander@1259: native GetMenuOptionFlags(Handle:menu);
dvander@1259: 
dvander@1259: /**
dvander@1259:  * Sets a menu's option flags.
dvander@1259:  *
dvander@1259:  * If a certain bit is not supported, it will be stripped before
dvander@1259:  * being set.
dvander@1259:  *
dvander@1259:  * @param menu				Menu Handle.
dvander@1259:  * @param flags				A new bitstring of MENUFLAG bits.
dvander@1259:  * @noreturn
dvander@1259:  * @error					Invalid Handle.
dvander@1259:  */
dvander@1259: native SetMenuOptionFlags(Handle:menu, flags);
dvander@1259: 
dvander@1259: /**
dvander@885:  * Returns whether a vote is in progress on the given menu.
dvander@885:  *
dvander@885:  * @param menu				Menu Handle.
dvander@885:  * @return					True if a vote is in progress, false otherwise.
dvander@885:  */
dvander@885: native bool:IsVoteInProgress(Handle:menu);
dvander@885: 
dvander@885: /**
dvander@878:  * Broadcasts a menu to a list of clients.  The most selected item will be 
dvander@878:  * returned through MenuAction_End.  On a tie, a random item will be returned 
dvander@878:  * from a list of the tied items.
dvander@790:  *
dvander@878:  * Note that MenuAction_VoteEnd and MenuAction_VoteStart are both
dvander@878:  * default callbacks and do not need to be enabled.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@878:  * @param clients			Array of clients to broadcast to.
dvander@878:  * @param numClients		Number of clients in the array.
dvander@790:  * @param time				Maximum time to leave menu on the screen.
dvander@878:  * @return					True on success, false if this menu already has a vote session
dvander@878:  *							in progress.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@878: native bool:VoteMenu(Handle:menu, clients[], numClients, time);
dvander@790: 
dvander@790: /**
dvander@878:  * Sends a vote menu to all clients.  See VoteMenu() for more information.
dvander@790:  *
dvander@790:  * @param menu				Menu Handle.
dvander@790:  * @param time				Maximum time to leave menu on the screen.
dvander@878:  * @return					True on success, false if this menu already has a vote session
dvander@878:  *							in progress.
dvander@790:  * @error					Invalid Handle.
dvander@790:  */
dvander@878: stock VoteMenuToAll(Handle:menu, time)
dvander@790: {
dvander@790: 	new num = GetMaxClients();
dvander@790: 	new total;
dvander@790: 	decl players[num];
dvander@790: 	
dvander@790: 	for (new i=1; i<=num; i++)
dvander@790: 	{
ds@891: 		if (!IsClientInGame(i))
dvander@790: 		{
dvander@790: 			continue;
dvander@790: 		}
dvander@790: 		players[total++] = i;
dvander@790: 	}
dvander@790: 	
dvander@878: 	return VoteMenu(menu, players, total, time);
dvander@790: }
dvander@790: 
dvander@790: /**
dvander@790:  * Returns a style's global Handle.
dvander@790:  *
dvander@790:  * @param style			Menu Style.
dvander@790:  * @return				A Handle, or INVALID_HANDLE if not found or unusable.
dvander@790:  */
dvander@790: native Handle:GetMenuStyleHandle(MenuStyle:style);
dvander@790: 
dvander@790: /**
dvander@790:  * Creates a MenuPanel from a MenuStyle.  Panels are used for drawing raw 
dvander@790:  * menus without any extra helper functions.  The Handle must be closed
dvander@790:  * with CloseHandle().
dvander@790:  *
dvander@790:  * @param hStyle		MenuStyle Handle, or INVALID_HANDLE to use the default style.
dvander@790:  * @return				A new MenuPanel Handle.
dvander@790:  * @error				Invalid Handle other than INVALID_HANDLE.
dvander@790:  */
dvander@790: native Handle:CreatePanel(Handle:hStyle=INVALID_HANDLE);
dvander@790: 
dvander@790: /** 
dvander@790:  * Creates a Menu from a MenuStyle.  The Handle must be closed with 
dvander@790:  * CloseHandle().
dvander@790:  *
dvander@790:  * @parma hStyle		MenuStyle Handle, or INVALID_HANDLE to use the default style.
dvander@790:  * @param handler		Function which will receive menu actions.
dvander@790:  * @param actions		Optionally set which actions to receive.  Select, 
dvander@790:  *						Cancel, and End will always be received regardless
dvander@790:  *						of whether they are set or not.  They are also
dvander@790:  *						the only default actions.
dvander@790:  * @return				A new menu Handle.
dvander@790:  * @error				Invalid Handle other than INVALID_HANDLE.
dvander@790:  */
dvander@790: native Handle:CreateMenuEx(Handle:hStyle=INVALID_HANDLE, MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns whether a client is viewing a menu.  If the menu source 
dvander@790:  * is MenuSource_Normal, a menu Handle will also be returned.
dvander@790:  *
dvander@790:  * @param client		Client index.
dvander@790:  * @param hStyle		MenuStyle Handle, or INVALID_HANDLE to use the default style.
dvander@790:  * @return				A MenuSource value.
dvander@790:  * @error				Invalid Handle other than INVALID_HANDLE.
dvander@790:  */
dvander@790: native MenuSource:GetClientMenu(client, Handle:hStyle=INVALID_HANDLE);
dvander@790: 
dvander@790: /** 
dvander@790:  * Cancels a menu on a client.  This will only affect non-external menus.
dvander@790:  *
dvander@790:  * @param hstyle		MenuStyle Handle, or INVALID_HANDLE to use the default style.
dvander@790:  * @param client		Client index.
dvander@790:  * @param autoIgnore	If true, no menus can be re-drawn on the client during
dvander@790:  *						the cancellation process.
dvander@790:  * @return				True if a menu was cancelled, false otherwise.
dvander@790:  */
dvander@790: native bool:CancelClientMenu(client, bool:autoIgnore=false, Handle:hStyle=INVALID_HANDLE);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns a style's maximum items per page.
dvander@790:  *
dvander@790:  * @param hStyle		MenuStyle Handle, or INVALID_HANDLE to use the default style.
dvander@790:  * @return				Maximum items per page.
dvander@790:  * @error				Invalid Handle other than INVALID_HANDLE.
dvander@790:  */
dvander@790: native GetMaxPageItems(Handle:hStyle=INVALID_HANDLE);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns a MenuPanel's parent style.
dvander@790:  *
dvander@790:  * @param panel			A MenuPanel Handle.
dvander@790:  * @return				The MenuStyle Handle that created the panel.
dvander@790:  * @error				Invalid Handle.
dvander@790:  */
dvander@790: native Handle:GetPanelStyle(Handle:panel);
dvander@790: 
dvander@790: /**
dvander@790:  * Sets the panel's title.
dvander@790:  *
dvander@790:  * @param panel			A MenuPanel Handle.
dvander@790:  * @param title			Text to set as the title.
dvander@790:  * @param onlyIfEmpty	If true, the title will only be set if no title is set.
dvander@790:  * @noreturn
dvander@790:  * @error				Invalid Handle.
dvander@790:  */
dvander@790: native Handle:SetPanelTitle(Handle:panel, const String:text[], bool:onlyIfEmpty=false);
dvander@790: 
dvander@790: /**
dvander@790:  * Draws an item on a panel.  If the item takes up a slot, the position
dvander@790:  * is returned.
dvander@790:  *
dvander@790:  * @param panel			A MenuPanel Handle.
dvander@790:  * @param text			Display text to use.  If not a raw line, 
dvander@790:  *						the style may automatically add color markup.
dvander@790:  *						No numbering or newlines are needed.
dvander@790:  * @param style			ITEMDRAW style flags.
dvander@790:  * @return				A slot position, or 0 if item was a rawline or could not be drawn.
dvander@790:  * @error				Invalid Handle.
dvander@790:  */
dvander@790: native DrawPanelItem(Handle:panel, const String:text[], style=ITEMDRAW_DEFAULT);
dvander@790: 
dvander@790: /**
dvander@790:  * Draws a raw line of text on a panel, without any markup other than a newline.
dvander@790:  *
dvander@1163:  * @param panel			A MenuPanel Handle, or INVALID_HANDLE if inside a 
dvander@1163:  *						MenuAction_DisplayItem callback.
dvander@790:  * @param text			Display text to use.
dvander@790:  * @return				True on success, false if raw lines are not supported.
dvander@790:  * @error				Invalid Handle.
dvander@790:  */
dvander@790: native DrawPanelText(Handle:panel, const String:text[]);
dvander@790: 
dvander@790: /**
dvander@790:  * Returns whether or not the given drawing flags are supported by
dvander@790:  * the menu style.
dvander@790:  *
dvander@790:  * @param panel			A MenuPanel Handle.
dvander@790:  * @param style			ITEMDRAW style flags.
dvander@790:  * @return				True if item is drawable, false otherwise.
dvander@790:  * @error				Invalid Handle.
dvander@790:  */
dvander@790: native CanPanelDrawFlags(Handle:panel, style);
dvander@790: 
dvander@790: /**
dvander@819:  * Sets the selectable key map of a panel.  This is not supported by
dvander@819:  * all styles (only by Radio, as of this writing).  
dvander@819:  *
dvander@819:  * @param keys			An integer where each bit N allows key
dvander@819:  *						N+1 to be selected.  If no keys are selectable,
dvander@819:  *						then key 0 (bit 9) is automatically set.
dvander@819:  * @return 				True if supported, false otherwise.
dvander@819:  */
dvander@819: native bool:SetPanelKeys(Handle:panel, keys);
dvander@819: 
dvander@819: /**
dvander@790:  * Sends a panel to a client.  Unlike full menus, the handler
dvander@790:  * function will only receive the following actions, both of 
dvander@790:  * which will have INVALID_HANDLE for a menu, and the client
dvander@790:  * as param1.
dvander@790:  *
dvander@790:  * MenuAction_Select (param2 will be the key pressed)
dvander@790:  * MenuAction_Cancel (param2 will be the reason)
dvander@790:  *
dvander@790:  * Also, if the menu fails to display, no callbacks will be called.
dvander@790:  *
dvander@790:  * @param panel			A MenuPanel Handle.
dvander@790:  * @param client		A client to draw to.
dvander@790:  * @param handler		The MenuHandler function to catch actions with.
dvander@790:  * @param time			Time to hold the menu for.
dvander@790:  * @return				True on success, false on failure.
dvander@790:  * @error				Invalid Handle.
dvander@790:  */
dvander@790: native bool:SendPanelToClient(Handle:panel, client, MenuHandler:handler, time);
dvander@840: 
dvander@840: /**
dvander@840:  * @brief Returns the current key position.
dvander@840:  *
dvander@840:  * @param panel			A MenuPanel Handle.
dvander@840:  * @return				Current key position starting at 1.
dvander@840:  * @error				Invalid Handle.
dvander@840:  */
dvander@840: native GetPanelCurrentKey(Handle:panel);
dvander@840: 
dvander@840: /**
dvander@840:  * @brief Sets the next key position.  This cannot be used
dvander@840:  * to traverse backwards.
dvander@840:  *
dvander@840:  * @param panel			A MenuPanel Handle.
dvander@840:  * @param key			Key that is greater or equal to
dvander@840:  *						GetPanelCurrentKey().
dvander@840:  * @return				True on success, false otherwise.
dvander@840:  * @error				Invalid Handle.
dvander@840:  */
dvander@840: native bool:SetPanelCurrentKey(Handle:panel, key);
dvander@960: 
dvander@960: /**
dvander@1163:  * @brief Redraws menu text from inside a MenuAction_DisplayItem callback.
dvander@1163:  * 
dvander@1163:  * @param text			Menu text to draw.
dvander@1163:  * @return				Item position; must be returned via the callback.
dvander@1163:  */
dvander@1163: native RedrawMenuItem(const String:text[]);
dvander@1163: 
dvander@1163: /**
dvander@960:  * Retrieves voting information from MenuAction_VoteEnd.
dvander@960:  *
dvander@960:  * @param param2		Second parameter of MenuAction_VoteEnd.
dvander@960:  * @param winningVotes	Number of votes received by the winning option.
dvander@960:  * @param totalVotes	Number of total votes received.
dvander@960:  * @noreturn
dvander@960:  */
dvander@960: stock GetMenuVoteInfo(param2, &winningVotes, &totalVotes)
dvander@960: {
dvander@960: 	winningVotes = param2 & 0xFFFF;
dvander@960: 	totalVotes = param2 >> 16;
dvander@960: }