Fixed the name of the last parameter in the set_time() prototype to match that of...
[synfig.git] / synfig-core / trunk / src / synfig / layer.h
1 /* === S Y N F I G ========================================================= */
2 /*!     \file layer.h
3 **      \brief Layer Class Header
4 **
5 **      $Id: layer.h,v 1.2 2005/01/24 03:08:18 darco Exp $
6 **
7 **      \legal
8 **      Copyright (c) 2002-2005 Robert B. Quattlebaum Jr., Adrian Bentley
9 **
10 **      This package is free software; you can redistribute it and/or
11 **      modify it under the terms of the GNU General Public License as
12 **      published by the Free Software Foundation; either version 2 of
13 **      the License, or (at your option) any later version.
14 **
15 **      This package is distributed in the hope that it will be useful,
16 **      but WITHOUT ANY WARRANTY; without even the implied warranty of
17 **      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 **      General Public License for more details.
19 **      \endlegal
20 */
21 /* ========================================================================= */
22
23 /* === S T A R T =========================================================== */
24
25 #ifndef __SYNFIG_LAYER_H
26 #define __SYNFIG_LAYER_H
27
28 /* === H E A D E R S ======================================================= */
29
30 #include "string_decl.h"
31 #include <map>
32 #include <ETL/handle>
33 #include "real.h"
34 #include "string.h"
35 #include <sigc++/signal.h>
36 #include <sigc++/connection.h>
37 #include "node.h"
38 #include "time.h"
39 #include "guid.h"
40
41 /* === M A C R O S ========================================================= */
42
43 //! \writeme
44 #define SYNFIG_LAYER_MODULE_EXT public: static const char name__[], version__[], cvs_id__[], local_name__[], category__[]; static Layer *create();
45
46 //! Sets the name of the layer
47 #define SYNFIG_LAYER_SET_NAME(class,x) const char class::name__[]=x
48
49 //! Sets the local name of the layer
50 #define SYNFIG_LAYER_SET_LOCAL_NAME(class,x) const char class::local_name__[]=x;
51
52 //! Sets the category of the layer
53 #define SYNFIG_LAYER_SET_CATEGORY(class,x) const char class::category__[]=x
54
55 //! Sets the version string for the layer
56 #define SYNFIG_LAYER_SET_VERSION(class,x) const char class::version__[]=x
57
58 //! Sets the CVS ID string for the layer
59 #define SYNFIG_LAYER_SET_CVS_ID(class,x) const char class::cvs_id__[]=x
60
61 //! \writeme
62 #define SYNFIG_LAYER_INIT(class) synfig::Layer* class::create() { return new class(); }
63
64 //! \writeme
65 #define IMPORT_PLUS(x,y) if(param==#x && value.same_as(x)) { value.put(&x);{y;}return true;}
66
67 //! \writeme
68 #define IMPORT_AS(x,y) if(param==y && value.same_as(x)) { value.put(&x); return true;}
69
70 //! \writeme
71 #define IMPORT(x) IMPORT_AS(x,#x)
72
73 //! \writeme
74 #define EXPORT_AS(x,y) if(param==y) { return ValueBase(x); }
75
76 //! \writeme
77 #define EXPORT(x)                                       EXPORT_AS(x,#x)
78
79 //! \writeme
80 #define EXPORT_NAME()   if(param=="Name" || param=="name" || param=="name__") { return name__; } if(param=="local_name__") { return local_name__; }
81
82 //! \writeme
83 #define EXPORT_VERSION()        if(param=="Version" || param=="version" || param=="version__") { return version__; }
84
85 /* === T Y P E D E F S ===================================================== */
86
87 /* === C L A S S E S & S T R U C T S ======================================= */
88
89 namespace synfig {
90
91 class Canvas;
92 class Vector;
93 typedef Vector Point;
94 class Canvas;
95 class ParamDesc;
96 class ParamVocab;
97 class ValueNode;
98 class ValueBase;
99 class Time;
100 class Surface;
101 class RendDesc;
102 class ProgressCallback;
103 class Context;
104 class Color;
105 class Transform;
106 class Rect;
107 class GUID;
108
109
110 /*!     \class Layer
111 **      \todo writeme
112 **      \see Canvas
113 */
114 class Layer : public Node
115 {
116         friend class ValueNode;
117         friend class Context;
118
119         /*
120  --     ** -- T Y P E S -----------------------------------------------------------
121         */
122
123 public:
124
125         //! Type that represents a pointer to a layer's constructor
126         typedef Layer* (*Factory)();
127
128         struct BookEntry
129         {
130                 Factory factory;
131                 String name;
132                 String local_name;
133                 String category;
134                 String cvs_id;
135                 String version;
136                 BookEntry() { }
137                 BookEntry(Factory factory, const String& name,const String& local_name,const String& category,const String& cvs_id,const String& version):
138                         factory(factory),name(name),local_name(local_name),category(category),cvs_id(cvs_id),version(version) { }
139         };
140
141         typedef std::map<String,BookEntry> Book;
142
143         static void register_in_book(const BookEntry &);
144
145         static Book& book();
146
147         static bool subsys_init();
148
149         static bool subsys_stop();
150
151         typedef std::map<String,ValueBase> ParamList;
152
153         typedef etl::handle<Layer> Handle;
154
155         typedef etl::loose_handle<Layer> LooseHandle;
156
157         typedef etl::handle<const Layer> ConstHandle;
158
159         typedef std::map<String,etl::rhandle<ValueNode> > DynamicParamList;
160
161         //! A list type which describes all the parameters that a layer has.
162         /*! \see get_param_vocab() */
163         typedef ParamVocab Vocab;
164
165         /*
166  --     ** -- D A T A -------------------------------------------------------------
167         */
168
169 private:
170
171         /*! \c true if the layer is visible, \c is it is to be skipped
172         **      \see set_active(), enable(), disable, active()
173         */
174         bool active_;
175
176         //! Handle to the canvas to which this layer belongs
177         etl::loose_handle<Canvas> canvas_;
178
179         DynamicParamList dynamic_param_list_;
180
181         //! A description of what this layer does
182         String description_;
183
184         //! \writeme
185         float z_depth_;
186
187         //! \writeme
188         mutable Time dirty_time_;
189
190         //! Contains the name of the group that this layer belongs to
191         String group_;
192
193         //! \writeme
194         sigc::connection parent_death_connect_;
195
196         /*
197  -- ** -- S I G N A L S -------------------------------------------------------
198         */
199
200 private:
201
202         //!     Status Changed
203         sigc::signal<void> signal_status_changed_;
204
205         //!     Parameter changed
206         sigc::signal<void,String> signal_param_changed_;
207
208         //!     Description Changed
209         sigc::signal<void> signal_description_changed_;
210
211         //!     Moved
212         sigc::signal<void, int, etl::handle<Canvas> > signal_moved_;
213
214         sigc::signal<void, String> signal_added_to_group_;
215
216         sigc::signal<void, String> signal_removed_from_group_;
217
218         /*
219  -- ** -- S I G N A L   I N T E R F A C E -------------------------------------
220         */
221
222 public:
223
224         //!     Status Changed
225         sigc::signal<void>& signal_status_changed() { return signal_status_changed_; }
226
227         //!     Parameter changed
228         sigc::signal<void,String>& signal_param_changed() { return signal_param_changed_; }
229
230         //!     Description Changed
231         sigc::signal<void>& signal_description_changed() { return signal_description_changed_;}
232
233         //!     Moved
234         sigc::signal<void, int, etl::handle<Canvas> >& signal_moved() { return signal_moved_; }
235
236         sigc::signal<void, String>& signal_added_to_group() { return signal_added_to_group_; }
237
238         sigc::signal<void, String>& signal_removed_from_group() { return signal_removed_from_group_; }
239
240         /*
241  --     ** -- C O N S T R U C T O R S ---------------------------------------------
242         */
243
244 protected:
245
246         Layer();
247
248 public:
249         virtual ~Layer();
250
251         /*
252  --     ** -- M E M B E R   F U N C T I O N S -------------------------------------
253         */
254
255 public:
256
257         virtual void on_canvas_set();
258
259         //! Adds this layer to the given layer group
260         void add_to_group(const String&);
261
262         //! Removes this layer from the given layer group
263         void remove_from_group(const String&);
264
265         //! Removes this layer from all layer groups
266         void remove_from_all_groups();
267
268         //! Gets the name of the group that this layer belongs to
269         String get_group()const;
270
271         //! \todo writeme
272         //DynamicParamList &dynamic_param_list() { return dynamic_param_list_; }
273
274         //! \todo writeme
275         const DynamicParamList &dynamic_param_list()const { return dynamic_param_list_; }
276
277         bool connect_dynamic_param(const String& param, etl::loose_handle<ValueNode>);
278         bool disconnect_dynamic_param(const String& param);
279
280         //! Enables the layer for rendering (Making it \em active)
281         void enable() { set_active(true); }
282
283         //! Disables the layer for rendering. (Making it \em inactive)
284         /*! When a layer is disabled, it will be skipped when the
285         **      canvas is rendered. */
286         void disable() { set_active(false); }
287
288         //! Sets the 'active' flag for the Layer to the state described by \a x
289         /*! When a layer is disabled, it will be skipped when the
290         **      canvas is rendered. */
291         void set_active(bool x);
292
293         //! Returns that status of the 'active' flag
294         bool active()const { return active_; }
295
296         //! Returns the position of the layer in the canvas.
297         /*! Returns negative on error */
298         int get_depth()const;
299
300         //! \writeme
301         float get_z_depth()const { return z_depth_; }
302
303         //! \writeme
304         float get_z_depth(const synfig::Time& t)const;
305
306         //! \writeme
307         void set_z_depth(float x) { z_depth_=x; }
308
309         //! Sets the Canvas that this Layer is a part of
310         void set_canvas(etl::loose_handle<Canvas> canvas);
311
312         //! Returns a handle to the Canvas to which this Layer belongs
313         etl::loose_handle<Canvas> get_canvas()const;
314
315         //! \writeme
316         const String& get_description()const { return description_; }
317
318         //! \writeme
319         void set_description(const String& x);
320
321         /*
322  --     ** -- V I R T U A L   F U N C T I O N S -----------------------------------
323         */
324
325 public:
326         virtual Rect get_bounding_rect()const;
327
328         virtual Rect get_full_bounding_rect(Context context)const;
329
330         //! Returns a string containing the name of the Layer
331         virtual String get_name()const;
332
333         //! Returns a string containing the localized name of the Layer
334         virtual String get_local_name()const;
335
336         //! Gets the paramater vocabulary
337         virtual Vocab get_param_vocab()const;
338
339         //! Gets the version string for this layer
340         virtual String get_version()const;
341
342         //! \writeme
343         virtual etl::handle<Transform> get_transform()const;
344
345         //! Sets the virtual version to use for backwards-compatibility
346         /*!
347         **      \see reset_version() */
348         virtual bool set_version(const String &ver);
349
350         //! Resets the virtual version
351         /*!
352         **      \see set_version() */
353         virtual void reset_version();
354
355         //!     Sets the parameter described by \a param to \a value.
356         /*!     \param param The name of the parameter to set
357         **      \param value What the parameter is to be set to.
358         **      \return \c true on success, \c false upon rejection or failure.
359         **              If it returns \c false, then the Layer is assumed to remain unchanged.
360         **      \sa get_param()
361         **      \todo \a param should be of the type <tt>const String \&param</tt>
362         */
363         virtual bool set_param(const String &param, const ValueBase &value);
364
365         //!     Sets a list of parameters
366         virtual bool set_param_list(const ParamList &);
367
368         //! Get the value of the specified parameter.
369         /*!     \return The requested parameter value, or (upon failure) a NIL ValueBase.
370         **      \sa set_param()
371         **      \todo \a param should be of the type <tt>const String \&</tt>
372         */
373         virtual ValueBase get_param(const String &param)const;
374
375         //! Get a list of all of the parameters and their values
376         virtual ParamList get_param_list()const;
377
378         //! Sets the \a time for the selected Layer and those under it
379         /*!     \param context          Context iterator refering to next Layer.
380         **      \param time                     writeme
381         **      \see Handle::set_time()
382         */
383         virtual void set_time(Context context, Time time)const;
384
385         //! Sets the \a time for the selected Layer and those under it for a specific \a point
386         /*!     \param context          Context iterator refering to next Layer.
387         **      \param time                     writeme
388         **      \param point            writeme
389         **      \see Handle::set_time()
390         **      \todo \a point should be of the type <tt>const Point \&</tt> */
391         virtual void set_time(Context context, Time time, const Point &point)const;
392
393         //! Gets the color of the Canvas at \a pos
394         /*!     \param context          Context iterator refering to next Layer.
395         **      \param pos              Point which indicates where the Color should come from
396         **      \see Handle::get_color()
397         */
398         virtual Color get_color(Context context, const Point &pos)const;
399
400         //! Renders the Canvas to the given Surface in an accelerated manner
401         /*!     \param context          Context iterator refering to next Layer.
402         **      \param surface          Pointer to Surface to render to.
403         **      \param quality          The requested quality-level to render at.
404         **      \param renddesc         The associated RendDesc.
405         **      \param cb                       Pointer to callback object. May be NULL if there is no callback.
406         **      \return \c true on success, \c false on failure
407         **      \see Handle::accelerated_render()
408         */
409         virtual bool accelerated_render(Context context,Surface *surface,int quality, const RendDesc &renddesc, ProgressCallback *cb)const;
410
411         //! Checks to see if a part of the layer is directly under \a point
412         /*!     \param context          Context iterator refering to next Layer.
413         **      \param point            The point to check
414         **      \return         The handle of the layer under \a point. If there is not
415         **                              a layer under \a point, then returns an empty handle. */
416         virtual Handle hit_check(Context context, const Point &point)const;
417
418         //! Duplicates the Layer
419         virtual Handle clone(const GUID& deriv_guid=GUID())const;
420
421         //! Duplicates the Layer without duplicating the value nodes
422         virtual Layer *simple_clone()const;
423
424 protected:
425
426         //! This is called whenever a parameter is changed
427         virtual void on_changed();
428
429         //! Called to figure out the animation time information
430         virtual void get_times_vfunc(Node::time_set &set) const;
431
432         /*
433  --     ** -- S T A T I C  F U N C T I O N S --------------------------------------
434         */
435
436 public:
437
438         //! Creates a Layer of type \a type
439         /*!     If the Layer type is unknown, then a Mime layer is created in its place.
440         **      \param type     A string describing the name of the layer to construct.
441         **      \return Always returns a handle to a new Layer.
442         **      \see Mime
443         */
444         static Layer::LooseHandle create(const String &type);
445
446 }; // END of class Layer
447
448 }; // END of namespace synfig
449
450
451 /* === E N D =============================================================== */
452
453 #endif