sourcemod-central: public/IMenuManager.h@de422b59bdfc (annotated)

ds@1952	1	/**
ds@1952	2	* vim: set ts=4 :
ds@1952	3	* =============================================================================
ds@1952	4	* SourceMod
ds@1952	5	* Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
ds@1952	6	* =============================================================================
ds@1952	7	*
ds@1952	8	* This program is free software; you can redistribute it and/or modify it under
ds@1952	9	* the terms of the GNU General Public License, version 3.0, as published by the
ds@1952	10	* Free Software Foundation.
ds@1952	11	*
ds@1952	12	* This program is distributed in the hope that it will be useful, but WITHOUT
ds@1952	13	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1952	14	* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
ds@1952	15	* details.
ds@1952	16	*
ds@1952	17	* You should have received a copy of the GNU General Public License along with
ds@1952	18	* this program. If not, see <http://www.gnu.org/licenses/>.
ds@1952	19	*
ds@1952	20	* As a special exception, AlliedModders LLC gives you permission to link the
ds@1952	21	* code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1952	22	* "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1952	23	* by the Valve Corporation. You must obey the GNU General Public License in
ds@1952	24	* all respects for all other code used. Additionally, AlliedModders LLC grants
ds@1952	25	* this exception to all derivative works. AlliedModders LLC defines further
ds@1952	26	* exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1952	27	* or <http://www.sourcemod.net/license.php>.
ds@1952	28	*
ds@1952	29	* Version: $Id$
ds@1952	30	*/
ds@1952	31
ds@1952	32	#ifndef _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_
ds@1952	33	#define _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_
ds@1952	34
ds@1952	35	#include <IShareSys.h>
ds@1952	36	#include <IHandleSys.h>
ds@1952	37
ds@1952	38	#define SMINTERFACE_MENUMANAGER_NAME "IMenuManager"
dvander@2056	39	#define SMINTERFACE_MENUMANAGER_VERSION 15
ds@1952	40
ds@1952	41	/**
ds@1952	42	* @file IMenuManager.h
ds@1952	43	* @brief Abstracts on-screen menus for clients.
ds@1952	44	*/
ds@1952	45
ds@1952	46	namespace SourceMod
ds@1952	47	{
ds@1952	48	/**
ds@1952	49	* @brief Used to determine how an item selection is interpreted.
ds@1952	50	*/
ds@1952	51	enum ItemSelection
ds@1952	52	{
ds@1952	53	ItemSel_None, /*< Invalid selection /
ds@1952	54	ItemSel_Back, /*< Go back one page (really "Previous") /
ds@1952	55	ItemSel_Next, /*< Go forward one page /
ds@1952	56	ItemSel_Exit, /*< Menu was exited /
ds@1952	57	ItemSel_Item, /*< Valid item selection /
ds@1952	58	ItemSel_ExitBack, /*< Sends MenuEnd_ExitBack /
ds@1952	59	};
ds@1952	60
ds@1952	61	/**
ds@1952	62	* @brief Used to determine which order to search for items in.
ds@1952	63	*/
ds@1952	64	enum ItemOrder
ds@1952	65	{
ds@1952	66	ItemOrder_Ascending, /*< Items should be drawn ascendingly /
ds@1952	67	ItemOrder_Descending, /*< Items should be drawn descendingly /
ds@1952	68	};
ds@1952	69
ds@1952	70	/**
ds@1952	71	* @brief Pairs an item type with an item menu position.
ds@1952	72	*/
ds@1952	73	struct menu_slots_t
ds@1952	74	{
ds@1952	75	ItemSelection type; /*< Item selection type /
ds@1952	76	unsigned int item; /*< Item position, if applicable /
ds@1952	77	};
ds@1952	78
ds@1952	79	class IBaseMenu;
ds@1952	80	class IMenuPanel;
ds@1952	81	class IMenuHandler;
ds@1952	82
ds@1952	83	/**
ds@1952	84	* @brief Describes menu display information.
ds@1952	85	*/
ds@1952	86	struct menu_states_t
ds@1952	87	{
ds@1952	88	unsigned int apiVers; /*< Must be filled with the API version /
ds@1952	89	IBaseMenu menu; /< Menu pointer, or NULL if there is only a display /
ds@1952	90	IMenuHandler mh; /< Menu callbacks handler /
ds@1952	91	unsigned int firstItem; /*< MENU ONLY: First item displayed on the last page /
ds@1952	92	unsigned int lastItem; /*< MENU ONLY: Last item displayed on the last page /
ds@1952	93	unsigned int item_on_page; /*< MENU ONLY: First item on page /
ds@1952	94	menu_slots_t slots[11]; /*< MENU ONLY: Item selection table (first index is 1) /
ds@1952	95	};
ds@1952	96
ds@1952	97	#define ITEMDRAW_DEFAULT (0) /*< Item should be drawn normally /
ds@1952	98	#define ITEMDRAW_DISABLED (1<<0) /*< Item is drawn but not selectable /
ds@1952	99	#define ITEMDRAW_RAWLINE (1<<1) /*< Item should be a raw line, without a slot /
ds@1952	100	#define ITEMDRAW_NOTEXT (1<<2) /*< No text should be drawn /
ds@1952	101	#define ITEMDRAW_SPACER (1<<3) /*< Item should be drawn as a spacer, if possible /
ds@1952	102	#define ITEMDRAW_IGNORE ((1<<1)\|(1<<2)) /*< Item should be completely ignored (rawline + notext) /
ds@1952	103	#define ITEMDRAW_CONTROL (1<<4) /*< Item is control text (back/next/exit) /
ds@1952	104
ds@1952	105	/**
ds@1952	106	* @brief Information about item drawing.
ds@1952	107	*/
ds@1952	108	struct ItemDrawInfo
ds@1952	109	{
ds@1952	110	ItemDrawInfo(const char *DISPLAY=NULL, unsigned int STYLE=ITEMDRAW_DEFAULT,
ds@1952	111	unsigned int FLAGS=0, const char *HELPTEXT=NULL)
ds@1952	112	: display(DISPLAY), style(STYLE)
ds@1952	113	{
ds@1952	114	}
ds@1952	115	const char display; /< Display text (NULL for none) /
ds@1952	116	unsigned int style; /*< ITEMDRAW style flags /
ds@1952	117	};
ds@1952	118
ds@1952	119	/**
ds@1952	120	* @brief Contains information about a vote result.
ds@1952	121	*/
ds@1952	122	struct menu_vote_result_t
ds@1952	123	{
ds@1952	124	unsigned int num_clients; /*< Number of clients the menu was displayed to /
ds@1952	125	unsigned int num_votes; /*< Number of votes received /
ds@1952	126	struct menu_client_vote_t
ds@1952	127	{
ds@1952	128	int client; /*< Client index /
ds@1952	129	int item; /*< Item # (or -1 for none) /
ds@1952	130	} client_list; /< Array of size num_clients /
ds@1952	131	unsigned int num_items; /*< Number of items voted for /
ds@1952	132	struct menu_item_vote_t
ds@1952	133	{
ds@1952	134	unsigned int item; /*< Item index /
ds@1952	135	unsigned int count; /*< Number of votes /
ds@1952	136	} item_list; /*< Array of size num_items, sorted by count,
ds@1952	137	descending */
ds@1952	138	};
ds@1952	139
ds@1952	140	/**
ds@1952	141	* @brief Reasons for a menu dying.
ds@1952	142	*/
ds@1952	143	enum MenuCancelReason
ds@1952	144	{
ds@1952	145	MenuCancel_Disconnected = -1, /*< Client dropped from the server /
ds@1952	146	MenuCancel_Interrupted = -2, /*< Client was interrupted with another menu /
ds@1952	147	MenuCancel_Exit = -3, /*< Client selected "exit" on a paginated menu /
ds@1952	148	MenuCancel_NoDisplay = -4, /*< Menu could not be displayed to the client /
ds@1952	149	MenuCancel_Timeout = -5, /*< Menu timed out /
ds@1952	150	MenuCancel_ExitBack = -6, /*< Client selected "exit back" on a paginated menu /
ds@1952	151	};
ds@1952	152
ds@1952	153	/**
ds@1952	154	* @brief Reasons a menu ended.
ds@1952	155	*/
ds@1952	156	enum MenuEndReason
ds@1952	157	{
ds@1952	158	MenuEnd_Selected = 0, /*< Menu item was selected /
ds@1952	159	MenuEnd_VotingDone = -1, /*< Voting finished /
ds@1952	160	MenuEnd_VotingCancelled = -2, /*< Voting was cancelled /
ds@1952	161	MenuEnd_Cancelled = -3, /*< Menu was uncleanly cancelled /
ds@1952	162	MenuEnd_Exit = -4, /*< Menu was cleanly exited via "exit" /
ds@1952	163	MenuEnd_ExitBack = -5, /*< Menu was cleanly exited via "back" /
ds@1952	164	};
ds@1952	165
ds@1952	166	/**
ds@1952	167	* @brief Reasons a vote can be cancelled.
ds@1952	168	*/
ds@1952	169	enum VoteCancelReason
ds@1952	170	{
ds@1952	171	VoteCancel_Generic = -1, /*< Vote was generically cancelled. /
ds@1952	172	VoteCancel_NoVotes = -2, /*< Vote did not receive any votes. /
ds@1952	173	};
ds@1952	174
ds@1952	175	#define MENU_NO_PAGINATION 0 /*< Menu should not be paginated (10 items max) /
ds@1952	176	#define MENU_TIME_FOREVER 0 /*< Menu should be displayed as long as possible /
ds@1952	177
ds@1952	178	#define MENUFLAG_BUTTON_EXIT (1<<0) /*< Menu has an "exit" button /
ds@1952	179	#define MENUFLAG_BUTTON_EXITBACK (1<<1) /*< Menu has an "exit back" button /
ds@1952	180	#define MENUFLAG_NO_SOUND (1<<2) /*< Menu will not have any select sounds /
ds@1952	181
ds@1952	182	/**
ds@1952	183	* @brief Extended menu options.
ds@1952	184	*/
ds@1952	185	enum MenuOption
ds@1952	186	{
ds@1952	187	MenuOption_IntroMessage, /*< CONST CHAR : Valve menus only; defaults to:
ds@1952	188	"You have a menu, hit ESC"
ds@1952	189	*/
ds@1952	190	MenuOption_IntroColor, /**< INT[4]: Valve menus only; specifies the intro message colour
ds@1952	191	using R,G,B,A (defaults to 255,0,0,255)
ds@1952	192	*/
ds@1952	193	MenuOption_Priority, /*< INT : Valve menus only; priority (less is higher) */
ds@1952	194	};
ds@1952	195
ds@1952	196	/**
ds@1952	197	* @brief Describes the menu a player is viewing.
ds@1952	198	*/
ds@1952	199	enum MenuSource
ds@1952	200	{
ds@1952	201	MenuSource_None = 0, /*< No menu is being displayed /
ds@1952	202	MenuSource_External = 1, /*< External menu, no pointer /
ds@1952	203	MenuSource_BaseMenu = 2, /*< An IBaseMenu pointer. /
ds@1952	204	MenuSource_Display = 3, /*< IMenuPanel source, no pointer /
ds@1952	205	};
ds@1952	206
ds@1952	207	class IMenuStyle;
ds@1952	208
ds@1952	209	/**
ds@1952	210	* @brief Sets how a raw menu should be drawn.
ds@1952	211	*/
ds@1952	212	class IMenuPanel
ds@1952	213	{
ds@1952	214	public:
ds@1952	215	/**
ds@1952	216	* @brief Returns the parent IMenuStyle pointer.
ds@1952	217	*
ds@1952	218	* @return IMenuStyle pointer which created
ds@1952	219	* this object.
ds@1952	220	*/
ds@1952	221	virtual IMenuStyle *GetParentStyle() =0;
ds@1952	222
ds@1952	223	/**
ds@1952	224	* @brief Resets/clears the cached display text.
ds@1952	225	*/
ds@1952	226	virtual void Reset() =0;
ds@1952	227
ds@1952	228	/**
ds@1952	229	* @brief Sets how the title should be drawn.
ds@1952	230	*
ds@1952	231	* @param text Text string to display for the title.
ds@1952	232	* @param onlyIfEmpty Only sets the title if one does not already
ds@1952	233	* exist.
ds@1952	234	*/
ds@1952	235	virtual void DrawTitle(const char *text, bool onlyIfEmpty=false) =0;
ds@1952	236
ds@1952	237	/**
ds@1952	238	* @brief Adds an item to the menu and returns the position (1-10).
ds@1952	239	*
ds@1952	240	* Note: Item will fail to draw if there are too many items,
ds@1952	241	* or the item is not drawable (for example, invisible).
ds@1952	242	*
ds@1952	243	* @return Item draw position, or 0 on failure.
ds@1952	244	*/
ds@1952	245	virtual unsigned int DrawItem(const ItemDrawInfo &item) =0;
ds@1952	246
ds@1952	247	/**
ds@1952	248	* @brief Draws a raw line of text, if supported. The line does not
ds@1952	249	* need to be newline terminated.
ds@1952	250	*
ds@1952	251	* @return True on success, false if not supported.
ds@1952	252	*/
ds@1952	253	virtual bool DrawRawLine(const char *rawline) =0;
ds@1952	254
ds@1952	255	/**
ds@1952	256	* @brief Sets an extended menu option.
ds@1952	257	*
ds@1952	258	* @param option Option type.
ds@1952	259	* @param valuePtr Pointer of the type expected by the option.
ds@1952	260	* @return True on success, false if option or value is not supported.
ds@1952	261	*/
ds@1952	262	virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0;
ds@1952	263
ds@1952	264	/**
ds@1952	265	* @brief Returns whether the display is capable of rendering an item
ds@1952	266	* with the given flags.
ds@1952	267	*
ds@1952	268	* @param drawFlags ITEMDRAW flags.
ds@1952	269	* @return True if renderable, false otherwise.
ds@1952	270	*/
ds@1952	271	virtual bool CanDrawItem(unsigned int drawFlags) =0;
ds@1952	272
ds@1952	273	/**
ds@1952	274	* @brief Sends the menu display to a client.
ds@1952	275	*
ds@1952	276	* @param client Client index to display to.
ds@1952	277	* @param handler Menu handler to use.
ds@1952	278	* @param time Time to hold menu for.
ds@1952	279	* @return True on success, false otherwise.
ds@1952	280	*/
ds@1952	281	virtual bool SendDisplay(int client, IMenuHandler *handler, unsigned int time) =0;
ds@1952	282
ds@1952	283	/**
ds@1952	284	* @brief Destroys the display object.
ds@1952	285	*/
ds@1952	286	virtual void DeleteThis() =0;
ds@1952	287
ds@1952	288	/**
ds@1952	289	* @brief Sets the selectable key map. Returns false if the function
ds@1952	290	* is not supported.
ds@1952	291	*
ds@1952	292	* @param keymap A bit string where each bit N-1 specifies
ds@1952	293	* that key N is selectable (key 0 is bit 9).
ds@1952	294	* If the selectable key map is 0, it will be
ds@1952	295	* automatically set to allow 0.
ds@1952	296	* @return True on success, false if not supported.
ds@1952	297	*/
ds@1952	298	virtual bool SetSelectableKeys(unsigned int keymap) =0;
ds@1952	299
ds@1952	300	/**
ds@1952	301	* @brief Returns the current key position.
ds@1952	302	*
ds@1952	303	* @return Current key position starting at 1.
ds@1952	304	*/
ds@1952	305	virtual unsigned int GetCurrentKey() =0;
ds@1952	306
ds@1952	307	/**
ds@1952	308	* @brief Sets the next key position. This cannot be used
ds@1952	309	* to traverse backwards.
ds@1952	310	*
ds@1952	311	* @param key Key that is greater or equal to
ds@1952	312	* GetCurrentKey().
ds@1952	313	* @return True on success, false otherwise.
ds@1952	314	*/
ds@1952	315	virtual bool SetCurrentKey(unsigned int key) =0;
ds@1952	316
ds@1952	317	/**
ds@1952	318	* @brief Returns the number of characters that can be added to the
ds@1952	319	* menu. The internal buffer is truncated if overflowed; this is for
ds@1952	320	* manual truncation/wrapping purposes.
ds@1952	321	*
ds@1952	322	* @return Number of bytes available. If the result is
ds@1952	323	* -1, then the panel has no text limit.
ds@1952	324	*/
ds@1952	325	virtual int GetAmountRemaining() =0;
ds@1952	326
ds@1952	327	/**
ds@1952	328	* @brief For the Handle system, returns approximate memory usage.
ds@1952	329	*
ds@1952	330	* @return Approximate number of bytes being used.
ds@1952	331	*/
ds@1952	332	virtual unsigned int GetApproxMemUsage() =0;
ds@1952	333	};
ds@1952	334
ds@1952	335	/**
ds@1952	336	* @brief Describes a "MenuStyle" system which manages
ds@1952	337	* menu drawing and construction.
ds@1952	338	*/
ds@1952	339	class IMenuStyle
ds@1952	340	{
ds@1952	341	public:
ds@1952	342	/**
ds@1952	343	* @brief Returns the style API version.
ds@1952	344	*
ds@1952	345	* @return API version.
ds@1952	346	*/
ds@1952	347	virtual unsigned int GetStyleAPIVersion()
ds@1952	348	{
ds@1952	349	return SMINTERFACE_MENUMANAGER_VERSION;
ds@1952	350	}
ds@1952	351
ds@1952	352	/**
ds@1952	353	* @brief Returns the name of the menu style.
ds@1952	354	*
ds@1952	355	* @return String containing the style name.
ds@1952	356	*/
ds@1952	357	virtual const char *GetStyleName() =0;
ds@1952	358
ds@1952	359	/**
ds@1952	360	* @brief Creates an IMenuPanel object.
ds@1952	361	*
ds@1952	362	* Note: the object should be freed using ::DeleteThis.
ds@1952	363	*
ds@1952	364	* @return IMenuPanel object.
ds@1952	365	*/
ds@1952	366	virtual IMenuPanel *CreatePanel() =0;
ds@1952	367
ds@1952	368	/**
ds@1952	369	* @brief Creates an IBaseMenu object of this style.
ds@1952	370	*
ds@1952	371	* Note: the object should be freed using IBaseMenu::Destroy.
ds@1952	372	*
ds@1952	373	* @param handler IMenuHandler pointer.
ds@1952	374	* @param pOwner Optional IdentityToken_t owner for handle
ds@1952	375	* creation.
ds@1952	376	* @return An IBaseMenu pointer.
ds@1952	377	*/
ds@1952	378	virtual IBaseMenu CreateMenu(IMenuHandler handler, IdentityToken_t *pOwner=NULL) =0;
ds@1952	379
ds@1952	380	/**
ds@1952	381	* @brief Returns the maximum number of items per page.
ds@1952	382	*
ds@1952	383	* Menu implementations must return >= 2. Styles with only 1 or 0
ds@1952	384	* items per page are not valid.
ds@1952	385	*
ds@1952	386	* @return Number of items per page.
ds@1952	387	*/
ds@1952	388	virtual unsigned int GetMaxPageItems() =0;
ds@1952	389
ds@1952	390	/**
ds@1952	391	* @brief Returns whether or not a client is viewing a menu.
ds@1952	392	*
ds@1952	393	* @param client Client index.
ds@1952	394	* @param object Optional pointer to retrieve menu object,
ds@1952	395	* if any.
ds@1952	396	* @return MenuSource value.
ds@1952	397	*/
ds@1952	398	virtual MenuSource GetClientMenu(int client, void **object) =0;
ds@1952	399
ds@1952	400	/**
ds@1952	401	* @brief Cancels a client's menu.
ds@1952	402	*
ds@1952	403	* @param client Client index.
ds@1952	404	* @param autoIgnore If true, no menus can be created during
ds@1952	405	* the cancellation process.
ds@1952	406	* @return True if a menu was cancelled, false otherwise.
ds@1952	407	*/
ds@1952	408	virtual bool CancelClientMenu(int client, bool autoIgnore=false) =0;
ds@1952	409
ds@1952	410	/**
ds@1952	411	* @brief Returns a Handle the IMenuStyle object.
ds@1952	412	*
ds@1952	413	* @return Handle_t pointing to this object.
ds@1952	414	*/
ds@1952	415	virtual Handle_t GetHandle() =0;
ds@1952	416
ds@1952	417	/**
ds@1952	418	* @brief For the Handle system, returns approximate memory usage.
ds@1952	419	*
ds@1952	420	* @return Approximate number of bytes being used.
ds@1952	421	*/
ds@1952	422	virtual unsigned int GetApproxMemUsage() =0;
ds@1952	423	};
ds@1952	424
ds@1952	425	/**
ds@1952	426	* @brief High-level interface for building menus.
ds@1952	427	*/
ds@1952	428	class IBaseMenu
ds@1952	429	{
ds@1952	430	public:
ds@1952	431	/**
ds@1952	432	* @brief Appends an item to the end of a menu.
ds@1952	433	*
ds@1952	434	* @param info Item information string.
ds@1952	435	* @param draw Default drawing information.
ds@1952	436	* @return True on success, false on item limit reached.
ds@1952	437	*/
ds@1952	438	virtual bool AppendItem(const char *info, const ItemDrawInfo &draw) =0;
ds@1952	439
ds@1952	440	/**
ds@1952	441	* @brief Inserts an item into the menu before a certain position;
ds@1952	442	* the new item will be at the given position and all next items
ds@1952	443	* pushed forward.
ds@1952	444	*
ds@1952	445	* @param position Position, starting from 0.
ds@1952	446	* @param info Item information string.
ds@1952	447	* @param draw Default item draw info.
ds@1952	448	* @return True on success, false on invalid menu position
ds@1952	449	*/
ds@1952	450	virtual bool InsertItem(unsigned int position, const char *info, const ItemDrawInfo &draw) =0;
ds@1952	451
ds@1952	452	/**
ds@1952	453	* @brief Removes an item from the menu.
ds@1952	454	*
ds@1952	455	* @param position Position, starting from 0.
ds@1952	456	* @return True on success, false on invalid menu position.
ds@1952	457	*/
ds@1952	458	virtual bool RemoveItem(unsigned int position) =0;
ds@1952	459
ds@1952	460	/**
ds@1952	461	* @brief Removes all items from the menu.
ds@1952	462	*/
ds@1952	463	virtual void RemoveAllItems() =0;
ds@1952	464
ds@1952	465	/**
ds@1952	466	* @brief Returns an item's info.
ds@1952	467	*
ds@1952	468	* @param position Position, starting from 0.
ds@1952	469	* @param draw Optional pointer to store a draw information.
ds@1952	470	* @return Info string pointer, or NULL if position was invalid.
ds@1952	471	*/
ds@1952	472	virtual const char GetItemInfo(unsigned int position, ItemDrawInfo draw) =0;
ds@1952	473
ds@1952	474	/**
ds@1952	475	* @brief Returns the number of items.
ds@1952	476	*
ds@1952	477	* @return Number of items in the menu.
ds@1952	478	*/
ds@1952	479	virtual unsigned int GetItemCount() =0;
ds@1952	480
ds@1952	481	/**
ds@1952	482	* @brief Sets the menu's pagination,.
ds@1952	483	*
ds@1952	484	* If pagination is set to MENU_NO_PAGINATION, and the previous
ds@1952	485	* pagination was not MENU_NO_PAGINATION, then the MENUFLAG_BUTTON_EXIT
ds@1952	486	* is unset. It can be re-applied if desired.
ds@1952	487	*
ds@1952	488	* @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION.
ds@1952	489	* @return True on success, false if itemsPerPage is too
ds@1952	490	* large.
ds@1952	491	*/
ds@1952	492	virtual bool SetPagination(unsigned int itemsPerPage) =0;
ds@1952	493
ds@1952	494	/**
ds@1952	495	* @brief Returns an item's pagination.
ds@1952	496	*
ds@1952	497	* @return Pagination setting.
ds@1952	498	*/
ds@1952	499	virtual unsigned int GetPagination() =0;
ds@1952	500
ds@1952	501	/**
ds@1952	502	* @brief Returns the menu style.
ds@1952	503	*
ds@1952	504	* @return Menu style.
ds@1952	505	*/
ds@1952	506	virtual IMenuStyle *GetDrawStyle() =0;
ds@1952	507
ds@1952	508	/**
ds@1952	509	* @brief Sets the menu's display title/message.
ds@1952	510	*
ds@1952	511	* @param message Message (format options allowed).
ds@1952	512	*/
ds@1952	513	virtual void SetDefaultTitle(const char *message) =0;
ds@1952	514
ds@1952	515	/**
ds@1952	516	* @brief Returns the menu's display/title message.
ds@1952	517	*
ds@1952	518	* @return Message string.
ds@1952	519	*/
ds@1952	520	virtual const char *GetDefaultTitle() =0;
ds@1952	521
ds@1952	522	/**
ds@1952	523	* @brief Sets an extended menu option.
ds@1952	524	*
ds@1952	525	* @param option Option type.
ds@1952	526	* @param valuePtr Pointer of the type expected by the option.
ds@1952	527	* @return True on success, false if option or value is not supported.
ds@1952	528	*/
ds@1952	529	virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0;
ds@1952	530
ds@1952	531	/**
ds@1952	532	* @brief Creates a new IMenuPanel object using extended options specific
ds@1952	533	* to the IMenuStyle parent. Titles, items, etc, are not copied.
ds@1952	534	*
ds@1952	535	* Note: The object should be freed with IMenuPanel::DeleteThis.
ds@1952	536	*
ds@1952	537	* @return IMenuPanel pointer.
ds@1952	538	*/
ds@1952	539	virtual IMenuPanel *CreatePanel() =0;
ds@1952	540
ds@1952	541	/**
ds@1952	542	* @brief Sends the menu to a client.
ds@1952	543	*
ds@1952	544	* @param client Client index to display to.
ds@1952	545	* @param time Time to hold menu for.
ds@1952	546	* @param alt_handler Alternate IMenuHandler.
ds@1952	547	* @return True on success, false otherwise.
ds@1952	548	*/
ds@1952	549	virtual bool Display(int client, unsigned int time, IMenuHandler *alt_handler=NULL) =0;
ds@1952	550
ds@1952	551	/**
ds@1952	552	* @brief Destroys the menu and frees all associated resources.
ds@1952	553	*
ds@1952	554	* @param releaseHandle If true, the Handle will be released
ds@1952	555	* in the destructor. This should be set
ds@1952	556	* to true except for IHandleTypeDispatch
ds@1952	557	* destructors.
ds@1952	558	*/
ds@1952	559	virtual void Destroy(bool releaseHandle=true) =0;
ds@1952	560
ds@1952	561	/**
ds@1952	562	* @brief Cancels the menu on all client's displays. While the menu is
ds@1952	563	* being cancelled, the menu may not be re-displayed to any clients.
ds@1952	564	* If a vote menu is currently active, it will be cancelled as well.
ds@1952	565	*
ds@1952	566	* @return Number of menus cancelled.
ds@1952	567	*/
ds@1952	568	virtual void Cancel() =0;
ds@1952	569
ds@1952	570	/**
ds@1952	571	* @brief Returns the menu's Handle. The Handle is automatically
ds@1952	572	* removed when the menu is destroyed.
ds@1952	573	*
ds@1952	574	* @return Handle_t handle value.
ds@1952	575	*/
ds@1952	576	virtual Handle_t GetHandle() =0;
ds@1952	577
ds@1952	578	/**
ds@1952	579	* @brief Returns menu option flags.
ds@1952	580	*
ds@1952	581	* @return Menu option flags.
ds@1952	582	*/
ds@1952	583	virtual unsigned int GetMenuOptionFlags() =0;
ds@1952	584
ds@1952	585	/**
ds@1952	586	* @brief Sets menu option flags.
ds@1952	587	*
ds@1952	588	* @param flags Menu option flags.
ds@1952	589	*/
ds@1952	590	virtual void SetMenuOptionFlags(unsigned int flags) =0;
ds@1952	591
ds@1952	592	/**
ds@1952	593	* @brief Returns the menu's handler.
ds@1952	594	*
ds@1952	595	* @return IMenuHandler of the menu.
ds@1952	596	*/
ds@1952	597	virtual IMenuHandler *GetHandler() =0;
ds@1952	598
ds@1952	599	/**
ds@1952	600	* @brief Sends the menu to a client, starting from the given item number.
ds@1952	601	*
ds@1952	602	* Note: this API call was added in v13.
ds@1952	603	*
ds@1952	604	* @param client Client index to display to.
ds@1952	605	* @param time Time to hold menu for.
ds@1952	606	* @param start_item Starting item to draw.
ds@1952	607	* @param alt_handler Alternate IMenuHandler.
ds@1952	608	* @return True on success, false otherwise.
ds@1952	609	*/
ds@1952	610	virtual bool DisplayAtItem(int client,
ds@1952	611	unsigned int time,
ds@1952	612	unsigned int start_item,
ds@1952	613	IMenuHandler *alt_handler=NULL) =0;
ds@1952	614
ds@1952	615	/**
ds@1952	616	* @brief For the Handle system, returns approximate memory usage.
ds@1952	617	*
ds@1952	618	* @return Approximate number of bytes being used.
ds@1952	619	*/
ds@1952	620	virtual unsigned int GetApproxMemUsage() =0;
ds@1952	621	};
ds@1952	622
ds@1952	623	/**
ds@1952	624	* @brief Contains callbacks for menu actions.
ds@1952	625	*/
ds@1952	626	class IMenuHandler
ds@1952	627	{
ds@1952	628	public:
ds@1952	629	/**
ds@1952	630	* @brief Returns the menu api verison.
ds@1952	631	*
ds@1952	632	* @return Menu API version.
ds@1952	633	*/
ds@1952	634	virtual unsigned int GetMenuAPIVersion2()
ds@1952	635	{
ds@1952	636	return SMINTERFACE_MENUMANAGER_VERSION;
ds@1952	637	}
ds@1952	638
ds@1952	639	/**
ds@1952	640	* @brief A display/selection cycle has started.
ds@1952	641	*
ds@1952	642	* @param menu Menu pointer.
ds@1952	643	*/
ds@1952	644	virtual void OnMenuStart(IBaseMenu *menu)
ds@1952	645	{
ds@1952	646	}
ds@1952	647
ds@1952	648	/**
ds@1952	649	* @brief Called before a menu is being displayed. This is where
ds@1952	650	* you can set an alternate title on the menu.
ds@1952	651	*
ds@1952	652	* @param menu Menu pointer.
ds@1952	653	* @param client Client index.
ds@1952	654	* @param display IMenuPanel pointer.
ds@1952	655	*/
ds@1952	656	virtual void OnMenuDisplay(IBaseMenu menu, int client, IMenuPanel display)
ds@1952	657	{
ds@1952	658	}
ds@1952	659
ds@1952	660	/**
ds@1952	661	* @brief Called when an item is selected.
ds@1952	662	*
ds@1952	663	* @param menu Menu pointer.
ds@1952	664	* @param client Client that selected the item.
ds@1952	665	* @param item Item number.
ds@1952	666	*/
ds@1952	667	virtual void OnMenuSelect(IBaseMenu *menu, int client, unsigned int item)
ds@1952	668	{
ds@1952	669	}
ds@1952	670
ds@1952	671	/**
ds@1952	672	* @brief An active menu display was dropped from a client.
ds@1952	673	*
ds@1952	674	* @param menu Menu pointer.
ds@1952	675	* @param client Client that had the menu.
ds@1952	676	* @param reason Menu cancellation reason.
ds@1952	677	*/
ds@1952	678	virtual void OnMenuCancel(IBaseMenu *menu, int client, MenuCancelReason reason)
ds@1952	679	{
ds@1952	680	}
ds@1952	681
ds@1952	682	/**
ds@1952	683	* @brief A display/selection cycle has ended.
ds@1952	684	*
ds@1952	685	* @param menu Menu pointer.
ds@1952	686	* @param reason MenuEndReason reason.
ds@1952	687	*/
ds@1952	688	virtual void OnMenuEnd(IBaseMenu *menu, MenuEndReason reason)
ds@1952	689	{
ds@1952	690	}
ds@1952	691
ds@1952	692	/**
ds@1952	693	* @brief Called when the menu object is destroyed.
ds@1952	694	*
ds@1952	695	* @param menu Menu pointer.
ds@1952	696	*/
ds@1952	697	virtual void OnMenuDestroy(IBaseMenu *menu)
ds@1952	698	{
ds@1952	699	}
ds@1952	700
ds@1952	701	/**
ds@1952	702	* @brief Called when requesting how to render an item.
ds@1952	703	*
ds@1952	704	* @param menu Menu pointer.
ds@1952	705	* @param client Client index receiving the menu.
ds@1952	706	* @param item Item number in the menu.
ds@1952	707	* @param style ITEMSTYLE flags, by reference for modification.
ds@1952	708	*/
ds@1952	709	virtual void OnMenuDrawItem(IBaseMenu *menu, int client, unsigned int item, unsigned int &style)
ds@1952	710	{
ds@1952	711	}
ds@1952	712
ds@1952	713	/**
ds@1952	714	* @brief Called when drawing item text.
ds@1952	715	*
ds@1952	716	* @param menu Menu pointer.
ds@1952	717	* @param client Client index receiving the menu.
ds@1952	718	* @param panel Panel being used to draw the menu.
ds@1952	719	* @param item Item number in the menu.
ds@1952	720	* @param dr Item draw information.
ds@1952	721	* @return 0 to let the render algorithm decide how to draw, otherwise,
ds@1952	722	* the return value from panel->DrawItem should be returned.
ds@1952	723	*/
ds@1952	724	virtual unsigned int OnMenuDisplayItem(IBaseMenu *menu,
ds@1952	725	int client,
ds@1952	726	IMenuPanel *panel,
ds@1952	727	unsigned int item,
ds@1952	728	const ItemDrawInfo &dr)
ds@1952	729	{
ds@1952	730	return 0;
ds@1952	731	}
ds@1952	732
ds@1952	733	/**
ds@1952	734	* @brief Called when a vote has been started and displayed to
ds@1952	735	* clients. This is called after OnMenuStart() and OnMenuDisplay(),
ds@1952	736	* but before OnMenuSelect().
ds@1952	737	*
ds@1952	738	* @param menu Menu pointer.
ds@1952	739	*/
ds@1952	740	virtual void OnMenuVoteStart(IBaseMenu *menu)
ds@1952	741	{
ds@1952	742	}
ds@1952	743
ds@1952	744	/**
ds@1952	745	* @brief Called when a vote ends. This is automatically called by the
ds@1952	746	* wrapper, and never needs to called from a style implementation.
ds@1952	747	*
ds@1952	748	* This function does not replace OnMenuEnd(), nor does it have the
ds@1952	749	* same meaning as OnMenuEnd(), meaning you should not destroy a menu
ds@1952	750	* while it is in this function.
ds@1952	751	*
ds@1952	752	* @param menu Menu pointer.
ds@1952	753	* @param results Menu vote results.
ds@1952	754	*/
ds@1952	755	virtual void OnMenuVoteResults(IBaseMenu menu, const menu_vote_result_t results)
ds@1952	756	{
ds@1952	757	}
ds@1952	758
ds@1952	759	/**
ds@1952	760	* @brief Called when a vote is cancelled. If this is called, then
ds@1952	761	* OnMenuVoteResults() will not be called. In both cases, OnMenuEnd will
ds@1952	762	* always be called.
ds@1952	763	*
ds@1952	764	* @param menu Menu pointer.
ds@1952	765	* @param reason VoteCancelReason reason.
ds@1952	766	*/
ds@1952	767	virtual void OnMenuVoteCancel(IBaseMenu *menu, VoteCancelReason reason)
ds@1952	768	{
ds@1952	769	}
ds@1952	770
ds@1952	771	/**
ds@1952	772	* @brief Call to set private handler stuff.
ds@1952	773	*
ds@1952	774	* @param option Option name.
ds@1952	775	* @param data Private data.
ds@1952	776	* @return True if set, false if invalid or unrecognized.
ds@1952	777	*/
ds@1952	778	virtual bool OnSetHandlerOption(const char option, const void data)
ds@1952	779	{
ds@1952	780	return false;
ds@1952	781	}
ds@1952	782
ds@1952	783	/**
ds@1952	784	* @brief Called when an item is selected.
ds@1952	785	*
ds@1952	786	* Note: This callback was added in v13. It is called after OnMenuSelect().
ds@1952	787	*
ds@1952	788	* @param menu Menu pointer.
ds@1952	789	* @param client Client that selected the item.
ds@1952	790	* @param item Item number.
ds@1952	791	* @param item_on_page The first item on the page the player was last
ds@1952	792	* viewing.
ds@1952	793	*/
ds@1952	794	virtual void OnMenuSelect2(IBaseMenu *menu,
ds@1952	795	int client,
ds@1952	796	unsigned int item,
ds@1952	797	unsigned int item_on_page)
ds@1952	798	{
ds@1952	799	}
ds@1952	800	};
ds@1952	801
ds@1952	802	/**
ds@1952	803	* @brief Manages menu creation and displaying.
ds@1952	804	*/
ds@1952	805	class IMenuManager : public SMInterface
ds@1952	806	{
ds@1952	807	public:
ds@1952	808	virtual const char *GetInterfaceName()
ds@1952	809	{
ds@1952	810	return SMINTERFACE_MENUMANAGER_NAME;
ds@1952	811	}
ds@1952	812	virtual unsigned int GetInterfaceVersion()
ds@1952	813	{
ds@1952	814	return SMINTERFACE_MENUMANAGER_VERSION;
ds@1952	815	}
ds@1952	816	virtual bool IsVersionCompatible(unsigned int version)
ds@1952	817	{
ds@1952	818	if (version < 11 \|\| version > GetInterfaceVersion())
ds@1952	819	{
ds@1952	820	return false;
ds@1952	821	}
ds@1952	822	return true;
ds@1952	823	}
ds@1952	824	public:
ds@1952	825	/**
ds@1952	826	* @brief Finds a style by name.
ds@1952	827	*
ds@1952	828	* @param name Name of the style (case insensitive).
ds@1952	829	* @return IMenuStyle pointer, or NULL if not found.
ds@1952	830	*/
ds@1952	831	virtual IMenuStyle FindStyleByName(const char name) =0;
ds@1952	832
ds@1952	833	/**
ds@1952	834	* @brief Returns the default draw style Core is using.
ds@1952	835	*
ds@1952	836	* @return Menu style pointer.
ds@1952	837	*/
ds@1952	838	virtual IMenuStyle *GetDefaultStyle() =0;
ds@1952	839
ds@1952	840	/**
ds@1952	841	* @brief Given a set of menu states, converts it to an IMenuPanel object.
ds@1952	842	*
ds@1952	843	* The state parameter is both INPUT and OUTPUT.
ds@1952	844	* INPUT: menu, mh, firstItem, lastItem
ds@1952	845	* OUTPUT: display, firstItem, lastItem, slots
ds@1952	846	*
ds@1952	847	* @param client Client index.
ds@1952	848	* @param states Menu states.
ds@1952	849	* @param order Order to search for items.
ds@1952	850	* @return IMenuPanel pointer, or NULL if no items could be
ds@1952	851	* found in the IBaseMenu pointer, or NULL if any
ds@1952	852	* other error occurred. Any valid pointer must
ds@1952	853	* be freed using IMenuPanel::DeleteThis.
ds@1952	854	*/
ds@1952	855	virtual IMenuPanel *RenderMenu(int client, menu_states_t &states, ItemOrder order) =0;
ds@1952	856
ds@1952	857	/**
ds@1952	858	* @brief Cancels a menu. Calls IBaseMenu::Cancel() after doing some preparatory
ds@1952	859	* work. This should always be used instead of directly calling Cancel().
ds@1952	860	*
ds@1952	861	* @param menu IBaseMenu pointer.
ds@1952	862	*/
ds@1952	863	virtual void CancelMenu(IBaseMenu *menu) =0;
ds@1952	864
ds@1952	865	/**
ds@1952	866	* @brief Displays a menu as a vote.
ds@1952	867	*
ds@1952	868	* @param menu IBaseMenu pointer.
ds@1952	869	* @param num_clients Number of clients to display to.
ds@1952	870	* @param clients Client index array.
ds@1952	871	* @param max_time Maximum time to hold menu for.
ds@1952	872	* @param flags Vote flags (currently unused).
ds@1952	873	* @return True on success, false if a vote is in progress.
ds@1952	874	*/
ds@1952	875	virtual bool StartVote(IBaseMenu *menu,
ds@1952	876	unsigned int num_clients,
ds@1952	877	int clients[],
ds@1952	878	unsigned int max_time,
ds@1952	879	unsigned int flags=0) =0;
ds@1952	880
ds@1952	881	/**
ds@1952	882	* @brief Returns whether or not a vote is in progress.
ds@1952	883	*
ds@1952	884	* @return True if a vote is in progress, false otherwise.
ds@1952	885	*/
ds@1952	886	virtual bool IsVoteInProgress() =0;
ds@1952	887
ds@1952	888	/**
ds@1952	889	* @brief Cancels the vote in progress. This calls IBaseMenu::Cancel().
ds@1952	890	*/
ds@1952	891	virtual void CancelVoting() =0;
ds@1952	892
ds@1952	893	/**
ds@1952	894	* @brief Returns the remaining vote delay from the last menu. This delay is
ds@1952	895	* a suggestion for all public votes, and is not enforced.
ds@1952	896	*
ds@1952	897	* @return Number of seconds to wait.
ds@1952	898	*/
ds@1952	899	virtual unsigned int GetRemainingVoteDelay() =0;
dvander@2056	900
dvander@2056	901	/**
dvander@2056	902	* @brief Returns whether a client is in the "allowed to vote" pool determined
dvander@2056	903	* by the initial call to StartVote().
dvander@2056	904	*
dvander@2056	905	* @param client Client index.
dvander@2056	906	* @return True if client is allowed to vote, false on failure.
dvander@2056	907	*/
dvander@2056	908	virtual bool IsClientInVotePool(int client) =0;
dvander@2056	909
dvander@2056	910	/**
dvander@2056	911	* @brief Redraws the current vote menu to a client in the voting pool.
dvander@2056	912	*
dvander@2056	913	* @param client Client index.
dvander@2056	914	* @return True on success, false if client is not allowed to vote.
dvander@2056	915	*/
dvander@2056	916	virtual bool RedrawClientVoteMenu(int client) =0;
ds@1952	917	};
ds@1952	918	}
ds@1952	919
ds@1952	920	#endif //_INCLUDE_SOURCEMOD_MENU_SYSTEM_H_

author	David Anderson <dvander@alliedmods.net>
	Sat Sep 06 09:12:21 2008 +0000 (2008-09-06)
changeset 2256	de422b59bdfc
parent 2056	f1fcde46ac7c
child 2289	44045ead61cd
permissions	-rw-r--r--