1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/plugins/include/menus.inc Sun Mar 30 07:00:22 2008 +0000
1.3 @@ -0,0 +1,787 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * =============================================================================
1.7 + * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
1.8 + * =============================================================================
1.9 + *
1.10 + * This file is part of the SourceMod/SourcePawn SDK.
1.11 + *
1.12 + * This program is free software; you can redistribute it and/or modify it under
1.13 + * the terms of the GNU General Public License, version 3.0, as published by the
1.14 + * Free Software Foundation.
1.15 + *
1.16 + * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 + * details.
1.20 + *
1.21 + * You should have received a copy of the GNU General Public License along with
1.22 + * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 + *
1.24 + * As a special exception, AlliedModders LLC gives you permission to link the
1.25 + * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 + * by the Valve Corporation. You must obey the GNU General Public License in
1.28 + * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 + * this exception to all derivative works. AlliedModders LLC defines further
1.30 + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 + * or <http://www.sourcemod.net/license.php>.
1.32 + *
1.33 + * Version: $Id$
1.34 + */
1.35 +
1.36 +#if defined _menus_included
1.37 + #endinput
1.38 +#endif
1.39 +#define _menus_included
1.40 +
1.41 +/**
1.42 + * Low-level drawing style of the menu.
1.43 + */
1.44 +enum MenuStyle
1.45 +{
1.46 + MenuStyle_Default = 0, /**< The "default" menu style for the mod */
1.47 + MenuStyle_Valve = 1, /**< The Valve provided menu style (Used on HL2DM) */
1.48 + MenuStyle_Radio = 2, /**< The simpler menu style commonly used on CS:S */
1.49 +};
1.50 +
1.51 +/**
1.52 + * Different actions for the menu "pump" callback
1.53 + */
1.54 +enum MenuAction
1.55 +{
1.56 + MenuAction_Start = (1<<0), /**< A menu has been started (nothing passed) */
1.57 + MenuAction_Display = (1<<1), /**< A menu is about to be displayed (param1=client, param2=MenuPanel Handle) */
1.58 + MenuAction_Select = (1<<2), /**< An item was selected (param1=client, param2=item) */
1.59 + MenuAction_Cancel = (1<<3), /**< The menu was cancelled (param1=client, param2=reason) */
1.60 + MenuAction_End = (1<<4), /**< A menu display has fully ended.
1.61 + param1 is the MenuEnd reason, and if it's MenuEnd_Cancelled, then
1.62 + param2 is the MenuCancel reason from MenuAction_Cancel.
1.63 + */
1.64 + MenuAction_VoteEnd = (1<<5), /**< (VOTE ONLY): A vote sequence has succeeded (param1=chosen item)
1.65 + This is not called if SetVoteResultCallback has been used on the menu. */
1.66 + MenuAction_VoteStart = (1<<6), /**< (VOTE ONLY): A vote sequence has started (nothing passed) */
1.67 + MenuAction_VoteCancel = (1<<7), /**< (VOTE ONLY): A vote sequence has been cancelled (param1=reason) */
1.68 + MenuAction_DrawItem = (1<<8), /**< An item is being drawn; return the new style (param1=client, param2=item) */
1.69 + MenuAction_DisplayItem = (1<<9),/**< Item text is being drawn to the display (param1=client, param2=item)
1.70 + To change the text, use RedrawMenuItem().
1.71 + If you do so, return its return value. Otherwise, return 0.
1.72 + */
1.73 +};
1.74 +
1.75 +/** Default menu actions */
1.76 +#define MENU_ACTIONS_DEFAULT MenuAction_Select|MenuAction_Cancel|MenuAction_End
1.77 +/** All menu actions */
1.78 +#define MENU_ACTIONS_ALL MenuAction:0xFFFFFFFF
1.79 +
1.80 +#define MENU_NO_PAGINATION 0 /**< Menu should not be paginated (10 items max) */
1.81 +#define MENU_TIME_FOREVER 0 /**< Menu should be displayed as long as possible */
1.82 +
1.83 +#define ITEMDRAW_DEFAULT (0) /**< Item should be drawn normally */
1.84 +#define ITEMDRAW_DISABLED (1<<0) /**< Item is drawn but not selectable */
1.85 +#define ITEMDRAW_RAWLINE (1<<1) /**< Item should be a raw line, without a slot */
1.86 +#define ITEMDRAW_NOTEXT (1<<2) /**< No text should be drawn */
1.87 +#define ITEMDRAW_SPACER (1<<3) /**< Item should be drawn as a spacer, if possible */
1.88 +#define ITEMDRAW_IGNORE ((1<<1)|(1<<2)) /**< Item should be completely ignored (rawline + notext) */
1.89 +#define ITEMDRAW_CONTROL (1<<4) /**< Item is control text (back/next/exit) */
1.90 +
1.91 +#define MENUFLAG_BUTTON_EXIT (1<<0) /**< Menu has an "exit" button (default if paginated) */
1.92 +#define MENUFLAG_BUTTON_EXITBACK (1<<1) /**< Menu has an "exit back" button */
1.93 +#define MENUFLAG_NO_SOUND (1<<2) /**< Menu will not have any select sounds */
1.94 +
1.95 +#define VOTEINFO_CLIENT_INDEX 0 /**< Client index */
1.96 +#define VOTEINFO_CLIENT_ITEM 1 /**< Item the client selected, or -1 for none */
1.97 +#define VOTEINFO_ITEM_INDEX 0 /**< Item index */
1.98 +#define VOTEINFO_ITEM_VOTES 1 /**< Number of votes for the item */
1.99 +
1.100 +/**
1.101 + * Reasons a menu can be cancelled (MenuAction_Cancel).
1.102 + */
1.103 +enum
1.104 +{
1.105 + MenuCancel_Disconnected = -1, /**< Client dropped from the server */
1.106 + MenuCancel_Interrupted = -2, /**< Client was interrupted with another menu */
1.107 + MenuCancel_Exit = -3, /**< Client exited via "exit" */
1.108 + MenuCancel_NoDisplay = -4, /**< Menu could not be displayed to the client */
1.109 + MenuCancel_Timeout = -5, /**< Menu timed out */
1.110 + MenuCancel_ExitBack = -6, /**< Client selected "exit back" on a paginated menu */
1.111 +};
1.112 +
1.113 +/**
1.114 + * Reasons a vote can be cancelled (MenuAction_VoteCancel).
1.115 + */
1.116 +enum
1.117 +{
1.118 + VoteCancel_Generic = -1, /**< Vote was generically cancelled. */
1.119 + VoteCancel_NoVotes = -2, /**< Vote did not receive any votes. */
1.120 +};
1.121 +
1.122 +/**
1.123 + * Reasons a menu ended (MenuAction_End).
1.124 + */
1.125 +enum
1.126 +{
1.127 + MenuEnd_Selected = 0, /**< Menu item was selected */
1.128 + MenuEnd_VotingDone = -1, /**< Voting finished */
1.129 + MenuEnd_VotingCancelled = -2, /**< Voting was cancelled */
1.130 + MenuEnd_Cancelled = -3, /**< Menu was cancelled (reason in param2) */
1.131 + MenuEnd_Exit = -4, /**< Menu was cleanly exited via "exit" */
1.132 + MenuEnd_ExitBack = -5, /**< Menu was cleanly exited via "back" */
1.133 +};
1.134 +
1.135 +/**
1.136 + * Describes a menu's source
1.137 + */
1.138 +enum MenuSource
1.139 +{
1.140 + MenuSource_None = 0, /**< No menu is being displayed */
1.141 + MenuSource_External = 1, /**< External menu */
1.142 + MenuSource_Normal = 2, /**< A basic menu is being displayed */
1.143 + MenuSource_RawPanel = 3, /**< A display is active, but it is not tied to a menu */
1.144 +};
1.145 +
1.146 +/**
1.147 + * Called when a menu action is completed.
1.148 + *
1.149 + * @param menu The menu being acted upon.
1.150 + * @param action The action of the menu.
1.151 + * @param param1 First action parameter (usually the client).
1.152 + * @param param2 Second action parameter (usually the item).
1.153 + * @noreturn
1.154 + */
1.155 +functag MenuHandler public(Handle:menu, MenuAction:action, param1, param2);
1.156 +
1.157 +/**
1.158 + * Creates a new, empty menu using the default style.
1.159 + *
1.160 + * @param handler Function which will receive menu actions.
1.161 + * @param actions Optionally set which actions to receive. Select,
1.162 + * Cancel, and End will always be received regardless
1.163 + * of whether they are set or not. They are also
1.164 + * the only default actions.
1.165 + * @return A new menu Handle.
1.166 + */
1.167 +native Handle:CreateMenu(MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
1.168 +
1.169 +/**
1.170 + * Displays a menu to a client.
1.171 + *
1.172 + * @param menu Menu Handle.
1.173 + * @param client Client index.
1.174 + * @param time Maximum time to leave menu on the screen.
1.175 + * @return True on success, false on failure.
1.176 + * @error Invalid Handle or client not in game.
1.177 + */
1.178 +native bool:DisplayMenu(Handle:menu, client, time);
1.179 +
1.180 +/**
1.181 + * Displays a menu to a client, starting from the given item.
1.182 + *
1.183 + * @param menu Menu Handle.
1.184 + * @param client Client index.
1.185 + * @param first_item First item to begin drawing from.
1.186 + * @param time Maximum time to leave menu on the screen.
1.187 + * @return True on success, false on failure.
1.188 + * @error Invalid Handle or client not in game.
1.189 + */
1.190 +native bool:DisplayMenuAtItem(Handle:menu, client, first_item, time);
1.191 +
1.192 +/**
1.193 + * Appends a new item to the end of a menu.
1.194 + *
1.195 + * @param menu Menu Handle.
1.196 + * @param info Item information string.
1.197 + * @param display Default item display string.
1.198 + * @param style Drawing style flags. Anything other than DEFAULT or
1.199 + * DISABLED will be completely ignored when paginating.
1.200 + * @return True on success, false on failure.
1.201 + * @error Invalid Handle or item limit reached.
1.202 + */
1.203 +native AddMenuItem(Handle:menu,
1.204 + const String:info[],
1.205 + const String:display[],
1.206 + style=ITEMDRAW_DEFAULT);
1.207 +
1.208 +/**
1.209 + * Inserts an item into the menu before a certain position; the new item will
1.210 + * be at the given position and all next items pushed forward.
1.211 + *
1.212 + * @param menu Menu Handle.
1.213 + * @param position Position, starting from 0.
1.214 + * @param info Item information string.
1.215 + * @param display Default item display string.
1.216 + * @param style Drawing style flags. Anything other than DEFAULT or
1.217 + * DISABLED will be completely ignored when paginating.
1.218 + * @return True on success, false on failure.
1.219 + * @error Invalid Handle or menu position.
1.220 + */
1.221 +native bool:InsertMenuItem(Handle:menu,
1.222 + position,
1.223 + const String:info[],
1.224 + const String:display[],
1.225 + style=ITEMDRAW_DEFAULT);
1.226 +
1.227 +/**
1.228 + * Removes an item from the menu.
1.229 + *
1.230 + * @param menu Menu Handle.
1.231 + * @param position Position, starting from 0.
1.232 + * @return True on success, false on failure.
1.233 + * @error Invalid Handle or menu position.
1.234 + */
1.235 +native bool:RemoveMenuItem(Handle:menu, position);
1.236 +
1.237 +/**
1.238 + * Removes all items from a menu.
1.239 + *
1.240 + * @param menu Menu Handle.
1.241 + * @noreturn
1.242 + * @error Invalid Handle or menu position.
1.243 + */
1.244 +native RemoveAllMenuItems(Handle:menu);
1.245 +
1.246 +/**
1.247 + * Retrieves information about a menu item.
1.248 + *
1.249 + * @param menu Menu Handle.
1.250 + * @param position Position, starting from 0.
1.251 + * @param infoBuf Info buffer.
1.252 + * @param infoBufLen Maximum length of the info buffer.
1.253 + * @param style By-reference variable to store drawing flags.
1.254 + * @param dispBuf Display buffer.
1.255 + * @param dispBufLen Maximum length of the display buffer.
1.256 + * @return True on success, false if position is invalid.
1.257 + * @error Invalid Handle.
1.258 + */
1.259 +native bool:GetMenuItem(Handle:menu,
1.260 + position,
1.261 + String:infoBuf[],
1.262 + infoBufLen,
1.263 + &style=0,
1.264 + String:dispBuf[]="",
1.265 + dispBufLen=0);
1.266 +
1.267 +/**
1.268 + * Returns the first item on the page of a currently selected menu.
1.269 + *
1.270 + * This is only valid inside a MenuAction_Select callback.
1.271 + *
1.272 + * @return First item number on the page the client was viewing
1.273 + * before selecting the item in the callback. This can
1.274 + * be used to re-display the menu from the original
1.275 + * position.
1.276 + * @error Not called from inside a MenuAction_Select callback.
1.277 + */
1.278 +native GetMenuSelectionPosition();
1.279 +
1.280 +/**
1.281 + * Returns the number of items in a menu.
1.282 + *
1.283 + * @param menu Menu Handle.
1.284 + * @return Number of items in the menu.
1.285 + * @error Invalid Handle.
1.286 + */
1.287 +native GetMenuItemCount(Handle:menu);
1.288 +
1.289 +/**
1.290 + * Sets whether the menu should be paginated or not.
1.291 + *
1.292 + * If itemsPerPage is MENU_NO_PAGINATION, and the exit button flag is set,
1.293 + * then the exit button flag is removed. It can be re-applied if desired.
1.294 + *
1.295 + * @param menu Handle to the menu.
1.296 + * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION.
1.297 + * @return True on success, false if pagination is too high or
1.298 + * low.
1.299 + * @error Invalid Handle.
1.300 + */
1.301 +native bool:SetMenuPagination(Handle:menu, itemsPerPage);
1.302 +
1.303 +/**
1.304 + * Returns a menu's pagination setting.
1.305 + *
1.306 + * @param menu Handle to the menu.
1.307 + * @return Pagination setting.
1.308 + * @error Invalid Handle.
1.309 + */
1.310 +native GetMenuPagination(Handle:menu);
1.311 +
1.312 +/**
1.313 + * Returns a menu's MenuStyle Handle. The Handle
1.314 + * is global and cannot be freed.
1.315 + *
1.316 + * @param menu Handle to the menu.
1.317 + * @return Handle to the menu's draw style.
1.318 + * @error Invalid Handle.
1.319 + */
1.320 +native Handle:GetMenuStyle(Handle:menu);
1.321 +
1.322 +/**
1.323 + * Sets the menu's default title/instruction message.
1.324 + *
1.325 + * @param menu Menu Handle.
1.326 + * @param fmt Message string format
1.327 + * @param ... Message string arguments.
1.328 + * @noreturn
1.329 + * @error Invalid Handle.
1.330 + */
1.331 +native SetMenuTitle(Handle:menu, const String:fmt[], any:...);
1.332 +
1.333 +/**
1.334 + * Returns the text of a menu's title.
1.335 + *
1.336 + * @param menu Menu Handle.
1.337 + * @param buffer Buffer to store title.
1.338 + * @param maxlength Maximum length of the buffer.
1.339 + * @return Number of bytes written.
1.340 + * @error Invalid Handle/
1.341 + */
1.342 +native GetMenuTitle(Handle:menu, String:buffer[], maxlength);
1.343 +
1.344 +/**
1.345 + * Creates a raw MenuPanel based off the menu's style.
1.346 + * The Handle must be freed with CloseHandle().
1.347 + *
1.348 + * @return A new MenuPanel Handle.
1.349 + * @error Invalid Handle.
1.350 + */
1.351 +native Handle:CreatePanelFromMenu(Handle:menu);
1.352 +
1.353 +/**
1.354 + * Returns whether or not the menu has an exit button.
1.355 + * By default, menus have an exit button.
1.356 + *
1.357 + * @param menu Menu Handle.
1.358 + * @return True if the menu has an exit button; false otherwise.
1.359 + * @error Invalid Handle.
1.360 + */
1.361 +native bool:GetMenuExitButton(Handle:menu);
1.362 +
1.363 +/**
1.364 + * Sets whether or not the menu has an exit button. By default, paginated menus
1.365 + * have an exit button.
1.366 + *
1.367 + * If a menu's pagination is changed to MENU_NO_PAGINATION, and the pagination
1.368 + * was previously a different value, then the Exit button status is changed to
1.369 + * false. It must be explicitly re-enabled afterwards.
1.370 + *
1.371 + * If a non-paginated menu has an exit button, then at most 9 items will be
1.372 + * displayed.
1.373 + *
1.374 + * @param menu Menu Handle.
1.375 + * @param button True to enable the button, false to remove it.
1.376 + * @return True if allowed; false on failure.
1.377 + * @error Invalid Handle.
1.378 + */
1.379 +native bool:SetMenuExitButton(Handle:menu, bool:button);
1.380 +
1.381 +/**
1.382 + * Returns whether or not the menu has an "exit back" button. By default,
1.383 + * menus do not have an exit back button.
1.384 + *
1.385 + * Exit Back buttons appear as "Back" on page 1 of paginated menus and have
1.386 + * functionality defined by the user in MenuEnd_ExitBack.
1.387 + *
1.388 + * @param menu Menu Handle.
1.389 + * @return True if the menu has an exit back button; false otherwise.
1.390 + * @error Invalid Handle.
1.391 + */
1.392 +native bool:GetMenuExitBackButton(Handle:menu);
1.393 +
1.394 +/**
1.395 + * Sets whether or not the menu has an "exit back" button. By default, menus
1.396 + * do not have an exit back button.
1.397 + *
1.398 + * Exit Back buttons appear as "Back" on page 1 of paginated menus and have
1.399 + * functionality defined by the user in MenuEnd_ExitBack.
1.400 + *
1.401 + * @param menu Menu Handle.
1.402 + * @param button True to enable the button, false to remove it.
1.403 + * @error Invalid Handle.
1.404 + */
1.405 +native SetMenuExitBackButton(Handle:menu, bool:button);
1.406 +
1.407 +
1.408 +/**
1.409 + * Cancels a menu from displaying on all clients. While the
1.410 + * cancellation is in progress, this menu cannot be re-displayed
1.411 + * to any clients.
1.412 + *
1.413 + * The menu may still exist on the client's screen after this command.
1.414 + * This simply verifies that the menu is not being used anywhere.
1.415 + *
1.416 + * If any vote is in progress on a menu, it will be cancelled.
1.417 + *
1.418 + * @param menu Menu Handle.
1.419 + * @noreturn
1.420 + * @error Invalid Handle.
1.421 + */
1.422 +native CancelMenu(Handle:menu);
1.423 +
1.424 +/**
1.425 + * Retrieves a menu's option flags.
1.426 + *
1.427 + * @param menu Menu Handle.
1.428 + * @return A bitstring of MENUFLAG bits.
1.429 + * @error Invalid Handle.
1.430 + */
1.431 +native GetMenuOptionFlags(Handle:menu);
1.432 +
1.433 +/**
1.434 + * Sets a menu's option flags.
1.435 + *
1.436 + * If a certain bit is not supported, it will be stripped before being set.
1.437 + * See SetMenuExitButton() for information on Exit buttons.
1.438 + * See SetMenuExitBackButton() for information on Exit Back buttons.
1.439 + *
1.440 + * @param menu Menu Handle.
1.441 + * @param flags A new bitstring of MENUFLAG bits.
1.442 + * @noreturn
1.443 + * @error Invalid Handle.
1.444 + */
1.445 +native SetMenuOptionFlags(Handle:menu, flags);
1.446 +
1.447 +/**
1.448 + * Returns whether a vote is in progress.
1.449 + *
1.450 + * @param menu Deprecated; no longer used.
1.451 + * @return True if a vote is in progress, false otherwise.
1.452 + */
1.453 +native bool:IsVoteInProgress(Handle:menu=INVALID_HANDLE);
1.454 +
1.455 +/**
1.456 + * Cancels the vote in progress.
1.457 + *
1.458 + * @noreturn
1.459 + * @error If no vote is in progress.
1.460 + */
1.461 +native CancelVote();
1.462 +
1.463 +/**
1.464 + * Broadcasts a menu to a list of clients. The most selected item will be
1.465 + * returned through MenuAction_End. On a tie, a random item will be returned
1.466 + * from a list of the tied items.
1.467 + *
1.468 + * Note that MenuAction_VoteEnd and MenuAction_VoteStart are both
1.469 + * default callbacks and do not need to be enabled.
1.470 + *
1.471 + * @param menu Menu Handle.
1.472 + * @param clients Array of clients to broadcast to.
1.473 + * @param numClients Number of clients in the array.
1.474 + * @param time Maximum time to leave menu on the screen.
1.475 + * @return True on success, false if this menu already has a vote session
1.476 + * in progress.
1.477 + * @error Invalid Handle, or a vote is already in progress.
1.478 + */
1.479 +native bool:VoteMenu(Handle:menu, clients[], numClients, time);
1.480 +
1.481 +/**
1.482 + * Sends a vote menu to all clients. See VoteMenu() for more information.
1.483 + *
1.484 + * @param menu Menu Handle.
1.485 + * @param time Maximum time to leave menu on the screen.
1.486 + * @return True on success, false if this menu already has a vote session
1.487 + * in progress.
1.488 + * @error Invalid Handle.
1.489 + */
1.490 +stock VoteMenuToAll(Handle:menu, time)
1.491 +{
1.492 + new num = GetMaxClients();
1.493 + new total;
1.494 + decl players[num];
1.495 +
1.496 + for (new i=1; i<=num; i++)
1.497 + {
1.498 + if (!IsClientInGame(i))
1.499 + {
1.500 + continue;
1.501 + }
1.502 + players[total++] = i;
1.503 + }
1.504 +
1.505 + return VoteMenu(menu, players, total, time);
1.506 +}
1.507 +/**
1.508 + * Callback for when a vote has ended and results are available.
1.509 + *
1.510 + * @param menu The menu being voted on.
1.511 + * @param num_votes Number of votes tallied in total.
1.512 + * @param num_clients Number of clients who could vote.
1.513 + * @param client_info Array of clients. Use VOTEINFO_CLIENT_ defines.
1.514 + * @param num_items Number of unique items that were selected.
1.515 + * @param item_info Array of items, sorted by count. Use VOTEINFO_ITEM
1.516 + * defines.
1.517 + * @noreturn
1.518 + */
1.519 +functag VoteHandler public(Handle:menu,
1.520 + num_votes,
1.521 + num_clients,
1.522 + const client_info[][2],
1.523 + num_items,
1.524 + const item_info[][2]);
1.525 +
1.526 +/**
1.527 + * Sets an advanced vote handling callback. If this callback is set,
1.528 + * MenuAction_VoteEnd will not be called.
1.529 + *
1.530 + * @param menu Menu Handle.
1.531 + * @param callback Callback function.
1.532 + * @noreturn
1.533 + * @error Invalid Handle or callback.
1.534 + */
1.535 +native SetVoteResultCallback(Handle:menu, VoteHandler:callback);
1.536 +
1.537 +/**
1.538 + * Returns the number of seconds you should "wait" before displaying
1.539 + * a publicly invocable menu. This number is the time remaining until
1.540 + * (last_vote + sm_vote_delay).
1.541 + *
1.542 + * @return Number of seconds to wait, or 0 for none.
1.543 + */
1.544 +native CheckVoteDelay();
1.545 +
1.546 +/**
1.547 + * Returns a style's global Handle.
1.548 + *
1.549 + * @param style Menu Style.
1.550 + * @return A Handle, or INVALID_HANDLE if not found or unusable.
1.551 + */
1.552 +native Handle:GetMenuStyleHandle(MenuStyle:style);
1.553 +
1.554 +/**
1.555 + * Creates a MenuPanel from a MenuStyle. Panels are used for drawing raw
1.556 + * menus without any extra helper functions. The Handle must be closed
1.557 + * with CloseHandle().
1.558 + *
1.559 + * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
1.560 + * @return A new MenuPanel Handle.
1.561 + * @error Invalid Handle other than INVALID_HANDLE.
1.562 + */
1.563 +native Handle:CreatePanel(Handle:hStyle=INVALID_HANDLE);
1.564 +
1.565 +/**
1.566 + * Creates a Menu from a MenuStyle. The Handle must be closed with
1.567 + * CloseHandle().
1.568 + *
1.569 + * @parma hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
1.570 + * @param handler Function which will receive menu actions.
1.571 + * @param actions Optionally set which actions to receive. Select,
1.572 + * Cancel, and End will always be received regardless
1.573 + * of whether they are set or not. They are also
1.574 + * the only default actions.
1.575 + * @return A new menu Handle.
1.576 + * @error Invalid Handle other than INVALID_HANDLE.
1.577 + */
1.578 +native Handle:CreateMenuEx(Handle:hStyle=INVALID_HANDLE, MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
1.579 +
1.580 +/**
1.581 + * Returns whether a client is viewing a menu.
1.582 + *
1.583 + * @param client Client index.
1.584 + * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
1.585 + * @return A MenuSource value.
1.586 + * @error Invalid Handle other than INVALID_HANDLE.
1.587 + */
1.588 +native MenuSource:GetClientMenu(client, Handle:hStyle=INVALID_HANDLE);
1.589 +
1.590 +/**
1.591 + * Cancels a menu on a client. This will only affect non-external menus.
1.592 + *
1.593 + * @param hstyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
1.594 + * @param client Client index.
1.595 + * @param autoIgnore If true, no menus can be re-drawn on the client during
1.596 + * the cancellation process.
1.597 + * @return True if a menu was cancelled, false otherwise.
1.598 + */
1.599 +native bool:CancelClientMenu(client, bool:autoIgnore=false, Handle:hStyle=INVALID_HANDLE);
1.600 +
1.601 +/**
1.602 + * Returns a style's maximum items per page.
1.603 + *
1.604 + * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
1.605 + * @return Maximum items per page.
1.606 + * @error Invalid Handle other than INVALID_HANDLE.
1.607 + */
1.608 +native GetMaxPageItems(Handle:hStyle=INVALID_HANDLE);
1.609 +
1.610 +/**
1.611 + * Returns a MenuPanel's parent style.
1.612 + *
1.613 + * @param panel A MenuPanel Handle.
1.614 + * @return The MenuStyle Handle that created the panel.
1.615 + * @error Invalid Handle.
1.616 + */
1.617 +native Handle:GetPanelStyle(Handle:panel);
1.618 +
1.619 +/**
1.620 + * Sets the panel's title.
1.621 + *
1.622 + * @param panel A MenuPanel Handle.
1.623 + * @param title Text to set as the title.
1.624 + * @param onlyIfEmpty If true, the title will only be set if no title is set.
1.625 + * @noreturn
1.626 + * @error Invalid Handle.
1.627 + */
1.628 +native Handle:SetPanelTitle(Handle:panel, const String:text[], bool:onlyIfEmpty=false);
1.629 +
1.630 +/**
1.631 + * Draws an item on a panel. If the item takes up a slot, the position
1.632 + * is returned.
1.633 + *
1.634 + * @param panel A MenuPanel Handle.
1.635 + * @param text Display text to use. If not a raw line,
1.636 + * the style may automatically add color markup.
1.637 + * No numbering or newlines are needed.
1.638 + * @param style ITEMDRAW style flags.
1.639 + * @return A slot position, or 0 if item was a rawline or could not be drawn.
1.640 + * @error Invalid Handle.
1.641 + */
1.642 +native DrawPanelItem(Handle:panel, const String:text[], style=ITEMDRAW_DEFAULT);
1.643 +
1.644 +/**
1.645 + * Draws a raw line of text on a panel, without any markup other than a newline.
1.646 + *
1.647 + * @param panel A MenuPanel Handle, or INVALID_HANDLE if inside a
1.648 + * MenuAction_DisplayItem callback.
1.649 + * @param text Display text to use.
1.650 + * @return True on success, false if raw lines are not supported.
1.651 + * @error Invalid Handle.
1.652 + */
1.653 +native DrawPanelText(Handle:panel, const String:text[]);
1.654 +
1.655 +/**
1.656 + * Returns whether or not the given drawing flags are supported by
1.657 + * the menu style.
1.658 + *
1.659 + * @param panel A MenuPanel Handle.
1.660 + * @param style ITEMDRAW style flags.
1.661 + * @return True if item is drawable, false otherwise.
1.662 + * @error Invalid Handle.
1.663 + */
1.664 +native CanPanelDrawFlags(Handle:panel, style);
1.665 +
1.666 +/**
1.667 + * Sets the selectable key map of a panel. This is not supported by
1.668 + * all styles (only by Radio, as of this writing).
1.669 + *
1.670 + * @param keys An integer where each bit N allows key
1.671 + * N+1 to be selected. If no keys are selectable,
1.672 + * then key 0 (bit 9) is automatically set.
1.673 + * @return True if supported, false otherwise.
1.674 + */
1.675 +native bool:SetPanelKeys(Handle:panel, keys);
1.676 +
1.677 +/**
1.678 + * Sends a panel to a client. Unlike full menus, the handler
1.679 + * function will only receive the following actions, both of
1.680 + * which will have INVALID_HANDLE for a menu, and the client
1.681 + * as param1.
1.682 + *
1.683 + * MenuAction_Select (param2 will be the key pressed)
1.684 + * MenuAction_Cancel (param2 will be the reason)
1.685 + *
1.686 + * Also, if the menu fails to display, no callbacks will be called.
1.687 + *
1.688 + * @param panel A MenuPanel Handle.
1.689 + * @param client A client to draw to.
1.690 + * @param handler The MenuHandler function to catch actions with.
1.691 + * @param time Time to hold the menu for.
1.692 + * @return True on success, false on failure.
1.693 + * @error Invalid Handle.
1.694 + */
1.695 +native bool:SendPanelToClient(Handle:panel, client, MenuHandler:handler, time);
1.696 +
1.697 +/**
1.698 + * @brief Returns the amount of text the menu can still hold. If this is
1.699 + * limit is reached or overflowed, the text is silently truncated.
1.700 + *
1.701 + * Radio menus: Currently 511 characters (512 bytes).
1.702 + * Valve menus: Currently -1 (no meaning).
1.703 + *
1.704 + * @param panel A MenuPanel Handle.
1.705 + * @return Number of characters that the menu can still hold,
1.706 + * or -1 if there is no known limit.
1.707 + * @error Invalid Handle.
1.708 + */
1.709 +native GetPanelTextRemaining(Handle:panel);
1.710 +
1.711 +/**
1.712 + * @brief Returns the current key position.
1.713 + *
1.714 + * @param panel A MenuPanel Handle.
1.715 + * @return Current key position starting at 1.
1.716 + * @error Invalid Handle.
1.717 + */
1.718 +native GetPanelCurrentKey(Handle:panel);
1.719 +
1.720 +/**
1.721 + * @brief Sets the next key position. This cannot be used
1.722 + * to traverse backwards.
1.723 + *
1.724 + * @param panel A MenuPanel Handle.
1.725 + * @param key Key that is greater or equal to
1.726 + * GetPanelCurrentKey().
1.727 + * @return True on success, false otherwise.
1.728 + * @error Invalid Handle.
1.729 + */
1.730 +native bool:SetPanelCurrentKey(Handle:panel, key);
1.731 +
1.732 +/**
1.733 + * @brief Redraws menu text from inside a MenuAction_DisplayItem callback.
1.734 + *
1.735 + * @param text Menu text to draw.
1.736 + * @return Item position; must be returned via the callback.
1.737 + */
1.738 +native RedrawMenuItem(const String:text[]);
1.739 +
1.740 +/**
1.741 + * This function is provided for legacy code only. Some older plugins may use
1.742 + * network messages instead of the panel API. This function wraps the panel
1.743 + * API for eased portability into the SourceMod menu system.
1.744 + *
1.745 + * This function is only usable with the Radio Menu style. You do not need to
1.746 + * split up your menu into multiple packets; SourceMod will break the string
1.747 + * up internally.
1.748 + *
1.749 + * @param client Client index.
1.750 + * @param str Full menu string as would be passed over the network.
1.751 + * @param time Time to hold the menu for.
1.752 + * @param keys Selectable key bitstring.
1.753 + * @param handler Optional handler function, with the same rules as
1.754 + * SendPanelToClient().
1.755 + * @return True on success, false on failure.
1.756 + * @error Invalid client index, or radio menus not supported.
1.757 + */
1.758 +native bool:InternalShowMenu(client, const String:str[], time, keys=-1, MenuHandler:handler=MenuHandler:-1);
1.759 +
1.760 +/**
1.761 + * Retrieves voting information from MenuAction_VoteEnd.
1.762 + *
1.763 + * @param param2 Second parameter of MenuAction_VoteEnd.
1.764 + * @param winningVotes Number of votes received by the winning option.
1.765 + * @param totalVotes Number of total votes received.
1.766 + * @noreturn
1.767 + */
1.768 +stock GetMenuVoteInfo(param2, &winningVotes, &totalVotes)
1.769 +{
1.770 + winningVotes = param2 & 0xFFFF;
1.771 + totalVotes = param2 >> 16;
1.772 +}
1.773 +
1.774 +/**
1.775 + * Quick stock to determine whether voting is allowed. This doesn't let you
1.776 + * fine-tune a reason for not voting, so it's not recommended for lazily
1.777 + * telling clients that voting isn't allowed.
1.778 + *
1.779 + * @return True if voting is allowed, false if voting is in progress
1.780 + * or the cooldown is active.
1.781 + */
1.782 +stock bool:IsNewVoteAllowed()
1.783 +{
1.784 + if (IsVoteInProgress() || CheckVoteDelay() != 0)
1.785 + {
1.786 + return false;
1.787 + }
1.788 +
1.789 + return true;
1.790 +}
