ds@1990: /**
ds@1990:  * vim: set ts=4 :
ds@1990:  * =============================================================================
ds@1990:  * SourceMod (C)2004-2008 AlliedModders LLC.  All rights reserved.
ds@1990:  * =============================================================================
ds@1990:  *
ds@1990:  * This file is part of the SourceMod/SourcePawn SDK.
ds@1990:  *
ds@1990:  * This program is free software; you can redistribute it and/or modify it under
ds@1990:  * the terms of the GNU General Public License, version 3.0, as published by the
ds@1990:  * Free Software Foundation.
ds@1990:  * 
ds@1990:  * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1990:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1990:  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
ds@1990:  * details.
ds@1990:  *
ds@1990:  * You should have received a copy of the GNU General Public License along with
ds@1990:  * this program.  If not, see <http://www.gnu.org/licenses/>.
ds@1990:  *
ds@1990:  * As a special exception, AlliedModders LLC gives you permission to link the
ds@1990:  * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1990:  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1990:  * by the Valve Corporation.  You must obey the GNU General Public License in
ds@1990:  * all respects for all other code used.  Additionally, AlliedModders LLC grants
ds@1990:  * this exception to all derivative works.  AlliedModders LLC defines further
ds@1990:  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1990:  * or <http://www.sourcemod.net/license.php>.
ds@1990:  *
ds@1990:  * Version: $Id$
ds@1990:  */
ds@1990:  
ds@1990: #if defined _topmenus_included
ds@1990:  #endinput
ds@1990: #endif
ds@1990: #define _topmenus_included
ds@1990: 
ds@1990: #include <menus>
ds@1990: 
ds@1990: /**
ds@1990:  * Actions a top menu will take on an object.
ds@1990:  */
ds@1990: enum TopMenuAction
ds@1990: {
ds@1990: 	/**
ds@1990: 	 * An option is being drawn for a menu (or for sorting purposes).
ds@1990: 	 *
ds@1990: 	 * INPUT : TopMenu Handle, object ID, client index.
ds@1990: 	 * OUTPUT: Buffer for rendering, maxlength of buffer.
ds@1990: 	 */
ds@1990: 	TopMenuAction_DisplayOption = 0,
ds@1990: 	
ds@1990: 	/**
ds@1990: 	 * The title of a menu is being drawn for a given object.
ds@1990: 	 *
ds@1990: 	 * Note: The Object ID will be INVALID_TOPMENUOBJECT if drawing the 
ds@1990: 	 * root title.  Otherwise, the Object ID is a category.
ds@1990: 	 *
ds@1990: 	 * INPUT : TopMenu Handle, object ID, client index.
ds@1990: 	 * OUTPUT: Buffer for rendering, maxlength of buffer.
ds@1990: 	 */
ds@1990: 	TopMenuAction_DisplayTitle = 1,
ds@1990: 	
ds@1990: 	/**
ds@1990: 	 * A menu option has been selected.
ds@1990: 	 *
ds@1990: 	 * The Object ID will always be an item (not a category).
ds@1990: 	 *
ds@1990: 	 * INPUT : TopMenu Handle, object ID, client index.
ds@1990: 	 */
ds@1990: 	TopMenuAction_SelectOption = 2,
ds@1990: 
ds@1990: 	/**
ds@1990: 	 * A menu option is being drawn and its flags can be overridden.
ds@1990: 	 *
ds@1990: 	 * INPUT : TopMenu Handle, object ID, client index.
ds@1990: 	 * OUTPUT: The first byte of the 'buffer' string should be set 
ds@1990: 	 *		   to the desired flags.  By default, it will contain
ds@1990: 	 *		   ITEMDRAW_DEFAULT.
ds@1990: 	 */
ds@1990: 	 TopMenuAction_DrawOption = 3,
ds@1990: 	 
ds@1990: 	/**
ds@1990: 	 * Called when an object is being removed from the menu.
ds@1990: 	 * This can be used to clean up data stored in the info string.
ds@1990: 	 *
ds@1990: 	 * INPUT : TopMenu Handle, object ID.
ds@1990: 	 */
ds@1990: 	 TopMenuAction_RemoveObject = 4,
ds@1990: };
ds@1990: 
ds@1990: /**
ds@1990:  * Top menu object types.
ds@1990:  */
ds@1990: enum TopMenuObjectType
ds@1990: {
ds@1990: 	TopMenuObject_Category = 0,			/**< Category (sub-menu branching from root) */
ds@1990: 	TopMenuObject_Item = 1				/**< Item on a sub-menu */
ds@1990: };
ds@1990: 
ds@1990: /**
ds@1990:  * Top menu starting positions for display.
ds@1990:  */
ds@1990: enum TopMenuPosition
ds@1990: {
ds@1990: 	TopMenuPosition_Start = 0,			/**< Start/root of the menu */
ds@1990: 	TopMenuPosition_LastRoot = 1,		/**< Last position in the root menu */
ds@1990: 	TopMenuPosition_LastCategory = 3,	/**< Last position in their last category */
ds@1990: };
ds@1990: 
ds@1990: /**
ds@1990:  * Top menu object tag for type checking.
ds@1990:  */
ds@1990: enum TopMenuObject
ds@1990: {
ds@1990: 	INVALID_TOPMENUOBJECT = 0,
pred@2018: };
ds@1990: 
ds@1990: /**
ds@1990:  * TopMenu callback prototype.
ds@1990:  *
ds@1990:  * @param topmenu			Handle to the TopMenu.
ds@1990:  * @param action			TopMenuAction being performed.
ds@1990:  * @param object_id			The object ID (if used).
ds@1990:  * @param param				Extra parameter (if used).
ds@1990:  * @param buffer			Output buffer (if used).
ds@1990:  * @param maxlength			Output buffer (if used).
ds@1990:  * @noreturn
ds@1990:  */
dvander@2317: functag public TopMenuHandler(Handle:topmenu, 
ds@1990: 							  TopMenuAction:action,
ds@1990: 							  TopMenuObject:object_id,
ds@1990: 							  param,
ds@1990: 							  String:buffer[],
ds@1990: 							  maxlength);
ds@1990: 
ds@1990: /**
ds@1990:  * Creates a TopMenu.
ds@1990:  *
ds@1990:  * @param handler			Handler to use for drawing the root title.
ds@1990:  * @return					A new TopMenu Handle, or INVALID_HANDLE on failure.
ds@1990:  */						  
ds@1990: native Handle:CreateTopMenu(TopMenuHandler:handler);
ds@1990: 
ds@1990: /**
ds@1990:  * Re-sorts the items in a TopMenu via a configuration file.
ds@1990:  *
ds@1990:  * The format of the configuration file should be a Valve Key-Values 
ds@1990:  * formatted file that SourceMod can parse.  There should be one root 
ds@1990:  * section, and one sub-section for each category.  Each sub-section's 
ds@1990:  * name should match the category name.
ds@1990:  *
ds@1990:  * Each sub-section may only contain key/value pairs in the form of:
ds@1990:  * key: "item"
ds@1990:  * value: Name of the item as passed to AddToTopMenu().
ds@1990:  *
ds@1990:  * The TopMenu will draw items in the order declared in the configuration 
ds@1990:  * file.  If items do not appear in the configuration file, they are sorted 
ds@1990:  * per-player based on how the handler function renders for that player.  
ds@1990:  * These items appear after the configuration sorted items.
ds@1990:  *
ds@1990:  * @param topmenu			TopMenu Handle.
ds@1990:  * @param file				File path.
ds@1990:  * @param error				Error buffer.
ds@1990:  * @param maxlength			Maximum size of the error buffer.
ds@1990:  *							Error buffer will be filled with a 
ds@1990:  *							zero-terminated string if false is 
ds@1990:  *							returned.
ds@1990:  * @return					True on success, false on failure.
ds@1990:  * @error					Invalid TopMenu Handle.
ds@1990:  */
ds@1990: native bool:LoadTopMenuConfig(Handle:topmenu, const String:file[], String:error[], maxlength);
ds@1990: 
ds@1990: /**
ds@1990:  * Adds an object to a TopMenu.
ds@1990:  *
ds@1990:  * @param topmenu			TopMenu Handle.
ds@1990:  * @param name				Object name (MUST be unique).
ds@1990:  * @param type				Object type.
ds@1990:  * @param handler			Handler for object.
ds@1990:  * @param parent			Parent object ID, or INVALID_TOPMENUOBJECT for none.
ds@1990:  *							Items must have a category parent.
ds@1990:  *							Categories must not have a parent.
januk@4240:  * @param cmdname			Command name (for access overrides).
januk@4240:  * @param flags				Default access flags.
ds@1990:  * @param info_string		Arbitrary storage (max 255 bytes).
ds@1990:  * @return					A new TopMenuObject ID, or INVALID_TOPMENUOBJECT on
ds@1990:  *							failure.
ds@1990:  * @error					Invalid TopMenu Handle.
ds@1990:  */
ds@1990: native TopMenuObject:AddToTopMenu(Handle:topmenu,
ds@1990: 								  const String:name[],
ds@1990: 								  TopMenuObjectType:type,
ds@1990: 								  TopMenuHandler:handler,
ds@1990: 								  TopMenuObject:parent,
ds@1990: 								  const String:cmdname[]="",
ds@1990: 								  flags=0,
ds@1990: 								  const String:info_string[]="");
ds@1990: 								  
ds@1990: /**
ds@1990:  * Retrieves the info string of a top menu item.
ds@1990:  *
ds@1990:  * @param topmenu			TopMenu Handle.
erik@3967:  * @param parent			TopMenuObject ID.
ds@1990:  * @param buffer			Buffer to store info string.
ds@1990:  * @param maxlength			Maximum size of info string.
ds@1990:  * @return					Number of bytes written, not including the 
ds@1990:  *							null terminator.
ds@1990:  * @error					Invalid TopMenu Handle or TopMenuObject ID.
ds@1990:  */
ds@1990: native GetTopMenuInfoString(Handle:topmenu, TopMenuObject:parent, String:buffer[], maxlength);
ds@1990: 
ds@1990: /**
ds@1990:  * Retrieves the name string of a top menu item.
ds@1990:  *
ds@1990:  * @param topmenu			TopMenu Handle.
ds@1990:  * @param object			TopMenuObject ID.
ds@1990:  * @param buffer			Buffer to store info string.
ds@1990:  * @param maxlength			Maximum size of info string.
ds@1990:  * @return					Number of bytes written, not including the 
ds@1990:  *							null terminator.
ds@1990:  * @error					Invalid TopMenu Handle or TopMenuObject ID.
ds@1990:  */
ds@1990: native GetTopMenuObjName(Handle:topmenu, TopMenuObject:object, String:buffer[], maxlength);
ds@1990: 
ds@1990: /**
ds@1990:  * Removes an object from a TopMenu.
ds@1990:  *
ds@1990:  * Plugins' objects are automatically removed all TopMenus when the given 
ds@1990:  * plugin unloads or pauses.  In the case of unpausing, all items are restored.
ds@1990:  *
ds@1990:  * @param topmenu			TopMenu Handle.
ds@1990:  * @param object			TopMenuObject ID.
ds@1990:  * @noreturn
ds@1990:  * @error					Invalid TopMenu Handle.
ds@1990:  */
ds@1990: native RemoveFromTopMenu(Handle:topmenu, TopMenuObject:object);
ds@1990: 
ds@1990: /**
ds@1990:  * Displays a TopMenu to a client.
ds@1990:  *
ds@1990:  * @param topmenu			TopMenu Handle.
ds@1990:  * @param client			Client index.
ds@1990:  * @param position			Position to display from.
ds@1990:  * @return					True on success, false on failure.
ds@1990:  * @error					Invalid TopMenu Handle or client not in game.
ds@1990:  */
ds@1990: native bool:DisplayTopMenu(Handle:topmenu, client, TopMenuPosition:position);
ds@1990: 
ds@1990: /**
januk@4351:  * Displays a TopMenu category to a client.
januk@4351:  *
januk@4351:  * @param topmenu			TopMenu Handle.
januk@4351:  * @param category		Category object id.
januk@4351:  * @param client			Client index.
januk@4351:  * @return					True on success, false on failure.
januk@4351:  * @error					Invalid TopMenu Handle or client not in game.
januk@4351:  */
januk@4351: native bool:DisplayTopMenuCategory(Handle:topmenu, TopMenuObject:category, client);
januk@4351: 
januk@4351: /**
ds@1990:  * Finds a category's object ID in a TopMenu.
ds@1990:  *
ds@1990:  * @param topmenu			TopMenu Handle.
ds@1990:  * @param name				Object's unique name.
ds@1990:  * @return					TopMenuObject ID on success, or 
ds@1990:  *							INVALID_TOPMENUOBJECT on failure.
ds@1990:  * @error					Invalid TopMenu Handle.
ds@1990:  */
ds@1990: native TopMenuObject:FindTopMenuCategory(Handle:topmenu, const String:name[]);
ds@1990: 
ds@1990: /**
januk@4350:  * Change the menu title caching behaviour of the TopMenu. By default the titles are cached to reduce overhead.
januk@4350:  * If you need dynamic menu titles, which can change everytime the menu is displayed to a user, set this to false.
januk@4350:  *
januk@4350:  * @param topmenu       TopMenu Handle.
januk@4350:  * @param cache_titles  Cache the menu titles and don't call the handler with TopMenuAction_DisplayTitle everytime the menu is drawn?
januk@4350:  * @noreturn
januk@4350:  * @error               Invalid TopMenu Handle
januk@4350:  */
januk@4350: native SetTopMenuTitleCaching(Handle:topmenu, bool:cache_titles);
januk@4350: 
januk@4350: /**
ds@1990:  * Do not edit below this line!
ds@1990:  */
ds@1990: public Extension:__ext_topmenus = 
ds@1990: {
ds@1990: 	name = "TopMenus",
ds@1990: 	file = "topmenus.ext",
ds@1990: #if defined AUTOLOAD_EXTENSIONS
ds@1990: 	autoload = 1,
ds@1990: #else
ds@1990: 	autoload = 0,
ds@1990: #endif
ds@1990: #if defined REQUIRE_EXTENSIONS
ds@1990: 	required = 1,
ds@1990: #else
ds@1990: 	required = 0,
ds@1990: #endif
ds@1990: };
ds@1990: 
ds@1990: #if !defined REQUIRE_EXTENSIONS
ds@1990: public __ext_topmenus_SetNTVOptional()
ds@1990: {
ds@1990: 	MarkNativeAsOptional("CreateTopMenu");
ds@1990: 	MarkNativeAsOptional("LoadTopMenuConfig");
ds@1990: 	MarkNativeAsOptional("AddToTopMenu");
ds@1990: 	MarkNativeAsOptional("RemoveFromTopMenu");
ds@1990: 	MarkNativeAsOptional("DisplayTopMenu");
januk@4351: 	MarkNativeAsOptional("DisplayTopMenuCategory");
ds@1990: 	MarkNativeAsOptional("FindTopMenuCategory");
januk@4350: 	MarkNativeAsOptional("SetTopMenuTitleCaching");
ds@1990: }
ds@1990: #endif