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_MAIN_MENU_INTERFACE_H_ 00033 #define _INCLUDE_SOURCEMOD_MAIN_MENU_INTERFACE_H_ 00034 00035 #include <IShareSys.h> 00036 #include <ILibrarySys.h> 00037 #include <IAdminSystem.h> 00038 #include <IMenuManager.h> 00039 00040 /** 00041 * @file ITopMenus.h 00042 * @brief Interface header for creating and managing top-level menus. 00043 */ 00044 00045 #define SMINTERFACE_TOPMENUS_NAME "ITopMenus" 00046 #define SMINTERFACE_TOPMENUS_VERSION 4 00047 00048 namespace SourceMod 00049 { 00050 /** 00051 * @brief Top menu object types. 00052 */ 00053 enum TopMenuObjectType 00054 { 00055 TopMenuObject_Category = 0, /**< Category (sub-menu branching from root) */ 00056 TopMenuObject_Item = 1 /**< Item on a sub-menu */ 00057 }; 00058 00059 /** 00060 * @brief Top menu starting positions for display. 00061 */ 00062 enum TopMenuPosition 00063 { 00064 TopMenuPosition_Start = 0, /**< Start/root of the menu */ 00065 TopMenuPosition_LastRoot = 1, /**< Last position in the root menu */ 00066 TopMenuPosition_LastCategory = 3, /**< Last position in their last category */ 00067 }; 00068 00069 class ITopMenu; 00070 00071 /** 00072 * @brief Top Menu callbacks for rendering/drawing. 00073 */ 00074 class ITopMenuObjectCallbacks 00075 { 00076 public: 00077 /** 00078 * @brief Must return the topmenu API version. 00079 * 00080 * @return Top Menu API version. 00081 */ 00082 virtual unsigned int GetTopMenuAPIVersion1() 00083 { 00084 return SMINTERFACE_TOPMENUS_VERSION; 00085 } 00086 00087 /** 00088 * @brief Requests how the given item should be drawn for a client. 00089 * 00090 * Unlike the other callbacks, this is only called in determining 00091 * whether to enable, disable, or ignore an item on a client's menu. 00092 * 00093 * @param menu A pointer to the parent ITopMenu. 00094 * @param client Client index. 00095 * @param object_id Object ID returned from ITopMenu::AddToMenu(). 00096 * @return ITEMDRAW flags to disable or not draw the 00097 * option for this operation. 00098 */ 00099 virtual unsigned int OnTopMenuDrawOption(ITopMenu *menu, 00100 int client, 00101 unsigned int object_id) 00102 { 00103 return ITEMDRAW_DEFAULT; 00104 } 00105 00106 /** 00107 * @brief Requests how the given item should be displayed for a client. 00108 * 00109 * This can be called either while drawing a menu or to decide how to 00110 * sort a menu for a player. 00111 * 00112 * @param menu A pointer to the parent ITopMenu. 00113 * @param client Client index. 00114 * @param object_id Object ID returned from ITopMenu::AddToMenu(). 00115 * @param buffer Buffer to store rendered text. 00116 * @param maxlength Maximum length of the rendering buffer. 00117 */ 00118 virtual void OnTopMenuDisplayOption(ITopMenu *menu, 00119 int client, 00120 unsigned int object_id, 00121 char buffer[], 00122 size_t maxlength) =0; 00123 00124 /** 00125 * @brief Requests how the given item's title should be displayed for 00126 * a client. This is called on any object_id that is a category. 00127 * 00128 * @param menu A pointer to the parent ITopMenu. 00129 * @param client Client index. 00130 * @param object_id Object ID returned from ITopMenu::AddToMenu(), 00131 * or 0 if the title is the root menu title. 00132 * @param buffer Buffer to store rendered text. 00133 * @param maxlength Maximum length of the rendering buffer. 00134 */ 00135 virtual void OnTopMenuDisplayTitle(ITopMenu *menu, 00136 int client, 00137 unsigned int object_id, 00138 char buffer[], 00139 size_t maxlength) =0; 00140 00141 /** 00142 * @brief Notifies the listener that the menu option has been selected. 00143 * 00144 * @param menu A pointer to the parent ITopMenu. 00145 * @param client Client index. 00146 * @param object_id Object ID returned from ITopMenu::AddToMenu(). 00147 */ 00148 virtual void OnTopMenuSelectOption(ITopMenu *menu, 00149 int client, 00150 unsigned int object_id) =0; 00151 00152 /** 00153 * @brief Notified when the given item is removed. 00154 * 00155 * @param menu A pointer to the parent ITopMenu. 00156 * @param object_id Object ID returned from ITopMenu::AddToMenu(), 00157 * or 0 if the title callbacks are being removed. 00158 */ 00159 virtual void OnTopMenuObjectRemoved(ITopMenu *menu, unsigned int object_id) =0; 00160 }; 00161 00162 /** 00163 * @brief "Top menu" interface, for managing top-level categorized menus. 00164 */ 00165 class ITopMenu 00166 { 00167 public: 00168 /** 00169 * @brief Creates and adds an object type type to the top menu. 00170 * 00171 * @param name Unique, string name to give the object. 00172 * @param type Object type. 00173 * @param callbacks ITopMenuObjectCallbacks pointer. 00174 * @param owner IdentityToken_t owner of the object. 00175 * @param cmdname Command name used for override access checks. 00176 * If NULL or empty, access will not be Checked. 00177 * @param flags Default flag(s) to use for access checks. 00178 * @param parent Parent object, or 0 if none. 00179 * Currently, categories cannot have a parent, 00180 * and items must have a category parent. 00181 * @return An object ID, or 0 on failure. 00182 */ 00183 virtual unsigned int AddToMenu(const char *name, 00184 TopMenuObjectType type, 00185 ITopMenuObjectCallbacks *callbacks, 00186 IdentityToken_t *owner, 00187 const char *cmdname, 00188 FlagBits flags, 00189 unsigned int parent) =0; 00190 00191 /** 00192 * @brief Removes an object from a menu. If the object has any 00193 * children, those will be removed. 00194 * 00195 * @param object_id Object ID returned from AddToMenu. 00196 */ 00197 virtual void RemoveFromMenu(unsigned int object_id) =0; 00198 00199 /** 00200 * @brief Sends the main menu to a given client. 00201 * 00202 * Once the menu is drawn to a client, the drawing order is cached. 00203 * If text on the menu is rendered differently for the client's next 00204 * viewing, the text will render properly, but its order will not 00205 * change. The menu is sorted by its configuration. Remaining items 00206 * are sorted in alphabetical order using the initial display text. 00207 * 00208 * @param client Client index. 00209 * @param hold_time Time to hold the menu on the screen for. 00210 * @param position TopMenuPosition enumeration value. 00211 * @return True on success, false if nothing displayed. 00212 */ 00213 virtual bool DisplayMenu(int client, unsigned int hold_time, TopMenuPosition position) =0; 00214 00215 /** 00216 * @brief Loads a configuration file for organizing the menu. This 00217 * forces all known categories to be re-sorted. 00218 * 00219 * Only one configuration can be active at a time. Loading a new one 00220 * will cause the old sorting to disappear. 00221 * 00222 * @param file File path. 00223 * @param error Error buffer. 00224 * @param maxlength Maximum length of the error buffer. 00225 * @return True on success, false on failure. 00226 */ 00227 virtual bool LoadConfiguration(const char *file, char *error, size_t maxlength) =0; 00228 00229 /** 00230 * @brief Finds a category's ID by name. 00231 * 00232 * @param name Category's name. 00233 * @return Object ID of the category, or 0 if none. 00234 */ 00235 virtual unsigned int FindCategory(const char *name) =0; 00236 00237 /** 00238 * @brief Creates and adds an object type type to the top menu. 00239 * 00240 * @param name Unique, string name to give the object. 00241 * @param type Object type. 00242 * @param callbacks ITopMenuObjectCallbacks pointer. 00243 * @param owner IdentityToken_t owner of the object. 00244 * @param cmdname Command name used for override access checks. 00245 * If NULL or empty, access will not be Checked. 00246 * @param flags Default flag(s) to use for access checks. 00247 * @param parent Parent object, or 0 if none. 00248 * Currently, categories cannot have a parent, 00249 * and items must have a category parent. 00250 * @param info_string Optional info string to attach to the object. 00251 * Only 255 bytes of the string (including null 00252 * terminator) will be stored. 00253 * @return An object ID, or 0 on failure. 00254 */ 00255 virtual unsigned int AddToMenu2(const char *name, 00256 TopMenuObjectType type, 00257 ITopMenuObjectCallbacks *callbacks, 00258 IdentityToken_t *owner, 00259 const char *cmdname, 00260 FlagBits flags, 00261 unsigned int parent, 00262 const char *info_string) =0; 00263 00264 /** 00265 * @brief Returns an object's info string. 00266 * 00267 * @param object_id Object ID. 00268 * @return Object's info string, or NULL if none. 00269 */ 00270 virtual const char *GetObjectInfoString(unsigned int object_id) =0; 00271 00272 /** 00273 * @brief Returns an object's name string. 00274 * 00275 * @param object_id Object ID. 00276 * @return Object's name string, or NULL if none. 00277 */ 00278 virtual const char *GetObjectName(unsigned int object_id) =0; 00279 }; 00280 00281 /** 00282 * @brief Top menu manager. 00283 */ 00284 class ITopMenuManager : public SMInterface 00285 { 00286 public: 00287 virtual const char *GetInterfaceName() =0; 00288 virtual unsigned int GetInterfaceVersion() =0; 00289 virtual bool IsVersionCompatible(unsigned int version) 00290 { 00291 if (version < 2) 00292 { 00293 return false; 00294 } 00295 return SMInterface::IsVersionCompatible(version); 00296 } 00297 public: 00298 /** 00299 * @brief Creates a new top-level menu. 00300 * 00301 * @param callbacks Callbacks for the title text. 00302 * The object_id for the title will always be 0. 00303 * @return A new ITopMenu pointer. 00304 */ 00305 virtual ITopMenu *CreateTopMenu(ITopMenuObjectCallbacks *callbacks) =0; 00306 00307 /** 00308 * @brief Destroys a top-level menu. 00309 * 00310 * @param topmenu Pointer to an ITopMenu. 00311 */ 00312 virtual void DestroyTopMenu(ITopMenu *topmenu) =0; 00313 }; 00314 } 00315 00316 #endif //_INCLUDE_SOURCEMOD_MAIN_MENU_INTERFACE_H_ 00317
1.5.1