/**

 * vim: set ts=4 :

 * =============================================================================

 * SourceMod (C)2004-2008 AlliedModders LLC.  All rights reserved.

 * =============================================================================

 *

 * This file is part of the SourceMod/SourcePawn SDK.

 *

 * This program is free software; you can redistribute it and/or modify it under

 * the terms of the GNU General Public License, version 3.0, as published by the

 * Free Software Foundation.

 * 

 * This program is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

 * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more

 * details.

 *

 * You should have received a copy of the GNU General Public License along with

 * this program.  If not, see <http://www.gnu.org/licenses/>.

 *

 * As a special exception, AlliedModders LLC gives you permission to link the

 * code of this program (as well as its derivative works) to "Half-Life 2," the

 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software

 * by the Valve Corporation.  You must obey the GNU General Public License in

 * all respects for all other code used.  Additionally, AlliedModders LLC grants

 * this exception to all derivative works.  AlliedModders LLC defines further

 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),

 * or <http://www.sourcemod.net/license.php>.

 *

 * Version: $Id$

 */

#if defined _topmenus_included

 #endinput

#endif

#define _topmenus_included

#include <menus>

/**

 * Actions a top menu will take on an object.

 */

enum TopMenuAction

{

	/**

	 * An option is being drawn for a menu (or for sorting purposes).

	 *

	 * INPUT : TopMenu Handle, object ID, client index.

	 * OUTPUT: Buffer for rendering, maxlength of buffer.

	 */

	TopMenuAction_DisplayOption = 0,

	/**

	 * The title of a menu is being drawn for a given object.

	 *

	 * Note: The Object ID will be INVALID_TOPMENUOBJECT if drawing the 

	 * root title.  Otherwise, the Object ID is a category.

	 *

	 * INPUT : TopMenu Handle, object ID, client index.

	 * OUTPUT: Buffer for rendering, maxlength of buffer.

	 */

	TopMenuAction_DisplayTitle = 1,

	/**

	 * A menu option has been selected.

	 *

	 * The Object ID will always be an item (not a category).

	 *

	 * INPUT : TopMenu Handle, object ID, client index.

	 */

	TopMenuAction_SelectOption = 2,

	/**

	 * A menu option is being drawn and its flags can be overridden.

	 *

	 * INPUT : TopMenu Handle, object ID, client index.

	 * OUTPUT: The first byte of the 'buffer' string should be set 

	 *		   to the desired flags.  By default, it will contain

	 *		   ITEMDRAW_DEFAULT.

	 */

	 TopMenuAction_DrawOption = 3,

	/**

	 * Called when an object is being removed from the menu.

	 * This can be used to clean up data stored in the info string.

	 *

	 * INPUT : TopMenu Handle, object ID.

	 */

	 TopMenuAction_RemoveObject = 4,

};

/**

 * Top menu object types.

 */

enum TopMenuObjectType

{

	TopMenuObject_Category = 0,			/**< Category (sub-menu branching from root) */

	TopMenuObject_Item = 1				/**< Item on a sub-menu */

};

/**

 * Top menu starting positions for display.

 */

enum TopMenuPosition

{

	TopMenuPosition_Start = 0,			/**< Start/root of the menu */

	TopMenuPosition_LastRoot = 1,		/**< Last position in the root menu */

	TopMenuPosition_LastCategory = 3,	/**< Last position in their last category */

};

/**

 * Top menu object tag for type checking.

 */

enum TopMenuObject

{

	INVALID_TOPMENUOBJECT = 0,

};

/**

 * TopMenu callback prototype.

 *

 * @param topmenu			Handle to the TopMenu.

 * @param action			TopMenuAction being performed.

 * @param object_id			The object ID (if used).

 * @param param				Extra parameter (if used).

 * @param buffer			Output buffer (if used).

 * @param maxlength			Output buffer (if used).

 * @noreturn

 */

functag public TopMenuHandler(Handle:topmenu, 

							  TopMenuAction:action,

							  TopMenuObject:object_id,

							  param,

							  String:buffer[],

							  maxlength);

/**

 * Creates a TopMenu.

 *

 * @param handler			Handler to use for drawing the root title.

 * @return					A new TopMenu Handle, or INVALID_HANDLE on failure.

 */						  

native Handle:CreateTopMenu(TopMenuHandler:handler);

/**

 * Re-sorts the items in a TopMenu via a configuration file.

 *

 * The format of the configuration file should be a Valve Key-Values 

 * formatted file that SourceMod can parse.  There should be one root 

 * section, and one sub-section for each category.  Each sub-section's 

 * name should match the category name.

 *

 * Each sub-section may only contain key/value pairs in the form of:

 * key: "item"

 * value: Name of the item as passed to AddToTopMenu().

 *

 * The TopMenu will draw items in the order declared in the configuration 

 * file.  If items do not appear in the configuration file, they are sorted 

 * per-player based on how the handler function renders for that player.  

 * These items appear after the configuration sorted items.

 *

 * @param topmenu			TopMenu Handle.

 * @param file				File path.

 * @param error				Error buffer.

 * @param maxlength			Maximum size of the error buffer.

 *							Error buffer will be filled with a 

 *							zero-terminated string if false is 

 *							returned.

 * @return					True on success, false on failure.

 * @error					Invalid TopMenu Handle.

 */

native bool:LoadTopMenuConfig(Handle:topmenu, const String:file[], String:error[], maxlength);

/**

 * Adds an object to a TopMenu.

 *

 * @param topmenu			TopMenu Handle.

 * @param name				Object name (MUST be unique).

 * @param type				Object type.

 * @param handler			Handler for object.

 * @param cmdname			Command name (for access overrides).

 * @param flags				Default access flags.

 * @param parent			Parent object ID, or INVALID_TOPMENUOBJECT for none.

 *							Items must have a category parent.

 *							Categories must not have a parent.

 * @param info_string		Arbitrary storage (max 255 bytes).

 * @return					A new TopMenuObject ID, or INVALID_TOPMENUOBJECT on

 *							failure.

 * @error					Invalid TopMenu Handle.

 */

native TopMenuObject:AddToTopMenu(Handle:topmenu,

								  const String:name[],

								  TopMenuObjectType:type,

								  TopMenuHandler:handler,

								  TopMenuObject:parent,

								  const String:cmdname[]="",

								  flags=0,

								  const String:info_string[]="");

/**

 * Retrieves the info string of a top menu item.

 *

 * @param topmenu			TopMenu Handle.

 * @param object			TopMenuObject ID.

 * @param buffer			Buffer to store info string.

 * @param maxlength			Maximum size of info string.

 * @return					Number of bytes written, not including the 

 *							null terminator.

 * @error					Invalid TopMenu Handle or TopMenuObject ID.

 */

native GetTopMenuInfoString(Handle:topmenu, TopMenuObject:parent, String:buffer[], maxlength);

/**

 * Retrieves the name string of a top menu item.

 *

 * @param topmenu			TopMenu Handle.

 * @param object			TopMenuObject ID.

 * @param buffer			Buffer to store info string.

 * @param maxlength			Maximum size of info string.

 * @return					Number of bytes written, not including the 

 *							null terminator.

 * @error					Invalid TopMenu Handle or TopMenuObject ID.

 */

native GetTopMenuObjName(Handle:topmenu, TopMenuObject:object, String:buffer[], maxlength);

/**

 * Removes an object from a TopMenu.

 *

 * Plugins' objects are automatically removed all TopMenus when the given 

 * plugin unloads or pauses.  In the case of unpausing, all items are restored.

 *

 * @param topmenu			TopMenu Handle.

 * @param object			TopMenuObject ID.

 * @noreturn

 * @error					Invalid TopMenu Handle.

 */

native RemoveFromTopMenu(Handle:topmenu, TopMenuObject:object);

/**

 * Displays a TopMenu to a client.

 *

 * @param topmenu			TopMenu Handle.

 * @param client			Client index.

 * @param position			Position to display from.

 * @return					True on success, false on failure.

 * @error					Invalid TopMenu Handle or client not in game.

 */

native bool:DisplayTopMenu(Handle:topmenu, client, TopMenuPosition:position);

/**

 * Finds a category's object ID in a TopMenu.

 *

 * @param topmenu			TopMenu Handle.

 * @param name				Object's unique name.

 * @return					TopMenuObject ID on success, or 

 *							INVALID_TOPMENUOBJECT on failure.

 * @error					Invalid TopMenu Handle.

 */

native TopMenuObject:FindTopMenuCategory(Handle:topmenu, const String:name[]);

/**

 * Do not edit below this line!

 */

public Extension:__ext_topmenus = 

{

	name = "TopMenus",

	file = "topmenus.ext",

#if defined AUTOLOAD_EXTENSIONS

	autoload = 1,

#else

	autoload = 0,

#endif

#if defined REQUIRE_EXTENSIONS

	required = 1,

#else

	required = 0,

#endif

};

#if !defined REQUIRE_EXTENSIONS

public __ext_topmenus_SetNTVOptional()

{

	MarkNativeAsOptional("CreateTopMenu");

	MarkNativeAsOptional("LoadTopMenuConfig");

	MarkNativeAsOptional("AddToTopMenu");

	MarkNativeAsOptional("RemoveFromTopMenu");

	MarkNativeAsOptional("DisplayTopMenu");

	MarkNativeAsOptional("FindTopMenuCategory");

}

#endif