class GUID;
/*! \class Canvas
-** \todo writeme
+** \brief Canvas is a double ended queue of Layers. It is the base class
+* for a Synfig document.
+*
+* As a node it inherits all the parent child relationship and the GUID
+* methods. As a double queue it allows insertion and deletion of Layers
+* and can access to the layers on the queue easily.
*/
class Canvas : public CanvasBase, public Node
{
/*! \see value_node_list(), find_value_node() */
ValueNodeList value_node_list_;
- //! \writeme
+ //! Contains a list of Keyframes that are in the Canvas
+ /*! \see keyframe_list()*/
KeyframeList keyframe_list_;
//! A handle to the parent canvas of this canvas.
//! Contains the value of the last call to set_time()
Time cur_time_;
- //! \writeme
+ //! Map of external Canvases used in this Canvas
mutable std::map<String,Handle> externals_;
//! This flag is set if this canvas is "inline"
bool is_inline_;
+ //! True if the Canvas properties has changed
mutable bool is_dirty_;
+ //! It is set to true when synfig::optimize_layers is called
bool op_flag_;
//! Layer Group database
std::map<String,std::set<etl::handle<Layer> > > group_db_;
- //! Layer Connection database
+ //! Layer Signal Connection database. Seems to be unused.
std::map<etl::loose_handle<Layer>,std::vector<sigc::connection> > connections_;
/*
//! ValueBasenode Changed
sigc::signal<void, etl::handle<ValueNode> > signal_value_node_changed_;
-
+ //! ValueBasenode Renamed
sigc::signal<void, etl::handle<ValueNode> > signal_value_node_renamed_;
-
+ //! Child Value Node Added. Used in Dynamic List Value Nodes
sigc::signal<void, etl::handle<ValueNode>, etl::handle<ValueNode> > signal_value_node_child_added_;
-
+ //! Child Value Node Removed. Used in Dynamic List Value Nodes
sigc::signal<void, etl::handle<ValueNode>, etl::handle<ValueNode> > signal_value_node_child_removed_;
/*
//! Metadata Changed
sigc::signal<void>& signal_meta_data_changed(const String& key) { return signal_map_meta_data_changed_[key]; }
-
+ //! Value Node Changed
sigc::signal<void, etl::handle<ValueNode> >& signal_value_node_changed() { return signal_value_node_changed_; }
-
+ //! Value Node Renamed
sigc::signal<void, etl::handle<ValueNode> >& signal_value_node_renamed() { return signal_value_node_renamed_; }
- //! Dirty
+ //! Dirty
sigc::signal<void>& signal_dirty() { return signal_changed(); }
- //! \writeme
+ //! Child Value Node Added
sigc::signal<void, etl::handle<ValueNode>, etl::handle<ValueNode> >& signal_value_node_child_added() { return signal_value_node_child_added_; }
- //! \writeme
+ //! Child Value Node Removed
sigc::signal<void, etl::handle<ValueNode>, etl::handle<ValueNode> >& signal_value_node_child_removed() { return signal_value_node_child_removed_; }
/*
*/
protected:
-
+ //! Canvas constructor by Canvas name
Canvas(const String &name);
public:
//! Renames the given group
void rename_group(const String&old_name,const String&new_name);
- //! \writeme
+ //! Returns true if the Canvas is in line
bool is_inline()const { return is_inline_; }
//! Returns a handle to the RendDesc for this Canvas
//! Removes a meta data key
void erase_meta_data(const String& key);
- //! \writeme
+ //! Gets the relative ID string for an ancestor Canvas
String get_relative_id(etl::loose_handle<const Canvas> x)const;
- //! \internal \writeme
+ //! Gets the relative ID string for an ancestor Canvas. Don't call it directly
String _get_relative_id(etl::loose_handle<const Canvas> x)const;
//! Returns \c true if the Canvas is a root Canvas. \c false otherwise
/*! The returned handle will be empty if this is a root canvas */
LooseHandle parent()const { return parent_; }
+ //! Returns a handle to the root Canvas
LooseHandle get_root()const;
//! Returns a list of all child canvases in this canvas
//! Sets the time for all the layers in the canvas
void set_time(Time t)const;
- //! \writeme
+ //! Returns the current time of the Canvas
Time get_time()const { return cur_time_; }
//! Returns the number of layers in the canvas
*/
ValueNode::ConstHandle find_value_node(const String &id)const;
- //! \writeme
+ //! Adds a Value node by its Id.
+ /*! Throws an error if the Id is not
+ //! correct or the Value node is already exported
+ **/
void add_value_node(ValueNode::Handle x, const String &id);
//! writeme
//void rename_value_node(ValueNode::Handle x, const String &id);
- //! \writeme
+ //! Removes a Value Node from the Canvas by its Handle
void remove_value_node(ValueNode::Handle x);
- //! \writeme
+ //! Removes a Value Node from the Canvas by its Id
void remove_value_node(const String &id) { remove_value_node(find_value_node(id)); }
//! Finds a child Canvas in the Canvas with the given \a name
//! Adds the given canvas as a child
Handle add_child_canvas(Handle child_canvas, const String &id);
+ //! Remove Child Canvas by its handle. If Current canvas is a child of a parent
+ //! it ask to the parent to remove the Child canvas.
void remove_child_canvas(Handle child_canvas);
+ //! Finds a Layer by its position.
+ //! \see get_context()
etl::handle<Layer> find_layer(const Point &pos);
+ //! Gets the depth of a particular Layer by its handle
int get_depth(etl::handle<Layer>)const;
+ //! Retireves the first layer of the double queue of Layers
Context get_context()const;
-
+ //! Returns the last Canvas layer queue iterator. Notice that it
+ /*! overrides the std::end() member that would return an interator
+ * just past the last element of the queue.*/
iterator end();
-
+ //! Returns the last Canvas layer queue const_iterator. Notice that it
+ /*! overrides the std::end() member that would return an interator
+ * just past the last element of the queue.*/
const_iterator end()const;
-
+ //! Returns the last Canvas layer queue reverse iterator. Notice that it
+ /*! overrides the std::rbegin() member that would return an interator
+ * just past the last element of the queue.*/
reverse_iterator rbegin();
-
+ //! Returns the last Canvas layer queue reverse const iterator. Notice that it
+ /*! overrides the std::rbegin() member that would return an interator
+ * just past the last element of the queue.*/
const_reverse_iterator rbegin()const;
-
+ //! Returns last layer in Canvas layer stack
etl::handle<Layer> &back();
-
+ //! Returns last layer in Canvas layer stack
+ const etl::handle<Layer> &back()const;
+ //! Inserts a layer just before the last layer.
+ //! \see end(), insert(iterator iter,etl::handle<Layer> x)
void push_back(etl::handle<Layer> x);
-
+ //! Inserts a layer just at the beggining of the Canvas layer dqueue
void push_front(etl::handle<Layer> x);
-
+ //! Inserts a layer in the last position of the Canvas layer dqueue
+ //! Uses the standard methods and doesn't perform any parentship
+ //! or signal update
void push_back_simple(etl::handle<Layer> x);
-
+ //! Inserts a layer before the given position by \iter and performs
+ //! the proper child parent relationships and signals update
void insert(iterator iter,etl::handle<Layer> x);
+ //! Removes a layer from the Canvas layer dqueue and its group and parent
+ //! relatioship. Although it is not already used, it clears the connections
+ //! see connections_
void erase(iterator iter);
-
- const etl::handle<Layer> &back()const;
-
+ //! Sets to be a inline canvas of a given Canvas \parent. The inline
+ //! Canvas inherits the groups and the render description.
+ //! \see rend_desc()
void set_inline(LooseHandle parent);
-
+ //! Returns a Canvas handle with "Untitled" as ID
static Handle create();
-
+ //! Creates an inline Canvas for a given Canvas \parent
static Handle create_inline(Handle parent);
-
+ //! Clones (copies) the Canvas if it is inline.
Handle clone(const GUID& deriv_guid=GUID())const;
-
+ //! Stores the external canvas by its file name and the Canvas handle
void register_external_canvas(String file, Handle canvas);
#ifdef _DEBUG
#endif // _DEBUG
private:
+ //! Adds a \layer to a group given by its \group string to the group
+ //! database
void add_group_pair(String group, etl::handle<Layer> layer);
+ //! Removes a \layer from a group given by its \group string to the group
+ //! database
void remove_group_pair(String group, etl::handle<Layer> layer);
+ //! Seems to be used to add the stored signals connections of the layers.
+ //! \see connections_
void add_connection(etl::loose_handle<Layer> layer, sigc::connection connection);
+ //! Seems to be used to disconnect the stored signals connections of the layers.
+ //! \see connections_
void disconnect_connections(etl::loose_handle<Layer> layer);
protected:
+ //! Sets the Canvas to dirty and calls Node::on_changed()
virtual void on_changed();
+ //! Collects the times (TimePoints) of the Layers of the Canvas and
+ //! stores it in the passed Time Set \set
+ //! \see Node::get_times()
virtual void get_times_vfunc(Node::time_set &set) const;
}; // END of class Canvas
+ //! Optimize layers based on its calculated Z depth to perform a quick
+ //! render of the layers to the output.
void optimize_layers(Time time, Context context, Canvas::Handle op_canvas, bool seen_motion_blur=false);