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) */
47 /** Default menu actions */
48 #define MENU_ACTIONS_DEFAULT MenuAction_Select|MenuAction_Cancel|MenuAction_End
49 /** All menu actions */
50 #define MENU_ACTIONS_ALL -1
52 #define MENU_NO_PAGINATION 0 /**< Menu should not be paginated (10 items max) */
53 #define MENU_TIME_FOREVER 0 /**< Menu should be displayed as long as possible */
55 #define ITEMDRAW_DEFAULT (0) /**< Item should be drawn normally */
56 #define ITEMDRAW_DISABLED (1<<0) /**< Item is drawn but not selectable */
57 #define ITEMDRAW_RAWLINE (1<<1) /**< Item should be a raw line, without a slot */
58 #define ITEMDRAW_NOTEXT (1<<2) /**< No text should be drawn */
59 #define ITEMDRAW_SPACER (1<<3) /**< Item should be drawn as a spacer, if possible */
60 #define ITEMDRAW_IGNORE ((1<<1)|(1<<2)) /**< Item should be completely ignored (rawline + notext) */
61 #define ITEMDRAW_CONTROL (1<<4) /**< Item is control text (back/next/exit) */
64 * Reasons a menu can be cancelled.
68 MenuCancel_Disconnected = -1, /**< Client dropped from the server */
69 MenuCancel_Interrupted = -2, /**< Client was interrupted with another menu */
70 MenuCancel_Exit = -3, /**< Client exited via "exit" */
71 MenuCancel_NoDisplay = -4, /**< Menu could not be displayed to the client */
72 MenuCancel_Timeout = -5, /**< Menu timed out */
73 MenuCancel_ExitBack = -6, /**< Client selected "exit back" on a paginated menu */
77 * Reasons a menu ended.
81 MenuEnd_Selected = 0, /**< Menu item was selected */
82 MenuEnd_VotingDone = -1, /**< Voting finished */
83 MenuEnd_VotingCancelled = -2, /**< Voting was cancelled */
84 MenuEnd_Cancelled = -3, /**< Menu was cancelled (reason in param2) */
85 MenuEnd_Exit = -4, /**< Menu was cleanly exited via "exit" */
86 MenuEnd_ExitBack = -5, /**< Menu was cleanly exited via "back" */
90 * Describes a menu's source
94 MenuSource_None = 0, /**< No menu is being displayed */
95 MenuSource_External = 1, /**< External menu */
96 MenuSource_Normal = 2, /**< A basic menu is being displayed */
97 MenuSource_RawPanel = 3, /**< A display is active, but it is not tied to a menu */
101 * Called when a menu action is completed.
103 * @param menu The menu being acted upon.
104 * @param action The action of the menu.
105 * @param param1 First action parameter (usually the client).
106 * @param param2 Second action parameter (usually the item).
109 functag MenuHandler public(Handle:menu, MenuAction:action, param1, param2);
112 * Creates a new, empty menu using the default style.
114 * @param handler Function which will receive menu actions.
115 * @param actions Optionally set which actions to receive. Select,
116 * Cancel, and End will always be received regardless
117 * of whether they are set or not. They are also
118 * the only default actions.
119 * @return A new menu Handle.
121 native Handle:CreateMenu(MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
124 * Displays a menu to a client.
126 * @param menu Menu Handle.
127 * @param client Client index.
128 * @param time Maximum time to leave menu on the screen.
129 * @return True on success, false on failure.
130 * @error Invalid Handle or client not in game.
132 native bool:DisplayMenu(Handle:menu, client, time);
135 * Appends a new item to the end of a menu.
137 * @param menu Menu Handle.
138 * @param info Item information string.
139 * @param display Default item display string.
140 * @param style Drawing style flags.
141 * @return True on success, false on failure.
142 * @error Invalid Handle or item limit reached.
144 native AddMenuItem(Handle:menu,
146 const String:display[],
147 style=ITEMDRAW_DEFAULT);
150 * Inserts an item into the menu before a certain position; the new item will
151 * be at the given position and all next items pushed forward.
153 * @param menu Menu Handle.
154 * @param position Position, starting from 0.
155 * @param info Item information string.
156 * @param display Default item display string.
157 * @param style Drawing style flags.
158 * @return True on success, false on failure.
159 * @error Invalid Handle or menu position.
161 native bool:InsertMenuItem(Handle:menu,
164 const String:display[],
165 style=ITEMDRAW_DEFAULT);
168 * Removes an item from the menu.
170 * @param menu Menu Handle.
171 * @param position Position, starting from 0.
172 * @return True on success, false on failure.
173 * @error Invalid Handle or menu position.
175 native bool:RemoveMenuItem(Handle:menu, position);
178 * Removes all items from a menu.
180 * @param menu Menu Handle.
182 * @error Invalid Handle or menu position.
184 native RemoveAllMenuItems(Handle:menu);
187 * Retrieves information about a menu item.
189 * @param menu Menu Handle.
190 * @param position Position, starting from 0.
191 * @param infoBuf Info buffer.
192 * @param infoBufLen Maximum length of the info buffer.
193 * @param style By-reference variable to store drawing flags.
194 * @param dispBuf Display buffer.
195 * @param dispBufLen Maximum length of the display buffer.
196 * @return True on success, false if position is invalid.
197 * @error Invalid Handle.
199 native bool:GetMenuItem(Handle:menu, position, String:infoBuf[], infoBufLen, &style=0, String:dispBuf[]="", dispBufLen=0);
202 * Returns the number of items in a menu.
204 * @param menu Menu Handle.
205 * @return Number of items in the menu.
206 * @error Invalid Handle.
208 native GetMenuItemCount(Handle:menu);
211 * Sets whether the menu should be paginated or not.
213 * @param menu Handle to the menu.
214 * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION.
215 * @return True on success, false if pagination is too high or low.
216 * @error Invalid Handle.
218 native bool:SetMenuPagination(Handle:menu, itemsPerPage);
221 * Returns a menu's pagination setting.
223 * @param menu Handle to the menu.
224 * @return Pagination setting.
225 * @error Invalid Handle.
227 native GetMenuPagination(Handle:menu);
230 * Returns a menu's MenuStyle Handle. The Handle
231 * is global and cannot be freed.
233 * @param menu Handle to the menu.
234 * @return Handle to the menu's draw style.
235 * @error Invalid Handle.
237 native Handle:GetMenuStyle(Handle:menu);
240 * Sets the menu's default title/instruction message.
242 * @param menu Menu Handle.
243 * @param fmt Message string format
244 * @param ... Message string arguments.
246 * @error Invalid Handle.
248 native SetMenuTitle(Handle:menu, const String:fmt[], any:...);
251 * Creates a raw MenuPanel based off the menu's style.
252 * The Handle must be freed with CloseHandle().
254 * @return A new MenuPanel Handle.
255 * @error Invalid Handle.
257 native Handle:CreatePanelFromMenu(Handle:menu);
260 * Returns whether or not the menu has an exit button.
261 * By default, menus have an exit button.
263 * @param menu Menu Handle.
264 * @return True if the menu has an exit button; false otherwise.
265 * @error Invalid Handle.
267 native bool:GetMenuExitButton(Handle:menu);
270 * Sets whether or not the menu has an exit button.
271 * By default, menus have an exit button.
273 * @param menu Menu Handle.
274 * @param button True to enable the button, false to remove it.
275 * @return True if allowed; false on failure.
276 * @error Invalid Handle.
278 native bool:SetMenuExitButton(Handle:menu, bool:button);
281 * Returns whether or not the menu has an "exit back" button.
282 * By default, menus do not have an exit back button.
283 * Exit Back buttons appear as "Back" on page 1 of paginated menus and
284 * have functionality defined by the user in MenuEnd_ExitBack.
286 * @param menu Menu Handle.
287 * @return True if the menu has an exit back button; false otherwise.
288 * @error Invalid Handle.
290 native bool:GetMenuExitBackButton(Handle:menu);
293 * Sets whether or not the menu has an "exit back" button.
294 * By default, menus do not have an exit back button.
295 * Exit Back buttons appear as "Back" on page 1 of paginated menus and
296 * have functionality defined by the user in MenuEnd_ExitBack.
298 * @param menu Menu Handle.
299 * @param button True to enable the button, false to remove it.
300 * @error Invalid Handle.
302 native SetMenuExitBackButton(Handle:menu, bool:button);
306 * Cancels a menu from displaying on all clients. While the
307 * cancellation is in progress, this menu cannot be re-displayed
310 * The menu may still exist on the client's screen after this command.
311 * This simply verifies that the menu is not being used anywhere.
313 * If any vote is in progress on a menu, it will be cancelled.
315 * @param menu Menu Handle.
317 * @error Invalid Handle.
319 native CancelMenu(Handle:menu);
322 * Returns whether a vote is in progress on the given menu.
324 * @param menu Menu Handle.
325 * @return True if a vote is in progress, false otherwise.
327 native bool:IsVoteInProgress(Handle:menu);
330 * Broadcasts a menu to a list of clients. The most selected item will be
331 * returned through MenuAction_End. On a tie, a random item will be returned
332 * from a list of the tied items.
334 * Note that MenuAction_VoteEnd and MenuAction_VoteStart are both
335 * default callbacks and do not need to be enabled.
337 * @param menu Menu Handle.
338 * @param clients Array of clients to broadcast to.
339 * @param numClients Number of clients in the array.
340 * @param time Maximum time to leave menu on the screen.
341 * @return True on success, false if this menu already has a vote session
343 * @error Invalid Handle.
345 native bool:VoteMenu(Handle:menu, clients[], numClients, time);
348 * Sends a vote menu to all clients. See VoteMenu() for more information.
350 * @param menu Menu Handle.
351 * @param time Maximum time to leave menu on the screen.
352 * @return True on success, false if this menu already has a vote session
354 * @error Invalid Handle.
356 stock VoteMenuToAll(Handle:menu, time)
358 new num = GetMaxClients();
362 for (new i=1; i<=num; i++)
364 if (!IsClientInGame(i))
368 players[total++] = i;
371 return VoteMenu(menu, players, total, time);
375 * Returns a style's global Handle.
377 * @param style Menu Style.
378 * @return A Handle, or INVALID_HANDLE if not found or unusable.
380 native Handle:GetMenuStyleHandle(MenuStyle:style);
383 * Creates a MenuPanel from a MenuStyle. Panels are used for drawing raw
384 * menus without any extra helper functions. The Handle must be closed
385 * with CloseHandle().
387 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
388 * @return A new MenuPanel Handle.
389 * @error Invalid Handle other than INVALID_HANDLE.
391 native Handle:CreatePanel(Handle:hStyle=INVALID_HANDLE);
394 * Creates a Menu from a MenuStyle. The Handle must be closed with
397 * @parma hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
398 * @param handler Function which will receive menu actions.
399 * @param actions Optionally set which actions to receive. Select,
400 * Cancel, and End will always be received regardless
401 * of whether they are set or not. They are also
402 * the only default actions.
403 * @return A new menu Handle.
404 * @error Invalid Handle other than INVALID_HANDLE.
406 native Handle:CreateMenuEx(Handle:hStyle=INVALID_HANDLE, MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
409 * Returns whether a client is viewing a menu. If the menu source
410 * is MenuSource_Normal, a menu Handle will also be returned.
412 * @param client Client index.
413 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
414 * @return A MenuSource value.
415 * @error Invalid Handle other than INVALID_HANDLE.
417 native MenuSource:GetClientMenu(client, Handle:hStyle=INVALID_HANDLE);
420 * Cancels a menu on a client. This will only affect non-external menus.
422 * @param hstyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
423 * @param client Client index.
424 * @param autoIgnore If true, no menus can be re-drawn on the client during
425 * the cancellation process.
426 * @return True if a menu was cancelled, false otherwise.
428 native bool:CancelClientMenu(client, bool:autoIgnore=false, Handle:hStyle=INVALID_HANDLE);
431 * Returns a style's maximum items per page.
433 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
434 * @return Maximum items per page.
435 * @error Invalid Handle other than INVALID_HANDLE.
437 native GetMaxPageItems(Handle:hStyle=INVALID_HANDLE);
440 * Returns a MenuPanel's parent style.
442 * @param panel A MenuPanel Handle.
443 * @return The MenuStyle Handle that created the panel.
444 * @error Invalid Handle.
446 native Handle:GetPanelStyle(Handle:panel);
449 * Sets the panel's title.
451 * @param panel A MenuPanel Handle.
452 * @param title Text to set as the title.
453 * @param onlyIfEmpty If true, the title will only be set if no title is set.
455 * @error Invalid Handle.
457 native Handle:SetPanelTitle(Handle:panel, const String:text[], bool:onlyIfEmpty=false);
460 * Draws an item on a panel. If the item takes up a slot, the position
463 * @param panel A MenuPanel Handle.
464 * @param text Display text to use. If not a raw line,
465 * the style may automatically add color markup.
466 * No numbering or newlines are needed.
467 * @param style ITEMDRAW style flags.
468 * @return A slot position, or 0 if item was a rawline or could not be drawn.
469 * @error Invalid Handle.
471 native DrawPanelItem(Handle:panel, const String:text[], style=ITEMDRAW_DEFAULT);
474 * Draws a raw line of text on a panel, without any markup other than a newline.
476 * @param panel A MenuPanel Handle.
477 * @param text Display text to use.
478 * @return True on success, false if raw lines are not supported.
479 * @error Invalid Handle.
481 native DrawPanelText(Handle:panel, const String:text[]);
484 * Returns whether or not the given drawing flags are supported by
487 * @param panel A MenuPanel Handle.
488 * @param style ITEMDRAW style flags.
489 * @return True if item is drawable, false otherwise.
490 * @error Invalid Handle.
492 native CanPanelDrawFlags(Handle:panel, style);
495 * Sets the selectable key map of a panel. This is not supported by
496 * all styles (only by Radio, as of this writing).
498 * @param keys An integer where each bit N allows key
499 * N+1 to be selected. If no keys are selectable,
500 * then key 0 (bit 9) is automatically set.
501 * @return True if supported, false otherwise.
503 native bool:SetPanelKeys(Handle:panel, keys);
506 * Sends a panel to a client. Unlike full menus, the handler
507 * function will only receive the following actions, both of
508 * which will have INVALID_HANDLE for a menu, and the client
511 * MenuAction_Select (param2 will be the key pressed)
512 * MenuAction_Cancel (param2 will be the reason)
514 * Also, if the menu fails to display, no callbacks will be called.
516 * @param panel A MenuPanel Handle.
517 * @param client A client to draw to.
518 * @param handler The MenuHandler function to catch actions with.
519 * @param time Time to hold the menu for.
520 * @return True on success, false on failure.
521 * @error Invalid Handle.
523 native bool:SendPanelToClient(Handle:panel, client, MenuHandler:handler, time);
526 * @brief Returns the current key position.
528 * @param panel A MenuPanel Handle.
529 * @return Current key position starting at 1.
530 * @error Invalid Handle.
532 native GetPanelCurrentKey(Handle:panel);
535 * @brief Sets the next key position. This cannot be used
536 * to traverse backwards.
538 * @param panel A MenuPanel Handle.
539 * @param key Key that is greater or equal to
540 * GetPanelCurrentKey().
541 * @return True on success, false otherwise.
542 * @error Invalid Handle.
544 native bool:SetPanelCurrentKey(Handle:panel, key);
547 * Retrieves voting information from MenuAction_VoteEnd.
549 * @param param2 Second parameter of MenuAction_VoteEnd.
550 * @param winningVotes Number of votes received by the winning option.
551 * @param totalVotes Number of total votes received.
554 stock GetMenuVoteInfo(param2, &winningVotes, &totalVotes)
556 winningVotes = param2 & 0xFFFF;
557 totalVotes = param2 >> 16;
