00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id$ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_ 00033 #define _INCLUDE_SOURCEMOD_MENU_SYSTEM_H_ 00034 00035 #include <IShareSys.h> 00036 #include <IHandleSys.h> 00037 00038 #define SMINTERFACE_MENUMANAGER_NAME "IMenuManager" 00039 #define SMINTERFACE_MENUMANAGER_VERSION 16 00040 00041 /** 00042 * @file IMenuManager.h 00043 * @brief Abstracts on-screen menus for clients. 00044 */ 00045 00046 namespace SourceMod 00047 { 00048 /** 00049 * @brief Used to determine how an item selection is interpreted. 00050 */ 00051 enum ItemSelection 00052 { 00053 ItemSel_None, /**< Invalid selection */ 00054 ItemSel_Back, /**< Go back one page (really "Previous") */ 00055 ItemSel_Next, /**< Go forward one page */ 00056 ItemSel_Exit, /**< Menu was exited */ 00057 ItemSel_Item, /**< Valid item selection */ 00058 ItemSel_ExitBack, /**< Sends MenuEnd_ExitBack */ 00059 }; 00060 00061 /** 00062 * @brief Used to determine which order to search for items in. 00063 */ 00064 enum ItemOrder 00065 { 00066 ItemOrder_Ascending, /**< Items should be drawn ascendingly */ 00067 ItemOrder_Descending, /**< Items should be drawn descendingly */ 00068 }; 00069 00070 /** 00071 * @brief Pairs an item type with an item menu position. 00072 */ 00073 struct menu_slots_t 00074 { 00075 ItemSelection type; /**< Item selection type */ 00076 unsigned int item; /**< Item position, if applicable */ 00077 }; 00078 00079 class IBaseMenu; 00080 class IMenuPanel; 00081 class IMenuHandler; 00082 00083 /** 00084 * @brief Describes menu display information. 00085 */ 00086 struct menu_states_t 00087 { 00088 unsigned int apiVers; /**< Must be filled with the API version */ 00089 IBaseMenu *menu; /**< Menu pointer, or NULL if there is only a display */ 00090 IMenuHandler *mh; /**< Menu callbacks handler */ 00091 unsigned int firstItem; /**< MENU ONLY: First item displayed on the last page */ 00092 unsigned int lastItem; /**< MENU ONLY: Last item displayed on the last page */ 00093 unsigned int item_on_page; /**< MENU ONLY: First item on page */ 00094 menu_slots_t slots[11]; /**< MENU ONLY: Item selection table (first index is 1) */ 00095 }; 00096 00097 #define ITEMDRAW_DEFAULT (0) /**< Item should be drawn normally */ 00098 #define ITEMDRAW_DISABLED (1<<0) /**< Item is drawn but not selectable */ 00099 #define ITEMDRAW_RAWLINE (1<<1) /**< Item should be a raw line, without a slot */ 00100 #define ITEMDRAW_NOTEXT (1<<2) /**< No text should be drawn */ 00101 #define ITEMDRAW_SPACER (1<<3) /**< Item should be drawn as a spacer, if possible */ 00102 #define ITEMDRAW_IGNORE ((1<<1)|(1<<2)) /**< Item should be completely ignored (rawline + notext) */ 00103 #define ITEMDRAW_CONTROL (1<<4) /**< Item is control text (back/next/exit) */ 00104 00105 /** 00106 * @brief Information about item drawing. 00107 */ 00108 struct ItemDrawInfo 00109 { 00110 ItemDrawInfo(const char *DISPLAY=NULL, unsigned int STYLE=ITEMDRAW_DEFAULT, 00111 unsigned int FLAGS=0, const char *HELPTEXT=NULL) 00112 : display(DISPLAY), style(STYLE) 00113 { 00114 } 00115 const char *display; /**< Display text (NULL for none) */ 00116 unsigned int style; /**< ITEMDRAW style flags */ 00117 }; 00118 00119 /** 00120 * @brief Contains information about a vote result. 00121 */ 00122 struct menu_vote_result_t 00123 { 00124 unsigned int num_clients; /**< Number of clients the menu was displayed to */ 00125 unsigned int num_votes; /**< Number of votes received */ 00126 struct menu_client_vote_t 00127 { 00128 int client; /**< Client index */ 00129 int item; /**< Item # (or -1 for none) */ 00130 } *client_list; /**< Array of size num_clients */ 00131 unsigned int num_items; /**< Number of items voted for */ 00132 struct menu_item_vote_t 00133 { 00134 unsigned int item; /**< Item index */ 00135 unsigned int count; /**< Number of votes */ 00136 } *item_list; /**< Array of size num_items, sorted by count, 00137 descending */ 00138 }; 00139 00140 /** 00141 * @brief Reasons for a menu dying. 00142 */ 00143 enum MenuCancelReason 00144 { 00145 MenuCancel_Disconnected = -1, /**< Client dropped from the server */ 00146 MenuCancel_Interrupted = -2, /**< Client was interrupted with another menu */ 00147 MenuCancel_Exit = -3, /**< Client selected "exit" on a paginated menu */ 00148 MenuCancel_NoDisplay = -4, /**< Menu could not be displayed to the client */ 00149 MenuCancel_Timeout = -5, /**< Menu timed out */ 00150 MenuCancel_ExitBack = -6, /**< Client selected "exit back" on a paginated menu */ 00151 }; 00152 00153 /** 00154 * @brief Reasons a menu ended. 00155 */ 00156 enum MenuEndReason 00157 { 00158 MenuEnd_Selected = 0, /**< Menu item was selected */ 00159 MenuEnd_VotingDone = -1, /**< Voting finished */ 00160 MenuEnd_VotingCancelled = -2, /**< Voting was cancelled */ 00161 MenuEnd_Cancelled = -3, /**< Menu was uncleanly cancelled */ 00162 MenuEnd_Exit = -4, /**< Menu was cleanly exited via "exit" */ 00163 MenuEnd_ExitBack = -5, /**< Menu was cleanly exited via "back" */ 00164 }; 00165 00166 /** 00167 * @brief Reasons a vote can be cancelled. 00168 */ 00169 enum VoteCancelReason 00170 { 00171 VoteCancel_Generic = -1, /**< Vote was generically cancelled. */ 00172 VoteCancel_NoVotes = -2, /**< Vote did not receive any votes. */ 00173 }; 00174 00175 #define MENU_NO_PAGINATION 0 /**< Menu should not be paginated (10 items max) */ 00176 #define MENU_TIME_FOREVER 0 /**< Menu should be displayed as long as possible */ 00177 00178 #define MENUFLAG_BUTTON_EXIT (1<<0) /**< Menu has an "exit" button */ 00179 #define MENUFLAG_BUTTON_EXITBACK (1<<1) /**< Menu has an "exit back" button */ 00180 #define MENUFLAG_NO_SOUND (1<<2) /**< Menu will not have any select sounds */ 00181 #define MENUFLAG_BUTTON_NOVOTE (1<<3) /**< Menu has a "No Vote" button at slot 1 */ 00182 00183 #define VOTEFLAG_NO_REVOTES (1<<0) /**< Players cannot change their votes */ 00184 00185 /** 00186 * @brief Extended menu options. 00187 */ 00188 enum MenuOption 00189 { 00190 MenuOption_IntroMessage, /**< CONST CHAR *: Valve menus only; defaults to: 00191 "You have a menu, hit ESC" 00192 */ 00193 MenuOption_IntroColor, /**< INT[4]: Valve menus only; specifies the intro message colour 00194 using R,G,B,A (defaults to 255,0,0,255) 00195 */ 00196 MenuOption_Priority, /**< INT *: Valve menus only; priority (less is higher) */ 00197 }; 00198 00199 /** 00200 * @brief Describes the menu a player is viewing. 00201 */ 00202 enum MenuSource 00203 { 00204 MenuSource_None = 0, /**< No menu is being displayed */ 00205 MenuSource_External = 1, /**< External menu, no pointer */ 00206 MenuSource_BaseMenu = 2, /**< An IBaseMenu pointer. */ 00207 MenuSource_Display = 3, /**< IMenuPanel source, no pointer */ 00208 }; 00209 00210 class IMenuStyle; 00211 00212 /** 00213 * @brief Sets how a raw menu should be drawn. 00214 */ 00215 class IMenuPanel 00216 { 00217 public: 00218 /** 00219 * @brief Returns the parent IMenuStyle pointer. 00220 * 00221 * @return IMenuStyle pointer which created 00222 * this object. 00223 */ 00224 virtual IMenuStyle *GetParentStyle() =0; 00225 00226 /** 00227 * @brief Resets/clears the cached display text. 00228 */ 00229 virtual void Reset() =0; 00230 00231 /** 00232 * @brief Sets how the title should be drawn. 00233 * 00234 * @param text Text string to display for the title. 00235 * @param onlyIfEmpty Only sets the title if one does not already 00236 * exist. 00237 */ 00238 virtual void DrawTitle(const char *text, bool onlyIfEmpty=false) =0; 00239 00240 /** 00241 * @brief Adds an item to the menu and returns the position (1-10). 00242 * 00243 * Note: Item will fail to draw if there are too many items, 00244 * or the item is not drawable (for example, invisible). 00245 * 00246 * @return Item draw position, or 0 on failure. 00247 */ 00248 virtual unsigned int DrawItem(const ItemDrawInfo &item) =0; 00249 00250 /** 00251 * @brief Draws a raw line of text, if supported. The line does not 00252 * need to be newline terminated. 00253 * 00254 * @return True on success, false if not supported. 00255 */ 00256 virtual bool DrawRawLine(const char *rawline) =0; 00257 00258 /** 00259 * @brief Sets an extended menu option. 00260 * 00261 * @param option Option type. 00262 * @param valuePtr Pointer of the type expected by the option. 00263 * @return True on success, false if option or value is not supported. 00264 */ 00265 virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0; 00266 00267 /** 00268 * @brief Returns whether the display is capable of rendering an item 00269 * with the given flags. 00270 * 00271 * @param drawFlags ITEMDRAW flags. 00272 * @return True if renderable, false otherwise. 00273 */ 00274 virtual bool CanDrawItem(unsigned int drawFlags) =0; 00275 00276 /** 00277 * @brief Sends the menu display to a client. 00278 * 00279 * @param client Client index to display to. 00280 * @param handler Menu handler to use. 00281 * @param time Time to hold menu for. 00282 * @return True on success, false otherwise. 00283 */ 00284 virtual bool SendDisplay(int client, IMenuHandler *handler, unsigned int time) =0; 00285 00286 /** 00287 * @brief Destroys the display object. 00288 */ 00289 virtual void DeleteThis() =0; 00290 00291 /** 00292 * @brief Sets the selectable key map. Returns false if the function 00293 * is not supported. 00294 * 00295 * @param keymap A bit string where each bit N-1 specifies 00296 * that key N is selectable (key 0 is bit 9). 00297 * If the selectable key map is 0, it will be 00298 * automatically set to allow 0. 00299 * @return True on success, false if not supported. 00300 */ 00301 virtual bool SetSelectableKeys(unsigned int keymap) =0; 00302 00303 /** 00304 * @brief Returns the current key position. 00305 * 00306 * @return Current key position starting at 1. 00307 */ 00308 virtual unsigned int GetCurrentKey() =0; 00309 00310 /** 00311 * @brief Sets the next key position. This cannot be used 00312 * to traverse backwards. 00313 * 00314 * @param key Key that is greater or equal to 00315 * GetCurrentKey(). 00316 * @return True on success, false otherwise. 00317 */ 00318 virtual bool SetCurrentKey(unsigned int key) =0; 00319 00320 /** 00321 * @brief Returns the number of characters that can be added to the 00322 * menu. The internal buffer is truncated if overflowed; this is for 00323 * manual truncation/wrapping purposes. 00324 * 00325 * @return Number of bytes available. If the result is 00326 * -1, then the panel has no text limit. 00327 */ 00328 virtual int GetAmountRemaining() =0; 00329 00330 /** 00331 * @brief For the Handle system, returns approximate memory usage. 00332 * 00333 * @return Approximate number of bytes being used. 00334 */ 00335 virtual unsigned int GetApproxMemUsage() =0; 00336 }; 00337 00338 /** 00339 * @brief Describes a "MenuStyle" system which manages 00340 * menu drawing and construction. 00341 */ 00342 class IMenuStyle 00343 { 00344 public: 00345 /** 00346 * @brief Returns the style API version. 00347 * 00348 * @return API version. 00349 */ 00350 virtual unsigned int GetStyleAPIVersion() 00351 { 00352 return SMINTERFACE_MENUMANAGER_VERSION; 00353 } 00354 00355 /** 00356 * @brief Returns the name of the menu style. 00357 * 00358 * @return String containing the style name. 00359 */ 00360 virtual const char *GetStyleName() =0; 00361 00362 /** 00363 * @brief Creates an IMenuPanel object. 00364 * 00365 * Note: the object should be freed using ::DeleteThis. 00366 * 00367 * @return IMenuPanel object. 00368 */ 00369 virtual IMenuPanel *CreatePanel() =0; 00370 00371 /** 00372 * @brief Creates an IBaseMenu object of this style. 00373 * 00374 * Note: the object should be freed using IBaseMenu::Destroy. 00375 * 00376 * @param handler IMenuHandler pointer. 00377 * @param pOwner Optional IdentityToken_t owner for handle 00378 * creation. 00379 * @return An IBaseMenu pointer. 00380 */ 00381 virtual IBaseMenu *CreateMenu(IMenuHandler *handler, IdentityToken_t *pOwner=NULL) =0; 00382 00383 /** 00384 * @brief Returns the maximum number of items per page. 00385 * 00386 * Menu implementations must return >= 2. Styles with only 1 or 0 00387 * items per page are not valid. 00388 * 00389 * @return Number of items per page. 00390 */ 00391 virtual unsigned int GetMaxPageItems() =0; 00392 00393 /** 00394 * @brief Returns whether or not a client is viewing a menu. 00395 * 00396 * @param client Client index. 00397 * @param object Optional pointer to retrieve menu object, 00398 * if any. 00399 * @return MenuSource value. 00400 */ 00401 virtual MenuSource GetClientMenu(int client, void **object) =0; 00402 00403 /** 00404 * @brief Cancels a client's menu. 00405 * 00406 * @param client Client index. 00407 * @param autoIgnore If true, no menus can be created during 00408 * the cancellation process. 00409 * @return True if a menu was cancelled, false otherwise. 00410 */ 00411 virtual bool CancelClientMenu(int client, bool autoIgnore=false) =0; 00412 00413 /** 00414 * @brief Returns a Handle the IMenuStyle object. 00415 * 00416 * @return Handle_t pointing to this object. 00417 */ 00418 virtual Handle_t GetHandle() =0; 00419 00420 /** 00421 * @brief For the Handle system, returns approximate memory usage. 00422 * 00423 * @return Approximate number of bytes being used. 00424 */ 00425 virtual unsigned int GetApproxMemUsage() =0; 00426 }; 00427 00428 /** 00429 * @brief High-level interface for building menus. 00430 */ 00431 class IBaseMenu 00432 { 00433 public: 00434 /** 00435 * @brief Appends an item to the end of a menu. 00436 * 00437 * @param info Item information string. 00438 * @param draw Default drawing information. 00439 * @return True on success, false on item limit reached. 00440 */ 00441 virtual bool AppendItem(const char *info, const ItemDrawInfo &draw) =0; 00442 00443 /** 00444 * @brief Inserts an item into the menu before a certain position; 00445 * the new item will be at the given position and all next items 00446 * pushed forward. 00447 * 00448 * @param position Position, starting from 0. 00449 * @param info Item information string. 00450 * @param draw Default item draw info. 00451 * @return True on success, false on invalid menu position 00452 */ 00453 virtual bool InsertItem(unsigned int position, const char *info, const ItemDrawInfo &draw) =0; 00454 00455 /** 00456 * @brief Removes an item from the menu. 00457 * 00458 * @param position Position, starting from 0. 00459 * @return True on success, false on invalid menu position. 00460 */ 00461 virtual bool RemoveItem(unsigned int position) =0; 00462 00463 /** 00464 * @brief Removes all items from the menu. 00465 */ 00466 virtual void RemoveAllItems() =0; 00467 00468 /** 00469 * @brief Returns an item's info. 00470 * 00471 * @param position Position, starting from 0. 00472 * @param draw Optional pointer to store a draw information. 00473 * @return Info string pointer, or NULL if position was invalid. 00474 */ 00475 virtual const char *GetItemInfo(unsigned int position, ItemDrawInfo *draw) =0; 00476 00477 /** 00478 * @brief Returns the number of items. 00479 * 00480 * @return Number of items in the menu. 00481 */ 00482 virtual unsigned int GetItemCount() =0; 00483 00484 /** 00485 * @brief Sets the menu's pagination,. 00486 * 00487 * If pagination is set to MENU_NO_PAGINATION, and the previous 00488 * pagination was not MENU_NO_PAGINATION, then the MENUFLAG_BUTTON_EXIT 00489 * is unset. It can be re-applied if desired. 00490 * 00491 * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION. 00492 * @return True on success, false if itemsPerPage is too 00493 * large. 00494 */ 00495 virtual bool SetPagination(unsigned int itemsPerPage) =0; 00496 00497 /** 00498 * @brief Returns an item's pagination. 00499 * 00500 * @return Pagination setting. 00501 */ 00502 virtual unsigned int GetPagination() =0; 00503 00504 /** 00505 * @brief Returns the menu style. 00506 * 00507 * @return Menu style. 00508 */ 00509 virtual IMenuStyle *GetDrawStyle() =0; 00510 00511 /** 00512 * @brief Sets the menu's display title/message. 00513 * 00514 * @param message Message (format options allowed). 00515 */ 00516 virtual void SetDefaultTitle(const char *message) =0; 00517 00518 /** 00519 * @brief Returns the menu's display/title message. 00520 * 00521 * @return Message string. 00522 */ 00523 virtual const char *GetDefaultTitle() =0; 00524 00525 /** 00526 * @brief Sets an extended menu option. 00527 * 00528 * @param option Option type. 00529 * @param valuePtr Pointer of the type expected by the option. 00530 * @return True on success, false if option or value is not supported. 00531 */ 00532 virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0; 00533 00534 /** 00535 * @brief Creates a new IMenuPanel object using extended options specific 00536 * to the IMenuStyle parent. Titles, items, etc, are not copied. 00537 * 00538 * Note: The object should be freed with IMenuPanel::DeleteThis. 00539 * 00540 * @return IMenuPanel pointer. 00541 */ 00542 virtual IMenuPanel *CreatePanel() =0; 00543 00544 /** 00545 * @brief Sends the menu to a client. 00546 * 00547 * @param client Client index to display to. 00548 * @param time Time to hold menu for. 00549 * @param alt_handler Alternate IMenuHandler. 00550 * @return True on success, false otherwise. 00551 */ 00552 virtual bool Display(int client, unsigned int time, IMenuHandler *alt_handler=NULL) =0; 00553 00554 /** 00555 * @brief Destroys the menu and frees all associated resources. 00556 * 00557 * @param releaseHandle If true, the Handle will be released 00558 * in the destructor. This should be set 00559 * to true except for IHandleTypeDispatch 00560 * destructors. 00561 */ 00562 virtual void Destroy(bool releaseHandle=true) =0; 00563 00564 /** 00565 * @brief Cancels the menu on all client's displays. While the menu is 00566 * being cancelled, the menu may not be re-displayed to any clients. 00567 * If a vote menu is currently active, it will be cancelled as well. 00568 * 00569 * @return Number of menus cancelled. 00570 */ 00571 virtual void Cancel() =0; 00572 00573 /** 00574 * @brief Returns the menu's Handle. The Handle is automatically 00575 * removed when the menu is destroyed. 00576 * 00577 * @return Handle_t handle value. 00578 */ 00579 virtual Handle_t GetHandle() =0; 00580 00581 /** 00582 * @brief Returns menu option flags. 00583 * 00584 * @return Menu option flags. 00585 */ 00586 virtual unsigned int GetMenuOptionFlags() =0; 00587 00588 /** 00589 * @brief Sets menu option flags. 00590 * 00591 * @param flags Menu option flags. 00592 */ 00593 virtual void SetMenuOptionFlags(unsigned int flags) =0; 00594 00595 /** 00596 * @brief Returns the menu's handler. 00597 * 00598 * @return IMenuHandler of the menu. 00599 */ 00600 virtual IMenuHandler *GetHandler() =0; 00601 00602 /** 00603 * @brief Sends the menu to a client, starting from the given item number. 00604 * 00605 * Note: this API call was added in v13. 00606 * 00607 * @param client Client index to display to. 00608 * @param time Time to hold menu for. 00609 * @param start_item Starting item to draw. 00610 * @param alt_handler Alternate IMenuHandler. 00611 * @return True on success, false otherwise. 00612 */ 00613 virtual bool DisplayAtItem(int client, 00614 unsigned int time, 00615 unsigned int start_item, 00616 IMenuHandler *alt_handler=NULL) =0; 00617 00618 /** 00619 * @brief For the Handle system, returns approximate memory usage. 00620 * 00621 * @return Approximate number of bytes being used. 00622 */ 00623 virtual unsigned int GetApproxMemUsage() =0; 00624 }; 00625 00626 /** 00627 * @brief Contains callbacks for menu actions. 00628 */ 00629 class IMenuHandler 00630 { 00631 public: 00632 /** 00633 * @brief Returns the menu api verison. 00634 * 00635 * @return Menu API version. 00636 */ 00637 virtual unsigned int GetMenuAPIVersion2() 00638 { 00639 return SMINTERFACE_MENUMANAGER_VERSION; 00640 } 00641 00642 /** 00643 * @brief A display/selection cycle has started. 00644 * 00645 * @param menu Menu pointer. 00646 */ 00647 virtual void OnMenuStart(IBaseMenu *menu) 00648 { 00649 } 00650 00651 /** 00652 * @brief Called before a menu is being displayed. This is where 00653 * you can set an alternate title on the menu. 00654 * 00655 * @param menu Menu pointer. 00656 * @param client Client index. 00657 * @param display IMenuPanel pointer. 00658 */ 00659 virtual void OnMenuDisplay(IBaseMenu *menu, int client, IMenuPanel *display) 00660 { 00661 } 00662 00663 /** 00664 * @brief Called when an item is selected. 00665 * 00666 * @param menu Menu pointer. 00667 * @param client Client that selected the item. 00668 * @param item Item number. 00669 */ 00670 virtual void OnMenuSelect(IBaseMenu *menu, int client, unsigned int item) 00671 { 00672 } 00673 00674 /** 00675 * @brief An active menu display was dropped from a client. 00676 * 00677 * @param menu Menu pointer. 00678 * @param client Client that had the menu. 00679 * @param reason Menu cancellation reason. 00680 */ 00681 virtual void OnMenuCancel(IBaseMenu *menu, int client, MenuCancelReason reason) 00682 { 00683 } 00684 00685 /** 00686 * @brief A display/selection cycle has ended. 00687 * 00688 * @param menu Menu pointer. 00689 * @param reason MenuEndReason reason. 00690 */ 00691 virtual void OnMenuEnd(IBaseMenu *menu, MenuEndReason reason) 00692 { 00693 } 00694 00695 /** 00696 * @brief Called when the menu object is destroyed. 00697 * 00698 * @param menu Menu pointer. 00699 */ 00700 virtual void OnMenuDestroy(IBaseMenu *menu) 00701 { 00702 } 00703 00704 /** 00705 * @brief Called when requesting how to render an item. 00706 * 00707 * @param menu Menu pointer. 00708 * @param client Client index receiving the menu. 00709 * @param item Item number in the menu. 00710 * @param style ITEMSTYLE flags, by reference for modification. 00711 */ 00712 virtual void OnMenuDrawItem(IBaseMenu *menu, int client, unsigned int item, unsigned int &style) 00713 { 00714 } 00715 00716 /** 00717 * @brief Called when drawing item text. 00718 * 00719 * @param menu Menu pointer. 00720 * @param client Client index receiving the menu. 00721 * @param panel Panel being used to draw the menu. 00722 * @param item Item number in the menu. 00723 * @param dr Item draw information. 00724 * @return 0 to let the render algorithm decide how to draw, otherwise, 00725 * the return value from panel->DrawItem should be returned. 00726 */ 00727 virtual unsigned int OnMenuDisplayItem(IBaseMenu *menu, 00728 int client, 00729 IMenuPanel *panel, 00730 unsigned int item, 00731 const ItemDrawInfo &dr) 00732 { 00733 return 0; 00734 } 00735 00736 /** 00737 * @brief Called when a vote has been started and displayed to 00738 * clients. This is called after OnMenuStart() and OnMenuDisplay(), 00739 * but before OnMenuSelect(). 00740 * 00741 * @param menu Menu pointer. 00742 */ 00743 virtual void OnMenuVoteStart(IBaseMenu *menu) 00744 { 00745 } 00746 00747 /** 00748 * @brief Called when a vote ends. This is automatically called by the 00749 * wrapper, and never needs to called from a style implementation. 00750 * 00751 * This function does not replace OnMenuEnd(), nor does it have the 00752 * same meaning as OnMenuEnd(), meaning you should not destroy a menu 00753 * while it is in this function. 00754 * 00755 * @param menu Menu pointer. 00756 * @param results Menu vote results. 00757 */ 00758 virtual void OnMenuVoteResults(IBaseMenu *menu, const menu_vote_result_t *results) 00759 { 00760 } 00761 00762 /** 00763 * @brief Called when a vote is cancelled. If this is called, then 00764 * OnMenuVoteResults() will not be called. In both cases, OnMenuEnd will 00765 * always be called. 00766 * 00767 * @param menu Menu pointer. 00768 * @param reason VoteCancelReason reason. 00769 */ 00770 virtual void OnMenuVoteCancel(IBaseMenu *menu, VoteCancelReason reason) 00771 { 00772 } 00773 00774 /** 00775 * @brief Call to set private handler stuff. 00776 * 00777 * @param option Option name. 00778 * @param data Private data. 00779 * @return True if set, false if invalid or unrecognized. 00780 */ 00781 virtual bool OnSetHandlerOption(const char *option, const void *data) 00782 { 00783 return false; 00784 } 00785 00786 /** 00787 * @brief Called when an item is selected. 00788 * 00789 * Note: This callback was added in v13. It is called after OnMenuSelect(). 00790 * 00791 * @param menu Menu pointer. 00792 * @param client Client that selected the item. 00793 * @param item Item number. 00794 * @param item_on_page The first item on the page the player was last 00795 * viewing. 00796 */ 00797 virtual void OnMenuSelect2(IBaseMenu *menu, 00798 int client, 00799 unsigned int item, 00800 unsigned int item_on_page) 00801 { 00802 } 00803 }; 00804 00805 /** 00806 * @brief Manages menu creation and displaying. 00807 */ 00808 class IMenuManager : public SMInterface 00809 { 00810 public: 00811 virtual const char *GetInterfaceName() 00812 { 00813 return SMINTERFACE_MENUMANAGER_NAME; 00814 } 00815 virtual unsigned int GetInterfaceVersion() 00816 { 00817 return SMINTERFACE_MENUMANAGER_VERSION; 00818 } 00819 virtual bool IsVersionCompatible(unsigned int version) 00820 { 00821 if (version < 11 || version > GetInterfaceVersion()) 00822 { 00823 return false; 00824 } 00825 return true; 00826 } 00827 public: 00828 /** 00829 * @brief Finds a style by name. 00830 * 00831 * @param name Name of the style (case insensitive). 00832 * @return IMenuStyle pointer, or NULL if not found. 00833 */ 00834 virtual IMenuStyle *FindStyleByName(const char *name) =0; 00835 00836 /** 00837 * @brief Returns the default draw style Core is using. 00838 * 00839 * @return Menu style pointer. 00840 */ 00841 virtual IMenuStyle *GetDefaultStyle() =0; 00842 00843 /** 00844 * @brief Given a set of menu states, converts it to an IMenuPanel object. 00845 * 00846 * The state parameter is both INPUT and OUTPUT. 00847 * INPUT: menu, mh, firstItem, lastItem 00848 * OUTPUT: display, firstItem, lastItem, slots 00849 * 00850 * @param client Client index. 00851 * @param states Menu states. 00852 * @param order Order to search for items. 00853 * @return IMenuPanel pointer, or NULL if no items could be 00854 * found in the IBaseMenu pointer, or NULL if any 00855 * other error occurred. Any valid pointer must 00856 * be freed using IMenuPanel::DeleteThis. 00857 */ 00858 virtual IMenuPanel *RenderMenu(int client, menu_states_t &states, ItemOrder order) =0; 00859 00860 /** 00861 * @brief Cancels a menu. Calls IBaseMenu::Cancel() after doing some preparatory 00862 * work. This should always be used instead of directly calling Cancel(). 00863 * 00864 * @param menu IBaseMenu pointer. 00865 */ 00866 virtual void CancelMenu(IBaseMenu *menu) =0; 00867 00868 /** 00869 * @brief Displays a menu as a vote. 00870 * 00871 * @param menu IBaseMenu pointer. 00872 * @param num_clients Number of clients to display to. 00873 * @param clients Client index array. 00874 * @param max_time Maximum time to hold menu for. 00875 * @param flags Vote flags. 00876 * @return True on success, false if a vote is in progress. 00877 */ 00878 virtual bool StartVote(IBaseMenu *menu, 00879 unsigned int num_clients, 00880 int clients[], 00881 unsigned int max_time, 00882 unsigned int flags=0) =0; 00883 00884 /** 00885 * @brief Returns whether or not a vote is in progress. 00886 * 00887 * @return True if a vote is in progress, false otherwise. 00888 */ 00889 virtual bool IsVoteInProgress() =0; 00890 00891 /** 00892 * @brief Cancels the vote in progress. This calls IBaseMenu::Cancel(). 00893 */ 00894 virtual void CancelVoting() =0; 00895 00896 /** 00897 * @brief Returns the remaining vote delay from the last menu. This delay is 00898 * a suggestion for all public votes, and is not enforced. 00899 * 00900 * @return Number of seconds to wait. 00901 */ 00902 virtual unsigned int GetRemainingVoteDelay() =0; 00903 00904 /** 00905 * @brief Returns whether a client is in the "allowed to vote" pool determined 00906 * by the initial call to StartVote(). 00907 * 00908 * @param client Client index. 00909 * @return True if client is allowed to vote, false on failure. 00910 */ 00911 virtual bool IsClientInVotePool(int client) =0; 00912 00913 /** 00914 * @brief Redraws the current vote menu to a client in the voting pool. 00915 * 00916 * @param client Client index. 00917 * @return True on success, false if client is not allowed to vote. 00918 */ 00919 virtual bool RedrawClientVoteMenu(int client) =0; 00920 00921 /** 00922 * @brief Redraws the current vote menu to a client in the voting pool. 00923 * 00924 * @param client Client index. 00925 * @param revotes True to allow revotes, false otherwise. 00926 * @return True on success, false if client is not allowed to vote. 00927 */ 00928 virtual bool RedrawClientVoteMenu2(int client, bool revotes) =0; 00929 }; 00930 } 00931 00932 #endif //_INCLUDE_SOURCEMOD_MENU_SYSTEM_H_ 00933
1.7.1