Papyrus::Group Class Reference

A group is a container for ordered collections of shapes, with the shapes at the top (front of the container) drawn last and the shapes at the bottom drawn first (end of the container). More...

#include <group.h>

Inheritance diagram for Papyrus::Group:

[legend]

List of all members.

Public Types
typedef std::list < Drawable::pointer >	Layer
	A layer is a list of child items.
typedef std::map< int, Layer >	Layers
	Layers are drawn starting for the lowest numbered layer to the highest layer.
Public Member Functions
	PAPYRUS_DRAWABLE (Group)
virtual	~Group ()
const Glib::ustring &	title () const
void	set_title (const Glib::ustring &t)
sigc::signal< void > &	signal_title_changed ()
const Glib::ustring &	description () const
void	set_description (const Glib::ustring &d)
sigc::signal< void > &	signal_description_changed ()
virtual void	freeze ()
	Reimplements Drawable::freeze() to also freeze children using the m_frozen_by_parent flag.
virtual void	thaw (bool force_redraw=false)
	Reimplements Drawable::thaw() to also thaw children using the m_frozen_by_parent flag.
virtual bool	is_intermediate_drawing_enabled ()
virtual void	enable_intermediate_drawing (bool enabled=true)
virtual void	set (const AttributeValueMap &avmap)
virtual bool	add (Drawable::pointer item, int layer=0)
	Adds a child to a given layer.
virtual bool	remove (Drawable::pointer object)
	Removes the object from the group.
virtual bool	remove (Drawable *object)
	The main purpose of this method is so that a child may use the this pointer to remove itself on destruction.
virtual bool	clear ()
	Clears all layers and children from the group.
Drawable::pointer	child (const Glib::ustring &id) const
	Returns the first child named id or a null pointer if no child found.
template<class T >
PapyrusPointer< T >	child (const Glib::ustring &id) const
	Returns the first child named id dynamically typecast to the template parameter type or a null pointer of the template parameter type if no child found of the requested type.
virtual bool	raise (Drawable::pointer item, int steps=1)
	Raises the item up n steps in its layer.
virtual bool	raise_to_top (Drawable::pointer item)
	Raises the item up to the top of its layer.
virtual bool	lower (Drawable::pointer item, int steps=1)
	Lowers the item down n steps in its layer.
virtual bool	lower_to_bottom (Drawable::pointer item)
	Lowers the item up to the bottom of its layer.
virtual bool	move_to_layer (int layer, Drawable::pointer item)
	Moves an item to a specific layer.
size_t	size () const
	Returns the number of children in the group.
const Layers &	layers () const
	Returns the layers in this group.
const Layer &	layer (int l) const throw (std::out_of_range)
	Returns the requested layer l or throws std::out_of_range if the layer doesn't exist.
bool	has_layer (int l)
	True if this group has layer l.
bool	has (Drawable::pointer d) const
	True if this group has the specified drawable in any layer.
virtual bool	inside (double x, double y)
	Overrides parent method for determining whether (x,y) is inside the drawable.
virtual Selection	select (double x, double y, unsigned depth=1)
sigc::signal< void, Drawable::pointer > &	signal_child_added ()
sigc::signal< void, Drawable::pointer > &	signal_child_removed ()
virtual bool	is_group ()
Fill::pointer	fill ()
	The default fill that is applied to all children derived from Shape.
void	set_fill (Fill::pointer fill)
	Sets the default fill for all children derived from Shape.
void	set_fill (Paint::pointer paint)
void	set_fill (const RGBA &color)
void	set_fill (const Glib::ustring &fill)
Stroke::pointer	stroke ()
	The default stroke that is applied to all children derived from Shape.
void	set_stroke (Stroke::pointer stroke)
	Sets the default stroke for all children derived from Shape.
void	set_stroke (Paint::pointer paint)
void	set_stroke (const RGBA &color)
void	set_stroke (const Glib::ustring &stroke)
const PaintDictionary &	paint_dictionary () const
	Returns this group's paint dictionary.
Paint::pointer	lookup_paint (const Glib::ustring &name) const
	Lookup the named paint in the paint dictionary.
void	add_paint_to_dictionary (const Glib::ustring &name, Paint::pointer p)
	Adds or replaces the named paint in the paint dictionary.
void	remove_paint_from_dictionary (const Glib::ustring &name)
	Removes the named paint from the dictionary.
void	clear_paint_dictionary ()
	Clears all paints in the dictionary.
sigc::signal< void, const Glib::ustring & > &	signal_paint_added_to_dictionary ()
	Signal emitted when a paint is added to the dictionary.
sigc::signal< void, const Glib::ustring & > &	signal_paint_removed_from_dictionary ()
	Signal emitted when a paint is removed from the dictionary.
const DrawableDictionary &	drawable_dictionary () const
	Returns this group's drawable dictionary.
Drawable::pointer	lookup_drawable (const Glib::ustring &name) const
	Lookup the named drawable.
void	add_drawable_to_dictionary (const Glib::ustring &name, Drawable::pointer p)
	Adds or replaces the named drawable in the drawable dictionary.
void	remove_drawable_from_dictionary (const Glib::ustring &name)
	Removes the named drawable from the dictionary.
void	clear_drawable_dictionary ()
	Clears all drawables in the dictionary.
sigc::signal< void, const Glib::ustring & > &	signal_drawable_added_to_dictionary ()
	Signal emitted when a drawable is added to the dictionary.
sigc::signal< void, const Glib::ustring & > &	signal_drawable_removed_from_dictionary ()
	Signal emitted when a drawable is removed from the dictionary.
virtual Glib::ustring	svg (unsigned depth=0)
Static Public Member Functions
static pointer	create (const Glib::ustring &id=Glib::ustring())
static pointer	create (const AttributeValueMap &avmap)
Protected Types
typedef std::map < Drawable::pointer, sigc::connection >	Connections
Protected Member Functions
	Group (const Glib::ustring &id=Glib::ustring())
	Group (const AttributeValueMap &avmap)
virtual void	on_child_changed (Drawable::pointer child)
	Virtual method called when a child is changed.
virtual Region	calculate_extents (const Matrix &m=Matrix::Identity, ExtentsPerformance ep=EXTENTS_QUICK) const
void	on_child_redraw (double x, double y, double w, double h, Drawable::pointer child)
virtual void	draw (Context &cairo) const
void	freeze_children ()
void	thaw_children (bool force_redraw=false)
Protected Attributes
Layers	m_layers
size_t	m_size
Connections	m_redraw_connections
Connections	m_changed_connections
sigc::signal< void, Drawable::pointer >	m_signal_child_added
sigc::signal< void, Drawable::pointer >	m_signal_child_removed
Fill::pointer	m_fill
Stroke::pointer	m_stroke
PaintDictionary	m_paint_dictionary
sigc::signal< void, const Glib::ustring & >	m_signal_paint_added_to_dictionary
sigc::signal< void, const Glib::ustring & >	m_signal_paint_removed_from_dictionary
DrawableDictionary	m_drawable_dictionary
sigc::signal< void, const Glib::ustring & >	m_signal_drawable_added_to_dictionary
sigc::signal< void, const Glib::ustring & >	m_signal_drawable_removed_from_dictionary
Glib::ustring	m_title
sigc::signal< void >	m_signal_title_changed
Glib::ustring	m_description
sigc::signal< void >	m_signal_description_changed
bool	m_intermediate_drawing_enabled
Private Member Functions
void	on_child_changed_proxy (Drawable::pointer child)
	When a child is added this is the actual method connected to the child's changed signal and in turn this method calls the virtual method on_child_changed().
Friends
class	Canvas

Detailed Description

A group is a container for ordered collections of shapes, with the shapes at the top (front of the container) drawn last and the shapes at the bottom drawn first (end of the container).

The current implementation is very simplistic, and doesn't even try to do anything smart like taking into account occlusion or anything else. Instead all objects are simply drawn and it is left to cairo to take care of efficiency. At the current time there are no plans to improve this behavior, since it runs 'fast enough' for now.

Groups are also useful since transforms upon the group are also applied to the contained objects. Thus, scaling, translating or rotating a group has the same effect as performing those operations upon each member of the group.

Group contain an ordered set of shapes

Author:: Rick L Vinyard Jr

Member Typedef Documentation

typedef std::map<Drawable::pointer, sigc::connection> Papyrus::Group::Connections [protected]

typedef std::list<Drawable::pointer> Papyrus::Group::Layer

A layer is a list of child items.

The children are drawn starting with the last item in the list, proceeding forward to the first item. Thus, the first item in the list will be drawn on top of all 'lower' items.

typedef std::map<int,Layer> Papyrus::Group::Layers

Layers are drawn starting for the lowest numbered layer to the highest layer.

Constructor & Destructor Documentation

Papyrus::Group::Group ( const Glib::ustring & id = Glib::ustring() ) [protected]

References Papyrus::Drawable::set_selectable().

Papyrus::Group::Group ( const AttributeValueMap & avmap ) [protected]

Papyrus::Group::~Group ( ) [virtual]

Member Function Documentation

bool Papyrus::Group::add	(	Drawable::pointer	item,
		int	layer = `0`
	)			`[virtual]`

Adds a child to a given layer.

Layer 0 is the default layer. Layers are drawn from the most negative to the most positive. Thus, layer 0 is on top of layer -1, and layer 1 is on top of layer 0.

References Papyrus::Region::include(), m_changed_connections, Papyrus::Drawable::m_extents_invalid, m_layers, Papyrus::Drawable::m_pre_viewbox_extents, m_redraw_connections, m_signal_child_added, Papyrus::Drawable::m_signal_extents_changed, m_size, on_child_changed_proxy(), on_child_redraw(), and Papyrus::Drawable::redraw().

Referenced by Papyrus::process_drawable().

void Papyrus::Group::add_drawable_to_dictionary	(	const Glib::ustring &	name,
		Drawable::pointer	p
	)

Adds or replaces the named drawable in the drawable dictionary.

References m_drawable_dictionary, and m_signal_drawable_added_to_dictionary.

Referenced by Papyrus::process_drawable().

void Papyrus::Group::add_paint_to_dictionary	(	const Glib::ustring &	name,
		Paint::pointer	p
	)

Adds or replaces the named paint in the paint dictionary.

References m_paint_dictionary, and m_signal_paint_added_to_dictionary.

Referenced by Papyrus::SVG::process_element().

Region Papyrus::Group::calculate_extents	(	const Matrix &	m = `Matrix::Identity`,
		ExtentsPerformance	ep = `EXTENTS_QUICK`
	)			const `[protected, virtual]`

Reimplemented from Papyrus::Drawable.

References Papyrus::Region::include(), and m_layers.

Referenced by Papyrus::Canvas::global_extents().

template<class T >

PapyrusPointer<T> Papyrus::Group::child ( const Glib::ustring & id ) const [inline]

Returns the first child named id dynamically typecast to the template parameter type or a null pointer of the template parameter type if no child found of the requested type.

This template form makes this possible:

 Group::pointer g = Group::create();
 g->add( Rectangle::create( "my_rectangle", 100, 50 );
 
 Rectangle rect;
 rect = group->child\<Rectangle\>("my_rectangle");

References m_layers, and papyrus_dynamic_pointer_cast.

Drawable::pointer Papyrus::Group::child ( const Glib::ustring & id ) const

Returns the first child named id or a null pointer if no child found.

Parameters:

id

is case sensitive

References m_layers.

Referenced by Papyrus::SVG::process_element().

bool Papyrus::Group::clear ( ) [virtual]

Clears all layers and children from the group.

References Papyrus::Drawable::invalidate_extents(), m_changed_connections, m_layers, m_redraw_connections, m_signal_child_removed, m_size, and Papyrus::Drawable::redraw().

Referenced by Papyrus::SVG::process_element().

void Papyrus::Group::clear_drawable_dictionary ( )

Clears all drawables in the dictionary.

Lookups can still succeed if the lookup name is a child or in an ancestor.

References m_drawable_dictionary, and m_signal_drawable_removed_from_dictionary.

void Papyrus::Group::clear_paint_dictionary ( )

Clears all paints in the dictionary.

Any children already set to a paint will retain their paints.

References m_paint_dictionary, and m_signal_paint_removed_from_dictionary.

Group::pointer Papyrus::Group::create ( const AttributeValueMap & avmap ) [static]

References PAPYRUS_CREATE.

Group::pointer Papyrus::Group::create ( const Glib::ustring & id = Glib::ustring() ) [static]

References PAPYRUS_CREATE.

Referenced by set().

const Glib::ustring & Papyrus::Group::description ( ) const

References m_description.

void Papyrus::Group::draw ( Context & cairo ) const [protected, virtual]

Implements Papyrus::Drawable.

Reimplemented in Papyrus::Canvas.

References m_intermediate_drawing_enabled, m_layers, and Papyrus::Context::paint().

const DrawableDictionary & Papyrus::Group::drawable_dictionary ( ) const

Returns this group's drawable dictionary.

References m_drawable_dictionary.

void Papyrus::Group::enable_intermediate_drawing ( bool enabled = true ) [virtual]

References m_intermediate_drawing_enabled, and Papyrus::Drawable::redraw().

Fill::pointer Papyrus::Group::fill ( )

The default fill that is applied to all children derived from Shape.

References fill(), m_fill, and Papyrus::Drawable::m_parent.

Referenced by fill(), set(), and set_fill().

void Papyrus::Group::freeze ( ) [virtual]

Reimplements Drawable::freeze() to also freeze children using the m_frozen_by_parent flag.

Reimplemented from Papyrus::Drawable.

References freeze_children(), and Papyrus::Drawable::m_frozen.

void Papyrus::Group::freeze_children ( ) [protected]

References m_layers, and papyrus_dynamic_pointer_cast.

Referenced by freeze().

bool Papyrus::Group::has ( Drawable::pointer d ) const

True if this group has the specified drawable in any layer.

References Papyrus::Object::id(), and m_layers.

bool Papyrus::Group::has_layer ( int l )

True if this group has layer l.

References m_layers.

bool Papyrus::Group::inside	(	double	x,
		double	y
	)			`[virtual]`

Overrides parent method for determining whether (x,y) is inside the drawable.

If the group itself is selectable, performs a simple extents test. If the group is not selectable, performs a test on each of the children, returning true if any of the children are selectable.

Reimplemented from Papyrus::Drawable.

References m_layers, Papyrus::Drawable::matrix(), and Papyrus::Matrix::transform_point_inverse().

bool Papyrus::Group::is_group ( ) [virtual]

Reimplemented from Papyrus::Drawable.

bool Papyrus::Group::is_intermediate_drawing_enabled ( ) [virtual]

References m_intermediate_drawing_enabled.

const Group::Layer & Papyrus::Group::layer ( int l ) const throw (std::out_of_range)

Returns the requested layer l or throws std::out_of_range if the layer doesn't exist.

To avoid throwing an error, check has_layer() before calling.

const Group::Layers & Papyrus::Group::layers ( ) const

Returns the layers in this group.

References m_layers.

Drawable::pointer Papyrus::Group::lookup_drawable ( const Glib::ustring & name ) const

Lookup the named drawable.

Looks first in this drawable's dictionary. If nothing is found, looks through children. If the name is still not found looks through ancestor's dictionaries and children.

References lookup_drawable(), m_drawable_dictionary, and Papyrus::Drawable::m_parent.

Referenced by lookup_drawable(), and Papyrus::SVG::process_element().

Paint::pointer Papyrus::Group::lookup_paint ( const Glib::ustring & name ) const

Lookup the named paint in the paint dictionary.

Looks in this group's paint dictionary plus any ancestor's dictionary

References if(), lookup_paint(), m_paint_dictionary, and Papyrus::Drawable::m_parent.

Referenced by lookup_paint(), Papyrus::Tiling::set_fill(), and Papyrus::Shape::set_fill().

bool Papyrus::Group::lower	(	Drawable::pointer	item,
		int	steps = `1`
	)			`[virtual]`

Lowers the item down n steps in its layer.

If steps < 0, the effect is a raise operation.

References m_layers.

Referenced by raise().

bool Papyrus::Group::lower_to_bottom ( Drawable::pointer item ) [virtual]

Lowers the item up to the bottom of its layer.

Returns true if the item is lowered or already at the bottom, and false if the item cannot be found.

References m_layers.

bool Papyrus::Group::move_to_layer	(	int	layer,
		Drawable::pointer	item
	)			`[virtual]`

Moves an item to a specific layer.

The item must already be in this group or no action will be taken.

References m_layers, and Papyrus::Drawable::redraw().

void Papyrus::Group::on_child_changed ( Drawable::pointer child ) [protected, virtual]

Virtual method called when a child is changed.

When a child is added, the child's changed signal is actually connected to the private proxy method, which in turn calls the virtual method. This allows children to implement their own behavior by reimplementing this method without worrying about modifying the add() or remove() methods.

References Papyrus::Drawable::invalidate_extents().

Referenced by on_child_changed_proxy().

void Papyrus::Group::on_child_changed_proxy ( Drawable::pointer child ) [private]

When a child is added this is the actual method connected to the child's changed signal and in turn this method calls the virtual method on_child_changed().

References on_child_changed().

Referenced by add().

void Papyrus::Group::on_child_redraw	(	double	x,
		double	y,
		double	w,
		double	h,
		Drawable::pointer	child
	)			`[protected]`

References Papyrus::Drawable::composed_matrix(), Papyrus::Drawable::m_signal_redraw, Papyrus::Region::transform(), and Papyrus::Region::xywh().

Referenced by add().

const PaintDictionary & Papyrus::Group::paint_dictionary ( ) const

Returns this group's paint dictionary.

References m_paint_dictionary.

Papyrus::Group::PAPYRUS_DRAWABLE ( Group )

Reimplemented in Papyrus::Canvas, and Papyrus::SVG.

bool Papyrus::Group::raise	(	Drawable::pointer	item,
		int	steps = `1`
	)			`[virtual]`

Raises the item up n steps in its layer.

If steps < 0, the effect is a lower operation.

References lower(), and m_layers.

bool Papyrus::Group::raise_to_top ( Drawable::pointer item ) [virtual]

Raises the item up to the top of its layer.

References m_layers.

bool Papyrus::Group::remove ( Drawable * object ) [virtual]

The main purpose of this method is so that a child may use the this pointer to remove itself on destruction.

References m_layers.

bool Papyrus::Group::remove ( Drawable::pointer object ) [virtual]

Removes the object from the group.

References Papyrus::Drawable::invalidate_extents(), m_changed_connections, m_layers, m_redraw_connections, m_signal_child_removed, m_size, and Papyrus::Drawable::redraw().

void Papyrus::Group::remove_drawable_from_dictionary ( const Glib::ustring & name )

Removes the named drawable from the dictionary.

References m_drawable_dictionary, and m_signal_drawable_removed_from_dictionary.

void Papyrus::Group::remove_paint_from_dictionary ( const Glib::ustring & name )

Removes the named paint from the dictionary.

References m_paint_dictionary, and m_signal_paint_removed_from_dictionary.

Selection Papyrus::Group::select	(	double	x,
		double	y,
		unsigned	depth = `1`
	)			`[virtual]`

Reimplemented in Papyrus::Canvas.

References m_layers, Papyrus::Drawable::matrix(), papyrus_dynamic_pointer_cast, and Papyrus::Matrix::transform_point_inverse().

void Papyrus::Group::set ( const AttributeValueMap & avmap ) [virtual]

Reimplemented from Papyrus::Drawable.

References create(), Papyrus::Stroke::create(), Papyrus::Fill::create(), fill(), set_fill(), set_stroke(), Papyrus::strcaseeq(), and stroke().

void Papyrus::Group::set_description ( const Glib::ustring & d )

References m_description, and m_signal_description_changed.

Referenced by Papyrus::SVG::process_element().

void Papyrus::Group::set_fill ( const Glib::ustring & fill )

References Papyrus::Fill::create(), and set_fill().

void Papyrus::Group::set_fill ( const RGBA & color )

References fill(), and set_fill().

void Papyrus::Group::set_fill ( Paint::pointer paint )

References Papyrus::Fill::create(), and set_fill().

void Papyrus::Group::set_fill ( Fill::pointer fill )

Sets the default fill for all children derived from Shape.

The fill is only applied to children that do not already have a fill. The fill will be applied to all children contained by this group when this method is called, and to all subsequent children added to the group.

References m_fill, and Papyrus::Drawable::redraw().

Referenced by Papyrus::SVG::process_element(), set(), and set_fill().

void Papyrus::Group::set_stroke ( const Glib::ustring & stroke )

References Papyrus::Stroke::create(), and set_stroke().

void Papyrus::Group::set_stroke ( const RGBA & color )

References set_stroke(), and stroke().

void Papyrus::Group::set_stroke ( Paint::pointer paint )

References Papyrus::Stroke::create(), and set_stroke().

void Papyrus::Group::set_stroke ( Stroke::pointer stroke )

Sets the default stroke for all children derived from Shape.

The stroke is only applied to children that do not already have a stroke. The stroke will be applied to all children contained by this group when this method is called, and to all subsequent children added to the group.

References m_stroke, and Papyrus::Drawable::redraw().

Referenced by set(), and set_stroke().

void Papyrus::Group::set_title ( const Glib::ustring & t )

References m_signal_title_changed, and m_title.

Referenced by Papyrus::SVG::process_element().

sigc::signal< void, Drawable::pointer > & Papyrus::Group::signal_child_added ( )

References m_signal_child_added.

sigc::signal< void, Drawable::pointer > & Papyrus::Group::signal_child_removed ( )

References m_signal_child_removed.

sigc::signal< void > & Papyrus::Group::signal_description_changed ( )

References m_signal_description_changed.

sigc::signal< void, const Glib::ustring & > & Papyrus::Group::signal_drawable_added_to_dictionary ( )