dvander@768: /**
dvander@768:  * vim: set ts=4 :
dvander@768:  * ===============================================================
dvander@768:  * SourceMod, Copyright (C) 2004-2007 AlliedModders LLC. 
dvander@768:  * All rights reserved.
dvander@768:  * ===============================================================
dvander@768:  *
dvander@768:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be 
dvander@768:  * used or modified under the Terms and Conditions of its License Agreement, 
dvander@768:  * which is found in public/licenses/LICENSE.txt.  As of this notice, derivative 
dvander@768:  * works must be licensed under the GNU General Public License (version 2 or 
dvander@768:  * greater).  A copy of the GPL is included under public/licenses/GPL.txt.
dvander@768:  * 
dvander@768:  * To view the latest information, see: http://www.sourcemod.net/license.php
dvander@768:  *
dvander@768:  * Version: $Id$
dvander@768:  */
dvander@768: 
dvander@768: #ifndef _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_
dvander@768: #define _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_
dvander@768: 
dvander@768: #include <IShareSys.h>
dvander@790: #include <IHandleSys.h>
dvander@768: 
dvander@768: #define SMINTERFACE_MENUMANAGER_NAME		"IMenuManager"
dvander@1005: #define SMINTERFACE_MENUMANAGER_VERSION		6
dvander@768: 
dvander@768: /**
dvander@768:  * @file IMenuManager.h
dvander@768:  * @brief Abstracts on-screen menus for clients.
dvander@768:  */
dvander@768: 
dvander@768: namespace SourceMod
dvander@768: {
dvander@768: 	/**
dvander@768: 	 * @brief Used to determine how an item selection is interpreted.
dvander@768: 	 */
dvander@768: 	enum ItemSelection
dvander@768: 	{
dvander@768: 		ItemSel_None,					/**< Invalid selection */
dvander@1005: 		ItemSel_Back,					/**< Go back one page (really "Previous") */
dvander@768: 		ItemSel_Next,					/**< Go forward one page */
dvander@768: 		ItemSel_Exit,					/**< Menu was exited */
dvander@768: 		ItemSel_Item,					/**< Valid item selection */
dvander@1005: 		ItemSel_ExitBack,				/**< Sends MenuEnd_ExitBack */
dvander@768: 	};
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Used to determine which order to search for items in.
dvander@768: 	 */
dvander@768: 	enum ItemOrder
dvander@768: 	{
dvander@768: 		ItemOrder_Ascending,			/**< Items should be drawn ascendingly */
dvander@768: 		ItemOrder_Descending,			/**< Items should be drawn descendingly */
dvander@768: 	};
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Pairs an item type with an item menu position.
dvander@768: 	 */
dvander@768: 	struct menu_slots_t
dvander@768: 	{
dvander@768: 		ItemSelection type;				/**< Item selection type */
dvander@768: 		unsigned int item;				/**< Item position, if applicable */
dvander@768: 	};
dvander@768: 
dvander@768: 	class IBaseMenu;
dvander@787: 	class IMenuPanel;
dvander@768: 	class IMenuHandler;
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Describes menu display information.
dvander@768: 	 */
dvander@768: 	struct menu_states_t
dvander@768: 	{
dvander@768: 		unsigned int apiVers;			/**< Must be filled with the API version */
dvander@768: 		IBaseMenu *menu;				/**< Menu pointer, or NULL if there is only a display */
dvander@768: 		IMenuHandler *mh;				/**< Menu callbacks handler */
dvander@768: 		unsigned int firstItem;			/**< MENU ONLY: First item displayed on the last page */
dvander@768: 		unsigned int lastItem;			/**< MENU ONLY: Last item displayed on the last page */
dvander@768: 		menu_slots_t slots[11];			/**< MENU ONLY: Item selection table (first index is 1) */
dvander@768: 	};
dvander@768: 
dvander@768: 	#define ITEMDRAW_DEFAULT		(0)		/**< Item should be drawn normally */
dvander@768: 	#define ITEMDRAW_DISABLED		(1<<0)	/**< Item is drawn but not selectable */
dvander@768: 	#define ITEMDRAW_RAWLINE		(1<<1)	/**< Item should be a raw line, without a slot */
dvander@768: 	#define ITEMDRAW_NOTEXT			(1<<2)	/**< No text should be drawn */
dvander@768: 	#define ITEMDRAW_SPACER			(1<<3)	/**< Item should be drawn as a spacer, if possible */
dvander@777: 	#define ITEMDRAW_IGNORE	((1<<1)|(1<<2))	/**< Item should be completely ignored (rawline + notext) */
dvander@785: 	#define ITEMDRAW_CONTROL		(1<<4)	/**< Item is control text (back/next/exit) */
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Information about item drawing.
dvander@768: 	 */
dvander@768: 	struct ItemDrawInfo
dvander@768: 	{
dvander@768: 		ItemDrawInfo()
dvander@768: 		{
dvander@768: 			style = 0;
dvander@768: 			display = NULL;
dvander@768: 		}
dvander@768: 		ItemDrawInfo(const char *DISPLAY, unsigned int STYLE=ITEMDRAW_DEFAULT) 
dvander@768: 			: display(DISPLAY), style(STYLE)
dvander@768: 		{
dvander@768: 		}
dvander@777: 		const char *display;			/**< Display text (NULL for none) */
dvander@768: 		unsigned int style;				/**< ITEMDRAW style flags */
dvander@768: 	};
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Reasons for a menu dying.
dvander@768: 	 */
dvander@768: 	enum MenuCancelReason
dvander@768: 	{
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 selected "exit" on a paginated menu */
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@768: 	};
dvander@768: 
dvander@997: 	/**
dvander@997: 	 * @brief Reasons a menu ended.
dvander@997: 	 */
dvander@997: 	enum MenuEndReason
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 uncleanly cancelled */
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@777: 	#define MENU_NO_PAGINATION			0		/**< Menu should not be paginated (10 items max) */
dvander@768: 	#define MENU_TIME_FOREVER			0		/**< Menu should be displayed as long as possible */
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Extended menu options.
dvander@768: 	 */
dvander@768: 	enum MenuOption
dvander@768: 	{
dvander@768: 		MenuOption_IntroMessage,				/**< CONST CHAR *: Valve menus only; defaults to:
dvander@768: 													 "You have a menu, hit ESC"
dvander@768: 													 */
dvander@768: 		MenuOption_IntroColor,					/**< INT[4]: Valve menus only; specifies the intro message colour
dvander@768: 													 using R,G,B,A (defaults to 255,0,0,255)
dvander@768: 													 */
dvander@776: 		MenuOption_Priority,					/**< INT *: Valve menus only; priority (less is higher) */
dvander@768: 	};
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Describes the menu a player is viewing.
dvander@768: 	 */
dvander@768: 	enum MenuSource
dvander@768: 	{
dvander@768: 		MenuSource_None = 0,					/**< No menu is being displayed */
dvander@768: 		MenuSource_External = 1,				/**< External menu, no pointer */
dvander@768: 		MenuSource_BaseMenu = 2,				/**< An IBaseMenu pointer. */
dvander@787: 		MenuSource_Display = 3,					/**< IMenuPanel source, no pointer */
dvander@768: 	};
dvander@768: 
dvander@768: 	class IMenuStyle;
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Sets how a raw menu should be drawn.
dvander@768: 	 */
dvander@787: 	class IMenuPanel
dvander@768: 	{
dvander@768: 	public:
dvander@768: 		/**
dvander@768: 		 * @brief Returns the parent IMenuStyle pointer.
dvander@768: 		 *
dvander@768: 		 * @return				IMenuStyle pointer which created
dvander@768: 		 *						this object.
dvander@768: 		 */
dvander@768: 		virtual IMenuStyle *GetParentStyle() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Resets/clears the cached display text.
dvander@768: 		 */
dvander@768: 		virtual void Reset() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Sets how the title should be drawn.
dvander@768: 		 *
dvander@768: 		 * @param text			Text string to display for the title.
dvander@768: 		 * @param onlyIfEmpty	Only sets the title if one does not already 
dvander@768: 		 *						exist.
dvander@768: 		 */
dvander@768: 		virtual void DrawTitle(const char *text, bool onlyIfEmpty=false) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Adds an item to the menu and returns the position (1-10).
dvander@768: 		 *
dvander@768: 		 * Note: Item will fail to draw if there are too many items,
dvander@768: 		 * or the item is not drawable (for example, invisible).	
dvander@768: 		 * 
dvander@768: 		 * @return				Item draw position, or 0 on failure.
dvander@768: 		 */
dvander@768: 		virtual unsigned int DrawItem(const ItemDrawInfo &item) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Draws a raw line of text, if supported.  The line does not 
dvander@768: 		 * need to be newline terminated.
dvander@768: 		 *
dvander@768: 		 * @return				True on success, false if not supported.
dvander@768: 		 */
dvander@768: 		virtual bool DrawRawLine(const char *rawline) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Sets an extended menu option.
dvander@768: 		 *
dvander@768: 		 * @param option		Option type.
dvander@768: 		 * @param valuePtr		Pointer of the type expected by the option.
dvander@768: 		 * @return				True on success, false if option or value is not supported.
dvander@768: 		 */
dvander@768: 		virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns whether the display is capable of rendering an item
dvander@768: 		 * with the given flags.
dvander@768: 		 *
dvander@768: 		 * @param flags			ITEMDRAW flags.
dvander@768: 		 * @return				True if renderable, false otherwise.
dvander@768: 		 */
dvander@768: 		virtual bool CanDrawItem(unsigned int drawFlags) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Sends the menu display to a client.
dvander@768: 		 *
dvander@768: 		 * @param client		Client index to display to.
dvander@768: 		 * @param handler		Menu handler to use.
dvander@768: 		 * @param time			Time to hold menu for.
dvander@768: 		 * @return				True on success, false otherwise.
dvander@768: 		 */
dvander@768: 		virtual bool SendDisplay(int client, IMenuHandler *handler, unsigned int time) =0;
dvander@776: 
dvander@776: 		/**
dvander@776: 		 * @brief Destroys the display object.
dvander@776: 		 */
dvander@776: 		virtual void DeleteThis() =0;
dvander@819: 
dvander@819: 		/**
dvander@819: 		 * @brief Sets the selectable key map.  Returns false if the function 
dvander@819: 		 * is not supported.
dvander@819: 		 * 
dvander@819: 		 * @param keys			A bit string where each bit N-1 specifies 
dvander@819: 		 *						that key N is selectable (key 0 is bit 9).  
dvander@819: 		 *						If the selectable key map is 0, it will be
dvander@819: 		 *						automatically set to allow 0.
dvander@819: 		 * @return				True on success, false if not supported.
dvander@819: 		 */
dvander@819: 		virtual bool SetSelectableKeys(unsigned int keymap) =0;
dvander@840: 
dvander@840: 		/**
dvander@840: 		 * @brief Returns the current key position.
dvander@840: 		 *
dvander@840: 		 * @return				Current key position starting at 1.
dvander@840: 		 */
dvander@840: 		virtual unsigned int GetCurrentKey() =0;
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 key			Key that is greater or equal to
dvander@840: 		 *						GetCurrentKey().
dvander@840: 		 * @return				True on success, false otherwise.
dvander@840: 		 */
dvander@840: 		virtual bool SetCurrentKey(unsigned int key) =0;
dvander@768: 	};
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Describes a "MenuStyle" system which manages
dvander@768: 	 * menu drawing and construction.
dvander@768: 	 */
dvander@768: 	class IMenuStyle
dvander@768: 	{
dvander@768: 	public:
dvander@768: 		/**
dvander@768: 		 * @brief Returns the style API version.
dvander@768: 		 *
dvander@768: 		 * @return				API version.
dvander@768: 		 */
dvander@768: 		virtual unsigned int GetStyleAPIVersion()
dvander@768: 		{
dvander@768: 			return SMINTERFACE_MENUMANAGER_VERSION;
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns the name of the menu style.
dvander@768: 		 *
dvander@768: 		 * @return				String containing the style name.
dvander@768: 		 */
dvander@768: 		virtual const char *GetStyleName() =0;
dvander@768: 
dvander@768: 		/**
dvander@787: 		 * @brief Creates an IMenuPanel object.
dvander@768: 		 *
dvander@776: 		 * Note: the object should be freed using ::DeleteThis.
dvander@768: 		 *
dvander@787: 		 * @return				IMenuPanel object.
dvander@768: 		 */
dvander@787: 		virtual IMenuPanel *CreatePanel() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Creates an IBaseMenu object of this style.
dvander@768: 		 *
dvander@768: 		 * Note: the object should be freed using IBaseMenu::Destroy.
dvander@768: 		 *
dvander@790: 		 * @param handler		IMenuHandler pointer.
dvander@790: 		 * @param pOwner		Optional IdentityToken_t owner for handle 
dvander@790: 		 *						creation.
dvander@768: 		 * @return				An IBaseMenu pointer.
dvander@768: 		 */
dvander@790: 		virtual IBaseMenu *CreateMenu(IMenuHandler *handler, IdentityToken_t *pOwner=NULL) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns the maximum number of items per page.
dvander@768: 		 *
dvander@768: 		 * @return				Number of items per page.
dvander@768: 		 */
dvander@768: 		virtual unsigned int GetMaxPageItems() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns whether or not a client is viewing a menu.
dvander@768: 		 *
dvander@768: 		 * @param client		Client index.
dvander@768: 		 * @param object		Optional pointer to retrieve menu object,
dvander@768: 		 *						if any.
dvander@768: 		 * @return				MenuSource value.
dvander@768: 		 */
dvander@768: 		virtual MenuSource GetClientMenu(int client, void **object) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Cancels a client's menu.
dvander@768: 		 *
dvander@768: 		 * @param client		Client index.
dvander@768: 		 * @param autoIgnore	If true, no menus can be created during 
dvander@768: 		 *						the cancellation process.
dvander@768: 		 * @return				True if a menu was cancelled, false otherwise.
dvander@768: 		 */
dvander@768: 		virtual bool CancelClientMenu(int client, bool autoIgnore=false) =0;
dvander@790: 
dvander@790: 		/**
dvander@790: 		 * @brief Returns a Handle the IMenuStyle object.
dvander@790: 		 *
dvander@790: 		 * @return				Handle_t pointing to this object.
dvander@790: 		 */
dvander@790: 		virtual Handle_t GetHandle() =0;
dvander@768: 	};
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief High-level interface for building menus.
dvander@768: 	 */
dvander@768: 	class IBaseMenu
dvander@768: 	{
dvander@768: 	public:
dvander@768: 		/**
dvander@768: 		 * @brief Appends an item to the end of a menu.
dvander@768: 		 *
dvander@768: 		 * @param info			Item information string.
dvander@768: 		 * @param draw			Default drawing information.
dvander@768: 		 * @return				True on success, false on item limit reached.
dvander@768: 		 */
dvander@768: 		virtual bool AppendItem(const char *info, const ItemDrawInfo &draw) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Inserts an item into the menu before a certain position; 
dvander@768: 		 * the new item will be at the given position and all next items 
dvander@768: 		 * pushed forward.
dvander@768: 		 *
dvander@768: 		 * @param position		Position, starting from 0.
dvander@768: 		 * @param info			Item information string.
dvander@768: 		 * @param draw			Default item draw info.
dvander@768: 		 * @return				True on success, false on invalid menu position
dvander@768: 		 */
dvander@768: 		virtual bool InsertItem(unsigned int position, const char *info, const ItemDrawInfo &draw) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Removes an item from the menu.
dvander@768: 		 *
dvander@768: 		 * @param position		Position, starting from 0.
dvander@768: 		 * @return				True on success, false on invalid menu position.
dvander@768: 		 */
dvander@768: 		virtual bool RemoveItem(unsigned int position) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Removes all items from the menu.
dvander@768: 		 */
dvander@768: 		virtual void RemoveAllItems() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns an item's info.
dvander@768: 		 *
dvander@768: 		 * @param position		Position, starting from 0.
dvander@768: 		 * @param draw			Optional pointer to store a draw information.
dvander@768: 		 * @return				Info string pointer, or NULL if position was invalid.
dvander@768: 		 */
dvander@768: 		virtual const char *GetItemInfo(unsigned int position, ItemDrawInfo *draw) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns the number of items.
dvander@768: 		 *
dvander@768: 		 * @return				Number of items in the menu.
dvander@768: 		 */
dvander@768: 		virtual unsigned int GetItemCount() =0;
dvander@768: 
dvander@768: 		/** 
dvander@768: 		 * @brief Sets the menu's pagination,.
dvander@768: 		 *
dvander@768: 		 * @param itemsPerPage	Number of items per page, or MENU_NO_PAGINATION.
dvander@768: 		 * @return				True on success, false if itemsPerPage is too large.
dvander@768: 		 */
dvander@768: 		virtual bool SetPagination(unsigned int itemsPerPage) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns an item's pagination.
dvander@768: 		 *
dvander@768: 		 * @return				Pagination setting.
dvander@768: 		 */
dvander@768: 		virtual unsigned int GetPagination() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns the menu style.
dvander@768: 		 * 
dvander@768: 		 * @return				Menu style.
dvander@768: 		 */
dvander@768: 		virtual IMenuStyle *GetDrawStyle() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Sets the menu's display title/message.
dvander@768: 		 *
dvander@768: 		 * @param message		Message (format options allowed).
dvander@768: 		 */
dvander@768: 		virtual void SetDefaultTitle(const char *message) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns the menu's display/title message.
dvander@768: 		 *
dvander@768: 		 * @return				Message string.
dvander@768: 		 */
dvander@768: 		virtual const char *GetDefaultTitle() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Sets an extended menu option.
dvander@768: 		 *
dvander@768: 		 * @param option		Option type.
dvander@768: 		 * @param valuePtr		Pointer of the type expected by the option.
dvander@768: 		 * @return				True on success, false if option or value is not supported.
dvander@768: 		 */
dvander@768: 		virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0;
dvander@768: 
dvander@768: 		/**
dvander@787: 		 * @brief Creates a new IMenuPanel object using extended options specific
dvander@768: 		 * to the IMenuStyle parent.  Titles, items, etc, are not copied.
dvander@768: 		 *
dvander@787: 		 * Note: The object should be freed with IMenuPanel::DeleteThis.
dvander@768: 		 *
dvander@787: 		 * @return				IMenuPanel pointer.
dvander@768: 		 */
dvander@787: 		virtual IMenuPanel *CreatePanel() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns whether or not the menu should have an "Exit" button for
dvander@768: 		 * paginated menus.
dvander@768: 		 *
dvander@768: 		 * @return				True to have an exit button, false otherwise.
dvander@768: 		 */
dvander@768: 		virtual bool GetExitButton() =0;
dvander@768: 		
dvander@768: 		/**
dvander@768: 		 * @brief Sets whether or not the menu should have an "Exit" button for
dvander@768: 		 * paginated menus.
dvander@768: 		 *
dvander@768: 		 * @param set			True to enable, false to disable the exit button.
dvander@768: 		 * @return				True on success, false if the exit button is 
dvander@768: 		 *						non-optional.
dvander@768: 		 */
dvander@768: 		virtual bool SetExitButton(bool set) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Sends the menu to a client.
dvander@768: 		 *
dvander@768: 		 * @param client		Client index to display to.
dvander@768: 		 * @param time			Time to hold menu for.
dvander@768: 		 * @return				True on success, false otherwise.
dvander@768: 		 */
dvander@790: 		virtual bool Display(int client, unsigned int time) =0;
dvander@768: 
dvander@768: 		/**
dvander@790: 		 * @brief Destroys the menu and frees all associated resources.
dvander@790: 		 *
dvander@790: 		 * @param releaseHandle	If true, the Handle will be released
dvander@790: 		 *						in the destructor.  This should be set
dvander@790: 		 *						to true except for IHandleTypeDispatch
dvander@790: 		 *						destructors.
dvander@768: 		 */
dvander@790: 		virtual void Destroy(bool releaseHandle=true) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Cancels the menu on all client's displays.  While the menu is
dvander@768: 		 * being cancelled, the menu may not be re-displayed to any clients.
dvander@884: 		 * If a vote menu is currently active, it will be cancelled as well.
dvander@768: 		 *
dvander@768: 		 * @return				Number of menus cancelled.
dvander@768: 		 */
dvander@768: 		virtual void Cancel() =0;
dvander@790: 
dvander@790: 		/**
dvander@790: 		 * @brief Returns the menu's Handle.  The Handle is automatically
dvander@790: 		 * removed when the menu is destroyed.
dvander@790: 		 *
dvander@790: 		 * @return				Handle_t handle value.
dvander@790: 		 */
dvander@790: 		virtual Handle_t GetHandle() =0;
dvander@877: 
dvander@877: 		/**
dvander@877: 		 * @brief Sends a menu to multiple clients as a vote menu.  All callbacks
dvander@877: 		 * will be sent as normal, except two extras, OnMenuVoteStart and 
dvander@877: 		 * OnMenuVoteEnd, will be called.
dvander@877: 		 *
dvander@877: 		 * @param clients		Array of client indexes.
dvander@877: 		 * @param numClients	Number of client indexes in the array.
dvander@877: 		 * @param maxTime		Maximum amount of time to hold the vote.
dvander@877: 		 * @param flags			Optional voting flags (currently unused).
dvander@877: 		 * @return				True on success, false if a vote is already in
dvander@877: 		 *						progress (the menu must be cancelled first).
dvander@877: 		 */
dvander@877: 		virtual bool BroadcastVote(int clients[], 
dvander@877: 			unsigned int numClients, 
dvander@877: 			unsigned int maxTime,
dvander@877: 			unsigned int flags=0) =0;
dvander@884: 
dvander@884: 		/**
dvander@884: 		 * @brief Returns whether a vote menu is active.
dvander@884: 		 *
dvander@884: 		 * @return				True if a vote menu is active, false otherwise.
dvander@884: 		 */
dvander@884: 		virtual bool IsVoteInProgress() =0;
dvander@1005: 
dvander@1005: 		/**
dvander@1005: 		 * @brief Returns whether to draw a "Back" button on the first page.
dvander@1005: 		 * ExitBack buttons are disabled by default.
dvander@1005: 		 *
dvander@1005: 		 * @return				True if enabled, false otherwise.
dvander@1005: 		 */
dvander@1005: 		virtual bool GetExitBackButton() =0;
dvander@1005: 
dvander@1005: 		/**
dvander@1005: 		 * @brief Sets whether to draw a "Back" button on the first page.
dvander@1005: 		 * ExitBack buttons are disabled by default.
dvander@1005: 		 *
dvander@1005: 		 * @param set			True to enable, false to disable.
dvander@1005: 		 */
dvander@1005: 		virtual void SetExitBackButton(bool set) =0;
dvander@768: 	};
dvander@768: 
dvander@768: 	/** 
dvander@768: 	 * @brief Contains callbacks for menu actions.
dvander@768: 	 */
dvander@768: 	class IMenuHandler
dvander@768: 	{
dvander@768: 	public:
dvander@768: 		/**
dvander@768: 		 * @brief Returns the menu api verison.
dvander@768: 		 *
dvander@768: 		 * @return				Menu API version.
dvander@768: 		 */
dvander@768: 		virtual unsigned int GetMenuAPIVersion2()
dvander@768: 		{
dvander@768: 			return SMINTERFACE_MENUMANAGER_VERSION;
dvander@768: 		}
dvander@768: 
dvander@768: 		/** 
dvander@768: 		 * @brief A display/selection cycle has started.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 */
dvander@768: 		virtual void OnMenuStart(IBaseMenu *menu)
dvander@768: 		{
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Called before a menu is being displayed.  This is where
dvander@768: 		 * you can set an alternate title on the menu.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 * @param client		Client index.
dvander@787: 		 * @param display		IMenuPanel pointer.
dvander@768: 		 */
dvander@787: 		virtual void OnMenuDisplay(IBaseMenu *menu, int client, IMenuPanel *display)
dvander@768: 		{
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Called when an item is selected.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 * @param client		Client that selected the item.
dvander@768: 		 * @param item			Item number.
dvander@768: 		 */
dvander@768: 		virtual void OnMenuSelect(IBaseMenu *menu, int client, unsigned int item)
dvander@768: 		{
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief An active menu display was dropped from a client.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 * @param client		Client that had the menu.
dvander@768: 		 * @param reason		Menu cancellation reason.
dvander@768: 		 */
dvander@768: 		virtual void OnMenuCancel(IBaseMenu *menu, int client, MenuCancelReason reason)
dvander@768: 		{
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief A display/selection cycle has ended.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 */
dvander@997: 		virtual void OnMenuEnd(IBaseMenu *menu, MenuEndReason reason)
dvander@768: 		{
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@790: 		 * @brief Called when the menu object is destroyed.
dvander@790: 		 *
dvander@790: 		 * @param menu			Menu pointer.
dvander@790: 		 */
dvander@790: 		virtual void OnMenuDestroy(IBaseMenu *menu)
dvander@790: 		{
dvander@790: 		}
dvander@790: 
dvander@790: 		/**
dvander@768: 		 * @brief Called when requesting how to render an item.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 * @param client		Client index receiving the menu.
dvander@768: 		 * @param item			Item number in the menu.
dvander@768: 		 * @param style			ITEMSTYLE flags, by reference for modification.
dvander@768: 		 */
dvander@768: 		virtual void OnMenuDrawItem(IBaseMenu *menu, int client, unsigned int item, unsigned int &style)
dvander@768: 		{
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Called when requesting how to draw an item's text.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 * @param client		Client index receiving the menu.
dvander@768: 		 * @param item			Item number in the menu.
dvander@768: 		 * @param display		Pointer to the display text string (changeable).
dvander@768: 		 */
dvander@768: 		virtual void OnMenuDisplayItem(IBaseMenu *menu, int client, unsigned int item, const char **display)
dvander@768: 		{
dvander@768: 		}
dvander@768: 
dvander@768: 		/**
dvander@877: 		 * @brief Called when a vote has been started and displayed to 
dvander@877: 		 * clients.  This is called after OnMenuStart() and OnMenuDisplay(),
dvander@877: 		 * but before OnMenuSelect().
dvander@877: 		 *
dvander@877: 		 * @param menu			Menu pointer.
dvander@877: 		 */
dvander@877: 		virtual void OnMenuVoteStart(IBaseMenu *menu)
dvander@877: 		{
dvander@877: 		}
dvander@877: 
dvander@877: 		/**
dvander@877: 		 * @brief Called when a vote ends.  This is automatically called by the 
dvander@884: 		 * wrapper, and never needs to called from a style implementation.  
dvander@884: 		 *
dvander@884: 		 * This function does not replace OnMenuEnd(), nor does it have the 
dvander@884: 		 * same meaning as OnMenuEnd(), meaning you should not destroy a menu
dvander@884: 		 * while it is in this function.
dvander@768: 		 *
dvander@768: 		 * @param menu			Menu pointer.
dvander@768: 		 * @param item			Item position that was chosen by a majority.
dvander@960: 		 * @param winningVotes	Number of votes from the winning item.
dvander@960: 		 * @param totalVotes	Number of votes total.
dvander@768: 		 */
dvander@960: 		virtual void OnMenuVoteEnd(IBaseMenu *menu,
dvander@960: 			unsigned int item, 
dvander@960: 			unsigned int winningVotes,
dvander@960: 			unsigned int totalVotes)
dvander@877: 		{
dvander@877: 		}
dvander@884: 
dvander@884: 		/**
dvander@884: 		 * @brief Called when a vote is cancelled.  If this is called, then 
dvander@884: 		 * OnMenuVoteEnd() will not be called.  In both cases, OnMenuEnd will 
dvander@884: 		 * always be called.
dvander@884: 		 *
dvander@884: 		 * @param menu			Menu pointer.
dvander@884: 		 */
dvander@884: 		virtual void OnMenuVoteCancel(IBaseMenu *menu)
dvander@884: 		{
dvander@884: 		}
dvander@877: 	};
dvander@877: 
dvander@877: 	/**
dvander@877: 	 * @brief Contains functions for managing a vote handler.
dvander@877: 	 */
dvander@877: 	class IVoteMenuHandler : public IMenuHandler
dvander@877: 	{
dvander@877: 	public:
dvander@877: 		/**
dvander@877: 		 * @brief Returns whether or not a vote is in progress.
dvander@877: 		 *
dvander@877: 		 * @return				True if a vote is in progress, false otherwise.
dvander@877: 		 */
dvander@877: 		virtual bool IsVoteInProgress() =0;
dvander@877: 
dvander@877: 		/**
dvander@877: 		 * @brief Use this to mark the vote as in progress (start).
dvander@877: 		 *
dvander@877: 		 * @param menu			Menu pointer.
dvander@877: 		 */
dvander@877: 		virtual void InitializeVoting(IBaseMenu *menu) =0;
dvander@877: 
dvander@877: 		/**
dvander@877: 		 * @brief Use this to notify that all clients' displays have been
dvander@877: 		 * processed (i.e., there are no more clients to display to).
dvander@877: 		 */
dvander@877: 		virtual void StartVoting() =0;
dvander@884: 
dvander@884: 		/**
dvander@884: 		 * @brief Notifies the vote handler that the voting should be 
dvander@884: 		 * cancelled.  
dvander@884: 		 *
dvander@884: 		 * Cancellation is not immediate and will only occur once every menu 
dvander@884: 		 * has been cancelled from clients.  Thus this should only be called
dvander@884: 		 * from the beginning of IBaseMenu::Cancel.
dvander@884: 		 */
dvander@884: 		virtual void CancelVoting() =0;
dvander@768: 	};
dvander@768: 
dvander@768: 	/**
dvander@768: 	 * @brief Manages menu creation and displaying.
dvander@768: 	 */
dvander@768: 	class IMenuManager : public SMInterface
dvander@768: 	{
dvander@768: 	public:
dvander@768: 		virtual const char *GetInterfaceName()
dvander@768: 		{
dvander@768: 			return SMINTERFACE_MENUMANAGER_NAME;
dvander@768: 		}
dvander@768: 		virtual unsigned int GetInterfaceVersion()
dvander@768: 		{
dvander@768: 			return SMINTERFACE_MENUMANAGER_VERSION;
dvander@768: 		}
dvander@960: 		virtual bool IsVersionCompatible(unsigned int version)
dvander@960: 		{
dvander@997: 			if (version < 5 || version > GetInterfaceVersion())
dvander@960: 			{
dvander@960: 				return false;
dvander@960: 			}
dvander@960: 			return true;
dvander@960: 		}
dvander@768: 	public:
dvander@768: 		/**
dvander@768: 		 * @brief Finds a style by name.
dvander@768: 		 *
dvander@768: 		 * @param name			Name of the style (case insensitive).
dvander@768: 		 * @return				IMenuStyle pointer, or NULL if not found.
dvander@768: 		 */
dvander@768: 		virtual IMenuStyle *FindStyleByName(const char *name) =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Returns the default draw style Core is using.
dvander@768: 		 *
dvander@768: 		 * @return				Menu style pointer.
dvander@768: 		 */
dvander@768: 		virtual IMenuStyle *GetDefaultStyle() =0;
dvander@768: 
dvander@768: 		/**
dvander@768: 		 * @brief Given a set of menu states, converts it to an IDisplay object.
dvander@768: 		 *
dvander@768: 		 * The state parameter is both INPUT and OUTPUT.
dvander@768: 		 * INPUT: menu, mh, firstItem, lastItem
dvander@768: 		 * OUTPUT: display, firstItem, lastItem, slots
dvander@768: 		 *
dvander@768: 		 * @param client		Client index.
dvander@768: 		 * @param states		Menu states.
dvander@768: 		 * @return				IDisplay pointer, or NULL if no items could be 
dvander@768: 		 *						found in the IBaseMenu pointer, or NULL if any
dvander@768: 		 *						other error occurred.  Any valid pointer must
dvander@787: 		 *						be freed using IMenuPanel::DeleteThis.
dvander@768: 		 */
dvander@787: 		virtual IMenuPanel *RenderMenu(int client, menu_states_t &states, ItemOrder order) =0;
dvander@877: 
dvander@877: 		/**
dvander@877: 		 * @brief Creates a standard voting wrapper.  The wrapper is not 
dvander@877: 		 * re-entrant; a second menu cannot be displayed on the same handler
dvander@877: 		 * at the same time.
dvander@877: 		 *
dvander@877: 		 * @param mh			Menu handler to wrap around.
dvander@877: 		 * @return				An IMenuHandler pointer that is a wrapper
dvander@877: 		 *						around IMenuHandler callbacks to invoke
dvander@877: 		 *						voting related callbacks.
dvander@877: 		 */
dvander@877: 		virtual IVoteMenuHandler *CreateVoteWrapper(IMenuHandler *mh) =0;
dvander@877: 
dvander@877: 		/**
dvander@877: 		 * @brief Frees a standard voting wrapper.
dvander@877: 		 *
dvander@877: 		 * @param mh			Menu handler pointer created by 
dvander@877: 		 *						CreateVoteWrapper().  NULL values will be 
dvander@877: 		 *						safely ignored.
dvander@877: 		 */
dvander@877: 		virtual void ReleaseVoteWrapper(IVoteMenuHandler *mh) =0;
dvander@768: 	};
dvander@768: }
dvander@768: 
dvander@768: #endif //_INCLUDE_SOURCEMOD_MENU_SYSTEM_H_