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's display/selection cycle is complete (nothing passed). */
41 MenuAction_VoteEnd = (1<<5), /**< (VOTE ONLY): A vote sequence has ended (param1=chosen item) */
42 MenuAction_VoteStart = (1<<6), /**< (VOTE ONLY): A vote sequence has started */
45 /** Default menu actions */
46 #define MENU_ACTIONS_DEFAULT MenuAction_Select|MenuAction_Cancel|MenuAction_End
47 /** All menu actions */
48 #define MENU_ACTIONS_ALL -1
50 #define MENU_NO_PAGINATION 0 /**< Menu should not be paginated (10 items max) */
51 #define MENU_TIME_FOREVER 0 /**< Menu should be displayed as long as possible */
53 #define ITEMDRAW_DEFAULT (0) /**< Item should be drawn normally */
54 #define ITEMDRAW_DISABLED (1<<0) /**< Item is drawn but not selectable */
55 #define ITEMDRAW_RAWLINE (1<<1) /**< Item should be a raw line, without a slot */
56 #define ITEMDRAW_NOTEXT (1<<2) /**< No text should be drawn */
57 #define ITEMDRAW_SPACER (1<<3) /**< Item should be drawn as a spacer, if possible */
58 #define ITEMDRAW_IGNORE ((1<<1)|(1<<2)) /**< Item should be completely ignored (rawline + notext) */
59 #define ITEMDRAW_CONTROL (1<<4) /**< Item is control text (back/next/exit) */
62 * Reasons a menu can be cancelled.
66 MenuCancel_Disconnect = -1, /**< Client dropped from the server */
67 MenuCancel_Interrupt = -2, /**< Client was interrupted with another menu */
68 MenuCancel_Exit = -3, /**< Client selected "exit" on a paginated menu */
69 MenuCancel_NoDisplay = -4, /**< Menu could not be displayed to the client */
73 * Describes a menu's source
77 MenuSource_None = 0, /**< No menu is being displayed */
78 MenuSource_External = 1, /**< External menu */
79 MenuSource_Normal = 2, /**< A basic menu is being displayed */
80 MenuSource_RawPanel = 3, /**< A display is active, but it is not tied to a menu */
84 * Called when a menu action is completed.
86 * @param menu The menu being acted upon.
87 * @param action The action of the menu.
88 * @param param1 First action parameter (usually the client).
89 * @param param2 Second action parameter (usually the item).
92 functag MenuHandler public(Handle:menu, MenuAction:action, param1, param2);
95 * Creates a new, empty menu using the default style.
97 * @param handler Function which will receive menu actions.
98 * @param actions Optionally set which actions to receive. Select,
99 * Cancel, and End will always be received regardless
100 * of whether they are set or not. They are also
101 * the only default actions.
102 * @return A new menu Handle.
104 native Handle:CreateMenu(MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
107 * Displays a menu to a client.
109 * @param menu Menu Handle.
110 * @param client Client index.
111 * @param time Maximum time to leave menu on the screen.
112 * @return True on success, false on failure.
113 * @error Invalid Handle or client not in game.
115 native bool:DisplayMenu(Handle:menu, client, time);
118 * Appends a new item to the end of a menu.
120 * @param menu Menu Handle.
121 * @param info Item information string.
122 * @param display Default item display string.
123 * @param style Drawing style flags.
124 * @return True on success, false on failure.
125 * @error Invalid Handle or item limit reached.
127 native AddMenuItem(Handle:menu,
129 const String:display[],
130 style=ITEMDRAW_DEFAULT);
133 * Inserts an item into the menu before a certain position; the new item will
134 * be at the given position and all next items pushed forward.
136 * @param menu Menu Handle.
137 * @param position Position, starting from 0.
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 menu position.
144 native bool:InsertMenuItem(Handle:menu,
147 const String:display[],
148 style=ITEMDRAW_DEFAULT);
151 * Removes an item from the menu.
153 * @param menu Menu Handle.
154 * @param position Position, starting from 0.
155 * @return True on success, false on failure.
156 * @error Invalid Handle or menu position.
158 native bool:RemoveMenuItem(Handle:menu, position);
161 * Removes all items from a menu.
163 * @param menu Menu Handle.
165 * @error Invalid Handle or menu position.
167 native RemoveAllMenuItems(Handle:menu);
170 * Retrieves information about a menu item.
172 * @param menu Menu Handle.
173 * @param position Position, starting from 0.
174 * @param infoBuf Info buffer.
175 * @param infoBufLen Maximum length of the info buffer.
176 * @param style By-reference variable to store drawing flags.
177 * @param dispBuf Display buffer.
178 * @param dispBufLen Maximum length of the display buffer.
179 * @return True on success, false if position is invalid.
180 * @error Invalid Handle.
182 native bool:GetMenuItem(Handle:menu, position, String:infoBuf[], infoBufLen, &style=0, String:dispBuf[]="", dispBufLen=0);
185 * Returns the number of items in a menu.
187 * @param menu Menu Handle.
188 * @return Number of items in the menu.
189 * @error Invalid Handle.
191 native GetMenuItemCount(Handle:menu);
194 * Sets whether the menu should be paginated or not.
196 * @param menu Handle to the menu.
197 * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION.
198 * @return True on success, false if pagination is too high or low.
199 * @error Invalid Handle.
201 native bool:SetMenuPagination(Handle:menu, itemsPerPage);
204 * Returns a menu's pagination setting.
206 * @param menu Handle to the menu.
207 * @return Pagination setting.
208 * @error Invalid Handle.
210 native GetMenuPagination(Handle:menu);
213 * Returns a menu's MenuStyle Handle. The Handle
214 * is global and cannot be freed.
216 * @param menu Handle to the menu.
217 * @return Handle to the menu's draw style.
218 * @error Invalid Handle.
220 native Handle:GetMenuStyle(Handle:menu);
223 * Sets the menu's default title/instruction message.
225 * @param menu Menu Handle.
226 * @param fmt Message string format
227 * @param ... Message string arguments.
229 * @error Invalid Handle.
231 native SetMenuTitle(Handle:menu, const String:fmt[], any:...);
234 * Creates a raw MenuPanel based off the menu's style.
235 * The Handle must be freed with CloseHandle().
237 * @return A new MenuPanel Handle.
238 * @error Invalid Handle.
240 native Handle:CreatePanelFromMenu(Handle:menu);
243 * Returns whether or not the menu has an exit button.
244 * By default, menus have an exit button.
246 * @param menu Menu Handle.
247 * @return True if the menu has an exit button; false otherwise.
248 * @error Invalid Handle.
250 native bool:GetMenuExitButton(Handle:menu);
253 * Sets whether or not the menu has an exit button.
254 * By default, menus have an exit button.
256 * @param menu Menu Handle.
257 * @param button True to enable the button, false to remove it.
258 * @return True if allowed; false on failure.
259 * @error Invalid Handle.
261 native bool:SetMenuExitButton(Handle:menu, bool:button);
264 * Cancels a menu from displaying on all clients. While the
265 * cancellation is in progress, this menu cannot be re-displayed
268 * The menu may still exist on the client's screen after this command.
269 * This simply verifies that the menu is not being used anywhere.
271 * @param menu Menu Handle.
273 * @error Invalid Handle.
275 native CancelMenu(Handle:menu);
278 * Broadcasts a menu to a list of clients. The most selected item will be
279 * returned through MenuAction_End. On a tie, a random item will be returned
280 * from a list of the tied items.
282 * Note that MenuAction_VoteEnd and MenuAction_VoteStart are both
283 * default callbacks and do not need to be enabled.
285 * @param menu Menu Handle.
286 * @param clients Array of clients to broadcast to.
287 * @param numClients Number of clients in the array.
288 * @param time Maximum time to leave menu on the screen.
289 * @return True on success, false if this menu already has a vote session
291 * @error Invalid Handle.
293 native bool:VoteMenu(Handle:menu, clients[], numClients, time);
296 * Sends a vote menu to all clients. See VoteMenu() for more information.
298 * @param menu Menu Handle.
299 * @param time Maximum time to leave menu on the screen.
300 * @return True on success, false if this menu already has a vote session
302 * @error Invalid Handle.
304 stock VoteMenuToAll(Handle:menu, time)
306 new num = GetMaxClients();
310 for (new i=1; i<=num; i++)
312 if (!IsClientConnected(i))
316 players[total++] = i;
319 return VoteMenu(menu, players, total, time);
323 * Returns a style's global Handle.
325 * @param style Menu Style.
326 * @return A Handle, or INVALID_HANDLE if not found or unusable.
328 native Handle:GetMenuStyleHandle(MenuStyle:style);
331 * Creates a MenuPanel from a MenuStyle. Panels are used for drawing raw
332 * menus without any extra helper functions. The Handle must be closed
333 * with CloseHandle().
335 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
336 * @return A new MenuPanel Handle.
337 * @error Invalid Handle other than INVALID_HANDLE.
339 native Handle:CreatePanel(Handle:hStyle=INVALID_HANDLE);
342 * Creates a Menu from a MenuStyle. The Handle must be closed with
345 * @parma hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
346 * @param handler Function which will receive menu actions.
347 * @param actions Optionally set which actions to receive. Select,
348 * Cancel, and End will always be received regardless
349 * of whether they are set or not. They are also
350 * the only default actions.
351 * @return A new menu Handle.
352 * @error Invalid Handle other than INVALID_HANDLE.
354 native Handle:CreateMenuEx(Handle:hStyle=INVALID_HANDLE, MenuHandler:handler, MenuAction:actions=MENU_ACTIONS_DEFAULT);
357 * Returns whether a client is viewing a menu. If the menu source
358 * is MenuSource_Normal, a menu Handle will also be returned.
360 * @param client Client index.
361 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
362 * @return A MenuSource value.
363 * @error Invalid Handle other than INVALID_HANDLE.
365 native MenuSource:GetClientMenu(client, Handle:hStyle=INVALID_HANDLE);
368 * Cancels a menu on a client. This will only affect non-external menus.
370 * @param hstyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
371 * @param client Client index.
372 * @param autoIgnore If true, no menus can be re-drawn on the client during
373 * the cancellation process.
374 * @return True if a menu was cancelled, false otherwise.
376 native bool:CancelClientMenu(client, bool:autoIgnore=false, Handle:hStyle=INVALID_HANDLE);
379 * Returns a style's maximum items per page.
381 * @param hStyle MenuStyle Handle, or INVALID_HANDLE to use the default style.
382 * @return Maximum items per page.
383 * @error Invalid Handle other than INVALID_HANDLE.
385 native GetMaxPageItems(Handle:hStyle=INVALID_HANDLE);
388 * Returns a MenuPanel's parent style.
390 * @param panel A MenuPanel Handle.
391 * @return The MenuStyle Handle that created the panel.
392 * @error Invalid Handle.
394 native Handle:GetPanelStyle(Handle:panel);
397 * Sets the panel's title.
399 * @param panel A MenuPanel Handle.
400 * @param title Text to set as the title.
401 * @param onlyIfEmpty If true, the title will only be set if no title is set.
403 * @error Invalid Handle.
405 native Handle:SetPanelTitle(Handle:panel, const String:text[], bool:onlyIfEmpty=false);
408 * Draws an item on a panel. If the item takes up a slot, the position
411 * @param panel A MenuPanel Handle.
412 * @param text Display text to use. If not a raw line,
413 * the style may automatically add color markup.
414 * No numbering or newlines are needed.
415 * @param style ITEMDRAW style flags.
416 * @return A slot position, or 0 if item was a rawline or could not be drawn.
417 * @error Invalid Handle.
419 native DrawPanelItem(Handle:panel, const String:text[], style=ITEMDRAW_DEFAULT);
422 * Draws a raw line of text on a panel, without any markup other than a newline.
424 * @param panel A MenuPanel Handle.
425 * @param text Display text to use.
426 * @return True on success, false if raw lines are not supported.
427 * @error Invalid Handle.
429 native DrawPanelText(Handle:panel, const String:text[]);
432 * Returns whether or not the given drawing flags are supported by
435 * @param panel A MenuPanel Handle.
436 * @param style ITEMDRAW style flags.
437 * @return True if item is drawable, false otherwise.
438 * @error Invalid Handle.
440 native CanPanelDrawFlags(Handle:panel, style);
443 * Sets the selectable key map of a panel. This is not supported by
444 * all styles (only by Radio, as of this writing).
446 * @param keys An integer where each bit N allows key
447 * N+1 to be selected. If no keys are selectable,
448 * then key 0 (bit 9) is automatically set.
449 * @return True if supported, false otherwise.
451 native bool:SetPanelKeys(Handle:panel, keys);
454 * Sends a panel to a client. Unlike full menus, the handler
455 * function will only receive the following actions, both of
456 * which will have INVALID_HANDLE for a menu, and the client
459 * MenuAction_Select (param2 will be the key pressed)
460 * MenuAction_Cancel (param2 will be the reason)
462 * Also, if the menu fails to display, no callbacks will be called.
464 * @param panel A MenuPanel Handle.
465 * @param client A client to draw to.
466 * @param handler The MenuHandler function to catch actions with.
467 * @param time Time to hold the menu for.
468 * @return True on success, false on failure.
469 * @error Invalid Handle.
471 native bool:SendPanelToClient(Handle:panel, client, MenuHandler:handler, time);
474 * @brief Returns the current key position.
476 * @param panel A MenuPanel Handle.
477 * @return Current key position starting at 1.
478 * @error Invalid Handle.
480 native GetPanelCurrentKey(Handle:panel);
483 * @brief Sets the next key position. This cannot be used
484 * to traverse backwards.
486 * @param panel A MenuPanel Handle.
487 * @param key Key that is greater or equal to
488 * GetPanelCurrentKey().
489 * @return True on success, false otherwise.
490 * @error Invalid Handle.
492 native bool:SetPanelCurrentKey(Handle:panel, key);
