318 lines
10 KiB
C
318 lines
10 KiB
C
|
/**
|
||
|
|
* vim: set ts=4 :
|
||
|
|
* =============================================================================
|
||
|
|
* SourceMod
|
||
|
|
* Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
|
||
|
|
* =============================================================================
|
||
|
|
*
|
||
|
|
* 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$
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef _INCLUDE_SOURCEMOD_MAIN_MENU_INTERFACE_H_
|
||
|
|
#define _INCLUDE_SOURCEMOD_MAIN_MENU_INTERFACE_H_
|
||
|
|
|
||
|
|
#include <IShareSys.h>
|
||
|
|
#include <ILibrarySys.h>
|
||
|
|
#include <IAdminSystem.h>
|
||
|
|
#include <IMenuManager.h>
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @file ITopMenus.h
|
||
|
|
* @brief Interface header for creating and managing top-level menus.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#define SMINTERFACE_TOPMENUS_NAME "ITopMenus"
|
||
|
|
#define SMINTERFACE_TOPMENUS_VERSION 4
|
||
|
|
|
||
|
|
namespace SourceMod
|
||
|
|
{
|
||
|
|
/**
|
||
|
|
* @brief Top menu object types.
|
||
|
|
*/
|
||
|
|
enum TopMenuObjectType
|
||
|
|
{
|
||
|
|
TopMenuObject_Category = 0, /**< Category (sub-menu branching from root) */
|
||
|
|
TopMenuObject_Item = 1 /**< Item on a sub-menu */
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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 */
|
||
|
|
};
|
||
|
|
|
||
|
|
class ITopMenu;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Top Menu callbacks for rendering/drawing.
|
||
|
|
*/
|
||
|
|
class ITopMenuObjectCallbacks
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
/**
|
||
|
|
* @brief Must return the topmenu API version.
|
||
|
|
*
|
||
|
|
* @return Top Menu API version.
|
||
|
|
*/
|
||
|
|
virtual unsigned int GetTopMenuAPIVersion1()
|
||
|
|
{
|
||
|
|
return SMINTERFACE_TOPMENUS_VERSION;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Requests how the given item should be drawn for a client.
|
||
|
|
*
|
||
|
|
* Unlike the other callbacks, this is only called in determining
|
||
|
|
* whether to enable, disable, or ignore an item on a client's menu.
|
||
|
|
*
|
||
|
|
* @param menu A pointer to the parent ITopMenu.
|
||
|
|
* @param client Client index.
|
||
|
|
* @param object_id Object ID returned from ITopMenu::AddToMenu().
|
||
|
|
* @return ITEMDRAW flags to disable or not draw the
|
||
|
|
* option for this operation.
|
||
|
|
*/
|
||
|
|
virtual unsigned int OnTopMenuDrawOption(ITopMenu *menu,
|
||
|
|
int client,
|
||
|
|
unsigned int object_id)
|
||
|
|
{
|
||
|
|
return ITEMDRAW_DEFAULT;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Requests how the given item should be displayed for a client.
|
||
|
|
*
|
||
|
|
* This can be called either while drawing a menu or to decide how to
|
||
|
|
* sort a menu for a player.
|
||
|
|
*
|
||
|
|
* @param menu A pointer to the parent ITopMenu.
|
||
|
|
* @param client Client index.
|
||
|
|
* @param object_id Object ID returned from ITopMenu::AddToMenu().
|
||
|
|
* @param buffer Buffer to store rendered text.
|
||
|
|
* @param maxlength Maximum length of the rendering buffer.
|
||
|
|
*/
|
||
|
|
virtual void OnTopMenuDisplayOption(ITopMenu *menu,
|
||
|
|
int client,
|
||
|
|
unsigned int object_id,
|
||
|
|
char buffer[],
|
||
|
|
size_t maxlength) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Requests how the given item's title should be displayed for
|
||
|
|
* a client. This is called on any object_id that is a category.
|
||
|
|
*
|
||
|
|
* @param menu A pointer to the parent ITopMenu.
|
||
|
|
* @param client Client index.
|
||
|
|
* @param object_id Object ID returned from ITopMenu::AddToMenu(),
|
||
|
|
* or 0 if the title is the root menu title.
|
||
|
|
* @param buffer Buffer to store rendered text.
|
||
|
|
* @param maxlength Maximum length of the rendering buffer.
|
||
|
|
*/
|
||
|
|
virtual void OnTopMenuDisplayTitle(ITopMenu *menu,
|
||
|
|
int client,
|
||
|
|
unsigned int object_id,
|
||
|
|
char buffer[],
|
||
|
|
size_t maxlength) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Notifies the listener that the menu option has been selected.
|
||
|
|
*
|
||
|
|
* @param menu A pointer to the parent ITopMenu.
|
||
|
|
* @param client Client index.
|
||
|
|
* @param object_id Object ID returned from ITopMenu::AddToMenu().
|
||
|
|
*/
|
||
|
|
virtual void OnTopMenuSelectOption(ITopMenu *menu,
|
||
|
|
int client,
|
||
|
|
unsigned int object_id) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Notified when the given item is removed.
|
||
|
|
*
|
||
|
|
* @param menu A pointer to the parent ITopMenu.
|
||
|
|
* @param object_id Object ID returned from ITopMenu::AddToMenu(),
|
||
|
|
* or 0 if the title callbacks are being removed.
|
||
|
|
*/
|
||
|
|
virtual void OnTopMenuObjectRemoved(ITopMenu *menu, unsigned int object_id) =0;
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief "Top menu" interface, for managing top-level categorized menus.
|
||
|
|
*/
|
||
|
|
class ITopMenu
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
/**
|
||
|
|
* @brief Creates and adds an object type type to the top menu.
|
||
|
|
*
|
||
|
|
* @param name Unique, string name to give the object.
|
||
|
|
* @param type Object type.
|
||
|
|
* @param callbacks ITopMenuObjectCallbacks pointer.
|
||
|
|
* @param owner IdentityToken_t owner of the object.
|
||
|
|
* @param cmdname Command name used for override access checks.
|
||
|
|
* If NULL or empty, access will not be Checked.
|
||
|
|
* @param flags Default flag(s) to use for access checks.
|
||
|
|
* @param parent Parent object, or 0 if none.
|
||
|
|
* Currently, categories cannot have a parent,
|
||
|
|
* and items must have a category parent.
|
||
|
|
* @return An object ID, or 0 on failure.
|
||
|
|
*/
|
||
|
|
virtual unsigned int AddToMenu(const char *name,
|
||
|
|
TopMenuObjectType type,
|
||
|
|
ITopMenuObjectCallbacks *callbacks,
|
||
|
|
IdentityToken_t *owner,
|
||
|
|
const char *cmdname,
|
||
|
|
FlagBits flags,
|
||
|
|
unsigned int parent) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Removes an object from a menu. If the object has any
|
||
|
|
* children, those will be removed.
|
||
|
|
*
|
||
|
|
* @param object_id Object ID returned from AddToMenu.
|
||
|
|
*/
|
||
|
|
virtual void RemoveFromMenu(unsigned int object_id) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Sends the main menu to a given client.
|
||
|
|
*
|
||
|
|
* Once the menu is drawn to a client, the drawing order is cached.
|
||
|
|
* If text on the menu is rendered differently for the client's next
|
||
|
|
* viewing, the text will render properly, but its order will not
|
||
|
|
* change. The menu is sorted by its configuration. Remaining items
|
||
|
|
* are sorted in alphabetical order using the initial display text.
|
||
|
|
*
|
||
|
|
* @param client Client index.
|
||
|
|
* @param hold_time Time to hold the menu on the screen for.
|
||
|
|
* @param position TopMenuPosition enumeration value.
|
||
|
|
* @return True on success, false if nothing displayed.
|
||
|
|
*/
|
||
|
|
virtual bool DisplayMenu(int client, unsigned int hold_time, TopMenuPosition position) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Loads a configuration file for organizing the menu. This
|
||
|
|
* forces all known categories to be re-sorted.
|
||
|
|
*
|
||
|
|
* Only one configuration can be active at a time. Loading a new one
|
||
|
|
* will cause the old sorting to disappear.
|
||
|
|
*
|
||
|
|
* @param file File path.
|
||
|
|
* @param error Error buffer.
|
||
|
|
* @param maxlength Maximum length of the error buffer.
|
||
|
|
* @return True on success, false on failure.
|
||
|
|
*/
|
||
|
|
virtual bool LoadConfiguration(const char *file, char *error, size_t maxlength) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Finds a category's ID by name.
|
||
|
|
*
|
||
|
|
* @param name Category's name.
|
||
|
|
* @return Object ID of the category, or 0 if none.
|
||
|
|
*/
|
||
|
|
virtual unsigned int FindCategory(const char *name) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Creates and adds an object type type to the top menu.
|
||
|
|
*
|
||
|
|
* @param name Unique, string name to give the object.
|
||
|
|
* @param type Object type.
|
||
|
|
* @param callbacks ITopMenuObjectCallbacks pointer.
|
||
|
|
* @param owner IdentityToken_t owner of the object.
|
||
|
|
* @param cmdname Command name used for override access checks.
|
||
|
|
* If NULL or empty, access will not be Checked.
|
||
|
|
* @param flags Default flag(s) to use for access checks.
|
||
|
|
* @param parent Parent object, or 0 if none.
|
||
|
|
* Currently, categories cannot have a parent,
|
||
|
|
* and items must have a category parent.
|
||
|
|
* @param info_string Optional info string to attach to the object.
|
||
|
|
* Only 255 bytes of the string (including null
|
||
|
|
* terminator) will be stored.
|
||
|
|
* @return An object ID, or 0 on failure.
|
||
|
|
*/
|
||
|
|
virtual unsigned int AddToMenu2(const char *name,
|
||
|
|
TopMenuObjectType type,
|
||
|
|
ITopMenuObjectCallbacks *callbacks,
|
||
|
|
IdentityToken_t *owner,
|
||
|
|
const char *cmdname,
|
||
|
|
FlagBits flags,
|
||
|
|
unsigned int parent,
|
||
|
|
const char *info_string) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Returns an object's info string.
|
||
|
|
*
|
||
|
|
* @param object_id Object ID.
|
||
|
|
* @return Object's info string, or NULL if none.
|
||
|
|
*/
|
||
|
|
virtual const char *GetObjectInfoString(unsigned int object_id) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Returns an object's name string.
|
||
|
|
*
|
||
|
|
* @param object_id Object ID.
|
||
|
|
* @return Object's name string, or NULL if none.
|
||
|
|
*/
|
||
|
|
virtual const char *GetObjectName(unsigned int object_id) =0;
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Top menu manager.
|
||
|
|
*/
|
||
|
|
class ITopMenuManager : public SMInterface
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
virtual const char *GetInterfaceName() =0;
|
||
|
|
virtual unsigned int GetInterfaceVersion() =0;
|
||
|
|
virtual bool IsVersionCompatible(unsigned int version)
|
||
|
|
{
|
||
|
|
if (version < 2)
|
||
|
|
{
|
||
|
|
return false;
|
||
|
|
}
|
||
|
|
return SMInterface::IsVersionCompatible(version);
|
||
|
|
}
|
||
|
|
public:
|
||
|
|
/**
|
||
|
|
* @brief Creates a new top-level menu.
|
||
|
|
*
|
||
|
|
* @param callbacks Callbacks for the title text.
|
||
|
|
* The object_id for the title will always be 0.
|
||
|
|
* @return A new ITopMenu pointer.
|
||
|
|
*/
|
||
|
|
virtual ITopMenu *CreateTopMenu(ITopMenuObjectCallbacks *callbacks) =0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Destroys a top-level menu.
|
||
|
|
*
|
||
|
|
* @param topmenu Pointer to an ITopMenu.
|
||
|
|
*/
|
||
|
|
virtual void DestroyTopMenu(ITopMenu *topmenu) =0;
|
||
|
|
};
|
||
|
|
}
|
||
|
|
|
||
|
|
#endif //_INCLUDE_SOURCEMOD_MAIN_MENU_INTERFACE_H_
|
||
|
|
|