Some documentation in the module.h file
[synfig.git] / synfig-core / src / synfig / module.h
1 /* === S Y N F I G ========================================================= */
2 /*!     \file synfig/module.h
3 **      \brief writeme
4 **
5 **      $Id$
6 **
7 **      \legal
8 **      Copyright (c) 2002-2005 Robert B. Quattlebaum Jr., Adrian Bentley
9 **      Copyright (c) 2007, 2008 Chris Moore
10 **
11 **      This package is free software; you can redistribute it and/or
12 **      modify it under the terms of the GNU General Public License as
13 **      published by the Free Software Foundation; either version 2 of
14 **      the License, or (at your option) any later version.
15 **
16 **      This package is distributed in the hope that it will be useful,
17 **      but WITHOUT ANY WARRANTY; without even the implied warranty of
18 **      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 **      General Public License for more details.
20 **      \endlegal
21 */
22 /* ========================================================================= */
23
24 /* === S T A R T =========================================================== */
25
26 #ifndef __SYNFIG_MODULE_H
27 #define __SYNFIG_MODULE_H
28
29 /* === H E A D E R S ======================================================= */
30
31 #include "general.h"
32 #include <ETL/handle>
33 #include <map>
34 #include "string.h"
35 #include "releases.h"
36 #include <utility>
37 #include "vector.h"
38 #include "color.h"
39 #include "layer.h"
40 #include "canvas.h"
41
42 //#include "value.h"
43
44 /* === M A C R O S ========================================================= */
45
46 //! Marks the start of a module description
47 #define MODULE_DESC_BEGIN(x) struct x##_modclass : public synfig::Module { x##_modclass(synfig::ProgressCallback *callback=NULL);
48
49 //! Sets the localized name of the module
50 #define MODULE_NAME(x)                  virtual const char * Name() { return x; }
51
52 //! Sets a localized description of the module
53 #define MODULE_DESCRIPTION(x)   virtual const char * Desc() { return x; }
54
55 //! Sets the name of the module's author
56 #define MODULE_AUTHOR(x)                virtual const char * Author() { return x; }
57
58 //! Sets the version string for the module
59 #define MODULE_VERSION(x)               virtual const char * Version() { return x; }
60
61 //! Sets the copyright string for the module
62 #define MODULE_COPYRIGHT(x)             virtual const char * Copyright() { return x; }
63
64 //! Describes the module's construction function
65 #define MODULE_CONSTRUCTOR(x)   bool constructor_(synfig::ProgressCallback *cb) { return x(cb); }
66
67 //! Describes the module's destruction function
68 #define MODULE_DESTRUCTOR(x)    virtual void destructor_() { return x(); }
69
70 //! Marks the end of a module description
71 #define MODULE_DESC_END };
72
73 //#if 0
74 #ifdef __APPLE__
75 //! Marks the start of a module's inventory
76 #define MODULE_INVENTORY_BEGIN(x)  extern "C" {         \
77         synfig::Module* _##x##_LTX_new_instance(synfig::ProgressCallback *cb) \
78         { if(SYNFIG_CHECK_VERSION()){x##_modclass *mod=new x##_modclass(cb); mod->constructor_(cb); return mod; }\
79         if(cb)cb->error(#x": Unable to load module due to version mismatch."); return NULL; } \
80         }; x##_modclass::x##_modclass(synfig::ProgressCallback */*cb*/) {
81 #else
82 //! Marks the start of a module's inventory
83 #define MODULE_INVENTORY_BEGIN(x)  extern "C" {         \
84         synfig::Module* x##_LTX_new_instance(synfig::ProgressCallback *cb) \
85         { if(SYNFIG_CHECK_VERSION()){x##_modclass *mod=new x##_modclass(cb); mod->constructor_(cb); return mod; }\
86         if(cb)cb->error(#x": Unable to load module due to version mismatch."); return NULL; } \
87         }; x##_modclass::x##_modclass(synfig::ProgressCallback */*cb*/) {
88 #endif
89
90 //! Marks the start of the layers in the module's inventory
91 #define BEGIN_LAYERS {
92
93 //! DEPRECATED - use #INCLUDE_LAYER(class)
94 // Really? ^^ The INCLUDE_LAYER(class) macro is defined in a cpp file and
95 // is undefined a few lines later. In fact the INCLUDE_LAYER is only
96 // used in the layer.cpp file and the functionality is the same. Even
97 // more, I think that we should use register_in_book call because maybe
98 // the Layer class would like to do something else when register the class.
99 //! Register a Layer class in the book of layers
100 #define LAYER(class)                                                                                                                                                    \
101         synfig::Layer::register_in_book(                                                                                                                        \
102                 synfig::Layer::BookEntry(class::create,                                                                                                 \
103                                                                  class::name__,                                                                                                 \
104                                                                  dgettext("synfig", class::local_name__),                                               \
105                                                                  class::category__,                                                                                             \
106                                                                  class::cvs_id__,                                                                                               \
107                                                                  class::version__));
108
109 //! Register a Layer class in the book of layers with an alias
110 #define LAYER_ALIAS(class,alias)                                                                                                                                \
111         synfig::Layer::register_in_book(                                                                                                                        \
112                 synfig::Layer::BookEntry(class::create,                                                                                                 \
113                                                                  alias,                                                                                                                 \
114                                                                  alias,                                                                                                                 \
115                                                                  CATEGORY_DO_NOT_USE,                                                                                   \
116                                                                  class::cvs_id__,                                                                                               \
117                                                                  class::version__));
118
119 //! Marks the end of the layers in the module's inventory
120 #define END_LAYERS }
121
122 //! Marks the start of the targets in the module's inventory
123 #define BEGIN_TARGETS {
124
125 #define TARGET(x)                                                                                                               \
126         synfig::Target::book()[synfig::String(x::name__)].factory =                     \
127                 reinterpret_cast<synfig::Target::Factory> (x::create);                  \
128         synfig::Target::book()[synfig::String(x::name__)].filename =            \
129                 synfig::String(x::ext__);                                                                               \
130         synfig::Target::book()[synfig::String(x::name__)].target_param =        \
131                 synfig::TargetParam();                                                                                                  \
132         synfig::Target::ext_book()[synfig::String(x::ext__)]=x::name__;
133
134 #define TARGET_EXT(x,y) synfig::Target::ext_book()[synfig::String(y)]=x::name__;
135
136 //! Marks the end of the targets in the module's inventory
137 #define END_TARGETS }
138
139 //! Marks the start of the importers in the module's inventory
140 #define BEGIN_IMPORTERS {
141
142 //! Register an Importer class in the book of importers by the default extension
143 #define IMPORTER(x) synfig::Importer::book()[synfig::String(x::ext__)]=x::create;
144
145 //!Register an Importer class in the book of importers by one file extension string
146 #define IMPORTER_EXT(x,y) synfig::Importer::book()[synfig::String(y)]=x::create;
147
148 //! Marks the end of the importers in the module's inventory
149 #define END_IMPORTERS }
150
151 //! Marks the start of the valuenodes in the module's inventory
152 #define BEGIN_VALUENODES { synfig::LinkableValueNode::Book &book(synfig::LinkableValueNode::book());
153
154 //! Registers a valuenode that is defined in the module's inventory
155 #define VALUENODE(class,name,local,version)                                                                                                             \
156         book[name].factory=reinterpret_cast<synfig::LinkableValueNode::Factory>(&class::create);        \
157         book[name].check_type=&class::check_type;                                                                                                       \
158         book[name].local_name=local;                                                                                                                            \
159         book[name].release_version=version;
160
161 //! Marks the end of the valuenodes in the module's inventory
162 #define END_VALUENODES }
163
164 //! Marks the end of a module's inventory
165 #define MODULE_INVENTORY_END    }
166
167 /* === T Y P E D E F S ===================================================== */
168
169 /* === C L A S S E S & S T R U C T S ======================================= */
170
171 namespace synfig {
172
173 class ProgressCallback;
174
175 /*!     \class Module
176 **      \todo writeme
177 */
178 class Module : public etl::shared_object
179 {
180 public:
181         bool constructor_(synfig::ProgressCallback */*cb*/) { return true; }
182         virtual void destructor_() { }
183
184         typedef etl::handle<Module> Handle;
185         typedef etl::loose_handle<Module> LooseHandle;
186         typedef etl::handle<const Module> ConstHandle;
187
188 public:
189         //! Type that represents a pointer to a Module's constructor by name.
190         //! As a pointer to the member, it represents a constructor of importer.
191         typedef Module* (*constructor_type)(ProgressCallback *);
192         typedef std::map<String, Handle > Book;
193 private:
194         static Book* book_;
195 public:
196         static Book& book();
197
198         static bool subsys_init(const String &prefix);
199         static bool subsys_stop();
200         static void register_default_modules(ProgressCallback *cb=NULL);
201
202         static void Register(Handle mod);
203         static bool Register(const String &module_name, ProgressCallback *cb=NULL);
204         static inline void Register(Module *mod) { Register(Handle(mod)); }
205
206         virtual const char * Name() { return " "; }
207         virtual const char * Desc() { return " "; }
208         virtual const char * Author() { return " "; }
209         virtual const char * Version() { return " "; }
210         virtual const char * Copyright() { return SYNFIG_COPYRIGHT; }
211
212         virtual ~Module() { destructor_(); }
213 };
214
215 }; // END of namespace synfig
216
217 /* === E N D =============================================================== */
218
219 #endif