dvander@2168: /**
dvander@2168: * vim: set ts=4 :
dvander@2168: * =============================================================================
dvander@2168: * SourceMod
dvander@2168: * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
dvander@2168: * =============================================================================
dvander@2168: *
dvander@2168: * This program is free software; you can redistribute it and/or modify it under
dvander@2168: * the terms of the GNU General Public License, version 3.0, as published by the
dvander@2168: * Free Software Foundation.
dvander@2168: *
dvander@2168: * This program is distributed in the hope that it will be useful, but WITHOUT
dvander@2168: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
dvander@2168: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
dvander@2168: * details.
dvander@2168: *
dvander@2168: * You should have received a copy of the GNU General Public License along with
dvander@2168: * this program. If not, see .
dvander@2168: *
dvander@2168: * As a special exception, AlliedModders LLC gives you permission to link the
dvander@2168: * code of this program (as well as its derivative works) to "Half-Life 2," the
dvander@2168: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
dvander@2168: * by the Valve Corporation. You must obey the GNU General Public License in
dvander@2168: * all respects for all other code used. Additionally, AlliedModders LLC grants
dvander@2168: * this exception to all derivative works. AlliedModders LLC defines further
dvander@2168: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
dvander@2168: * or .
dvander@2168: *
dvander@2168: * Version: $Id$
dvander@2168: */
dvander@2168:
dvander@2168: #ifndef _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_
dvander@2168: #define _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_
dvander@2168:
dvander@2168: #include
dvander@2168: #include
dvander@2168:
dvander@2168: #define SMINTERFACE_MENUMANAGER_NAME "IMenuManager"
dvander@2168: #define SMINTERFACE_MENUMANAGER_VERSION 15
dvander@2168:
dvander@2168: /**
dvander@2168: * @file IMenuManager.h
dvander@2168: * @brief Abstracts on-screen menus for clients.
dvander@2168: */
dvander@2168:
dvander@2168: namespace SourceMod
dvander@2168: {
dvander@2168: /**
dvander@2168: * @brief Used to determine how an item selection is interpreted.
dvander@2168: */
dvander@2168: enum ItemSelection
dvander@2168: {
dvander@2168: ItemSel_None, /**< Invalid selection */
dvander@2168: ItemSel_Back, /**< Go back one page (really "Previous") */
dvander@2168: ItemSel_Next, /**< Go forward one page */
dvander@2168: ItemSel_Exit, /**< Menu was exited */
dvander@2168: ItemSel_Item, /**< Valid item selection */
dvander@2168: ItemSel_ExitBack, /**< Sends MenuEnd_ExitBack */
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Used to determine which order to search for items in.
dvander@2168: */
dvander@2168: enum ItemOrder
dvander@2168: {
dvander@2168: ItemOrder_Ascending, /**< Items should be drawn ascendingly */
dvander@2168: ItemOrder_Descending, /**< Items should be drawn descendingly */
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Pairs an item type with an item menu position.
dvander@2168: */
dvander@2168: struct menu_slots_t
dvander@2168: {
dvander@2168: ItemSelection type; /**< Item selection type */
dvander@2168: unsigned int item; /**< Item position, if applicable */
dvander@2168: };
dvander@2168:
dvander@2168: class IBaseMenu;
dvander@2168: class IMenuPanel;
dvander@2168: class IMenuHandler;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Describes menu display information.
dvander@2168: */
dvander@2168: struct menu_states_t
dvander@2168: {
dvander@2168: unsigned int apiVers; /**< Must be filled with the API version */
dvander@2168: IBaseMenu *menu; /**< Menu pointer, or NULL if there is only a display */
dvander@2168: IMenuHandler *mh; /**< Menu callbacks handler */
dvander@2168: unsigned int firstItem; /**< MENU ONLY: First item displayed on the last page */
dvander@2168: unsigned int lastItem; /**< MENU ONLY: Last item displayed on the last page */
dvander@2168: unsigned int item_on_page; /**< MENU ONLY: First item on page */
dvander@2168: menu_slots_t slots[11]; /**< MENU ONLY: Item selection table (first index is 1) */
dvander@2168: };
dvander@2168:
dvander@2168: #define ITEMDRAW_DEFAULT (0) /**< Item should be drawn normally */
dvander@2168: #define ITEMDRAW_DISABLED (1<<0) /**< Item is drawn but not selectable */
dvander@2168: #define ITEMDRAW_RAWLINE (1<<1) /**< Item should be a raw line, without a slot */
dvander@2168: #define ITEMDRAW_NOTEXT (1<<2) /**< No text should be drawn */
dvander@2168: #define ITEMDRAW_SPACER (1<<3) /**< Item should be drawn as a spacer, if possible */
dvander@2168: #define ITEMDRAW_IGNORE ((1<<1)|(1<<2)) /**< Item should be completely ignored (rawline + notext) */
dvander@2168: #define ITEMDRAW_CONTROL (1<<4) /**< Item is control text (back/next/exit) */
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Information about item drawing.
dvander@2168: */
dvander@2168: struct ItemDrawInfo
dvander@2168: {
dvander@2168: ItemDrawInfo(const char *DISPLAY=NULL, unsigned int STYLE=ITEMDRAW_DEFAULT,
dvander@2168: unsigned int FLAGS=0, const char *HELPTEXT=NULL)
dvander@2168: : display(DISPLAY), style(STYLE)
dvander@2168: {
dvander@2168: }
dvander@2168: const char *display; /**< Display text (NULL for none) */
dvander@2168: unsigned int style; /**< ITEMDRAW style flags */
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Contains information about a vote result.
dvander@2168: */
dvander@2168: struct menu_vote_result_t
dvander@2168: {
dvander@2168: unsigned int num_clients; /**< Number of clients the menu was displayed to */
dvander@2168: unsigned int num_votes; /**< Number of votes received */
dvander@2168: struct menu_client_vote_t
dvander@2168: {
dvander@2168: int client; /**< Client index */
dvander@2168: int item; /**< Item # (or -1 for none) */
dvander@2168: } *client_list; /**< Array of size num_clients */
dvander@2168: unsigned int num_items; /**< Number of items voted for */
dvander@2168: struct menu_item_vote_t
dvander@2168: {
dvander@2168: unsigned int item; /**< Item index */
dvander@2168: unsigned int count; /**< Number of votes */
dvander@2168: } *item_list; /**< Array of size num_items, sorted by count,
dvander@2168: descending */
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Reasons for a menu dying.
dvander@2168: */
dvander@2168: enum MenuCancelReason
dvander@2168: {
dvander@2168: MenuCancel_Disconnected = -1, /**< Client dropped from the server */
dvander@2168: MenuCancel_Interrupted = -2, /**< Client was interrupted with another menu */
dvander@2168: MenuCancel_Exit = -3, /**< Client selected "exit" on a paginated menu */
dvander@2168: MenuCancel_NoDisplay = -4, /**< Menu could not be displayed to the client */
dvander@2168: MenuCancel_Timeout = -5, /**< Menu timed out */
dvander@2168: MenuCancel_ExitBack = -6, /**< Client selected "exit back" on a paginated menu */
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Reasons a menu ended.
dvander@2168: */
dvander@2168: enum MenuEndReason
dvander@2168: {
dvander@2168: MenuEnd_Selected = 0, /**< Menu item was selected */
dvander@2168: MenuEnd_VotingDone = -1, /**< Voting finished */
dvander@2168: MenuEnd_VotingCancelled = -2, /**< Voting was cancelled */
dvander@2168: MenuEnd_Cancelled = -3, /**< Menu was uncleanly cancelled */
dvander@2168: MenuEnd_Exit = -4, /**< Menu was cleanly exited via "exit" */
dvander@2168: MenuEnd_ExitBack = -5, /**< Menu was cleanly exited via "back" */
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Reasons a vote can be cancelled.
dvander@2168: */
dvander@2168: enum VoteCancelReason
dvander@2168: {
dvander@2168: VoteCancel_Generic = -1, /**< Vote was generically cancelled. */
dvander@2168: VoteCancel_NoVotes = -2, /**< Vote did not receive any votes. */
dvander@2168: };
dvander@2168:
dvander@2168: #define MENU_NO_PAGINATION 0 /**< Menu should not be paginated (10 items max) */
dvander@2168: #define MENU_TIME_FOREVER 0 /**< Menu should be displayed as long as possible */
dvander@2168:
dvander@2168: #define MENUFLAG_BUTTON_EXIT (1<<0) /**< Menu has an "exit" button */
dvander@2168: #define MENUFLAG_BUTTON_EXITBACK (1<<1) /**< Menu has an "exit back" button */
dvander@2168: #define MENUFLAG_NO_SOUND (1<<2) /**< Menu will not have any select sounds */
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Extended menu options.
dvander@2168: */
dvander@2168: enum MenuOption
dvander@2168: {
dvander@2168: MenuOption_IntroMessage, /**< CONST CHAR *: Valve menus only; defaults to:
dvander@2168: "You have a menu, hit ESC"
dvander@2168: */
dvander@2168: MenuOption_IntroColor, /**< INT[4]: Valve menus only; specifies the intro message colour
dvander@2168: using R,G,B,A (defaults to 255,0,0,255)
dvander@2168: */
dvander@2168: MenuOption_Priority, /**< INT *: Valve menus only; priority (less is higher) */
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Describes the menu a player is viewing.
dvander@2168: */
dvander@2168: enum MenuSource
dvander@2168: {
dvander@2168: MenuSource_None = 0, /**< No menu is being displayed */
dvander@2168: MenuSource_External = 1, /**< External menu, no pointer */
dvander@2168: MenuSource_BaseMenu = 2, /**< An IBaseMenu pointer. */
dvander@2168: MenuSource_Display = 3, /**< IMenuPanel source, no pointer */
dvander@2168: };
dvander@2168:
dvander@2168: class IMenuStyle;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets how a raw menu should be drawn.
dvander@2168: */
dvander@2168: class IMenuPanel
dvander@2168: {
dvander@2168: public:
dvander@2168: /**
dvander@2168: * @brief Returns the parent IMenuStyle pointer.
dvander@2168: *
dvander@2168: * @return IMenuStyle pointer which created
dvander@2168: * this object.
dvander@2168: */
dvander@2168: virtual IMenuStyle *GetParentStyle() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Resets/clears the cached display text.
dvander@2168: */
dvander@2168: virtual void Reset() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets how the title should be drawn.
dvander@2168: *
dvander@2168: * @param text Text string to display for the title.
dvander@2168: * @param onlyIfEmpty Only sets the title if one does not already
dvander@2168: * exist.
dvander@2168: */
dvander@2168: virtual void DrawTitle(const char *text, bool onlyIfEmpty=false) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Adds an item to the menu and returns the position (1-10).
dvander@2168: *
dvander@2168: * Note: Item will fail to draw if there are too many items,
dvander@2168: * or the item is not drawable (for example, invisible).
dvander@2168: *
dvander@2168: * @return Item draw position, or 0 on failure.
dvander@2168: */
dvander@2168: virtual unsigned int DrawItem(const ItemDrawInfo &item) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Draws a raw line of text, if supported. The line does not
dvander@2168: * need to be newline terminated.
dvander@2168: *
dvander@2168: * @return True on success, false if not supported.
dvander@2168: */
dvander@2168: virtual bool DrawRawLine(const char *rawline) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets an extended menu option.
dvander@2168: *
dvander@2168: * @param option Option type.
dvander@2168: * @param valuePtr Pointer of the type expected by the option.
dvander@2168: * @return True on success, false if option or value is not supported.
dvander@2168: */
dvander@2168: virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns whether the display is capable of rendering an item
dvander@2168: * with the given flags.
dvander@2168: *
dvander@2168: * @param drawFlags ITEMDRAW flags.
dvander@2168: * @return True if renderable, false otherwise.
dvander@2168: */
dvander@2168: virtual bool CanDrawItem(unsigned int drawFlags) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sends the menu display to a client.
dvander@2168: *
dvander@2168: * @param client Client index to display to.
dvander@2168: * @param handler Menu handler to use.
dvander@2168: * @param time Time to hold menu for.
dvander@2168: * @return True on success, false otherwise.
dvander@2168: */
dvander@2168: virtual bool SendDisplay(int client, IMenuHandler *handler, unsigned int time) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Destroys the display object.
dvander@2168: */
dvander@2168: virtual void DeleteThis() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets the selectable key map. Returns false if the function
dvander@2168: * is not supported.
dvander@2168: *
dvander@2168: * @param keymap A bit string where each bit N-1 specifies
dvander@2168: * that key N is selectable (key 0 is bit 9).
dvander@2168: * If the selectable key map is 0, it will be
dvander@2168: * automatically set to allow 0.
dvander@2168: * @return True on success, false if not supported.
dvander@2168: */
dvander@2168: virtual bool SetSelectableKeys(unsigned int keymap) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the current key position.
dvander@2168: *
dvander@2168: * @return Current key position starting at 1.
dvander@2168: */
dvander@2168: virtual unsigned int GetCurrentKey() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets the next key position. This cannot be used
dvander@2168: * to traverse backwards.
dvander@2168: *
dvander@2168: * @param key Key that is greater or equal to
dvander@2168: * GetCurrentKey().
dvander@2168: * @return True on success, false otherwise.
dvander@2168: */
dvander@2168: virtual bool SetCurrentKey(unsigned int key) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the number of characters that can be added to the
dvander@2168: * menu. The internal buffer is truncated if overflowed; this is for
dvander@2168: * manual truncation/wrapping purposes.
dvander@2168: *
dvander@2168: * @return Number of bytes available. If the result is
dvander@2168: * -1, then the panel has no text limit.
dvander@2168: */
dvander@2168: virtual int GetAmountRemaining() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief For the Handle system, returns approximate memory usage.
dvander@2168: *
dvander@2168: * @return Approximate number of bytes being used.
dvander@2168: */
dvander@2168: virtual unsigned int GetApproxMemUsage() =0;
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Describes a "MenuStyle" system which manages
dvander@2168: * menu drawing and construction.
dvander@2168: */
dvander@2168: class IMenuStyle
dvander@2168: {
dvander@2168: public:
dvander@2168: /**
dvander@2168: * @brief Returns the style API version.
dvander@2168: *
dvander@2168: * @return API version.
dvander@2168: */
dvander@2168: virtual unsigned int GetStyleAPIVersion()
dvander@2168: {
dvander@2168: return SMINTERFACE_MENUMANAGER_VERSION;
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the name of the menu style.
dvander@2168: *
dvander@2168: * @return String containing the style name.
dvander@2168: */
dvander@2168: virtual const char *GetStyleName() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Creates an IMenuPanel object.
dvander@2168: *
dvander@2168: * Note: the object should be freed using ::DeleteThis.
dvander@2168: *
dvander@2168: * @return IMenuPanel object.
dvander@2168: */
dvander@2168: virtual IMenuPanel *CreatePanel() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Creates an IBaseMenu object of this style.
dvander@2168: *
dvander@2168: * Note: the object should be freed using IBaseMenu::Destroy.
dvander@2168: *
dvander@2168: * @param handler IMenuHandler pointer.
dvander@2168: * @param pOwner Optional IdentityToken_t owner for handle
dvander@2168: * creation.
dvander@2168: * @return An IBaseMenu pointer.
dvander@2168: */
dvander@2168: virtual IBaseMenu *CreateMenu(IMenuHandler *handler, IdentityToken_t *pOwner=NULL) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the maximum number of items per page.
dvander@2168: *
dvander@2168: * Menu implementations must return >= 2. Styles with only 1 or 0
dvander@2168: * items per page are not valid.
dvander@2168: *
dvander@2168: * @return Number of items per page.
dvander@2168: */
dvander@2168: virtual unsigned int GetMaxPageItems() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns whether or not a client is viewing a menu.
dvander@2168: *
dvander@2168: * @param client Client index.
dvander@2168: * @param object Optional pointer to retrieve menu object,
dvander@2168: * if any.
dvander@2168: * @return MenuSource value.
dvander@2168: */
dvander@2168: virtual MenuSource GetClientMenu(int client, void **object) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Cancels a client's menu.
dvander@2168: *
dvander@2168: * @param client Client index.
dvander@2168: * @param autoIgnore If true, no menus can be created during
dvander@2168: * the cancellation process.
dvander@2168: * @return True if a menu was cancelled, false otherwise.
dvander@2168: */
dvander@2168: virtual bool CancelClientMenu(int client, bool autoIgnore=false) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns a Handle the IMenuStyle object.
dvander@2168: *
dvander@2168: * @return Handle_t pointing to this object.
dvander@2168: */
dvander@2168: virtual Handle_t GetHandle() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief For the Handle system, returns approximate memory usage.
dvander@2168: *
dvander@2168: * @return Approximate number of bytes being used.
dvander@2168: */
dvander@2168: virtual unsigned int GetApproxMemUsage() =0;
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief High-level interface for building menus.
dvander@2168: */
dvander@2168: class IBaseMenu
dvander@2168: {
dvander@2168: public:
dvander@2168: /**
dvander@2168: * @brief Appends an item to the end of a menu.
dvander@2168: *
dvander@2168: * @param info Item information string.
dvander@2168: * @param draw Default drawing information.
dvander@2168: * @return True on success, false on item limit reached.
dvander@2168: */
dvander@2168: virtual bool AppendItem(const char *info, const ItemDrawInfo &draw) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Inserts an item into the menu before a certain position;
dvander@2168: * the new item will be at the given position and all next items
dvander@2168: * pushed forward.
dvander@2168: *
dvander@2168: * @param position Position, starting from 0.
dvander@2168: * @param info Item information string.
dvander@2168: * @param draw Default item draw info.
dvander@2168: * @return True on success, false on invalid menu position
dvander@2168: */
dvander@2168: virtual bool InsertItem(unsigned int position, const char *info, const ItemDrawInfo &draw) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Removes an item from the menu.
dvander@2168: *
dvander@2168: * @param position Position, starting from 0.
dvander@2168: * @return True on success, false on invalid menu position.
dvander@2168: */
dvander@2168: virtual bool RemoveItem(unsigned int position) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Removes all items from the menu.
dvander@2168: */
dvander@2168: virtual void RemoveAllItems() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns an item's info.
dvander@2168: *
dvander@2168: * @param position Position, starting from 0.
dvander@2168: * @param draw Optional pointer to store a draw information.
dvander@2168: * @return Info string pointer, or NULL if position was invalid.
dvander@2168: */
dvander@2168: virtual const char *GetItemInfo(unsigned int position, ItemDrawInfo *draw) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the number of items.
dvander@2168: *
dvander@2168: * @return Number of items in the menu.
dvander@2168: */
dvander@2168: virtual unsigned int GetItemCount() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets the menu's pagination,.
dvander@2168: *
dvander@2168: * If pagination is set to MENU_NO_PAGINATION, and the previous
dvander@2168: * pagination was not MENU_NO_PAGINATION, then the MENUFLAG_BUTTON_EXIT
dvander@2168: * is unset. It can be re-applied if desired.
dvander@2168: *
dvander@2168: * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION.
dvander@2168: * @return True on success, false if itemsPerPage is too
dvander@2168: * large.
dvander@2168: */
dvander@2168: virtual bool SetPagination(unsigned int itemsPerPage) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns an item's pagination.
dvander@2168: *
dvander@2168: * @return Pagination setting.
dvander@2168: */
dvander@2168: virtual unsigned int GetPagination() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the menu style.
dvander@2168: *
dvander@2168: * @return Menu style.
dvander@2168: */
dvander@2168: virtual IMenuStyle *GetDrawStyle() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets the menu's display title/message.
dvander@2168: *
dvander@2168: * @param message Message (format options allowed).
dvander@2168: */
dvander@2168: virtual void SetDefaultTitle(const char *message) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the menu's display/title message.
dvander@2168: *
dvander@2168: * @return Message string.
dvander@2168: */
dvander@2168: virtual const char *GetDefaultTitle() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets an extended menu option.
dvander@2168: *
dvander@2168: * @param option Option type.
dvander@2168: * @param valuePtr Pointer of the type expected by the option.
dvander@2168: * @return True on success, false if option or value is not supported.
dvander@2168: */
dvander@2168: virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Creates a new IMenuPanel object using extended options specific
dvander@2168: * to the IMenuStyle parent. Titles, items, etc, are not copied.
dvander@2168: *
dvander@2168: * Note: The object should be freed with IMenuPanel::DeleteThis.
dvander@2168: *
dvander@2168: * @return IMenuPanel pointer.
dvander@2168: */
dvander@2168: virtual IMenuPanel *CreatePanel() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sends the menu to a client.
dvander@2168: *
dvander@2168: * @param client Client index to display to.
dvander@2168: * @param time Time to hold menu for.
dvander@2168: * @param alt_handler Alternate IMenuHandler.
dvander@2168: * @return True on success, false otherwise.
dvander@2168: */
dvander@2168: virtual bool Display(int client, unsigned int time, IMenuHandler *alt_handler=NULL) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Destroys the menu and frees all associated resources.
dvander@2168: *
dvander@2168: * @param releaseHandle If true, the Handle will be released
dvander@2168: * in the destructor. This should be set
dvander@2168: * to true except for IHandleTypeDispatch
dvander@2168: * destructors.
dvander@2168: */
dvander@2168: virtual void Destroy(bool releaseHandle=true) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Cancels the menu on all client's displays. While the menu is
dvander@2168: * being cancelled, the menu may not be re-displayed to any clients.
dvander@2168: * If a vote menu is currently active, it will be cancelled as well.
dvander@2168: *
dvander@2168: * @return Number of menus cancelled.
dvander@2168: */
dvander@2168: virtual void Cancel() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the menu's Handle. The Handle is automatically
dvander@2168: * removed when the menu is destroyed.
dvander@2168: *
dvander@2168: * @return Handle_t handle value.
dvander@2168: */
dvander@2168: virtual Handle_t GetHandle() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns menu option flags.
dvander@2168: *
dvander@2168: * @return Menu option flags.
dvander@2168: */
dvander@2168: virtual unsigned int GetMenuOptionFlags() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sets menu option flags.
dvander@2168: *
dvander@2168: * @param flags Menu option flags.
dvander@2168: */
dvander@2168: virtual void SetMenuOptionFlags(unsigned int flags) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the menu's handler.
dvander@2168: *
dvander@2168: * @return IMenuHandler of the menu.
dvander@2168: */
dvander@2168: virtual IMenuHandler *GetHandler() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Sends the menu to a client, starting from the given item number.
dvander@2168: *
dvander@2168: * Note: this API call was added in v13.
dvander@2168: *
dvander@2168: * @param client Client index to display to.
dvander@2168: * @param time Time to hold menu for.
dvander@2168: * @param start_item Starting item to draw.
dvander@2168: * @param alt_handler Alternate IMenuHandler.
dvander@2168: * @return True on success, false otherwise.
dvander@2168: */
dvander@2168: virtual bool DisplayAtItem(int client,
dvander@2168: unsigned int time,
dvander@2168: unsigned int start_item,
dvander@2168: IMenuHandler *alt_handler=NULL) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief For the Handle system, returns approximate memory usage.
dvander@2168: *
dvander@2168: * @return Approximate number of bytes being used.
dvander@2168: */
dvander@2168: virtual unsigned int GetApproxMemUsage() =0;
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Contains callbacks for menu actions.
dvander@2168: */
dvander@2168: class IMenuHandler
dvander@2168: {
dvander@2168: public:
dvander@2168: /**
dvander@2168: * @brief Returns the menu api verison.
dvander@2168: *
dvander@2168: * @return Menu API version.
dvander@2168: */
dvander@2168: virtual unsigned int GetMenuAPIVersion2()
dvander@2168: {
dvander@2168: return SMINTERFACE_MENUMANAGER_VERSION;
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief A display/selection cycle has started.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: */
dvander@2168: virtual void OnMenuStart(IBaseMenu *menu)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called before a menu is being displayed. This is where
dvander@2168: * you can set an alternate title on the menu.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param client Client index.
dvander@2168: * @param display IMenuPanel pointer.
dvander@2168: */
dvander@2168: virtual void OnMenuDisplay(IBaseMenu *menu, int client, IMenuPanel *display)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when an item is selected.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param client Client that selected the item.
dvander@2168: * @param item Item number.
dvander@2168: */
dvander@2168: virtual void OnMenuSelect(IBaseMenu *menu, int client, unsigned int item)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief An active menu display was dropped from a client.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param client Client that had the menu.
dvander@2168: * @param reason Menu cancellation reason.
dvander@2168: */
dvander@2168: virtual void OnMenuCancel(IBaseMenu *menu, int client, MenuCancelReason reason)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief A display/selection cycle has ended.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param reason MenuEndReason reason.
dvander@2168: */
dvander@2168: virtual void OnMenuEnd(IBaseMenu *menu, MenuEndReason reason)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when the menu object is destroyed.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: */
dvander@2168: virtual void OnMenuDestroy(IBaseMenu *menu)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when requesting how to render an item.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param client Client index receiving the menu.
dvander@2168: * @param item Item number in the menu.
dvander@2168: * @param style ITEMSTYLE flags, by reference for modification.
dvander@2168: */
dvander@2168: virtual void OnMenuDrawItem(IBaseMenu *menu, int client, unsigned int item, unsigned int &style)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when drawing item text.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param client Client index receiving the menu.
dvander@2168: * @param panel Panel being used to draw the menu.
dvander@2168: * @param item Item number in the menu.
dvander@2168: * @param dr Item draw information.
dvander@2168: * @return 0 to let the render algorithm decide how to draw, otherwise,
dvander@2168: * the return value from panel->DrawItem should be returned.
dvander@2168: */
dvander@2168: virtual unsigned int OnMenuDisplayItem(IBaseMenu *menu,
dvander@2168: int client,
dvander@2168: IMenuPanel *panel,
dvander@2168: unsigned int item,
dvander@2168: const ItemDrawInfo &dr)
dvander@2168: {
dvander@2168: return 0;
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when a vote has been started and displayed to
dvander@2168: * clients. This is called after OnMenuStart() and OnMenuDisplay(),
dvander@2168: * but before OnMenuSelect().
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: */
dvander@2168: virtual void OnMenuVoteStart(IBaseMenu *menu)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when a vote ends. This is automatically called by the
dvander@2168: * wrapper, and never needs to called from a style implementation.
dvander@2168: *
dvander@2168: * This function does not replace OnMenuEnd(), nor does it have the
dvander@2168: * same meaning as OnMenuEnd(), meaning you should not destroy a menu
dvander@2168: * while it is in this function.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param results Menu vote results.
dvander@2168: */
dvander@2168: virtual void OnMenuVoteResults(IBaseMenu *menu, const menu_vote_result_t *results)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when a vote is cancelled. If this is called, then
dvander@2168: * OnMenuVoteResults() will not be called. In both cases, OnMenuEnd will
dvander@2168: * always be called.
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param reason VoteCancelReason reason.
dvander@2168: */
dvander@2168: virtual void OnMenuVoteCancel(IBaseMenu *menu, VoteCancelReason reason)
dvander@2168: {
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Call to set private handler stuff.
dvander@2168: *
dvander@2168: * @param option Option name.
dvander@2168: * @param data Private data.
dvander@2168: * @return True if set, false if invalid or unrecognized.
dvander@2168: */
dvander@2168: virtual bool OnSetHandlerOption(const char *option, const void *data)
dvander@2168: {
dvander@2168: return false;
dvander@2168: }
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Called when an item is selected.
dvander@2168: *
dvander@2168: * Note: This callback was added in v13. It is called after OnMenuSelect().
dvander@2168: *
dvander@2168: * @param menu Menu pointer.
dvander@2168: * @param client Client that selected the item.
dvander@2168: * @param item Item number.
dvander@2168: * @param item_on_page The first item on the page the player was last
dvander@2168: * viewing.
dvander@2168: */
dvander@2168: virtual void OnMenuSelect2(IBaseMenu *menu,
dvander@2168: int client,
dvander@2168: unsigned int item,
dvander@2168: unsigned int item_on_page)
dvander@2168: {
dvander@2168: }
dvander@2168: };
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Manages menu creation and displaying.
dvander@2168: */
dvander@2168: class IMenuManager : public SMInterface
dvander@2168: {
dvander@2168: public:
dvander@2168: virtual const char *GetInterfaceName()
dvander@2168: {
dvander@2168: return SMINTERFACE_MENUMANAGER_NAME;
dvander@2168: }
dvander@2168: virtual unsigned int GetInterfaceVersion()
dvander@2168: {
dvander@2168: return SMINTERFACE_MENUMANAGER_VERSION;
dvander@2168: }
dvander@2168: virtual bool IsVersionCompatible(unsigned int version)
dvander@2168: {
dvander@2168: if (version < 11 || version > GetInterfaceVersion())
dvander@2168: {
dvander@2168: return false;
dvander@2168: }
dvander@2168: return true;
dvander@2168: }
dvander@2168: public:
dvander@2168: /**
dvander@2168: * @brief Finds a style by name.
dvander@2168: *
dvander@2168: * @param name Name of the style (case insensitive).
dvander@2168: * @return IMenuStyle pointer, or NULL if not found.
dvander@2168: */
dvander@2168: virtual IMenuStyle *FindStyleByName(const char *name) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the default draw style Core is using.
dvander@2168: *
dvander@2168: * @return Menu style pointer.
dvander@2168: */
dvander@2168: virtual IMenuStyle *GetDefaultStyle() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Given a set of menu states, converts it to an IMenuPanel object.
dvander@2168: *
dvander@2168: * The state parameter is both INPUT and OUTPUT.
dvander@2168: * INPUT: menu, mh, firstItem, lastItem
dvander@2168: * OUTPUT: display, firstItem, lastItem, slots
dvander@2168: *
dvander@2168: * @param client Client index.
dvander@2168: * @param states Menu states.
dvander@2168: * @param order Order to search for items.
dvander@2168: * @return IMenuPanel pointer, or NULL if no items could be
dvander@2168: * found in the IBaseMenu pointer, or NULL if any
dvander@2168: * other error occurred. Any valid pointer must
dvander@2168: * be freed using IMenuPanel::DeleteThis.
dvander@2168: */
dvander@2168: virtual IMenuPanel *RenderMenu(int client, menu_states_t &states, ItemOrder order) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Cancels a menu. Calls IBaseMenu::Cancel() after doing some preparatory
dvander@2168: * work. This should always be used instead of directly calling Cancel().
dvander@2168: *
dvander@2168: * @param menu IBaseMenu pointer.
dvander@2168: */
dvander@2168: virtual void CancelMenu(IBaseMenu *menu) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Displays a menu as a vote.
dvander@2168: *
dvander@2168: * @param menu IBaseMenu pointer.
dvander@2168: * @param num_clients Number of clients to display to.
dvander@2168: * @param clients Client index array.
dvander@2168: * @param max_time Maximum time to hold menu for.
dvander@2168: * @param flags Vote flags (currently unused).
dvander@2168: * @return True on success, false if a vote is in progress.
dvander@2168: */
dvander@2168: virtual bool StartVote(IBaseMenu *menu,
dvander@2168: unsigned int num_clients,
dvander@2168: int clients[],
dvander@2168: unsigned int max_time,
dvander@2168: unsigned int flags=0) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns whether or not a vote is in progress.
dvander@2168: *
dvander@2168: * @return True if a vote is in progress, false otherwise.
dvander@2168: */
dvander@2168: virtual bool IsVoteInProgress() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Cancels the vote in progress. This calls IBaseMenu::Cancel().
dvander@2168: */
dvander@2168: virtual void CancelVoting() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns the remaining vote delay from the last menu. This delay is
dvander@2168: * a suggestion for all public votes, and is not enforced.
dvander@2168: *
dvander@2168: * @return Number of seconds to wait.
dvander@2168: */
dvander@2168: virtual unsigned int GetRemainingVoteDelay() =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Returns whether a client is in the "allowed to vote" pool determined
dvander@2168: * by the initial call to StartVote().
dvander@2168: *
dvander@2168: * @param client Client index.
dvander@2168: * @return True if client is allowed to vote, false on failure.
dvander@2168: */
dvander@2168: virtual bool IsClientInVotePool(int client) =0;
dvander@2168:
dvander@2168: /**
dvander@2168: * @brief Redraws the current vote menu to a client in the voting pool.
dvander@2168: *
dvander@2168: * @param client Client index.
dvander@2168: * @return True on success, false if client is not allowed to vote.
dvander@2168: */
dvander@2168: virtual bool RedrawClientVoteMenu(int client) =0;
dvander@2168: };
dvander@2168: }
dvander@2168:
dvander@2168: #endif //_INCLUDE_SOURCEMOD_MENU_SYSTEM_H_