Main Page Modules Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

# PluginCommon.hpp

Go to the documentation of this file.

    00001 ///////////////////////////////////////////////////////////////////////////////
    00002 /// @file PluginCommon.hpp
    00003 /// @brief Common includes and definitions for the Destiny Edit Plugin Interface
    00004 ///
    00005 /// @author jwvanderbeck
    00006 ///
    00007 /// This file is the intellectual property of Novus Delta, LLC.. Usage of the
    00008 /// contents of this file is subject to the Destiny3D Member License which
    00009 /// can be found at http://www.destiny3d.com.  Any other usage is prohibited.
    00010 ///
    00011 /// This file is distributed "AS IS" without warranty of any kind.  Novus
    00012 /// Delta, LLC. does not guarantee the fitness of the contents of this file
    00013 /// for any particular purpose.
    00014 ///
    00015 /// Copyright (C) 2001-2003 Novus Delta, LLC. All Rights Reserved.
    00016 ///
    00017 /// <hr>
    00018 ///                                  Change History
    00019 /// <hr>
    00020 ///
    00021 /// @date March, 2002
    00022 /// @author jwvanderbeck
    00023 /// @remarks Initial creation
    00024 ///
    00025 /// @date May, 2002
    00026 /// @author jwvanderbeck
    00027 /// @remarks Added comments for generated documentation
    00028 ///
    00029 /// @bug RTF control not working propery on older Windows
    00030 /// @todo finish up command handler
    00031 /// @todo finish up this documentation
    00032 /// @todo add copy option to output logs
    00033 ///////////////////////////////////////////////////////////////////////////////
    00034
    00035 #ifndef _PLUGINCOMMON_H_
    00036 #define _PLUGINCOMMON_H_
    00037
    00038 // Include Destiny3D master datatypes
    00039 #include "deGlobalTypes.hpp"
    00040 #include "deString.hpp"
    00041
    00042 /// Sets up the proper exports/imports.  Plugins need to define PLUGIN_EXPORTS somewhere before
    00043 /// including this file in order to get the right exports
    00044 #ifdef PLUGIN_EXPORTS
    00045 #define PLUGIN_API extern "C" DEDLL_EXPORT
    00046 #else
    00047 #define PLUGIN_API extern "C" DEDLL_IMPORT
    00048 #endif
    00049
    00050 /****************************
    00051 Forward Interface Definitions
    00052 ****************************/
    00053 class IDPlugin;
    00054 class IDPControl;
    00055 class IDPObject;
    00056 class IDPManager;
    00057 class IDPMObject;
    00058 class IDPMScene;
    00059 class IDPMInterface;
    00060 class IDPMContextMenu;
    00061 class IDPMMenu;
    00062 class IDPMEventHandler;
    00063 class IDPMCommandHandler;
    00064 class IDPMUIHandler;
    00065 class IDPMSettingsManager;
    00066 /***********************
    00067 Create/Destroy functions
    00068 ***********************/
    00069
    00070 /// The PluginManager uses this function to create an instance of the plugin. This should
    00071 /// never be used by a plugin.
    00072 /// @return New instance of the interface created
    00073     PLUGIN_API IDPlugin* IDPlugin_Create();
    00074
    00075 /// The PluginManager uses this function to destroy an instance of the plugin. This should
    00076 /// never be used by a plugin.
    00077 /// @param pInterface Instance of the interface to be destroyed
    00078     PLUGIN_API void IDPlugin_Destroy(IDPlugin* pInterface);
    00079
    00080 /// Used internally to create an instance of the PluginManager. This should never be used
    00081 /// by a plugin.
    00082     PLUGIN_API IDPManager* IDPManager_Create();
    00083
    00084 /// Used internally to destroy an instance of the PluginManager. This should never be used
    00085 /// by a plugin.
    00086     PLUGIN_API void IDPManager_Destroy(IDPManager* pInterface);
    00087
    00088 /// The PluginManager uses this function to create an instance of the plugin. This should
    00089 /// never be used by a plugin.
    00090 typedef IDPManager* (*fnIDPManager_Create)();
    00091
    00092 /// The PluginManager uses this function to destroy an instance of the plugin. This should
    00093 /// never be used by a plugin.
    00094 typedef void (*fnIDPManager_Destroy)(IDPManager*);
    00095
    00096 /// Used internally to create an instance of the PluginManager. This should never be used
    00097 /// by a plugin.
    00098 typedef IDPlugin* (*fnIDPlugin_Create)();
    00099
    00100 /// Used internally to destroy an instance of the PluginManager. This should never be used
    00101 /// by a plugin.
    00102 typedef void (*fnIDPlugin_Destroy)(IDPlugin*);
    00103
    00104 /***********
    00105 Result Codes
    00106 ***********/
    00107
    00108 /// Standard result codes for Plugin use. These are the standard result codes that plugins
    00109 /// use to return from various functions.
    00110 enum IDPResult
    00111 {
    00112     /// Indictates that no error occured
    00113     IDP_OK = 0,
    00114     /// The specified object property could not be found
    00115     IDP_PROPERTY_NOT_FOUND = 1,
    00116     /// The specified property's native data type varies from that used, and no conversion is possible
    00117     IDP_CANNOT_CONVERT_PROPERTY = 2,
    00118     /// An unspecified error has occurred
    00119     IDP_ERROR = 3,
    00120     /// The specified property could not be set
    00121     IDP_PROPERTY_CANT_BE_SET = 4
    00122 };
    00123
    00124 /// Standard result codes for PluginManager use. These are the standard result codes that the
    00125 /// PluginManager will use to return from various functions.
    00126 enum IDPMResult
    00127 {
    00128     /// Indictates that no error occured
    00129     IDPM_OK = 0,
    00130     /// Attempted to register an object type that already exists
    00131     IDPM_DUPLICATE_OBJECT = 1,
    00132     /// Attempted to create a menu that already exists
    00133     IDPM_DUPLICATE_MENU = 2,
    00134     /// The specified menu id was not found
    00135     IDPM_MENU_NOT_FOUND = 3,
    00136     /// No valid handler could be found for the specified object type
    00137     IDPM_OBJECTHANDLER_NOT_FOUND = 4,
    00138     /// The SceneManager was unable to create an object of the specified type
    00139     IDPM_OBJECT_CREATE_FAILED = 5,
    00140     /// The menu can not be created because the system has run out of menu ids.
    00141     IDPM_NO_MORE_MENU_IDS = 6,
    00142     /// An unspecified error was returned
    00143     IDPM_ERROR = 7,
    00144     /// Attempted to create a control of a type that already exists
    00145     IDPM_DUPLICATE_CONTROL = 8
    00146 };
    00147
    00148
    00149
    00150 #define CONTROL_EDITBOX "EditBox"
    00151 #define CONTROL_STATIC "Static"
    00152 #define CONTROL_CHECKBOX "CheckBox"
    00153 #define CONTROL_LISTBOX "ListBox"
    00154 #define CONTROL_COLORPICKER "ColorPicker"
    00155 #define CONTROL_HIDDEN "Hidden"
    00156
    00157 #define DATATYPE_STRING "String"
    00158 #define DATATYPE_INT "Integer"
    00159 #define DATATYPE_REAL "Real"
    00160 #define DATATYPE_DWORD "DWORD"
    00161 #define DATATYPE_FLOAT "Real"
    00162 #define DATATYPE_DOUBLE "Real"
    00163 #define DATATYPE_UNSIGNEDINT "DWORD"
    00164 #define DATATYPE_INTEGER "Integer"
    00165 #define DATATYPE_BOOL "Boolean"
    00166 #define DATATYPE_LISTBOX_VALUES "ListBoxValues"
    00167
    00168 /**************
    00169 Data Structures
    00170 **************/
    00171 /// Details of an object's property make-up
    00172 struct IDPObjectProperty
    00173 {
    00174     /// The name of the property
    00175     const char* Name;
    00176     /// The control type used for viewing/editing the property
    00177     const char* ControlType;
    00178     /// The property's native data type
    00179     const char* NativeDataType;
    00180     /// Extended help/info text displayed for the user for this property
    00181     const char* HelpText;
    00182 };
    00183
    00184 /// Used to query the state of a menu item.  This struct is passed into the plugin's object, to
    00185 /// retrieve the current state of a menu item prior to it being displayed to the user.
    00186 struct MenuState
    00187 {
    00188     /// Specifies if the menu item should be shown as checked or unchecked
    00189     BOOL    bChecked;
    00190     /// Specifies if the menu item should be enabled or not.  If not enabled, it will be grayed out and unselectable.
    00191     BOOL    bEnabled;
    00192 };
    00193
    00194 /// IDPlugin Interface. This is the main plugin interface
    00195 /// and is the starting point for all loaded plugins.  This interface <b>Must</b> be used
    00196 /// for any plugin.
    00197 class IDPlugin
    00198 {
    00199 public:
    00200     /// Destructor
    00201     virtual ~IDPlugin() {};
    00202
    00203     /// Used to obtain the name of the plugin
    00204     /// @return The name of the plugin as a string
    00205     virtual const char* GetName() = 0;
    00206
    00207     /// Used to obtain a description of the plugin
    00208     /// @return Description of the plugin as a string
    00209     virtual const char* GetDescription() = 0;
    00210
    00211     /// Used to obtain the version of the plugin
    00212     /// @return Version of the plugin as a string
    00213     virtual const char* GetVersion() = 0;
    00214
    00215     /// Used to obtain the author of the plugin
    00216     /// @return Author of the plugin as a string
    00217     virtual const char* GetAuthor() = 0;
    00218
    00219     /// Used to obtain a contact email for the plugin
    00220     /// @return Contact email as a string
    00221     virtual const char* GetEmail() = 0;
    00222
    00223     /// Used to obtain a contact URL for the plugin
    00224     /// @return Contact URL for the plugin as a string
    00225     virtual const char* GetURL() = 0;
    00226
    00227     /// Called by the PluginManager when the plugin is first created. This event is called
    00228     /// on the plugin immediately after it has been loaded by the system.  This is where any
    00229     /// basic initialization should be done, as well as registration of object and control
    00230     /// types.
    00231     /// @return The plugin should return IDP_OK if everything is good and the plugin can be kept loaded
    00232     /// by the system.  If the plugin returns anything other than IDP_OK, then the system will
    00233     /// immediately unload the plugin.  In this case, the OnDestroy() event will NOT take place.
    00234     /// @param PluginManager Pointer to the main PluginManager instance that the plugin can save
    00235     /// and use throughout the life of the plugin.
    00236     /// @warning At this stage, not all of the plugins will be loaded, therefore any operations
    00237     /// that depend on another plugin should not be placed here (such as creating an object), but
    00238     /// instead should be placed in the OnInitialUpdate() event.
    00239     virtual IDPResult OnCreate(IDPManager* PluginManager) = 0;
    00240
    00241     /// Called by the PluginManager when the plugin is about to be unloaded.  This
    00242     /// event is called on the plugin just before it is unloaded, and should be used for last minute
    00243     /// cleanup and shutdown of the plugin and any objects it spawned.
    00244     virtual void OnDestroy() = 0;
    00245
    00246     /// The callback for most all plugin events.  OnEvent() is used for most all plugin events, such
    00247     /// as frame calls, window resizing, context menus, etc.
    00248     /// @param Event The event ID which caused this callback
    00249     /// @param Param1 DWRORD param used for passing event specific values
    00250     /// @param Param2 DWRORD param used for passing event specific values
    00251     /// @note Information on specific parameter packign can be found documented with the
    00252     /// specific event flag of interest.
    00253     /// @note The plugin or object will only recieve a callback for the events it has
    00254     /// enabled handlers for.  See the IDPMEventHandler interface, and IDPManager::GetEventHandler()
    00255     /// for more information on setting up event handlers.
    00256     virtual void OnEvent(int Event, DWORD Param1, DWORD Param2) = 0;
    00257
    00258     /// Callback for user hotkeyed commands.  OnCommand() will be called by the interface
    00259     /// whenever a hotkeyable command registerd by the plugin has been trigger by the user.
    00260     /// param sCommand Name of the command that has been fired off as it was registered by the plugin initially
    00261     virtual void OnCommand(deString* sCommand) = 0;
    00262
    00263     /// Retrieves the last result code set by the plugin.  This allows the system, or another plugin
    00264     /// to retrieve the last set result code, and is usefull in instances where a function doesn't
    00265     /// permitt a result code to be returned, but has the chance for failure, such as CreateObject()
    00266     /// @return The last IDPResult code set by the plugin
    00267     virtual IDPResult GetLastResult() = 0;
    00268
    00269     /// Retrieves an extended result code.  This allows plugins to return result codes that are
    00270     /// not system standard., but are more specific to the plugin.
    00271     /// @return Integer value indiciating the last set extended result code
    00272     virtual int GetLastResultEx() = 0;
    00273
    00274     /// Converts an extended result code to user readable text.  Because extended result codes are meaningless
    00275     /// to the system, this function can take an extended result code and return a user readable string
    00276     /// which can then be displayed to the user to help explain the problem.
    00277     /// @return User readable string describing the error
    00278     /// @param Result Extended result code to be converted
    00279     virtual const char* ResultToStringEx(int Result) = 0;
    00280
    00281     /// Called by the PluginManager to create a new Scene Object. Called by the PluginManager when
    00282     /// the user or another plugin has asked to create a new Scene Object of the specified type, and this
    00283     /// is the plugin registered to handle it.
    00284     /// @return Instance pointer for the new object
    00285     /// @param ObjectType String indicating the name of the registered object type being requested
    00286     virtual IDPObject* CreateObject(const char* ObjectType) = 0;
    00287
    00288     /// Called by the PluginManager to create a new Custom Control.   If an object property calls for a custom
    00289     /// control type, and this plugin is registered as the controller of that type, this method will be
    00290     /// called to obtain a new control instance pointer.
    00291     /// @return Instance pointer of the new control
    00292     /// @param ControlType String indicating the type of control to be created
    00293     virtual IDPControl* CreateControl(const char* ControlType) = 0;
    00294
    00295     /// Queries the interface to determine if a specified interface is supported. At the present
    00296     /// time there is only one revision level in each interface, and this is not used.  This function
    00297     /// is for future expansion.
    00298     /// @return TRUE if the interface specified is supported, or FALSE if not
    00299     /// @param InterfaceName Name of the interface to query for
    00300     virtual BOOL SupportsInterface(const char* InterfaceName) = 0;
    00301 };
    00302
    00303 /// IDPObject Interface. This interface is used to implement a Scene Object in the editor's scene.
    00304 /// Scene Objects can be pretty much anything, but in basic terms, it is an instance of an object that
    00305 /// exists in some form in the scene (rendered or not) and exposes 0 or more properties which the user
    00306 /// may or may not be able to see or edit.  Flexible enough for you? :p
    00307 class IDPObject
    00308 {
    00309 public:
    00310     /// Destructor
    00311     virtual ~IDPObject() {};
    00312
    00313     // object flags
    00314     virtual DWORD GetFlags() = 0;
    00315     virtual BOOL HasFlags(DWORD Flags) = 0;
    00316     virtual IDPResult SetFlags(DWORD Flags) = 0;
    00317
    00318     /// The callback for most all plugin events.  OnEvent() is used for most all plugin events, such
    00319     /// as frame calls, window resizing, context menus, etc.
    00320     /// @param Event The event ID which caused this callback
    00321     /// @param Param1 DWRORD param used for passing event specific values
    00322     /// @param Param2 DWRORD param used for passing event specific values
    00323     /// @note Information on specific parameter packign can be found documented with the
    00324     /// specific event flag of interest.
    00325     /// @note The plugin or object will only recieve a callback for the events it has
    00326     /// enabled handlers for.  See the IDPMEventHandler interface, and IDPManager::GetEventHandler()
    00327     /// for more information on setting up event handlers.
    00328     virtual void OnEvent(int Event, DWORD Param1, DWORD Param2) = 0;
    00329
    00330     /// Callback for user hotkeyed commands.  OnCommand() will be called by the interface
    00331     /// whenever a hotkeyable command registerd by the plugin has been trigger by the user.
    00332     /// param sCommand Name of the command that has been fired off as it was registered by the plugin initially
    00333     virtual void OnCommand(deString* sCommand) = 0;
    00334
    00335     /// Used to retrive a semicolon delimitted list of valid object properies.
    00336     /// @return IDPResult code
    00337     /// @param Name pointer to a deString which will be filled by the plugin with a semicolon delmitted list of properties
    00338     /// @note The list must be delimtted with semicolons between each valid property.  There should be no leading or trailing semicolon.
    00339     virtual IDPResult GetPropertyNames(deString* Name) = 0;
    00340
    00341     /// Used to retrieve details on a specific property.  This method is used to retrive the details on a property
    00342     /// such as what control it uses, native data type, and help text prompt
    00343     /// @return IDPResult code
    00344     /// @param Name deString pointer to the name of the property on which details should be returned
    00345     /// @param Property Pointer to a IDPObjectProperty struct which should be filled in for this property
    00346     virtual IDPResult GetPropertyDetails(const char* Name, IDPObjectProperty* Property) = 0;
    00347
    00348     // object properties
    00349     virtual IDPResult SetProperty(const char* Name, deString* Value) = 0;
    00350     virtual IDPResult SetProperty(const char* Name, int Value) = 0;
    00351     virtual IDPResult SetProperty(const char* Name, double Value) = 0;
    00352     virtual IDPResult SetProperty(const char* Name, DWORD Value) = 0;
    00353
    00354     virtual IDPResult GetProperty(const char* Name, deString* Value) = 0;
    00355     virtual IDPResult GetProperty(const char* Name, int* Value) = 0;
    00356     virtual IDPResult GetProperty(const char* Name, double* Value) = 0;
    00357     virtual IDPResult GetProperty(const char* Name, DWORD* Value) = 0;
    00358
    00359     /// Queries the interface to determine if a specified interface is supported. At the present
    00360     /// time there is only one revision level in each interface, and this is not used.  This function
    00361     /// is for future expansion.
    00362     /// @return TRUE if the interface specified is supported, or FALSE if not
    00363     /// @param InterfaceName Name of the interface to query for
    00364     virtual BOOL SupportsInterface(const char* InterfaceName) = 0;
    00365 };
    00366
    00367 /*******************
    00368 IDPManager interface
    00369 *******************/
    00370 class IDPManager
    00371 {
    00372 public:
    00373     virtual ~IDPManager() {};
    00374
    00375     virtual IDPMObject* GetObjectManager() = 0;
    00376     virtual IDPMScene* GetSceneManager() = 0;
    00377     virtual IDPMInterface* GetInterfaceManager() = 0;
    00378     virtual IDPMEventHandler* GetEventHandler() = 0;
    00379     virtual IDPMCommandHandler* GetCommandHandler() = 0;
    00380
    00381     virtual int GetPluginCount() = 0;
    00382     virtual IDPlugin* GetNextPlugin(IDPlugin* CurrentPlugin) = 0;
    00383
    00384     virtual BOOL SupportsInterface(const char* InterfaceName) = 0;
    00385 };
    00386
    00387 /*******************
    00388 IDPMObject Interface
    00389 *******************/
    00390 class IDPMObject
    00391 {
    00392 public:
    00393     virtual ~IDPMObject() {};
    00394     virtual IDPMResult RegisterObject(const char* ObjectType, IDPlugin* ObjectPlugin) = 0;
    00395
    00396     virtual BOOL SupportsInterface(const char* InterfaceName) = 0;
    00397 };
    00398
    00399 /******************
    00400 IDPMScene Interface
    00401 ******************/
    00402 class IDPMScene
    00403 {
    00404 public:
    00405     virtual ~IDPMScene() {};
    00406     virtual IDPObject* CreateObject(const char* ObjectType) = 0;
    00407     virtual IDPMResult RemoveObject(IDPObject* Object) = 0;
    00408     virtual int GetObjectCount() = 0;
    00409     virtual IDPObject* GetNextObject(IDPObject* CurrentObject) = 0;
    00410
    00411     /// Called to inform the system that changes have been made to an object.
    00412     virtual void UpdateObject(IDPObject* Object) = 0;
    00413
    00414     virtual BOOL SupportsInterface(const char* InterfaceName) = 0;
    00415 };
    00416
    00417 /************
    00418 IDPMInterface
    00419 ************/
    00420 class IDPMInterface
    00421 {
    00422 public:
    00423     virtual ~IDPMInterface() {};
    00424
    00425     virtual HWND GetWindowHandle() = 0;
    00426     virtual IDPMResult GetWindowSize(deRect* WindowRect) = 0;
    00427
    00428     virtual IDPMResult RegisterControlType(const char* ControlType, IDPlugin* Plugin) = 0;
    00429     virtual void SuspendUserInput(IDPControl* Control, BOOL Suspend = TRUE) = 0;
    00430     virtual void CommitControlChanges(IDPControl* Control) = 0;
    00431
    00432     virtual void AddLogEntry(const char* szText, int iLevel) = 0;
    00433
    00434     // interface handlers
    00435     virtual IDPMMenu* GetMenuHandler(const char* Parent, IDPlugin* Plugin) = 0;
    00436     virtual IDPMMenu* GetMenuHandler(const char* Parent, IDPObject* Object) = 0;
    00437     virtual IDPMMenu* GetMenuHandler(HMENU hMenu, IDPlugin* Plugin) = 0;
    00438     virtual IDPMMenu* GetMenuHandler(HMENU hMenu, IDPObject* Object) = 0;
    00439     virtual IDPMResult ReleaseMenuHandler(IDPMMenu* Handler) = 0;
    00440     virtual IDPMUIHandler* GetUIHandler() = 0;
    00441 };
    00442 /**************
    00443 IDPMContextMenu
    00444 **************/
    00445 class IDPMContextMenu
    00446 {
    00447 public:
    00448     virtual ~IDPMContextMenu() {};
    00449
    00450     virtual int AddItem(const char* Name) = 0;
    00451     virtual int AddItem(HMENU SubMenu, const char* Name) = 0;
    00452     virtual HMENU AddMenu(const char* Name) = 0;
    00453 };
    00454 /*******
    00455 IDPMMenu
    00456 *******/
    00457 class IDPMMenu
    00458 {
    00459 public:
    00460     virtual ~IDPMMenu() {};
    00461
    00462     virtual int AddItem(const char* Name) = 0;
    00463     virtual HMENU AddMenu(const char* Name) = 0;
    00464
    00465     virtual IDPMResult RemoveItem(int MenuID) = 0;
    00466     virtual IDPMResult RemoveMenu(HMENU hMenu) = 0;
    00467 };
    00468
    00469 /*****************
    00470 IDPMCommandHandler
    00471 *****************/
    00472 class IDPMCommandHandler
    00473 {
    00474 public:
    00475     virtual ~IDPMCommandHandler() {};
    00476
    00477     /// Used to register a "command" with the system.  A command is simply some form of command that the
    00478     /// plugin can perform in response to a user selectable hotkey. An example is menu items, but is not
    00479     /// limited to such.
    00480     /// @return IDPMResult code.  IDPM_ERROR if the command couldn't be registered (this should only happen
    00481     /// if the exact same name and pluginID is already used).  IDPM_OK otherwise.
    00482     /// @param Plugin Instance of the plugin which should receive the notification when the command is triggered
    00483     /// @param sCommandName Short, user readable name of the command.  This is shown to the user, and is also what will
    00484     /// be sent in the OnCommand callback to identify the command.
    00485     /// @param sCommandDesc An extended description explaining to the user just what the command does.
    00486     /// @param sPluginID This is a short string of characters, not shown to the user, which is used to help make commands "unique"
    00487     /// @param amongst plugins.  The sPluginID should always be the same, and should be something likely to be unique.
    00488     virtual IDPMResult RegisterCommand(IDPlugin* Plugin, deString* sCommandName, deString* sCommandDesc, deString* sPluginID) = 0;
    00489
    00490     /// Used to register a "command" with the system.  A command is simply some form of command that the
    00491     /// plugin can perform in response to a user selectable hotkey. An example is menu items, but is not
    00492     /// limited to such.
    00493     /// @return IDPMResult code.  IDPM_ERROR if the command couldn't be registered (this should only happen
    00494     /// if the exact same name and pluginID is already used).  IDPM_OK otherwise.
    00495     /// @param Object Instance of the object which should receive the notification when the command is triggered
    00496     /// @param sCommandName Short, user readable name of the command.  This is shown to the user, and is also what will
    00497     /// be sent in the OnCommand callback to identify the command.
    00498     /// @param sCommandDesc An extended description explaining to the user just what the command does.
    00499     /// @param sPluginID This is a short string of characters, not shown to the user, which is used to help make commands "unique"
    00500     /// @param amongst plugins.  The sPluginID should always be the same, and should be something likely to be unique.
    00501     virtual IDPMResult RegisterCommand(IDPObject* Object, deString* sCommandName, deString* sCommandDesc, deString* sPluginID) = 0;
    00502 };
    00503
    00504 /***************
    00505 IDPMEventHandler
    00506 ***************/
    00507
    00508 // Event Handler Flags
    00509
    00510 /// Event for changes in the view's window size
    00511 #define IDPMEVENT_WINDOW_RESIZE     1
    00512 /// Event for each frame of the editor
    00513 #define IDPMEVENT_FRAME             2
    00514 /// Indicates a scene object has been changed
    00515 #define IDPMEVENT_UPDATE_OBJECT     3
    00516 /// The editor is about to display a context menu
    00517 #define IDPMEVENT_CONTEXT_MENU      4
    00518 /// The user has selected a menu item
    00519 #define IDPMEVENT_MENU              5
    00520 /// Event to query the state of a menu item
    00521 #define IDPMEVENT_MENU_STATE        6
    00522 /// Called when the user moves the mouse in the view area
    00523 #define IDPMEVENT_MOUSEMOVE         7
    00524 /// Called when the user double clicks the left mouse button in the view area
    00525 #define IDPMEVENT_LBUTTONDBLCLK     8
    00526 /// Called when the user presses down the left mouse button in the view area
    00527 #define IDPMEVENT_LBUTTONDOWN       9
    00528 /// Called when the user releases the left mouse button in the view area
    00529 #define IDPMEVENT_LBUTTONUP         10
    00530 /// Called when the user double clicks the right mouse button in the view area
    00531 #define IDPMEVENT_RBUTTONDBLCLK     11
    00532 /// Called when the user presses down the right mouse button in the view area
    00533 #define IDPMEVENT_RBUTTONDOWN       12
    00534 /// Called when the user releases the right mouse button in the view area
    00535 #define IDPMEVENT_RBUTTONUP         13
    00536 /// Called when the user spins the mousewheel and the mouse is inthe view area
    00537 #define IDPMEVENT_MOUSEWHEEL        14
    00538 /// Called when the user preses a key down
    00539 #define IDPMEVENT_KEYDOWN           15
    00540 /// Called when the user releases a key
    00541 #define IDPMEVENT_KEYUP             16
    00542 /// Called to indicate a new scene object has been added to the scene
    00543 #define IDPMEVENT_ADD_OBJECT        17
    00544 /// Called to indicate that a scene object has been removed from the scene
    00545 #define IDPMEVENT_DELETE_OBJECT     18
    00546 /// Called on the very first frame event for the plugin/object
    00547 #define IDPMEVENT_INITIALFRAME      19
    00548 /// Called to indicate that the workspace settings are about to be displayed
    00549 /// Param1 in OnEvent() will be packed with a pointer to an IDPMSettingsHandler
    00550 /// which can be used to add settings to be displayed for the user.
    00551 #define IDPMEVENT_SHOW_SETTINGS     20
    00552 /// This event signifies that the user has clicked APPLY in the workspace settings
    00553 /// dialog and the plugin should run through its settings and apply any changes
    00554 /// Param1 will be a packaed pointer to an IDPMSettingsHandler
    00555 #define IDPMEVENT_APPLY_SETTINGS    21
    00556 /// This event signifies that the user has clicked OK to close the workspace
    00557 /// settings dialog and the plugin should run through its settings and apply
    00558 /// any changes.
    00559 /// Param1 will be a packaed pointer to an IDPMSettingsHandler
    00560 #define IDPMEVENT_CLOSE_SETTINGS    22
    00561
    00562 /// Starting point for plugin registered event ids
    00563 #define IDPMEVENT_CUSTOM            60000
    00564
    00565 /// Indicates ALL events above
    00566 #define IDPMEVENTS_ALL              65000
    00567
    00568
    00569 class IDPMEventHandler
    00570 {
    00571 public:
    00572     virtual ~IDPMEventHandler() {};
    00573
    00574     /// Adds an event handler for the plugin/object.  This function creates a new event handler
    00575     /// for the plugin or object for the specified event(s).  The function uses variable arguments
    00576     /// so that you may specify as many events in one call as you wish.
    00577     /// @return IDPMResult code
    00578     /// @param Plugin The instance of the plugin which should receive the event calls specified
    00579     /// @param ... Variable argument list of events (ints) that the plugin/object wants to receive
    00580     /// calls for.  The last event </b>must</b> be 0.
    00581     /// @warning You <b>must</b> use the number 0 as the last event tpo signal the end of the
    00582     /// events.  If you do not, you will most likely corrupt the stack and crash the editor.
    00583     virtual IDPMResult AddEventHandler(IDPlugin* Plugin, ...) = 0;
    00584
    00585     /// Adds an event handler for the plugin/object.  This function creates a new event handler
    00586     /// for the plugin or object for the specified event(s).  The function uses variable arguments
    00587     /// so that you may specify as many events in one call as you wish.
    00588     /// @return IDPMResult code
    00589     /// @param Object The instance of the object which should receive the event calls specified
    00590     /// @param ... Variable argument list of events (ints) that the plugin/object wants to receive
    00591     /// calls for.  The last event </b>must</b> be 0.
    00592     /// @warning You <b>must</b> use the number 0 as the last event tpo signal the end of the
    00593     /// events.  If you do not, you will most likely corrupt the stack and crash the editor.
    00594     virtual IDPMResult AddEventHandler(IDPObject* Object, ...) = 0;
    00595
    00596     virtual IDPMResult RemoveEventHandler(IDPlugin* Plugin, ...) = 0;
    00597     virtual IDPMResult RemoveEventHandler(IDPObject* Object, ...) = 0;
    00598
    00599     /// Creates a new event type in the system.  This function can be used to create a custom
    00600     /// event type that lasts until the editor is shut down.  The first plugin to make this call
    00601     /// will create a new event type with the specified event name, and receive an ID for that event.
    00602     /// Any other plugin that calls this function with the same name, will get the same ID.  This allows
    00603     /// a cusotm event to be created that all plugins can be aware of.  The returned ID is only valid for
    00604     /// the session, and may be different next time the application is run.  Therefore it should not
    00605     /// be saved.
    00606     /// @return ID of the specified event name
    00607     /// @param EventName Name of the event to create/return
    00608     virtual int RegisterCustomEvent(const char* EventName) = 0;
    00609 };
    00610
    00611
    00612 struct IDPMSettingsItem
    00613 {
    00614     int         Parent;
    00615     deString    Label;
    00616     deString    ControlType;
    00617     deString    DataType;
    00618     deString    HelpText;
    00619 };
    00620
    00621 class IDPMSettingsHandler
    00622 {
    00623 public:
    00624     virtual ~IDPMSettingsHandler() {};
    00625
    00626     virtual int FindItem(deString ItemLabel) = 0;
    00627     virtual BOOL IsItemRoot(int Item) = 0;
    00628     virtual int AddItem(IDPMSettingsItem *Item, deString *Value) = 0;
    00629     virtual int AddItem(IDPMSettingsItem *Item, double Value) = 0;
    00630     virtual int AddItem(IDPMSettingsItem *Item, int Value) = 0;
    00631     virtual int AddItem(IDPMSettingsItem *Item, DWORD Value) = 0;
    00632     virtual IDPMSettingsItem* GetItem(int Item) = 0;
    00633     virtual BOOL GetItemValue(int Item, deString *Value) = 0;
    00634     virtual BOOL GetItemValue(int Item, double *Value) = 0;
    00635     virtual BOOL GetItemValue(int Item, int *Value) = 0;
    00636     virtual BOOL GetItemValue(int Item, DWORD *Value) = 0;
    00637 };
    00638
    00639 /*************
    00640 UTILITY MACROS
    00641 *************/
    00642 /// Utility macro for returning details on a property
    00643 /// @param name deString variable that contains the Name value as passed in through GetPropertyDetails()
    00644 /// @param prop Pointer to Property structure to fill, as passed in through GetPropertyDetails()
    00645 /// @param propname Quoted string name of the property
    00646 /// @param propcontrol Quoted string name of the control type to use
    00647 /// @param proptype Quoted string name of the property's native data type
    00648 #define PROP_DETAILS(name, prop, propname, propcontrol, proptype)\
    00649 if (name == propname)\
    00650 {\
    00651     prop->ControlType = propcontrol;\
    00652     prop->Name = propname;\
    00653     prop->NativeDataType = proptype;\
    00654     return IDP_OK;\
    00655 }
    00656
    00657 /// Utility macro for indicating an IDP_CANNONT_CONVERT_PROPERTY return for a property
    00658 /// @param name deString variable that contains the Name value as passed in through Get/SetProperty()
    00659 /// @param propname Quoted string name of the property
    00660 #define PROP_BADTYPE(name, propname)\
    00661 if (name == propname)\
    00662     return IDP_CANNOT_CONVERT_PROPERTY;
    00663
    00664 /// Utility macro for doing a very simple property value return
    00665 /// @param name deString variable that contains the Name value as passed in through GetProperty()
    00666 /// @param pvalue Value pointer as passed in through GetProperty()
    00667 /// @param propname Quoted string name of the property
    00668 /// @param propvalue Value of the property
    00669 #define PROP_SETVALUE(name, pvalue, propname, propvalue)\
    00670 if (name == propname)\
    00671 {\
    00672     *pvalue = propvalue;\
    00673     return IDP_OK;\
    00674 }
    00675
    00676 /// Utility macro for building the values of a listbox in GetProperty()
    00677 /// @param name deString variable that contains the Name value as passed in through GetProperty()
    00678 /// @param pvalue Value pointer as passed in through GetProperty()
    00679 /// @param propname Quoted string name of the property
    00680 /// @param propvalues Quoted string list of semicolon delimitted values for the listbox
    00681 #define PROP_MAKELISTBOX(name, pvalue, propname, propvalues) PROP_SETVALUE(name, pvalue, propname ":Values", propvalues)
    00682
    00683 /// Utility macro for indicating an IDP_PROPERTY_CANT_BE_SET return for a property
    00684 /// @param name deString variable that contains the Name value as passed in through SetProperty()
    00685 /// @param propname Quoted string name of the property
    00686 #define PROP_CANTSET(name, propname)\
    00687 if (name == propname)\
    00688 {\
    00689     return IDP_PROPERTY_CANT_BE_SET;\
    00690 }
    00691
    00692 #endif