ryzom/tools/leveldesign/georges_dll/plugin_interface.h

   1 // Ryzom - MMORPG Framework <http://dev.ryzom.com/projects/ryzom/>
   2 // Copyright (C) 2010  Winch Gate Property Limited
   3 //
   4 // This program is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU Affero General Public License as
   6 // published by the Free Software Foundation, either version 3 of the
   7 // License, or (at your option) any later version.
   8 //
   9 // This program is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU Affero General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU Affero General Public License
  15 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 #ifndef NLGEORGES_PLUGIN_INTERFACE_H
  18 #define NLGEORGES_PLUGIN_INTERFACE_H
  19
  20 #include <nel/georges/u_form.h>
  21 #include "nel/misc/config_file.h"
  22
  23 namespace NLGEORGES
  24 {
  25
  26 /**
  27   * Georges plug-ins are dlls. To be loaded, dll must be listed in the georges.cfg config file.
  28   * The dll must export 1 function:
  29   *
  30   * IEditPlugin *IGeorgesEditGetInterface (int version, IEdit *globalInterface);
  31   *
  32   * This method must first compare the version number with NLGEORGES_PLUGIN_INTERFACE_VERSION defined in
  33   * plugin_interface.h. If the version is not the same, the function must returns NULL (can show an error message).
  34   * If the number is the same, the plugin must instanciate an interface and return its pointers. It should
  35   * do only basic initialisation stuff. This method is called only one time by georges editor session.
  36   * The IEditPlugin derived object must be allocated with new. It will be delete by the system.
  37   *
  38   * The globalInterface pointer is valid to the end of the session.
  39   */
  40
  41 class IEdit;
  42 class IEditPlugin;
  43 class IEditDocument;
  44 class IEditDocumentPlugin;
  45
  46 // The get interface plugin DLL entry.
  47 typedef IEditPlugin *(*IGeorgesEditGetInterface) (int version, IEdit *globalInterface, NLMISC::INelContext &nelContext);
  48
  49 #define NLGEORGES_PLUGIN_INTERFACE_VERSION 0x1
  50
  51 /**
  52   * Communication interface between the plugin and georges editor.
  53   *
  54   * This interface give access to global global events handling.
  55   *
  56   * If you use MFC, don't forget to call AFX_MANAGE_STATE(AfxGetStaticModuleState());
  57   * at the beginning of each callback of the interface.
  58   *
  59   * This interface is instancied by the plugin.
  60   */
  61 class IEditPlugin
  62 {
  63 public:
  64
  65         /**
  66           * Destructor must uninitialise the plugin interface
  67           */
  68         virtual ~IEditPlugin () {}
  69
  70         /// Window related
  71
  72         /**
  73           * This method is called at dialog initialisation.
  74           * Typicaly, this method will create / show some global edition tools. (Not document edition related dialog).
  75           *
  76           * \param is the HWND of georges editor main frame.
  77           */
  78         virtual void dialogInit (HWND mainFrm) = 0;
  79
  80         /**
  81           * This method is called to activate / disactivate the plugin UI.
  82           *
  83           * \param activate is true to activate the plugin UI, false to hide the plugin UI
  84           */
  85         virtual void activate (bool activate) = 0;
  86
  87         /**
  88           * Get the plugin name.
  89           */
  90         virtual void getPluginName (std::string &name) = 0;
  91
  92         /**
  93           * Pretranslate message hook.
  94           * This method give a chance to the plugin to pretranslate a message before the main frame.
  95           * Useful for shortcuts etc..
  96           * Default implementation returns "false";
  97           */
  98         virtual bool pretranslateMessage (MSG *pMsg) = 0;
  99
 100         /// Events
 101
 102         /**
 103           * This method is called when a document has been created / opened.
 104           */
 105         virtual void onCreateDocument (IEditDocument *document) = 0;
 106 };
 107
 108 /**
 109   * This interface give access to global functions.
 110   *
 111   * This interface is instancied by the system.
 112   */
 113 class IEdit
 114 {
 115 public:
 116         /**
 117           * Return the active document. Return NULL if no current document.
 118           */
 119         virtual IEditDocument   *getActiveDocument () = 0;
 120
 121         /**
 122           * Return the current search path.
 123           */
 124         virtual void                    getSearchPath (std::string &searchPath) = 0;
 125
 126         /**
 127           * Create a form in the editor.
 128           *
 129           * \param dfnName is the name of the DFN. Can't be NULL.
 130           * \param pathName is the file name of the created document. Can be NULL.
 131           * \return the document pointer or NULL if a problem occurred.
 132         */
 133         virtual IEditDocument   *createDocument (const char *dfnName, const char *pathName) = 0;
 134
 135         /**
 136           * Retreive the loaded config file.
 137           * Usefull for plugins to read any configuration var.
 138           */
 139         virtual NLMISC::CConfigFile             &getConfigFile() =0;
 140 };
 141
 142 /**
 143   * Communication interface between the plugin and georges editor document.
 144   * For the time, the interface can't modify document. It can only read it.
 145   * The interface must be allocated with new. It will be released by the
 146   * system when the document will be destroyed.
 147   *
 148   * If you use MFC, don't forget to call AFX_MANAGE_STATE(AfxGetStaticModuleState());
 149   * at the beginning of each callback of the interface.
 150   *
 151   * This interface is instancied by the plugin.
 152   */
 153 class IEditDocumentPlugin
 154 {
 155 public:
 156
 157         /**
 158           * Destructor must uninitialise the plugin interface
 159           */
 160         virtual ~IEditDocumentPlugin () {}
 161
 162         /// Event message
 163
 164         /**
 165           * This method is called to intialise dialog during IEditDocument::bind ().
 166           * Typicaly, this method will create / show some document control tools.
 167           *
 168           * \param is the HWND of the document view.
 169           */
 170         virtual void dialogInit (HWND documentView) = 0;
 171
 172         /**
 173           * Pretranslate message hook.
 174           * This method give a chance to the plugin to pretranslate a message before the main frame.
 175           * Useful for shortcuts etc..
 176           * Default implementation returns "false";
 177           */
 178         virtual bool pretranslateMessage (MSG *pMsg) = 0;
 179
 180         /**
 181           * This method is called when a document's view has been activated / unactivated.
 182           * If activated == true, the view has been activated, else the view is unactivated.
 183           */
 184         virtual void activate (bool activated) = 0;
 185
 186         /**
 187           * Called by the system when a georges value has been changed.
 188           */
 189         virtual void onValueChanged (const char *formName) = 0;
 190
 191         /**
 192           * Called by the system when the current edition node has been changed.
 193           * Call IEditDocument::getActiveNode () to get the active node form name.
 194           */
 195         virtual void onNodeChanged () = 0;
 196 };
 197
 198 /**
 199   * Document access interface.
 200   * By this interface, you can access some values of the document.
 201   *
 202   * This interface is instancied by the system.
 203   */
 204 class IEditDocument
 205 {
 206 public:
 207         /// Get the georges form pointer
 208         virtual UForm *getForm () = 0;
 209
 210         /// Get document DFN filename
 211         virtual void getDfnFilename (std::string &dfnName) = 0;
 212
 213         /// Get the document active node form name. Can return false if the node is not a form node.
 214         virtual bool getActiveNode (std::string &formName) = 0;
 215
 216         /// Refresh the document view.
 217         virtual void refreshView () = 0;
 218
 219         /// Return document filename.
 220         virtual void getFilename (std::string &pathname) = 0;
 221
 222         /// Return document title.
 223         virtual void getTitle (std::string &pathname) = 0;
 224
 225         /**
 226           * Attach a document interface to this document.
 227           *
 228           * \param plugin is the global plugin interface.
 229           * \param docInterface is a document interface allocated with new. It will be released by the document.
 230           */
 231         virtual void bind (NLGEORGES::IEditPlugin *plugin, NLGEORGES::IEditDocumentPlugin *docInterface) = 0;
 232
 233         /// \name Modify the document
 234
 235         /**
 236           * Set a form value with its name. If the node doesn't exist, it is created.
 237           *
 238           * \param value is a reference on the value to set in the form.
 239           * \param name is the form name of the value to set or create.
 240           * \param slot is 0, 1, 2, 3. 0 is the current document, 1 is 1st snapshot, 2 the 2nd snapshot etc..
 241           */
 242         virtual void setValue (const char *value, const char *name, uint slot=0) = 0;
 243 };
 244
 245 } // NLGEORGES
 246
 247 #endif // NLGEORGES_PLUGIN_INTERFACE_H
 248