AMXX-BG.INFO › newmenus.inc › Raw include

newmenus.inc

Original include source with line numbers.

Back Download .inc
1 // vim: set ts=4 sw=4 tw=99 noet:
2 //
3 // AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO").
4 // Copyright (C) The AMX Mod X Development Team.
5 //
6 // This software is licensed under the GNU General Public License, version 3 or higher.
7 // Additional exceptions apply. For full license details, see LICENSE.txt or visit:
8 // https://alliedmods.net/amxmodx-license
9
10 #if defined _newmenus_included
11 #endinput
12 #endif
13 #define _newmenus_included
14
15 /**
16 * @section Menu properties for using in menu_setprop
17 */
18
19 /**
20 * Menu will have an exit option (default)
21 */
22 #define MEXIT_ALL 1
23
24 /**
25 * Menu will have an exit option, even when pagination is disabled.
26 * There have to be less than 10 items in the menu or it won't appear. The exit
27 * option will be appended to the last item with no extra slot padding. If you
28 * want it in the 10th slot you have to pad it manually with menu_addblank2
29 */
30 #define MEXIT_FORCE 2
31
32 /**
33 * Menu will not have an exit option
34 */
35 #define MEXIT_NEVER -1
36
37 /**
38 * Number of items per page (param1 = number, 0=no paginating, 7=default)
39 */
40 #define MPROP_PERPAGE 1
41
42 /**
43 * Name of the back button (param1 = string)
44 */
45 #define MPROP_BACKNAME 2
46
47 /**
48 * Name of the next button (param1 = string)
49 */
50 #define MPROP_NEXTNAME 3
51
52 /**
53 * Name of the exit button (param1 = string)
54 */
55 #define MPROP_EXITNAME 4
56
57 /**
58 * Menu title text (param1 = string)
59 */
60 #define MPROP_TITLE 5
61
62 /**
63 * Exit functionality (param1 = number, see MEXIT constants)
64 */
65 #define MPROP_EXIT 6
66
67 /**
68 * Sets whether colors are not auto (param1 = number, 0=default)
69 */
70 #define MPROP_NOCOLORS 8
71
72 /**
73 * Color indicator to use for numbers (param1 = string, "\r"=default)
74 */
75 #define MPROP_NUMBER_COLOR 10
76
77 /**
78 * Function to be called on Back and Next (param1 = string)
79 * public function(id, status, menu); where status is either MENU_BACK or MENU_MORE
80 * Pass NULL_STRING to disable the callback
81 */
82 #define MPROP_PAGE_CALLBACK 11
83
84 /**
85 * Whether to show the page number in menu title (param1 = bool, true = default)
86 */
87 #define MPROP_SHOWPAGE 12
88
89 /**
90 * @deprecated
91 */
92 #define MEXIT_NORMAL 0 /* DEPRECATED, do not use (has no effect) */
93 #define MENUPAD_NONE 0 /* DEPRECATED, do not use (has no effect) */
94 #define MENUPAD_PAGE 1 /* DEPRECATED, do not use (has no effect) */
95 #define MPROP_ORDER 7 /* DEPRECATED, do not use (has no effect) */
96 #define MPROP_PADMENU 9 /* DEPRECATED, do not use (has no effect) */
97
98 /** @endsection */
99
100 /**
101 * Creates a new menu object.
102 *
103 * @note The handler function should be prototyped as:
104 *
105 * public <function>(id, menu, item)
106 * id - Client the menu is being acted upon.
107 * menu - Menu resource identifier.
108 * item - Item the client selected. If less than 0, the menu was
109 * cancelled and the item is a status code. menu_display
110 * should never be called immediately if the item is a status
111 * code, for re-entrancy reasons.
112 *
113 * @note The handler function should always return PLUGIN_HANDLED to block
114 * any old menu handlers from potentially feeding on the menu, unless
115 * that is the desired functionality.
116 *
117 * @param title Title the menu should use.
118 * @param handler Name of the handler function. The function will be invoked
119 * once and only once to every menu_display() call.
120 * @param ml If true, the menu title and items will be looked up as multilingual keys
121 * when the menu displays.
122 * @return Menu resource identifier which must be destroyed via
123 * menu_destroy(). All menus are destroyed when the plugin
124 * unloads.
125 * @error Function name not found.
126 */
127 native menu_create(const title[], const handler[], bool:ml = false);
128
129 /**
130 * Creates a menu item callback handler.
131 *
132 * @note The handler function should be prototyped as:
133 *
134 * public <function>(id, menu, item)
135 * id - Client index being displayed to.
136 * menu - Menu resource identifier.
137 * item - Item being drawn.
138 * <return> - ITEM_IGNORE to use the default functionality.
139 * ITEM_ENABLED to explicitly enable or ITEM_DISABLED to explicitly disable.
140 *
141 * @param function Function name.
142 * @return Menu callback ID.
143 */
144 native menu_makecallback(const function[]);
145
146 /**
147 * Adds an item to a menu.
148 *
149 * @param menu Menu resource identifier.
150 * @param name Item text to display.
151 * @param info Item info string for internal information.
152 * @param paccess Access required by the player viewing the menu.
153 * @param callback If set to a valid ID from menu_makecallback(), the
154 * callback will be invoked before drawing the item.
155 * @noreturn
156 * @error Invalid menu resource.
157 */
158 native menu_additem(menu, const name[], const info[]="", paccess=0, callback=-1);
159
160 /**
161 * Returns the number of pages in a menu.
162 *
163 * @param menu Menu resource identifier.
164 * @return Number of pages in the menu.
165 * @error Invalid menu resource.
166 */
167 native menu_pages(menu);
168
169 /**
170 * Returns the number of items in a menu.
171 *
172 * @param menu Menu resource identifier.
173 * @return Number of items in the menu.
174 * @error Invalid menu resource.
175 */
176 native menu_items(menu);
177
178 /**
179 * Displays a menu to one client. This should never be called from a handler
180 * when the item is less than 0 (i.e. calling this from a cancelled menu will
181 * result in an error).
182 *
183 * Starting with 1.8.3 this allows to specify a menu timeout similar to the
184 * show_menu native. If the menu exists on the client past the timeout *any*
185 * further action will send the MENU_TIMEOUT status code to the menu handler.
186 * That includes actions which would otherwise send MENU_EXIT, such as the
187 * client selecting an item or disconnecting and calling menu_cancel or
188 * menu_destroy on a live menu.
189 *
190 * @param id Client index.
191 * @param menu Menu resource identifier.
192 * @param page Page to start from (starting from 0).
193 * @param time If >=0 menu will timeout after this many seconds
194 * @noreturn
195 * @error Invalid menu resource or client index.
196 */
197 native menu_display(id, menu, page=0, time=-1);
198
199 /**
200 * Given a page on a menu and a keypress on that page, returns the item id selected.
201 * If the item is less than 0, a special option was chosen (such as MENU_EXIT).
202 *
203 * @param menu Menu resource identifier.
204 * @param page Page on the menu.
205 * @param key Key pressed (from 1 to 10).
206 * @return Item identifier, or <0 for a special selection code.
207 * @error Invalid menu resource.
208 */
209 native menu_find_id(menu, page, key);
210
211 /**
212 * Retrieves info about a menu item.
213 *
214 * @param menu Menu resource identifier.
215 * @param item Item identifier.
216 * @param access Variable to store access value.
217 * @param info Buffer to store item info.
218 * @param infolen Item info buffer length.
219 * @param name Buffer to store item display text.
220 * @param namelen Item name buffer length.
221 * @param callback Callback ID.
222 * @return 1 on success, 0 on failure.
223 * @error Invalid menu resource.
224 */
225 native menu_item_getinfo(menu, item, &access = 0, info[] = "", infolen = 0, name[]="", namelen=0, &callback = 0);
226
227 /**
228 * Sets an item's display text.
229 *
230 * @param menu Menu resource identifier.
231 * @param item Item identifier.
232 * @param name New item display text.
233 * @return 1 on success, 0 on failure.
234 * @error Invalid menu resource.
235 */
236 native menu_item_setname(menu, item, const name[]);
237
238 /**
239 * Sets an item's info string.
240 *
241 * @param menu Menu resource identifier.
242 * @param item Item identifier.
243 * @param info New item info string.
244 * @return 1 on success, 0 on failure.
245 * @error Invalid menu resource.
246 */
247 native menu_item_setcmd(menu, item, const info[]);
248
249 /**
250 * Sets an item's callback.
251 *
252 * @param menu Menu resource identifier.
253 * @param item Item identifier.
254 * @param callback New callback from menu_makecallback(), or -1 to clear.
255 * @return 1 on success, 0 on failure.
256 * @error Invalid menu resource.
257 */
258 native menu_item_setcall(menu, item, callback=-1);
259
260 /**
261 * Sets an item's access.
262 *
263 * @param menu Menu resource identifier.
264 * @param item Item identifier.
265 * @param access New access required by the player for access to the item.
266 * @return 1 on success, 0 on failure.
267 * @error Invalid menu resource.
268 */
269 native menu_item_setaccess(menu, item, access=0);
270
271 /**
272 * Destroys a menu. Player menus will be cancelled (although may still linger
273 * on the HUD), and future attempts to access the menu resource will result in
274 * an error.
275 *
276 * This must be called if you create menus dynamically, otherwise you will
277 * leak memory. For normal dynamic menus, you will destroy the menu in the
278 * handler function (remembering to handle the case of a menu being cancelled,
279 * it must still be destroyed).
280 *
281 * @param menu Menu resource identifier.
282 * @noreturn
283 * @error Invalid menu resource.
284 */
285 native menu_destroy(menu);
286
287 /**
288 * Returns information about a menu (if any) the client is currently viewing.
289 *
290 * @note If newmenu is valid, then the menu will refer to the menuid associated with
291 * the title. If newmenu is not valid, and the menu is valid, then the player
292 * is viewing a menu displayed with show_menu().
293 *
294 * @note Both may be invalid if the player is not viewing a menu.
295 *
296 * @param id Client index.
297 * @param menu Variable to store old menu id. If none, then <1 will be
298 * stored.
299 * @param newmenu Variable to store new menu id. If none, then -1 will be
300 * stored.
301 * @param menupage Variable to store current page of the new menu, if any.
302 * @return 1 if the player is viewing a menu, 0 otherwise.
303 * @error Invalid client.
304 */
305 native player_menu_info(id, &menu, &newmenu, &menupage=0);
306
307 /**
308 * Adds a blank line to a menu.
309 *
310 * @note When using slot=1 this might break your menu. To achieve this functionality
311 * menu_addblank2 should be used.
312 *
313 * @param menu Menu resource identifier.
314 * @param slot 1 (default) if the line should shift the numbering down.
315 * 0 if the line should be a visual shift only.
316 * @noreturn
317 * @error Invalid menu resource.
318 */
319 native menu_addblank(menu, slot=1);
320
321 /**
322 * Adds a text line to a menu.
323 *
324 * @note When using slot=1 this might break your menu. To achieve this functionality
325 * menu_addtext2 should be used.
326 *
327 * @param menu Menu resource identifier.
328 * @param text Text to add.
329 * @param slot 1 (default) if the line should shift the numbering down.
330 * 0 if the line should be a visual shift only.
331 * @noreturn
332 * @error Invalid menu resource.
333 */
334 native menu_addtext(menu, const text[], slot=1);
335
336 /**
337 * Adds a blank line to a menu, always shifting the numbering down.
338 *
339 * @note This will add a special item to create a blank line. It will affect the menu
340 * item count and pagination. These items can be modified later but will ignore
341 * access and item callback results.
342 *
343 * @param menu Menu resource identifier.
344 *
345 * @return 1 on success, 0 on failure.
346 * @error Invalid menu resource.
347 * Too many items on non-paginated menu (max is 10)
348 */
349 native menu_addblank2( menu );
350
351 /**
352 * Adds a text line to a menu, always shifting the numbering down.
353 *
354 * @note This will add a special item to create a blank line. It will affect the menu
355 * item count and pagination. These items can be modified later but will ignore
356 * access and item callback results.
357 *
358 * @param menu Menu resource identifier.
359 * @param text Text to add.
360 *
361 * @return 1 on success, 0 on failure.
362 * @error Invalid menu resource.
363 * Too many items on non-paginated menu (max is 10)
364 */
365 native menu_addtext2( menu, const text[] );
366
367 /**
368 * Sets a menu property.
369 *
370 * @param menu Menu resource identifier.
371 * @param prop MPROP_ constant.
372 * @param ... Property parameters.
373 * @return 1 on success, 0 on failure.
374 * @error Invalid menu resource or property.
375 */
376 native menu_setprop(menu, prop, ...);
377
378 /**
379 * Cancels a player's menu, effectively forcing the player to select MENU_EXIT.
380 * The menu will still exist on their screen but any results are invalidated,
381 * and the callback is invoked.
382 *
383 * @param player Client index.
384 * @noreturn
385 * @error Invalid client index.
386 */
387 native menu_cancel(player);
388