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: IMenuManager.h 2151 2008-05-17 05:12:52Z dvander $ 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 15 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 00182 /** 00183 * @brief Extended menu options. 00184 */ 00185 enum MenuOption 00186 { 00187 MenuOption_IntroMessage, /**< CONST CHAR *: Valve menus only; defaults to: 00188 "You have a menu, hit ESC" 00189 */ 00190 MenuOption_IntroColor, /**< INT[4]: Valve menus only; specifies the intro message colour 00191 using R,G,B,A (defaults to 255,0,0,255) 00192 */ 00193 MenuOption_Priority, /**< INT *: Valve menus only; priority (less is higher) */ 00194 }; 00195 00196 /** 00197 * @brief Describes the menu a player is viewing. 00198 */ 00199 enum MenuSource 00200 { 00201 MenuSource_None = 0, /**< No menu is being displayed */ 00202 MenuSource_External = 1, /**< External menu, no pointer */ 00203 MenuSource_BaseMenu = 2, /**< An IBaseMenu pointer. */ 00204 MenuSource_Display = 3, /**< IMenuPanel source, no pointer */ 00205 }; 00206 00207 class IMenuStyle; 00208 00209 /** 00210 * @brief Sets how a raw menu should be drawn. 00211 */ 00212 class IMenuPanel 00213 { 00214 public: 00215 /** 00216 * @brief Returns the parent IMenuStyle pointer. 00217 * 00218 * @return IMenuStyle pointer which created 00219 * this object. 00220 */ 00221 virtual IMenuStyle *GetParentStyle() =0; 00222 00223 /** 00224 * @brief Resets/clears the cached display text. 00225 */ 00226 virtual void Reset() =0; 00227 00228 /** 00229 * @brief Sets how the title should be drawn. 00230 * 00231 * @param text Text string to display for the title. 00232 * @param onlyIfEmpty Only sets the title if one does not already 00233 * exist. 00234 */ 00235 virtual void DrawTitle(const char *text, bool onlyIfEmpty=false) =0; 00236 00237 /** 00238 * @brief Adds an item to the menu and returns the position (1-10). 00239 * 00240 * Note: Item will fail to draw if there are too many items, 00241 * or the item is not drawable (for example, invisible). 00242 * 00243 * @return Item draw position, or 0 on failure. 00244 */ 00245 virtual unsigned int DrawItem(const ItemDrawInfo &item) =0; 00246 00247 /** 00248 * @brief Draws a raw line of text, if supported. The line does not 00249 * need to be newline terminated. 00250 * 00251 * @return True on success, false if not supported. 00252 */ 00253 virtual bool DrawRawLine(const char *rawline) =0; 00254 00255 /** 00256 * @brief Sets an extended menu option. 00257 * 00258 * @param option Option type. 00259 * @param valuePtr Pointer of the type expected by the option. 00260 * @return True on success, false if option or value is not supported. 00261 */ 00262 virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0; 00263 00264 /** 00265 * @brief Returns whether the display is capable of rendering an item 00266 * with the given flags. 00267 * 00268 * @param drawFlags ITEMDRAW flags. 00269 * @return True if renderable, false otherwise. 00270 */ 00271 virtual bool CanDrawItem(unsigned int drawFlags) =0; 00272 00273 /** 00274 * @brief Sends the menu display to a client. 00275 * 00276 * @param client Client index to display to. 00277 * @param handler Menu handler to use. 00278 * @param time Time to hold menu for. 00279 * @return True on success, false otherwise. 00280 */ 00281 virtual bool SendDisplay(int client, IMenuHandler *handler, unsigned int time) =0; 00282 00283 /** 00284 * @brief Destroys the display object. 00285 */ 00286 virtual void DeleteThis() =0; 00287 00288 /** 00289 * @brief Sets the selectable key map. Returns false if the function 00290 * is not supported. 00291 * 00292 * @param keymap A bit string where each bit N-1 specifies 00293 * that key N is selectable (key 0 is bit 9). 00294 * If the selectable key map is 0, it will be 00295 * automatically set to allow 0. 00296 * @return True on success, false if not supported. 00297 */ 00298 virtual bool SetSelectableKeys(unsigned int keymap) =0; 00299 00300 /** 00301 * @brief Returns the current key position. 00302 * 00303 * @return Current key position starting at 1. 00304 */ 00305 virtual unsigned int GetCurrentKey() =0; 00306 00307 /** 00308 * @brief Sets the next key position. This cannot be used 00309 * to traverse backwards. 00310 * 00311 * @param key Key that is greater or equal to 00312 * GetCurrentKey(). 00313 * @return True on success, false otherwise. 00314 */ 00315 virtual bool SetCurrentKey(unsigned int key) =0; 00316 00317 /** 00318 * @brief Returns the number of characters that can be added to the 00319 * menu. The internal buffer is truncated if overflowed; this is for 00320 * manual truncation/wrapping purposes. 00321 * 00322 * @return Number of bytes available. If the result is 00323 * -1, then the panel has no text limit. 00324 */ 00325 virtual int GetAmountRemaining() =0; 00326 00327 /** 00328 * @brief For the Handle system, returns approximate memory usage. 00329 * 00330 * @return Approximate number of bytes being used. 00331 */ 00332 virtual unsigned int GetApproxMemUsage() =0; 00333 }; 00334 00335 /** 00336 * @brief Describes a "MenuStyle" system which manages 00337 * menu drawing and construction. 00338 */ 00339 class IMenuStyle 00340 { 00341 public: 00342 /** 00343 * @brief Returns the style API version. 00344 * 00345 * @return API version. 00346 */ 00347 virtual unsigned int GetStyleAPIVersion() 00348 { 00349 return SMINTERFACE_MENUMANAGER_VERSION; 00350 } 00351 00352 /** 00353 * @brief Returns the name of the menu style. 00354 * 00355 * @return String containing the style name. 00356 */ 00357 virtual const char *GetStyleName() =0; 00358 00359 /** 00360 * @brief Creates an IMenuPanel object. 00361 * 00362 * Note: the object should be freed using ::DeleteThis. 00363 * 00364 * @return IMenuPanel object. 00365 */ 00366 virtual IMenuPanel *CreatePanel() =0; 00367 00368 /** 00369 * @brief Creates an IBaseMenu object of this style. 00370 * 00371 * Note: the object should be freed using IBaseMenu::Destroy. 00372 * 00373 * @param handler IMenuHandler pointer. 00374 * @param pOwner Optional IdentityToken_t owner for handle 00375 * creation. 00376 * @return An IBaseMenu pointer. 00377 */ 00378 virtual IBaseMenu *CreateMenu(IMenuHandler *handler, IdentityToken_t *pOwner=NULL) =0; 00379 00380 /** 00381 * @brief Returns the maximum number of items per page. 00382 * 00383 * Menu implementations must return >= 2. Styles with only 1 or 0 00384 * items per page are not valid. 00385 * 00386 * @return Number of items per page. 00387 */ 00388 virtual unsigned int GetMaxPageItems() =0; 00389 00390 /** 00391 * @brief Returns whether or not a client is viewing a menu. 00392 * 00393 * @param client Client index. 00394 * @param object Optional pointer to retrieve menu object, 00395 * if any. 00396 * @return MenuSource value. 00397 */ 00398 virtual MenuSource GetClientMenu(int client, void **object) =0; 00399 00400 /** 00401 * @brief Cancels a client's menu. 00402 * 00403 * @param client Client index. 00404 * @param autoIgnore If true, no menus can be created during 00405 * the cancellation process. 00406 * @return True if a menu was cancelled, false otherwise. 00407 */ 00408 virtual bool CancelClientMenu(int client, bool autoIgnore=false) =0; 00409 00410 /** 00411 * @brief Returns a Handle the IMenuStyle object. 00412 * 00413 * @return Handle_t pointing to this object. 00414 */ 00415 virtual Handle_t GetHandle() =0; 00416 00417 /** 00418 * @brief For the Handle system, returns approximate memory usage. 00419 * 00420 * @return Approximate number of bytes being used. 00421 */ 00422 virtual unsigned int GetApproxMemUsage() =0; 00423 }; 00424 00425 /** 00426 * @brief High-level interface for building menus. 00427 */ 00428 class IBaseMenu 00429 { 00430 public: 00431 /** 00432 * @brief Appends an item to the end of a menu. 00433 * 00434 * @param info Item information string. 00435 * @param draw Default drawing information. 00436 * @return True on success, false on item limit reached. 00437 */ 00438 virtual bool AppendItem(const char *info, const ItemDrawInfo &draw) =0; 00439 00440 /** 00441 * @brief Inserts an item into the menu before a certain position; 00442 * the new item will be at the given position and all next items 00443 * pushed forward. 00444 * 00445 * @param position Position, starting from 0. 00446 * @param info Item information string. 00447 * @param draw Default item draw info. 00448 * @return True on success, false on invalid menu position 00449 */ 00450 virtual bool InsertItem(unsigned int position, const char *info, const ItemDrawInfo &draw) =0; 00451 00452 /** 00453 * @brief Removes an item from the menu. 00454 * 00455 * @param position Position, starting from 0. 00456 * @return True on success, false on invalid menu position. 00457 */ 00458 virtual bool RemoveItem(unsigned int position) =0; 00459 00460 /** 00461 * @brief Removes all items from the menu. 00462 */ 00463 virtual void RemoveAllItems() =0; 00464 00465 /** 00466 * @brief Returns an item's info. 00467 * 00468 * @param position Position, starting from 0. 00469 * @param draw Optional pointer to store a draw information. 00470 * @return Info string pointer, or NULL if position was invalid. 00471 */ 00472 virtual const char *GetItemInfo(unsigned int position, ItemDrawInfo *draw) =0; 00473 00474 /** 00475 * @brief Returns the number of items. 00476 * 00477 * @return Number of items in the menu. 00478 */ 00479 virtual unsigned int GetItemCount() =0; 00480 00481 /** 00482 * @brief Sets the menu's pagination,. 00483 * 00484 * If pagination is set to MENU_NO_PAGINATION, and the previous 00485 * pagination was not MENU_NO_PAGINATION, then the MENUFLAG_BUTTON_EXIT 00486 * is unset. It can be re-applied if desired. 00487 * 00488 * @param itemsPerPage Number of items per page, or MENU_NO_PAGINATION. 00489 * @return True on success, false if itemsPerPage is too 00490 * large. 00491 */ 00492 virtual bool SetPagination(unsigned int itemsPerPage) =0; 00493 00494 /** 00495 * @brief Returns an item's pagination. 00496 * 00497 * @return Pagination setting. 00498 */ 00499 virtual unsigned int GetPagination() =0; 00500 00501 /** 00502 * @brief Returns the menu style. 00503 * 00504 * @return Menu style. 00505 */ 00506 virtual IMenuStyle *GetDrawStyle() =0; 00507 00508 /** 00509 * @brief Sets the menu's display title/message. 00510 * 00511 * @param message Message (format options allowed). 00512 */ 00513 virtual void SetDefaultTitle(const char *message) =0; 00514 00515 /** 00516 * @brief Returns the menu's display/title message. 00517 * 00518 * @return Message string. 00519 */ 00520 virtual const char *GetDefaultTitle() =0; 00521 00522 /** 00523 * @brief Sets an extended menu option. 00524 * 00525 * @param option Option type. 00526 * @param valuePtr Pointer of the type expected by the option. 00527 * @return True on success, false if option or value is not supported. 00528 */ 00529 virtual bool SetExtOption(MenuOption option, const void *valuePtr) =0; 00530 00531 /** 00532 * @brief Creates a new IMenuPanel object using extended options specific 00533 * to the IMenuStyle parent. Titles, items, etc, are not copied. 00534 * 00535 * Note: The object should be freed with IMenuPanel::DeleteThis. 00536 * 00537 * @return IMenuPanel pointer. 00538 */ 00539 virtual IMenuPanel *CreatePanel() =0; 00540 00541 /** 00542 * @brief Sends the menu to a client. 00543 * 00544 * @param client Client index to display to. 00545 * @param time Time to hold menu for. 00546 * @param alt_handler Alternate IMenuHandler. 00547 * @return True on success, false otherwise. 00548 */ 00549 virtual bool Display(int client, unsigned int time, IMenuHandler *alt_handler=NULL) =0; 00550 00551 /** 00552 * @brief Destroys the menu and frees all associated resources. 00553 * 00554 * @param releaseHandle If true, the Handle will be released 00555 * in the destructor. This should be set 00556 * to true except for IHandleTypeDispatch 00557 * destructors. 00558 */ 00559 virtual void Destroy(bool releaseHandle=true) =0; 00560 00561 /** 00562 * @brief Cancels the menu on all client's displays. While the menu is 00563 * being cancelled, the menu may not be re-displayed to any clients. 00564 * If a vote menu is currently active, it will be cancelled as well. 00565 * 00566 * @return Number of menus cancelled. 00567 */ 00568 virtual void Cancel() =0; 00569 00570 /** 00571 * @brief Returns the menu's Handle. The Handle is automatically 00572 * removed when the menu is destroyed. 00573 * 00574 * @return Handle_t handle value. 00575 */ 00576 virtual Handle_t GetHandle() =0; 00577 00578 /** 00579 * @brief Returns menu option flags. 00580 * 00581 * @return Menu option flags. 00582 */ 00583 virtual unsigned int GetMenuOptionFlags() =0; 00584 00585 /** 00586 * @brief Sets menu option flags. 00587 * 00588 * @param flags Menu option flags. 00589 */ 00590 virtual void SetMenuOptionFlags(unsigned int flags) =0; 00591 00592 /** 00593 * @brief Returns the menu's handler. 00594 * 00595 * @return IMenuHandler of the menu. 00596 */ 00597 virtual IMenuHandler *GetHandler() =0; 00598 00599 /** 00600 * @brief Sends the menu to a client, starting from the given item number. 00601 * 00602 * Note: this API call was added in v13. 00603 * 00604 * @param client Client index to display to. 00605 * @param time Time to hold menu for. 00606 * @param start_item Starting item to draw. 00607 * @param alt_handler Alternate IMenuHandler. 00608 * @return True on success, false otherwise. 00609 */ 00610 virtual bool DisplayAtItem(int client, 00611 unsigned int time, 00612 unsigned int start_item, 00613 IMenuHandler *alt_handler=NULL) =0; 00614 00615 /** 00616 * @brief For the Handle system, returns approximate memory usage. 00617 * 00618 * @return Approximate number of bytes being used. 00619 */ 00620 virtual unsigned int GetApproxMemUsage() =0; 00621 }; 00622 00623 /** 00624 * @brief Contains callbacks for menu actions. 00625 */ 00626 class IMenuHandler 00627 { 00628 public: 00629 /** 00630 * @brief Returns the menu api verison. 00631 * 00632 * @return Menu API version. 00633 */ 00634 virtual unsigned int GetMenuAPIVersion2() 00635 { 00636 return SMINTERFACE_MENUMANAGER_VERSION; 00637 } 00638 00639 /** 00640 * @brief A display/selection cycle has started. 00641 * 00642 * @param menu Menu pointer. 00643 */ 00644 virtual void OnMenuStart(IBaseMenu *menu) 00645 { 00646 } 00647 00648 /** 00649 * @brief Called before a menu is being displayed. This is where 00650 * you can set an alternate title on the menu. 00651 * 00652 * @param menu Menu pointer. 00653 * @param client Client index. 00654 * @param display IMenuPanel pointer. 00655 */ 00656 virtual void OnMenuDisplay(IBaseMenu *menu, int client, IMenuPanel *display) 00657 { 00658 } 00659 00660 /** 00661 * @brief Called when an item is selected. 00662 * 00663 * @param menu Menu pointer. 00664 * @param client Client that selected the item. 00665 * @param item Item number. 00666 */ 00667 virtual void OnMenuSelect(IBaseMenu *menu, int client, unsigned int item) 00668 { 00669 } 00670 00671 /** 00672 * @brief An active menu display was dropped from a client. 00673 * 00674 * @param menu Menu pointer. 00675 * @param client Client that had the menu. 00676 * @param reason Menu cancellation reason. 00677 */ 00678 virtual void OnMenuCancel(IBaseMenu *menu, int client, MenuCancelReason reason) 00679 { 00680 } 00681 00682 /** 00683 * @brief A display/selection cycle has ended. 00684 * 00685 * @param menu Menu pointer. 00686 * @param reason MenuEndReason reason. 00687 */ 00688 virtual void OnMenuEnd(IBaseMenu *menu, MenuEndReason reason) 00689 { 00690 } 00691 00692 /** 00693 * @brief Called when the menu object is destroyed. 00694 * 00695 * @param menu Menu pointer. 00696 */ 00697 virtual void OnMenuDestroy(IBaseMenu *menu) 00698 { 00699 } 00700 00701 /** 00702 * @brief Called when requesting how to render an item. 00703 * 00704 * @param menu Menu pointer. 00705 * @param client Client index receiving the menu. 00706 * @param item Item number in the menu. 00707 * @param style ITEMSTYLE flags, by reference for modification. 00708 */ 00709 virtual void OnMenuDrawItem(IBaseMenu *menu, int client, unsigned int item, unsigned int &style) 00710 { 00711 } 00712 00713 /** 00714 * @brief Called when drawing item text. 00715 * 00716 * @param menu Menu pointer. 00717 * @param client Client index receiving the menu. 00718 * @param panel Panel being used to draw the menu. 00719 * @param item Item number in the menu. 00720 * @param dr Item draw information. 00721 * @return 0 to let the render algorithm decide how to draw, otherwise, 00722 * the return value from panel->DrawItem should be returned. 00723 */ 00724 virtual unsigned int OnMenuDisplayItem(IBaseMenu *menu, 00725 int client, 00726 IMenuPanel *panel, 00727 unsigned int item, 00728 const ItemDrawInfo &dr) 00729 { 00730 return 0; 00731 } 00732 00733 /** 00734 * @brief Called when a vote has been started and displayed to 00735 * clients. This is called after OnMenuStart() and OnMenuDisplay(), 00736 * but before OnMenuSelect(). 00737 * 00738 * @param menu Menu pointer. 00739 */ 00740 virtual void OnMenuVoteStart(IBaseMenu *menu) 00741 { 00742 } 00743 00744 /** 00745 * @brief Called when a vote ends. This is automatically called by the 00746 * wrapper, and never needs to called from a style implementation. 00747 * 00748 * This function does not replace OnMenuEnd(), nor does it have the 00749 * same meaning as OnMenuEnd(), meaning you should not destroy a menu 00750 * while it is in this function. 00751 * 00752 * @param menu Menu pointer. 00753 * @param results Menu vote results. 00754 */ 00755 virtual void OnMenuVoteResults(IBaseMenu *menu, const menu_vote_result_t *results) 00756 { 00757 } 00758 00759 /** 00760 * @brief Called when a vote is cancelled. If this is called, then 00761 * OnMenuVoteResults() will not be called. In both cases, OnMenuEnd will 00762 * always be called. 00763 * 00764 * @param menu Menu pointer. 00765 * @param reason VoteCancelReason reason. 00766 */ 00767 virtual void OnMenuVoteCancel(IBaseMenu *menu, VoteCancelReason reason) 00768 { 00769 } 00770 00771 /** 00772 * @brief Call to set private handler stuff. 00773 * 00774 * @param option Option name. 00775 * @param data Private data. 00776 * @return True if set, false if invalid or unrecognized. 00777 */ 00778 virtual bool OnSetHandlerOption(const char *option, const void *data) 00779 { 00780 return false; 00781 } 00782 00783 /** 00784 * @brief Called when an item is selected. 00785 * 00786 * Note: This callback was added in v13. It is called after OnMenuSelect(). 00787 * 00788 * @param menu Menu pointer. 00789 * @param client Client that selected the item. 00790 * @param item Item number. 00791 * @param item_on_page The first item on the page the player was last 00792 * viewing. 00793 */ 00794 virtual void OnMenuSelect2(IBaseMenu *menu, 00795 int client, 00796 unsigned int item, 00797 unsigned int item_on_page) 00798 { 00799 } 00800 }; 00801 00802 /** 00803 * @brief Manages menu creation and displaying. 00804 */ 00805 class IMenuManager : public SMInterface 00806 { 00807 public: 00808 virtual const char *GetInterfaceName() 00809 { 00810 return SMINTERFACE_MENUMANAGER_NAME; 00811 } 00812 virtual unsigned int GetInterfaceVersion() 00813 { 00814 return SMINTERFACE_MENUMANAGER_VERSION; 00815 } 00816 virtual bool IsVersionCompatible(unsigned int version) 00817 { 00818 if (version < 11 || version > GetInterfaceVersion()) 00819 { 00820 return false; 00821 } 00822 return true; 00823 } 00824 public: 00825 /** 00826 * @brief Finds a style by name. 00827 * 00828 * @param name Name of the style (case insensitive). 00829 * @return IMenuStyle pointer, or NULL if not found. 00830 */ 00831 virtual IMenuStyle *FindStyleByName(const char *name) =0; 00832 00833 /** 00834 * @brief Returns the default draw style Core is using. 00835 * 00836 * @return Menu style pointer. 00837 */ 00838 virtual IMenuStyle *GetDefaultStyle() =0; 00839 00840 /** 00841 * @brief Given a set of menu states, converts it to an IMenuPanel object. 00842 * 00843 * The state parameter is both INPUT and OUTPUT. 00844 * INPUT: menu, mh, firstItem, lastItem 00845 * OUTPUT: display, firstItem, lastItem, slots 00846 * 00847 * @param client Client index. 00848 * @param states Menu states. 00849 * @param order Order to search for items. 00850 * @return IMenuPanel pointer, or NULL if no items could be 00851 * found in the IBaseMenu pointer, or NULL if any 00852 * other error occurred. Any valid pointer must 00853 * be freed using IMenuPanel::DeleteThis. 00854 */ 00855 virtual IMenuPanel *RenderMenu(int client, menu_states_t &states, ItemOrder order) =0; 00856 00857 /** 00858 * @brief Cancels a menu. Calls IBaseMenu::Cancel() after doing some preparatory 00859 * work. This should always be used instead of directly calling Cancel(). 00860 * 00861 * @param menu IBaseMenu pointer. 00862 */ 00863 virtual void CancelMenu(IBaseMenu *menu) =0; 00864 00865 /** 00866 * @brief Displays a menu as a vote. 00867 * 00868 * @param menu IBaseMenu pointer. 00869 * @param num_clients Number of clients to display to. 00870 * @param clients Client index array. 00871 * @param max_time Maximum time to hold menu for. 00872 * @param flags Vote flags (currently unused). 00873 * @return True on success, false if a vote is in progress. 00874 */ 00875 virtual bool StartVote(IBaseMenu *menu, 00876 unsigned int num_clients, 00877 int clients[], 00878 unsigned int max_time, 00879 unsigned int flags=0) =0; 00880 00881 /** 00882 * @brief Returns whether or not a vote is in progress. 00883 * 00884 * @return True if a vote is in progress, false otherwise. 00885 */ 00886 virtual bool IsVoteInProgress() =0; 00887 00888 /** 00889 * @brief Cancels the vote in progress. This calls IBaseMenu::Cancel(). 00890 */ 00891 virtual void CancelVoting() =0; 00892 00893 /** 00894 * @brief Returns the remaining vote delay from the last menu. This delay is 00895 * a suggestion for all public votes, and is not enforced. 00896 * 00897 * @return Number of seconds to wait. 00898 */ 00899 virtual unsigned int GetRemainingVoteDelay() =0; 00900 00901 /** 00902 * @brief Returns whether a client is in the "allowed to vote" pool determined 00903 * by the initial call to StartVote(). 00904 * 00905 * @param client Client index. 00906 * @return True if client is allowed to vote, false on failure. 00907 */ 00908 virtual bool IsClientInVotePool(int client) =0; 00909 00910 /** 00911 * @brief Redraws the current vote menu to a client in the voting pool. 00912 * 00913 * @param client Client index. 00914 * @return True on success, false if client is not allowed to vote. 00915 */ 00916 virtual bool RedrawClientVoteMenu(int client) =0; 00917 }; 00918 } 00919 00920 #endif //_INCLUDE_SOURCEMOD_MENU_SYSTEM_H_
1.5.1