@c creatnew.texi
      
@c This file is part of the 3DLDF User and Reference Manual.
@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The Free Software Foundation 
@c See the section "GNU Free Documentation License" in the file 
@c fdl.texi for copying conditions.


@node Dynamic Allocation of Shapes, System Information, Global Constants and Variables, Top
@chapter Dynamic Allocation of Shapes

@deftypefn {Template function} {@code{template <class C> C*}} create_new ({const C*} @var{arg})
@deftypefnx {Template function} {@code{template <class C> C*}} create_new ({const C&} @var{arg})
@c
These functions dynamically allocate an object derived from
@code{Shape} on the free store, 
returning a pointer to the type of the @code{Shape} and setting
@code{on_free_store} to @code{true}.

If a non-zero pointer or a reference is passed to @code{create_new()},
the new object will be a copy of @var{arg}.

It is not possible to instantiate more than one specialization of
@code{create_new()} that takes no argument, because calls to these
functions would be ambiguous.  If the new object is not meant to be a
copy of an existing one, @samp{0} must be passed to @code{create_new()}
as its argument.

@code{create_new} is called like this:

@example
Point* p = create_new<Point>(0);
p->show("*p:");
@print{} *p: (0, 0, 0)

Color c(.3, .5, .25);
Color* d = create_new<Color>(c);
d->show("*d:");
@print{} 
*d:
name == 
use_name == 0
red_part == 0.3
green_part == 0.5
blue_part == 0.25


Point a0(3, 2.5, 6);
Point a1(10, 11, 14);
Path q(a0, a1);
Path* r = create_new<Path>(&q);
r->show("*r:");
@print{} 
*r:
points.size() == 2
connectors.size() == 1
(3, 2.5, 6) -- (10, 11, 14);
@end example



Specializations of this template function are currently declared for
@code{Color}, @code{Point}, @code{Path}, @code{Reg_Polygon},
@code{Rectangle}, @code{Ellipse}, @code{Circle}, @code{Solid}, and 
@code{Cuboid}.
@end deftypefn 

  





