3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _menus_included
19 #define _menus_included
22 * Low-level drawing style of the menu.
26 MenuStyle_Default = 0, /**< The "default" menu style for the mod */
27 MenuStyle_Valve = 1, /**< The Valve provided menu style (Used on HL2DM) */
28 MenuStyle_Radio = 2, /**< The simpler menu style commonly used on CS:S */
32 * Different actions for the menu "pump" callback
36 MenuAction_Start = (1<<0), /**< A menu has been started (nothing passed) */
37 MenuAction_Display = (1<<1), /**< A menu is about to be displayed (param1=client, param2=MenuPanel Handle) */
38 MenuAction_Select = (1<<2), /**< An item was selected (param1=client, param2=item) */
39 MenuAction_Cancel = (1<<3), /**< The menu was cancelled (param1=client, param2=reason) */
40 MenuAction_End = (1<<4), /**< A menu display has fully ended (param1=reason, param2=cancel reason) */
41 MenuAction_VoteEnd = (1<<5), /**< (VOTE ONLY): A vote sequence has succeeded (param1=chosen item) */
42 MenuAction_VoteStart = (1<<6), /**< (VOTE ONLY): A vote sequence has started (nothing passed) */
43 MenuAction_VoteCancel = (1<<7), /**< (VOTE ONLY): A vote sequence has been cancelled (nothing passed) */
44 MenuAction_DrawItem = (1<<8), /**< An item is being drawn; return the new style (param1=client, param2=item) */
45 MenuAction_DisplayItem = (1<<9) /**< Item text is being drawn to the display (param1=client, param2=item)
46 To change the text, use RedrawMenuItem().
47 If you do so, return its return value. Otherwise, return 0.
51 /** Default menu actions */
52 #define MENU_ACTIONS_DEFAULT MenuAction_Select|MenuAction_Cancel|MenuAction_End
53 /** All menu actions */
54 #define MENU_ACTIONS_ALL -1
56 #define MENU_NO_PAGINATION 0 /**< Menu should not be paginated (10 items max) */
57 #define MENU_TIME_FOREVER 0 /**< Menu should be displayed as long as possible */
59 #define ITEMDRAW_DEFAULT (0) /**< Item should be drawn normally */
60 #define ITEMDRAW_DISABLED (1<<0) /**< Item is drawn but not selectable */
61 #define ITEMDRAW_RAWLINE (1<<1) /**< Item should be a raw line, without a slot */
62 #define ITEMDRAW_NOTEXT (1<<2) /**< No text should be drawn */
63 #define ITEMDRAW_SPACER (1<<3) /**< Item should be drawn as a spacer, if possible */
64 #define ITEMDRAW_IGNORE ((1<<1)|(1<<2)) /**< Item should be completely ignored (rawline + notext) */
65 #define ITEMDRAW_CONTROL (1<<4) /**< Item is control text (back/next/exit) */
68 * Reasons a menu can be cancelled.
72 MenuCancel_Disconnected = -1, /**< Client dropped from the server */
73 MenuCancel_Interrupted = -2, /**< Client was interrupted with another menu */
74 MenuCancel_Exit = -3, /**< Client exited via "exit" */
75 MenuCancel_NoDisplay = -4, /**< Menu could not be displayed to the client */
76 MenuCancel_Timeout = -5, /**< Menu timed out */
77 MenuCancel_ExitBack = -6, /**< Client selected "exit back" on a paginated menu */
81 * Reasons a menu ended.
85 MenuEnd_Selected = 0, /**< Menu item was selected */
86 MenuEnd_VotingDone = -1, /**< Voting finished */
87 MenuEnd_VotingCancelled = -2, /**< Voting was cancelled */
88 MenuEnd_Cancelled = -3, /**< Menu was cancelled (reason in param2) */
89 MenuEnd_Exit = -4, /**< Menu was cleanly exited via "exit" */
90 MenuEnd_ExitBack = -5, /**< Menu was cleanly exited via "back" */
94 * Describes a menu's source
98 MenuSource_None = 0, /**< No menu is being displayed */
99 MenuSource_External = 1, /**< External menu */
100 MenuSource_Normal = 2, /**< A basic menu is being displayed */
101 MenuSource_RawPanel = 3, /**< A display is active, but it is not tied to a menu */
105 * Called when a menu action is completed.
107 * @param menu The menu being acted upon.
108 * @param action The action of the menu.
109 * @param param1 First action parameter (usually the client).
110 * @param param2 Second action parameter (usually the item).
113 functag MenuHandler public(Handle:menu, MenuAction:action, param1, param2);
116 * Creates a new, empty menu using the default style.
118 * @param handler Function which will receive menu actions.
119 * @param actions Optionally set which actions to receive. Select,
120 * Cancel, and End will always be received regardless
121 * of whether they are set or not. They are also
122 * the only default actions.
123 * @return A new menu Handle.
125 native Handle:CreateMenu(MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
128 * Displays a menu to a client.
130 * @param menu Menu Handle.
131 * @param client Client index.
132 * @param time Maximum time to leave menu on the screen.
133 * @return True on success, false on failure.
134 * @error Invalid Handle or client not in game.
136 native bool:DisplayMenu(Handle:menu, client, time);
139 * Appends a new item to the end of a menu.
141 * @param menu Menu Handle.
142 * @param info Item information string.
143 * @param display Default item display string.
144 * @param style Drawing style flags. Anything other than DEFAULT or
145 * DISABLED will be completely ignored when paginating.
146 * @return True on success, false on failure.
147 * @error Invalid Handle or item limit reached.
149 native AddMenuItem(Handle:menu,
151 const String:display[],
152 style=ITEMDRAW_DEFAULT);
155 * Inserts an item into the menu before a certain position; the new item will
156 * be at the given position and all next items pushed forward.
158 * @param menu Menu Handle.
159 * @param position Position, starting from 0.
160 * @param info Item information string.
161 * @param display Default item display string.
162 * @param style Drawing style flags. Anything other than DEFAULT or
163 * DISABLED will be completely ignored when paginating.
164 * @return True on success, false on failure.
165 * @error Invalid Handle or menu position.
167 native bool:InsertMenuItem(Handle:menu,
170 const String:display[],
171 style=ITEMDRAW_DEFAULT);
174 * Removes an item from the menu.
176 * @param menu Menu Handle.
177 * @param position Position, starting from 0.
178 * @return True on success, false on failure.
179 * @error Invalid Handle or menu position.
181 native bool:RemoveMenuItem(Handle:menu, position);
184 * Removes all items from a menu.
186 * @param menu Menu Handle.
188 * @error Invalid Handle or menu position.
190 native RemoveAllMenuItems(Handle:menu);
193 * Retrieves information about a menu item.
195 * @param menu Menu Handle.
196 * @param position Position, starting from 0.
197 * @param infoBuf Info buffer.
198 * @param infoBufLen Maximum length of the info buffer.
199 * @param style By-reference variable to store drawing flags.
200 * @param dispBuf Display buffer.
201 * @param dispBufLen Maximum length of the display buffer.
202 * @return True on success, false if position is invalid.
203 * @error Invalid Handle.
205 native bool:GetMenuItem(Handle:menu, position, String:infoBuf[], infoBufLen, &style=0, String:dispBuf[]="", dispBufLen=0);
208 * Returns the number of items in a menu.
210 * @param menu Menu Handle.
211 * @return Number of items in the menu.
212 * @error Invalid Handle.
214 native GetMenuItemCount(Handle:menu);
217 * Sets whether the menu should be paginated or not.
219 * @param menu Handle to the menu.
220 * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION.
221 * @return True on success, false if pagination is too high or low.
222 * @error Invalid Handle.
224 native bool:SetMenuPagination(Handle:menu, itemsPerPage);
227 * Returns a menu's pagination setting.
229 * @param menu Handle to the menu.
230 * @return Pagination setting.
231 * @error Invalid Handle.
233 native GetMenuPagination(Handle:menu);
236 * Returns a menu's MenuStyle Handle. The Handle
237 * is global and cannot be freed.
239 * @param menu Handle to the menu.
240 * @return Handle to the menu's draw style.
241 * @error Invalid Handle.
243 native Handle:GetMenuStyle(Handle:menu);
246 * Sets the menu's default title/instruction message.
248 * @param menu Menu Handle.
249 * @param fmt Message string format
250 * @param ... Message string arguments.
252 * @error Invalid Handle.
254 native SetMenuTitle(Handle:menu, const String:fmt[], any:...);
257 * Creates a raw MenuPanel based off the menu's style.
258 * The Handle must be freed with CloseHandle().
260 * @return A new MenuPanel Handle.
261 * @error Invalid Handle.
263 native Handle:CreatePanelFromMenu(Handle:menu);
266 * Returns whether or not the menu has an exit button.
267 * By default, menus have an exit button.
269 * @param menu Menu Handle.
270 * @return True if the menu has an exit button; false otherwise.
271 * @error Invalid Handle.
273 native bool:GetMenuExitButton(Handle:menu);
276 * Sets whether or not the menu has an exit button.
277 * By default, menus have an exit button.
279 * @param menu Menu Handle.
280 * @param button True to enable the button, false to remove it.
281 * @return True if allowed; false on failure.
282 * @error Invalid Handle.
284 native bool:SetMenuExitButton(Handle:menu, bool:button);
287 * Returns whether or not the menu has an "exit back" button.
288 * By default, menus do not have an exit back button.
289 * Exit Back buttons appear as "Back" on page 1 of paginated menus and
290 * have functionality defined by the user in MenuEnd_ExitBack.
292 * @param menu Menu Handle.
293 * @return True if the menu has an exit back button; false otherwise.
294 * @error Invalid Handle.
296 native bool:GetMenuExitBackButton(Handle:menu);
299 * Sets whether or not the menu has an "exit back" button.
300 * By default, menus do not have an exit back button.
301 * Exit Back buttons appear as "Back" on page 1 of paginated menus and
302 * have functionality defined by the user in MenuEnd_ExitBack.
304 * @param menu Menu Handle.
305 * @param button True to enable the button, false to remove it.
306 * @error Invalid Handle.
308 native SetMenuExitBackButton(Handle:menu, bool:button);
312 * Cancels a menu from displaying on all clients. While the
313 * cancellation is in progress, this menu cannot be re-displayed
316 * The menu may still exist on the client's screen after this command.
317 * This simply verifies that the menu is not being used anywhere.
319 * If any vote is in progress on a menu, it will be cancelled.
321 * @param menu Menu Handle.
323 * @error Invalid Handle.
325 native CancelMenu(Handle:menu);
328 * Returns whether a vote is in progress on the given menu.
330 * @param menu Menu Handle.
331 * @return True if a vote is in progress, false otherwise.
333 native bool:IsVoteInProgress(Handle:menu);
336 * Broadcasts a menu to a list of clients. The most selected item will be
337 * returned through MenuAction_End. On a tie, a random item will be returned
338 * from a list of the tied items.
340 * Note that MenuAction_VoteEnd and MenuAction_VoteStart are both
341 * default callbacks and do not need to be enabled.
343 * @param menu Menu Handle.
344 * @param clients Array of clients to broadcast to.
345 * @param numClients Number of clients in the array.
346 * @param time Maximum time to leave menu on the screen.
347 * @return True on success, false if this menu already has a vote session
349 * @error Invalid Handle.
351 native bool:VoteMenu(Handle:menu, clients[], numClients, time);
354 * Sends a vote menu to all clients. See VoteMenu() for more information.
356 * @param menu Menu Handle.
357 * @param time Maximum time to leave menu on the screen.
358 * @return True on success, false if this menu already has a vote session
360 * @error Invalid Handle.
362 stock VoteMenuToAll(Handle:menu, time)
364 new num = GetMaxClients();
368 for (new i=1; i<=num; i++)
370 if (!IsClientInGame(i))
374 players[total++] = i;
377 return VoteMenu(menu, players, total, time);
381 * Returns a style's global Handle.
383 * @param style Menu Style.
384 * @return A Handle, or INVALID_HANDLE if not found or unusable.
386 native Handle:GetMenuStyleHandle(MenuStyle:style);
389 * Creates a MenuPanel from a MenuStyle. Panels are used for drawing raw
390 * menus without any extra helper functions. The Handle must be closed
391 * with CloseHandle().
393 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
394 * @return A new MenuPanel Handle.
395 * @error Invalid Handle other than INVALID_HANDLE.
397 native Handle:CreatePanel(Handle:hStyle=INVALID_HANDLE);
400 * Creates a Menu from a MenuStyle. The Handle must be closed with
403 * @parma hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
404 * @param handler Function which will receive menu actions.
405 * @param actions Optionally set which actions to receive. Select,
406 * Cancel, and End will always be received regardless
407 * of whether they are set or not. They are also
408 * the only default actions.
409 * @return A new menu Handle.
410 * @error Invalid Handle other than INVALID_HANDLE.
412 native Handle:CreateMenuEx(Handle:hStyle=INVALID_HANDLE, MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
415 * Returns whether a client is viewing a menu. If the menu source
416 * is MenuSource_Normal, a menu Handle will also be returned.
418 * @param client Client index.
419 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
420 * @return A MenuSource value.
421 * @error Invalid Handle other than INVALID_HANDLE.
423 native MenuSource:GetClientMenu(client, Handle:hStyle=INVALID_HANDLE);
426 * Cancels a menu on a client. This will only affect non-external menus.
428 * @param hstyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
429 * @param client Client index.
430 * @param autoIgnore If true, no menus can be re-drawn on the client during
431 * the cancellation process.
432 * @return True if a menu was cancelled, false otherwise.
434 native bool:CancelClientMenu(client, bool:autoIgnore=false, Handle:hStyle=INVALID_HANDLE);
437 * Returns a style's maximum items per page.
439 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
440 * @return Maximum items per page.
441 * @error Invalid Handle other than INVALID_HANDLE.
443 native GetMaxPageItems(Handle:hStyle=INVALID_HANDLE);
446 * Returns a MenuPanel's parent style.
448 * @param panel A MenuPanel Handle.
449 * @return The MenuStyle Handle that created the panel.
450 * @error Invalid Handle.
452 native Handle:GetPanelStyle(Handle:panel);
455 * Sets the panel's title.
457 * @param panel A MenuPanel Handle.
458 * @param title Text to set as the title.
459 * @param onlyIfEmpty If true, the title will only be set if no title is set.
461 * @error Invalid Handle.
463 native Handle:SetPanelTitle(Handle:panel, const String:text[], bool:onlyIfEmpty=false);
466 * Draws an item on a panel. If the item takes up a slot, the position
469 * @param panel A MenuPanel Handle.
470 * @param text Display text to use. If not a raw line,
471 * the style may automatically add color markup.
472 * No numbering or newlines are needed.
473 * @param style ITEMDRAW style flags.
474 * @return A slot position, or 0 if item was a rawline or could not be drawn.
475 * @error Invalid Handle.
477 native DrawPanelItem(Handle:panel, const String:text[], style=ITEMDRAW_DEFAULT);
480 * Draws a raw line of text on a panel, without any markup other than a newline.
482 * @param panel A MenuPanel Handle, or INVALID_HANDLE if inside a
483 * MenuAction_DisplayItem callback.
484 * @param text Display text to use.
485 * @return True on success, false if raw lines are not supported.
486 * @error Invalid Handle.
488 native DrawPanelText(Handle:panel, const String:text[]);
491 * Returns whether or not the given drawing flags are supported by
494 * @param panel A MenuPanel Handle.
495 * @param style ITEMDRAW style flags.
496 * @return True if item is drawable, false otherwise.
497 * @error Invalid Handle.
499 native CanPanelDrawFlags(Handle:panel, style);
502 * Sets the selectable key map of a panel. This is not supported by
503 * all styles (only by Radio, as of this writing).
505 * @param keys An integer where each bit N allows key
506 * N+1 to be selected. If no keys are selectable,
507 * then key 0 (bit 9) is automatically set.
508 * @return True if supported, false otherwise.
510 native bool:SetPanelKeys(Handle:panel, keys);
513 * Sends a panel to a client. Unlike full menus, the handler
514 * function will only receive the following actions, both of
515 * which will have INVALID_HANDLE for a menu, and the client
518 * MenuAction_Select (param2 will be the key pressed)
519 * MenuAction_Cancel (param2 will be the reason)
521 * Also, if the menu fails to display, no callbacks will be called.
523 * @param panel A MenuPanel Handle.
524 * @param client A client to draw to.
525 * @param handler The MenuHandler function to catch actions with.
526 * @param time Time to hold the menu for.
527 * @return True on success, false on failure.
528 * @error Invalid Handle.
530 native bool:SendPanelToClient(Handle:panel, client, MenuHandler:handler, time);
533 * @brief Returns the current key position.
535 * @param panel A MenuPanel Handle.
536 * @return Current key position starting at 1.
537 * @error Invalid Handle.
539 native GetPanelCurrentKey(Handle:panel);
542 * @brief Sets the next key position. This cannot be used
543 * to traverse backwards.
545 * @param panel A MenuPanel Handle.
546 * @param key Key that is greater or equal to
547 * GetPanelCurrentKey().
548 * @return True on success, false otherwise.
549 * @error Invalid Handle.
551 native bool:SetPanelCurrentKey(Handle:panel, key);
554 * @brief Redraws menu text from inside a MenuAction_DisplayItem callback.
556 * @param text Menu text to draw.
557 * @return Item position; must be returned via the callback.
559 native RedrawMenuItem(const String:text[]);
562 * Retrieves voting information from MenuAction_VoteEnd.
564 * @param param2 Second parameter of MenuAction_VoteEnd.
565 * @param winningVotes Number of votes received by the winning option.
566 * @param totalVotes Number of total votes received.
569 stock GetMenuVoteInfo(param2, &winningVotes, &totalVotes)
571 winningVotes = param2 & 0xFFFF;
572 totalVotes = param2 >> 16;
