ds@1952: /**
ds@1952: * vim: set ts=4 :
ds@1952: * =============================================================================
ds@1952: * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
ds@1952: * =============================================================================
ds@1952: *
ds@1952: * This file is part of the SourceMod/SourcePawn SDK.
ds@1952: *
ds@1952: * This program is free software; you can redistribute it and/or modify it under
ds@1952: * the terms of the GNU General Public License, version 3.0, as published by the
ds@1952: * Free Software Foundation.
ds@1952: *
ds@1952: * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1952: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1952: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
ds@1952: * details.
ds@1952: *
ds@1952: * You should have received a copy of the GNU General Public License along with
ds@1952: * this program. If not, see .
ds@1952: *
ds@1952: * As a special exception, AlliedModders LLC gives you permission to link the
ds@1952: * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1952: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1952: * by the Valve Corporation. You must obey the GNU General Public License in
ds@1952: * all respects for all other code used. Additionally, AlliedModders LLC grants
ds@1952: * this exception to all derivative works. AlliedModders LLC defines further
ds@1952: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1952: * or .
ds@1952: *
ds@1952: * Version: $Id$
ds@1952: */
ds@1952:
ds@1952: #if defined _menus_included
ds@1952: #endinput
ds@1952: #endif
ds@1952: #define _menus_included
ds@1952:
ds@1952: /**
ds@1952: * Low-level drawing style of the menu.
ds@1952: */
ds@1952: enum MenuStyle
ds@1952: {
ds@1952: MenuStyle_Default = 0, /**< The "default" menu style for the mod */
ds@1952: MenuStyle_Valve = 1, /**< The Valve provided menu style (Used on HL2DM) */
ds@1952: MenuStyle_Radio = 2, /**< The simpler menu style commonly used on CS:S */
ds@1952: };
ds@1952:
ds@1952: /**
ds@1952: * Different actions for the menu "pump" callback
ds@1952: */
ds@1952: enum MenuAction
ds@1952: {
ds@1952: MenuAction_Start = (1<<0), /**< A menu has been started (nothing passed) */
ds@1952: MenuAction_Display = (1<<1), /**< A menu is about to be displayed (param1=client, param2=MenuPanel Handle) */
ds@1952: MenuAction_Select = (1<<2), /**< An item was selected (param1=client, param2=item) */
ds@1952: MenuAction_Cancel = (1<<3), /**< The menu was cancelled (param1=client, param2=reason) */
ds@1952: MenuAction_End = (1<<4), /**< A menu display has fully ended.
ds@1952: param1 is the MenuEnd reason, and if it's MenuEnd_Cancelled, then
ds@1952: param2 is the MenuCancel reason from MenuAction_Cancel.
ds@1952: */
ds@1952: MenuAction_VoteEnd = (1<<5), /**< (VOTE ONLY): A vote sequence has succeeded (param1=chosen item)
ds@1952: This is not called if SetVoteResultCallback has been used on the menu. */
ds@1952: MenuAction_VoteStart = (1<<6), /**< (VOTE ONLY): A vote sequence has started (nothing passed) */
ds@1952: MenuAction_VoteCancel = (1<<7), /**< (VOTE ONLY): A vote sequence has been cancelled (param1=reason) */
ds@1952: MenuAction_DrawItem = (1<<8), /**< An item is being drawn; return the new style (param1=client, param2=item) */
ds@1952: MenuAction_DisplayItem = (1<<9),/**< Item text is being drawn to the display (param1=client, param2=item)
ds@1952: To change the text, use RedrawMenuItem().
ds@1952: If you do so, return its return value. Otherwise, return 0.
ds@1952: */
ds@1952: };
ds@1952:
ds@1952: /** Default menu actions */
ds@1952: #define MENU_ACTIONS_DEFAULT MenuAction_Select|MenuAction_Cancel|MenuAction_End
ds@1952: /** All menu actions */
ds@1952: #define MENU_ACTIONS_ALL MenuAction:0xFFFFFFFF
ds@1952:
ds@1952: #define MENU_NO_PAGINATION 0 /**< Menu should not be paginated (10 items max) */
ds@1952: #define MENU_TIME_FOREVER 0 /**< Menu should be displayed as long as possible */
ds@1952:
ds@1952: #define ITEMDRAW_DEFAULT (0) /**< Item should be drawn normally */
ds@1952: #define ITEMDRAW_DISABLED (1<<0) /**< Item is drawn but not selectable */
ds@1952: #define ITEMDRAW_RAWLINE (1<<1) /**< Item should be a raw line, without a slot */
ds@1952: #define ITEMDRAW_NOTEXT (1<<2) /**< No text should be drawn */
ds@1952: #define ITEMDRAW_SPACER (1<<3) /**< Item should be drawn as a spacer, if possible */
ds@1952: #define ITEMDRAW_IGNORE ((1<<1)|(1<<2)) /**< Item should be completely ignored (rawline + notext) */
ds@1952: #define ITEMDRAW_CONTROL (1<<4) /**< Item is control text (back/next/exit) */
ds@1952:
ds@1952: #define MENUFLAG_BUTTON_EXIT (1<<0) /**< Menu has an "exit" button (default if paginated) */
ds@1952: #define MENUFLAG_BUTTON_EXITBACK (1<<1) /**< Menu has an "exit back" button */
ds@1952: #define MENUFLAG_NO_SOUND (1<<2) /**< Menu will not have any select sounds */
ds@1952:
ds@1952: #define VOTEINFO_CLIENT_INDEX 0 /**< Client index */
ds@1952: #define VOTEINFO_CLIENT_ITEM 1 /**< Item the client selected, or -1 for none */
ds@1952: #define VOTEINFO_ITEM_INDEX 0 /**< Item index */
ds@1952: #define VOTEINFO_ITEM_VOTES 1 /**< Number of votes for the item */
ds@1952:
ds@1952: /**
ds@1952: * Reasons a menu can be cancelled (MenuAction_Cancel).
ds@1952: */
ds@1952: enum
ds@1952: {
ds@1952: MenuCancel_Disconnected = -1, /**< Client dropped from the server */
ds@1952: MenuCancel_Interrupted = -2, /**< Client was interrupted with another menu */
ds@1952: MenuCancel_Exit = -3, /**< Client exited via "exit" */
ds@1952: MenuCancel_NoDisplay = -4, /**< Menu could not be displayed to the client */
ds@1952: MenuCancel_Timeout = -5, /**< Menu timed out */
ds@1952: MenuCancel_ExitBack = -6, /**< Client selected "exit back" on a paginated menu */
ds@1952: };
ds@1952:
ds@1952: /**
ds@1952: * Reasons a vote can be cancelled (MenuAction_VoteCancel).
ds@1952: */
ds@1952: enum
ds@1952: {
ds@1952: VoteCancel_Generic = -1, /**< Vote was generically cancelled. */
ds@1952: VoteCancel_NoVotes = -2, /**< Vote did not receive any votes. */
ds@1952: };
ds@1952:
ds@1952: /**
ds@1952: * Reasons a menu ended (MenuAction_End).
ds@1952: */
ds@1952: enum
ds@1952: {
ds@1952: MenuEnd_Selected = 0, /**< Menu item was selected */
ds@1952: MenuEnd_VotingDone = -1, /**< Voting finished */
ds@1952: MenuEnd_VotingCancelled = -2, /**< Voting was cancelled */
ds@1952: MenuEnd_Cancelled = -3, /**< Menu was cancelled (reason in param2) */
ds@1952: MenuEnd_Exit = -4, /**< Menu was cleanly exited via "exit" */
ds@1952: MenuEnd_ExitBack = -5, /**< Menu was cleanly exited via "back" */
ds@1952: };
ds@1952:
ds@1952: /**
ds@1952: * Describes a menu's source
ds@1952: */
ds@1952: enum MenuSource
ds@1952: {
ds@1952: MenuSource_None = 0, /**< No menu is being displayed */
ds@1952: MenuSource_External = 1, /**< External menu */
ds@1952: MenuSource_Normal = 2, /**< A basic menu is being displayed */
ds@1952: MenuSource_RawPanel = 3, /**< A display is active, but it is not tied to a menu */
ds@1952: };
ds@1952:
ds@1952: /**
ds@1952: * Called when a menu action is completed.
ds@1952: *
ds@1952: * @param menu The menu being acted upon.
ds@1952: * @param action The action of the menu.
ds@1952: * @param param1 First action parameter (usually the client).
ds@1952: * @param param2 Second action parameter (usually the item).
ds@1952: * @noreturn
ds@1952: */
ds@1952: functag MenuHandler public(Handle:menu, MenuAction:action, param1, param2);
ds@1952:
ds@1952: /**
ds@1952: * Creates a new, empty menu using the default style.
ds@1952: *
ds@1952: * @param handler Function which will receive menu actions.
ds@1952: * @param actions Optionally set which actions to receive. Select,
ds@1952: * Cancel, and End will always be received regardless
ds@1952: * of whether they are set or not. They are also
ds@1952: * the only default actions.
ds@1952: * @return A new menu Handle.
ds@1952: */
ds@1952: native Handle:CreateMenu(MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
ds@1952:
ds@1952: /**
ds@1952: * Displays a menu to a client.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param client Client index.
ds@1952: * @param time Maximum time to leave menu on the screen.
ds@1952: * @return True on success, false on failure.
ds@1952: * @error Invalid Handle or client not in game.
ds@1952: */
ds@1952: native bool:DisplayMenu(Handle:menu, client, time);
ds@1952:
ds@1952: /**
ds@1952: * Displays a menu to a client, starting from the given item.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param client Client index.
ds@1952: * @param first_item First item to begin drawing from.
ds@1952: * @param time Maximum time to leave menu on the screen.
ds@1952: * @return True on success, false on failure.
ds@1952: * @error Invalid Handle or client not in game.
ds@1952: */
ds@1952: native bool:DisplayMenuAtItem(Handle:menu, client, first_item, time);
ds@1952:
ds@1952: /**
ds@1952: * Appends a new item to the end of a menu.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param info Item information string.
ds@1952: * @param display Default item display string.
ds@1952: * @param style Drawing style flags. Anything other than DEFAULT or
ds@1952: * DISABLED will be completely ignored when paginating.
ds@1952: * @return True on success, false on failure.
ds@1952: * @error Invalid Handle or item limit reached.
ds@1952: */
ds@1952: native AddMenuItem(Handle:menu,
ds@1952: const String:info[],
ds@1952: const String:display[],
ds@1952: style=ITEMDRAW_DEFAULT);
ds@1952:
ds@1952: /**
ds@1952: * Inserts an item into the menu before a certain position; the new item will
ds@1952: * be at the given position and all next items pushed forward.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param position Position, starting from 0.
ds@1952: * @param info Item information string.
ds@1952: * @param display Default item display string.
ds@1952: * @param style Drawing style flags. Anything other than DEFAULT or
ds@1952: * DISABLED will be completely ignored when paginating.
ds@1952: * @return True on success, false on failure.
ds@1952: * @error Invalid Handle or menu position.
ds@1952: */
ds@1952: native bool:InsertMenuItem(Handle:menu,
ds@1952: position,
ds@1952: const String:info[],
ds@1952: const String:display[],
ds@1952: style=ITEMDRAW_DEFAULT);
ds@1952:
ds@1952: /**
ds@1952: * Removes an item from the menu.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param position Position, starting from 0.
ds@1952: * @return True on success, false on failure.
ds@1952: * @error Invalid Handle or menu position.
ds@1952: */
ds@1952: native bool:RemoveMenuItem(Handle:menu, position);
ds@1952:
ds@1952: /**
ds@1952: * Removes all items from a menu.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @noreturn
ds@1952: * @error Invalid Handle or menu position.
ds@1952: */
ds@1952: native RemoveAllMenuItems(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Retrieves information about a menu item.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param position Position, starting from 0.
ds@1952: * @param infoBuf Info buffer.
ds@1952: * @param infoBufLen Maximum length of the info buffer.
ds@1952: * @param style By-reference variable to store drawing flags.
ds@1952: * @param dispBuf Display buffer.
ds@1952: * @param dispBufLen Maximum length of the display buffer.
ds@1952: * @return True on success, false if position is invalid.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native bool:GetMenuItem(Handle:menu,
ds@1952: position,
ds@1952: String:infoBuf[],
ds@1952: infoBufLen,
ds@1952: &style=0,
ds@1952: String:dispBuf[]="",
ds@1952: dispBufLen=0);
ds@1952:
ds@1952: /**
ds@1952: * Returns the first item on the page of a currently selected menu.
ds@1952: *
ds@1952: * This is only valid inside a MenuAction_Select callback.
ds@1952: *
ds@1952: * @return First item number on the page the client was viewing
ds@1952: * before selecting the item in the callback. This can
ds@1952: * be used to re-display the menu from the original
ds@1952: * position.
ds@1952: * @error Not called from inside a MenuAction_Select callback.
ds@1952: */
ds@1952: native GetMenuSelectionPosition();
ds@1952:
ds@1952: /**
ds@1952: * Returns the number of items in a menu.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @return Number of items in the menu.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native GetMenuItemCount(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Sets whether the menu should be paginated or not.
ds@1952: *
ds@1952: * If itemsPerPage is MENU_NO_PAGINATION, and the exit button flag is set,
ds@1952: * then the exit button flag is removed. It can be re-applied if desired.
ds@1952: *
ds@1952: * @param menu Handle to the menu.
ds@1952: * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION.
ds@1952: * @return True on success, false if pagination is too high or
ds@1952: * low.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native bool:SetMenuPagination(Handle:menu, itemsPerPage);
ds@1952:
ds@1952: /**
ds@1952: * Returns a menu's pagination setting.
ds@1952: *
ds@1952: * @param menu Handle to the menu.
ds@1952: * @return Pagination setting.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native GetMenuPagination(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Returns a menu's MenuStyle Handle. The Handle
ds@1952: * is global and cannot be freed.
ds@1952: *
ds@1952: * @param menu Handle to the menu.
ds@1952: * @return Handle to the menu's draw style.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native Handle:GetMenuStyle(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Sets the menu's default title/instruction message.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param fmt Message string format
ds@1952: * @param ... Message string arguments.
ds@1952: * @noreturn
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native SetMenuTitle(Handle:menu, const String:fmt[], any:...);
ds@1952:
ds@1952: /**
ds@1952: * Returns the text of a menu's title.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param buffer Buffer to store title.
ds@1952: * @param maxlength Maximum length of the buffer.
ds@1952: * @return Number of bytes written.
ds@1952: * @error Invalid Handle/
ds@1952: */
ds@1952: native GetMenuTitle(Handle:menu, String:buffer[], maxlength);
ds@1952:
ds@1952: /**
ds@1952: * Creates a raw MenuPanel based off the menu's style.
ds@1952: * The Handle must be freed with CloseHandle().
ds@1952: *
ds@1952: * @return A new MenuPanel Handle.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native Handle:CreatePanelFromMenu(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Returns whether or not the menu has an exit button.
ds@1952: * By default, menus have an exit button.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @return True if the menu has an exit button; false otherwise.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native bool:GetMenuExitButton(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Sets whether or not the menu has an exit button. By default, paginated menus
ds@1952: * have an exit button.
ds@1952: *
ds@1952: * If a menu's pagination is changed to MENU_NO_PAGINATION, and the pagination
ds@1952: * was previously a different value, then the Exit button status is changed to
ds@1952: * false. It must be explicitly re-enabled afterwards.
ds@1952: *
ds@1952: * If a non-paginated menu has an exit button, then at most 9 items will be
ds@1952: * displayed.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param button True to enable the button, false to remove it.
ds@1952: * @return True if allowed; false on failure.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native bool:SetMenuExitButton(Handle:menu, bool:button);
ds@1952:
ds@1952: /**
ds@1952: * Returns whether or not the menu has an "exit back" button. By default,
ds@1952: * menus do not have an exit back button.
ds@1952: *
ds@1952: * Exit Back buttons appear as "Back" on page 1 of paginated menus and have
ds@1952: * functionality defined by the user in MenuEnd_ExitBack.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @return True if the menu has an exit back button; false otherwise.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native bool:GetMenuExitBackButton(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Sets whether or not the menu has an "exit back" button. By default, menus
ds@1952: * do not have an exit back button.
ds@1952: *
ds@1952: * Exit Back buttons appear as "Back" on page 1 of paginated menus and have
ds@1952: * functionality defined by the user in MenuEnd_ExitBack.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param button True to enable the button, false to remove it.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native SetMenuExitBackButton(Handle:menu, bool:button);
ds@1952:
ds@1952:
ds@1952: /**
ds@1952: * Cancels a menu from displaying on all clients. While the
ds@1952: * cancellation is in progress, this menu cannot be re-displayed
ds@1952: * to any clients.
ds@1952: *
ds@1952: * The menu may still exist on the client's screen after this command.
ds@1952: * This simply verifies that the menu is not being used anywhere.
ds@1952: *
ds@1952: * If any vote is in progress on a menu, it will be cancelled.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @noreturn
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native CancelMenu(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Retrieves a menu's option flags.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @return A bitstring of MENUFLAG bits.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native GetMenuOptionFlags(Handle:menu);
ds@1952:
ds@1952: /**
ds@1952: * Sets a menu's option flags.
ds@1952: *
ds@1952: * If a certain bit is not supported, it will be stripped before being set.
ds@1952: * See SetMenuExitButton() for information on Exit buttons.
ds@1952: * See SetMenuExitBackButton() for information on Exit Back buttons.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param flags A new bitstring of MENUFLAG bits.
ds@1952: * @noreturn
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native SetMenuOptionFlags(Handle:menu, flags);
ds@1952:
ds@1952: /**
ds@1952: * Returns whether a vote is in progress.
ds@1952: *
ds@1952: * @param menu Deprecated; no longer used.
ds@1952: * @return True if a vote is in progress, false otherwise.
ds@1952: */
ds@1952: native bool:IsVoteInProgress(Handle:menu=INVALID_HANDLE);
ds@1952:
ds@1952: /**
ds@1952: * Cancels the vote in progress.
ds@1952: *
ds@1952: * @noreturn
ds@1952: * @error If no vote is in progress.
ds@1952: */
ds@1952: native CancelVote();
ds@1952:
ds@1952: /**
ds@1952: * Broadcasts a menu to a list of clients. The most selected item will be
ds@1952: * returned through MenuAction_End. On a tie, a random item will be returned
ds@1952: * from a list of the tied items.
ds@1952: *
ds@1952: * Note that MenuAction_VoteEnd and MenuAction_VoteStart are both
ds@1952: * default callbacks and do not need to be enabled.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param clients Array of clients to broadcast to.
ds@1952: * @param numClients Number of clients in the array.
ds@1952: * @param time Maximum time to leave menu on the screen.
ds@1952: * @return True on success, false if this menu already has a vote session
ds@1952: * in progress.
ds@1952: * @error Invalid Handle, or a vote is already in progress.
ds@1952: */
ds@1952: native bool:VoteMenu(Handle:menu, clients[], numClients, time);
ds@1952:
ds@1952: /**
ds@1952: * Sends a vote menu to all clients. See VoteMenu() for more information.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param time Maximum time to leave menu on the screen.
ds@1952: * @return True on success, false if this menu already has a vote session
ds@1952: * in progress.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: stock VoteMenuToAll(Handle:menu, time)
ds@1952: {
ds@1952: new num = GetMaxClients();
ds@1952: new total;
ds@1952: decl players[num];
ds@1952:
ds@1952: for (new i=1; i<=num; i++)
ds@1952: {
ds@1952: if (!IsClientInGame(i))
ds@1952: {
ds@1952: continue;
ds@1952: }
ds@1952: players[total++] = i;
ds@1952: }
ds@1952:
ds@1952: return VoteMenu(menu, players, total, time);
ds@1952: }
ds@1952: /**
ds@1952: * Callback for when a vote has ended and results are available.
ds@1952: *
ds@1952: * @param menu The menu being voted on.
ds@1952: * @param num_votes Number of votes tallied in total.
ds@1952: * @param num_clients Number of clients who could vote.
ds@1952: * @param client_info Array of clients. Use VOTEINFO_CLIENT_ defines.
ds@1952: * @param num_items Number of unique items that were selected.
ds@1952: * @param item_info Array of items, sorted by count. Use VOTEINFO_ITEM
ds@1952: * defines.
ds@1952: * @noreturn
ds@1952: */
ds@1952: functag VoteHandler public(Handle:menu,
ds@1952: num_votes,
ds@1952: num_clients,
ds@1952: const client_info[][2],
ds@1952: num_items,
ds@1952: const item_info[][2]);
ds@1952:
ds@1952: /**
ds@1952: * Sets an advanced vote handling callback. If this callback is set,
ds@1952: * MenuAction_VoteEnd will not be called.
ds@1952: *
ds@1952: * @param menu Menu Handle.
ds@1952: * @param callback Callback function.
ds@1952: * @noreturn
ds@1952: * @error Invalid Handle or callback.
ds@1952: */
ds@1952: native SetVoteResultCallback(Handle:menu, VoteHandler:callback);
ds@1952:
ds@1952: /**
ds@1952: * Returns the number of seconds you should "wait" before displaying
ds@1952: * a publicly invocable menu. This number is the time remaining until
ds@1952: * (last_vote + sm_vote_delay).
ds@1952: *
ds@1952: * @return Number of seconds to wait, or 0 for none.
ds@1952: */
ds@1952: native CheckVoteDelay();
ds@1952:
ds@1952: /**
dvander@2056: * Returns whether a client is in the pool of clients allowed
dvander@2056: * to participate in the current vote. This is determined by
dvander@2056: * the client list passed to StartVote().
dvander@2056: *
dvander@2056: * @param client Client index.
dvander@2056: * @return True if client is allowed to vote, false otherwise.
dvander@2056: * @error If no vote is in progress or client index is invalid.
dvander@2056: */
dvander@2056: native bool:IsClientInVotePool(client);
dvander@2056:
dvander@2056: /**
dvander@2056: * Redraws the current vote menu to a client in the voting pool.
dvander@2056: *
dvander@2056: * @param client Client index.
dvander@2056: * @return True on success, false if the client is in the vote pool
dvander@2056: * but cannot vote again.
dvander@2056: * @error No vote in progress, client is not in the voting pool,
dvander@2056: * or client index is invalid.
dvander@2056: */
dvander@2056: native bool:RedrawClientVoteMenu(client);
dvander@2056:
dvander@2056: /**
ds@1952: * Returns a style's global Handle.
ds@1952: *
ds@1952: * @param style Menu Style.
ds@1952: * @return A Handle, or INVALID_HANDLE if not found or unusable.
ds@1952: */
ds@1952: native Handle:GetMenuStyleHandle(MenuStyle:style);
ds@1952:
ds@1952: /**
ds@1952: * Creates a MenuPanel from a MenuStyle. Panels are used for drawing raw
ds@1952: * menus without any extra helper functions. The Handle must be closed
ds@1952: * with CloseHandle().
ds@1952: *
ds@1952: * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
ds@1952: * @return A new MenuPanel Handle.
ds@1952: * @error Invalid Handle other than INVALID_HANDLE.
ds@1952: */
ds@1952: native Handle:CreatePanel(Handle:hStyle=INVALID_HANDLE);
ds@1952:
ds@1952: /**
ds@1952: * Creates a Menu from a MenuStyle. The Handle must be closed with
ds@1952: * CloseHandle().
ds@1952: *
ds@1952: * @parma hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
ds@1952: * @param handler Function which will receive menu actions.
ds@1952: * @param actions Optionally set which actions to receive. Select,
ds@1952: * Cancel, and End will always be received regardless
ds@1952: * of whether they are set or not. They are also
ds@1952: * the only default actions.
ds@1952: * @return A new menu Handle.
ds@1952: * @error Invalid Handle other than INVALID_HANDLE.
ds@1952: */
ds@1952: native Handle:CreateMenuEx(Handle:hStyle=INVALID_HANDLE, MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
ds@1952:
ds@1952: /**
ds@1952: * Returns whether a client is viewing a menu.
ds@1952: *
ds@1952: * @param client Client index.
ds@1952: * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
ds@1952: * @return A MenuSource value.
ds@1952: * @error Invalid Handle other than INVALID_HANDLE.
ds@1952: */
ds@1952: native MenuSource:GetClientMenu(client, Handle:hStyle=INVALID_HANDLE);
ds@1952:
ds@1952: /**
ds@1952: * Cancels a menu on a client. This will only affect non-external menus.
ds@1952: *
ds@1952: * @param hstyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
ds@1952: * @param client Client index.
ds@1952: * @param autoIgnore If true, no menus can be re-drawn on the client during
ds@1952: * the cancellation process.
ds@1952: * @return True if a menu was cancelled, false otherwise.
ds@1952: */
ds@1952: native bool:CancelClientMenu(client, bool:autoIgnore=false, Handle:hStyle=INVALID_HANDLE);
ds@1952:
ds@1952: /**
ds@1952: * Returns a style's maximum items per page.
ds@1952: *
ds@1952: * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
ds@1952: * @return Maximum items per page.
ds@1952: * @error Invalid Handle other than INVALID_HANDLE.
ds@1952: */
ds@1952: native GetMaxPageItems(Handle:hStyle=INVALID_HANDLE);
ds@1952:
ds@1952: /**
ds@1952: * Returns a MenuPanel's parent style.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @return The MenuStyle Handle that created the panel.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native Handle:GetPanelStyle(Handle:panel);
ds@1952:
ds@1952: /**
ds@1952: * Sets the panel's title.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @param title Text to set as the title.
ds@1952: * @param onlyIfEmpty If true, the title will only be set if no title is set.
ds@1952: * @noreturn
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native Handle:SetPanelTitle(Handle:panel, const String:text[], bool:onlyIfEmpty=false);
ds@1952:
ds@1952: /**
ds@1952: * Draws an item on a panel. If the item takes up a slot, the position
ds@1952: * is returned.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @param text Display text to use. If not a raw line,
ds@1952: * the style may automatically add color markup.
ds@1952: * No numbering or newlines are needed.
ds@1952: * @param style ITEMDRAW style flags.
ds@1952: * @return A slot position, or 0 if item was a rawline or could not be drawn.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native DrawPanelItem(Handle:panel, const String:text[], style=ITEMDRAW_DEFAULT);
ds@1952:
ds@1952: /**
ds@1952: * Draws a raw line of text on a panel, without any markup other than a newline.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle, or INVALID_HANDLE if inside a
ds@1952: * MenuAction_DisplayItem callback.
ds@1952: * @param text Display text to use.
ds@1952: * @return True on success, false if raw lines are not supported.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native DrawPanelText(Handle:panel, const String:text[]);
ds@1952:
ds@1952: /**
ds@1952: * Returns whether or not the given drawing flags are supported by
ds@1952: * the menu style.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @param style ITEMDRAW style flags.
ds@1952: * @return True if item is drawable, false otherwise.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native CanPanelDrawFlags(Handle:panel, style);
ds@1952:
ds@1952: /**
ds@1952: * Sets the selectable key map of a panel. This is not supported by
ds@1952: * all styles (only by Radio, as of this writing).
ds@1952: *
ds@1952: * @param keys An integer where each bit N allows key
ds@1952: * N+1 to be selected. If no keys are selectable,
ds@1952: * then key 0 (bit 9) is automatically set.
ds@1952: * @return True if supported, false otherwise.
ds@1952: */
ds@1952: native bool:SetPanelKeys(Handle:panel, keys);
ds@1952:
ds@1952: /**
ds@1952: * Sends a panel to a client. Unlike full menus, the handler
ds@1952: * function will only receive the following actions, both of
ds@1952: * which will have INVALID_HANDLE for a menu, and the client
ds@1952: * as param1.
ds@1952: *
ds@1952: * MenuAction_Select (param2 will be the key pressed)
ds@1952: * MenuAction_Cancel (param2 will be the reason)
ds@1952: *
ds@1952: * Also, if the menu fails to display, no callbacks will be called.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @param client A client to draw to.
ds@1952: * @param handler The MenuHandler function to catch actions with.
ds@1952: * @param time Time to hold the menu for.
ds@1952: * @return True on success, false on failure.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native bool:SendPanelToClient(Handle:panel, client, MenuHandler:handler, time);
ds@1952:
ds@1952: /**
ds@1952: * @brief Returns the amount of text the menu can still hold. If this is
ds@1952: * limit is reached or overflowed, the text is silently truncated.
ds@1952: *
ds@1952: * Radio menus: Currently 511 characters (512 bytes).
ds@1952: * Valve menus: Currently -1 (no meaning).
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @return Number of characters that the menu can still hold,
ds@1952: * or -1 if there is no known limit.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native GetPanelTextRemaining(Handle:panel);
ds@1952:
ds@1952: /**
ds@1952: * @brief Returns the current key position.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @return Current key position starting at 1.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native GetPanelCurrentKey(Handle:panel);
ds@1952:
ds@1952: /**
ds@1952: * @brief Sets the next key position. This cannot be used
ds@1952: * to traverse backwards.
ds@1952: *
ds@1952: * @param panel A MenuPanel Handle.
ds@1952: * @param key Key that is greater or equal to
ds@1952: * GetPanelCurrentKey().
ds@1952: * @return True on success, false otherwise.
ds@1952: * @error Invalid Handle.
ds@1952: */
ds@1952: native bool:SetPanelCurrentKey(Handle:panel, key);
ds@1952:
ds@1952: /**
ds@1952: * @brief Redraws menu text from inside a MenuAction_DisplayItem callback.
ds@1952: *
ds@1952: * @param text Menu text to draw.
ds@1952: * @return Item position; must be returned via the callback.
ds@1952: */
ds@1952: native RedrawMenuItem(const String:text[]);
ds@1952:
ds@1952: /**
ds@1952: * This function is provided for legacy code only. Some older plugins may use
ds@1952: * network messages instead of the panel API. This function wraps the panel
ds@1952: * API for eased portability into the SourceMod menu system.
ds@1952: *
ds@1952: * This function is only usable with the Radio Menu style. You do not need to
ds@1952: * split up your menu into multiple packets; SourceMod will break the string
ds@1952: * up internally.
ds@1952: *
ds@1952: * @param client Client index.
ds@1952: * @param str Full menu string as would be passed over the network.
ds@1952: * @param time Time to hold the menu for.
ds@1952: * @param keys Selectable key bitstring.
ds@1952: * @param handler Optional handler function, with the same rules as
ds@1952: * SendPanelToClient().
ds@1952: * @return True on success, false on failure.
ds@1952: * @error Invalid client index, or radio menus not supported.
ds@1952: */
ds@1952: native bool:InternalShowMenu(client, const String:str[], time, keys=-1, MenuHandler:handler=MenuHandler:-1);
ds@1952:
ds@1952: /**
ds@1952: * Retrieves voting information from MenuAction_VoteEnd.
ds@1952: *
ds@1952: * @param param2 Second parameter of MenuAction_VoteEnd.
ds@1952: * @param winningVotes Number of votes received by the winning option.
ds@1952: * @param totalVotes Number of total votes received.
ds@1952: * @noreturn
ds@1952: */
ds@1952: stock GetMenuVoteInfo(param2, &winningVotes, &totalVotes)
ds@1952: {
ds@1952: winningVotes = param2 & 0xFFFF;
ds@1952: totalVotes = param2 >> 16;
ds@1952: }
ds@1952:
ds@1952: /**
ds@1952: * Quick stock to determine whether voting is allowed. This doesn't let you
ds@1952: * fine-tune a reason for not voting, so it's not recommended for lazily
ds@1952: * telling clients that voting isn't allowed.
ds@1952: *
ds@1952: * @return True if voting is allowed, false if voting is in progress
ds@1952: * or the cooldown is active.
ds@1952: */
ds@1952: stock bool:IsNewVoteAllowed()
ds@1952: {
ds@1952: if (IsVoteInProgress() || CheckVoteDelay() != 0)
ds@1952: {
ds@1952: return false;
ds@1952: }
ds@1952:
ds@1952: return true;
ds@1952: }