# Tutorial

This tutorial introduces SVG++ features by adding them one-by-one into some sample application.

All SVG++ headers may be included through this one:

    #include <svgpp/svgpp.hpp>

All SVG++ code is placed in `svgpp` namespace. We’ll import the entire namespace in our sample.

## Handling Shapes Geometry

Basic pattern of SVG++ usage: call `document_traversal::load_document` method, passing XML element and context to it. Library will call methods of context, passing the parsed data.

    #include <svgpp/svgpp.hpp>

    using namespace svgpp;

    class Context
    {
    public:
      void path_move_to(double x, double y, tag::coordinate::absolute);
      void path_line_to(double x, double y, tag::coordinate::absolute);
      void path_cubic_bezier_to(
        double x1, double y1,
        double x2, double y2,
        double x, double y,
        tag::coordinate::absolute);
      void path_quadratic_bezier_to(
        double x1, double y1,
        double x, double y,
        tag::coordinate::absolute);
      void path_elliptical_arc_to(
        double rx, double ry, double x_axis_rotation,
        bool large_arc_flag, bool sweep_flag,
        double x, double y,
        tag::coordinate::absolute);
      void path_close_subpath();
      void path_exit();

      void on_enter_element(tag::element::any);
      void on_exit_element();
    };

    typedef
      boost::mpl::set<
        // SVG Structural Elements
        tag::element::svg,
        tag::element::g,
        // SVG Shape Elements
        tag::element::circle,
        tag::element::ellipse,
        tag::element::line,
        tag::element::path,
        tag::element::polygon,
        tag::element::polyline,
        tag::element::rect
      >::type processed_elements_t;

    void loadSvg(xml_element_t xml_root_element)
    {
      Context context;
      document_traversal<
        processed_elements<processed_elements_t>,
        processed_attributes<traits::shapes_attributes_by_element>
      >::load_document(xml_root_element, context);
    }

document_traversal is a facade that provides access to most library capabilities.

In most cases only some subset of SVG elements is needed, so we pass named template parameter processed_elements to `document_traversal` template class. In our case it is `processed_elements_t` - `boost::mpl::set` that combines `traits::shape_elements` (enumerates SVG shapes) with svg and g elements.

SVG++ references SVG element types by tags.

We choose SVG attributes subset and pass it as processed_attributes parameter. `traits::shapes_attributes_by_element` contains attributes, that describe geometry of all shapes ({x, y, width, height, rx and ry} for rect, {d} for path etc.).

In this sample the same context instance is used for all SVG elements. `Context::on_enter_element(element_tag)` is called when moving to child SVG element, type of child element passed as tag in the only argument (`tag::element::any` is a base class for all element tags). `on_exit_element()` is called when processing of child element is finished:

XML element | Call to context
--- | ---
`<svg>` | `on_enter_element(tag::element::svg())`
`<rect` | `on_enter_element(tag::element::rect())`
`x="100" y="200"` |
`/>` | `on_exit_element()`
`<g>` | `on_enter_element(tag::element::g())`
`<rect` | `on_enter_element(tag::element::rect())`
`x="300" y="100"` |
`/>` | `on_exit_element()`
`</g>` | `on_exit_element()`
`</svg>` | `on_exit_element()`

Calls like `path_XXXX` except `path_exit` correspond to SVG path data commands. `path_exit` is called after path data attribute was parsed.

SVG++ by default (see Path Policy for details):

- converts relative coordinates to absolute ones;

- commands for horizontal and vertical lines (H, h, V, v) converts to calls to `path_line_to` with two coordinates;

- shorthand/smooth curveto and shorthand/smooth quadratic Bézier curveto replaces with calls with full parameters list.

SVG++ by default converts basic shapes to path (see Basic Shapes Policy for details).

## XML Parser

We didn’t declared `xml_element_t` yet. Let’s use RapidXML NS library (it is a clone of RapidXML with namespace handling added) that comes with SVG++ in the `third_party/rapidxml_ns/rapidxml_ns.hpp` file. It’s a single header library, so we just need to point to its header:

    #include <rapidxml_ns/rapidxml_ns.hpp>

Then we must include SVG++ policy for chosen XML parser:

    #include <svgpp/policy/xml/rapidxml_ns.hpp>

XML policy headers don’t include parser header because their location and names may differ. The programmer must include appropriate XML parser header herself before including policy header.

Setting appropriate XML element type for RapidXML NS parser:

    typedef rapidxml_ns::xml_node<> const * xml_element_t;

You can find the full cpp file here: src/samples/sample01a.cpp.

## Handling Transformations

Just add `tag::attribute::transform` to `processed_attributes` list and `transform_matrix` method to `Context` class:

    void transform_matrix(const boost::array<double, 6> & matrix);

    typedef
      boost::mpl::insert<
        traits::shapes_attributes_by_element,
        tag::attribute::transform
      >::type processed_attributes_t;

    /* ... */

    document_traversal<
      processed_elements<processed_elements_t>,
      processed_attributes<processed_attributes_t>
    >::load_document(xml_root_element, context);

Passed `matrix` array `[a b c d e f]` correspond to this matrix:

The default SVG++ behavior is to join all transformations in `transform` attribute into single affine transformation matrix.

Source file: src/samples/sample01b.cpp.

## Handling Viewports

The svg element may be used inside SVG document to establish a new viewport. To process new viewport coordinate system and new user coordinate system several attributes must be processed (x, y, width, height, preserveAspectRatio, viewbox). SVG++ will do it itself if we set `policy::viewport::as_transform` Viewport Policy

    document_traversal<
      processed_elements<processed_elements_t>,
      processed_attributes<processed_attributes_t>,
      viewport_policy<policy::viewport::as_transform>
    >::load_document(xml_root_element, context);

we also must append viewport attributes to the list of processed attributes:

    typedef
      boost::mpl::fold<
        boost::mpl::protect<
          boost::mpl::joint_view<
            traits::shapes_attributes_by_element,
            traits::viewport_attributes
          >
        >,
        boost::mpl::set<
          tag::attribute::transform
        >::type,
        boost::mpl::insert<boost::mpl::_1, boost::mpl::_2>
      >::type processed_attributes_t;

Please note that this cryptic code just merges predefined sequences `traits::shapes_attributes_by_element` and `traits::viewport_attributes` with `tag::attribute::transform` attribute into single MPL sequence equivalent to the following:

    typedef boost::mpl::set<
      // Transform attribute
      tag::attribute::transform,
      // Viewport attributes
      tag::attribute::x,
      tag::attribute::y,
      tag::attribute::width,
      tag::attribute::height,
      tag::attribute::viewBox,
      tag::attribute::preserveAspectRatio,
      // Shape attributes for each shape element
      boost::mpl::pair<tag::element::path,      tag::attribute::d>,
      boost::mpl::pair<tag::element::rect,      tag::attribute::x>,
      boost::mpl::pair<tag::element::rect,      tag::attribute::y>,
      boost::mpl::pair<tag::element::rect,      tag::attribute::width>,
      boost::mpl::pair<tag::element::rect,      tag::attribute::height>,
      boost::mpl::pair<tag::element::rect,      tag::attribute::rx>,
      boost::mpl::pair<tag::element::rect,      tag::attribute::ry>,
      boost::mpl::pair<tag::element::circle,    tag::attribute::cx>,
      boost::mpl::pair<tag::element::circle,    tag::attribute::cy>,
      boost::mpl::pair<tag::element::circle,    tag::attribute::r>,
      boost::mpl::pair<tag::element::ellipse,   tag::attribute::cx>,
      boost::mpl::pair<tag::element::ellipse,   tag::attribute::cy>,
      boost::mpl::pair<tag::element::ellipse,   tag::attribute::rx>,
      boost::mpl::pair<tag::element::ellipse,   tag::attribute::ry>,
      boost::mpl::pair<tag::element::line,      tag::attribute::x1>,
      boost::mpl::pair<tag::element::line,      tag::attribute::y1>,
      boost::mpl::pair<tag::element::line,      tag::attribute::x2>,
      boost::mpl::pair<tag::element::line,      tag::attribute::y2>,
      boost::mpl::pair<tag::element::polyline,  tag::attribute::points>,
      boost::mpl::pair<tag::element::polygon,   tag::attribute::points>
    >::type processed_attributes_t;

Now SVG++ will call the existing method `transform_matrix` to set new user coordinate system. And we must add some methods that will be passed with information about new viewport:

    void set_viewport(double viewport_x, double viewport_y, double viewport_width, double viewport_height);
    void set_viewbox_size(double viewbox_width, double viewbox_height);
    void disable_rendering();

The full cpp file for this step can be found here: src/samples/sample01c.cpp.

## Creating Contexts

Until now only one instance of context object was used for entire SVG document tree. It is convenient to create context instance on stack for each SVG element processed. This behavior is controlled by context factories, passed by context_factories parameter of `document_traversal` template class.

Context factories is a Metafunction Class that receives parent context type and child element tag as parameters and returns context factory type.

This sample application processes structural elements (svg and g) and shape elements (path, rect, circle etc). For the structural elements only transform attribute is processed, and for the shape elements - transform and attributes describing shape. So we can divide `Context` context class for `BaseContext` and `ShapeContext` subclass:

    class BaseContext
    {
    public:
      void on_exit_element();
      void transform_matrix(const boost::array<double, 6> & matrix);
      void set_viewport(double viewport_x, double viewport_y, double viewport_width, double viewport_height);
      void set_viewbox_size(double viewbox_width, double viewbox_height);
      void disable_rendering();
    };

    class ShapeContext: public BaseContext
    {
    public:
      ShapeContext(BaseContext const & parent);
      void path_move_to(double x, double y, tag::coordinate::absolute);
      /* ... other path methods ... */
    };

    struct ChildContextFactories
    {
      template<class ParentContext, class ElementTag, class Enable = void>
      struct apply
      {
        // Default definition handles "svg" and "g" elements
        typedef factory::context::on_stack<BaseContext> type;
      };
    };

    // This specialization handles all shape elements (elements from traits::shape_elements sequence)
    template<class ElementTag>
    struct ChildContextFactories::apply<BaseContext, ElementTag,
      typename boost::enable_if<boost::mpl::has_key<traits::shape_elements, ElementTag> >::type>
    {
      typedef factory::context::on_stack<ShapeContext> type;
    };

`factory::context::on_stack<ChildContext>` factory creates context object `ChildContext`, passing reference to parent context in `ChildContext` constructor. Lifetime of context object - until processing of element content (child elements and text nodes) is finished. `on_exit_element()` is called right before object destruction.

`ChildContextFactories` is passed to `document_traversal`:

    document_traversal<
      /* ... */
      context_factories<ChildContextFactories>
    >::load_document(xml_root_element, context);

Source file: src/samples/sample01d.cpp.

## The use Element Support

The use element is used to include/draw other SVG element. If use references svg or symbol, then new viewport and user coordinate system are established.

To add support for use in our sample we:

> - Add `tag::element::use_` to the list of processed elements, and `tag::attribute::xlink::href` to the list of processed attributes (x, y, width and height already included through `traits::viewport_attributes`).

> - Create context class `UseContext` to be used for use element, that will collect x, y, width, height and xlink:href attributes values.

> - After processing all use element attributes (in method `UseContext::on_exit_element()`), look inside document for element with given id and load it with call to `document_traversal_t::load_referenced_element<...>::load()`.

> - Implement Viewport Policy requirement - svg and symbol context must have method:

>       void get_reference_viewport_size(double & width, double & height);

>   that returns size of the viewport set in referenced use element. One of possible variant is creation of new context `ReferencedSymbolOrSvgContext`.

Full implementation is in file: src/samples/sample01e.cpp.

## Calculating Marker Positions

SVG++ may solve complex task of calculating orientations of markers with attribute orient=”auto”. Let’s set Markers Policy that enables this option:

    document_traversal<
      /* ... */
      markers_policy<policy::markers::calculate_always>
    > /* ... */

Then add Marker Events method to `ShapeContext`:

    void marker(marker_vertex v, double x, double y, double directionality, unsigned marker_index);

The sample (src/samples/sample01f.cpp) just shows how to get marker positions. To implement full marker support we also need to process marker, marker-start, marker-mid and marker-end properties and process marker element (similar to processing of use element). Demo application may give some idea about this.

## Processing of stroke and stroke-width Properties

Adding stroke-width property processing is trivial - just add `tag::attribute::stroke_width` to the list of processed attributes, and add method, that receives value, to the context class:

    void set(tag::attribute::stroke_width, double val);

Property stroke has complex type <paint>:

    <paint>:      none |
                  currentColor |
                  <color> [<icccolor>] |
                  <funciri> [ none | currentColor | <color> [<icccolor>] ] |
                  inherit

that is why so many methods are required to receive all possible values of the property:

    void set(tag::attribute::stroke_width, double val);
    void set(tag::attribute::stroke, tag::value::none);
    void set(tag::attribute::stroke, tag::value::currentColor);
    void set(tag::attribute::stroke, color_t color, tag::skip_icc_color = tag::skip_icc_color());
    template<class IRI>
    void set(tag::attribute::stroke tag, IRI const & iri);
    template<class IRI>
    void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment);
    template<class IRI>
    void set(tag::attribute::stroke tag, IRI const &, tag::value::none val);
    template<class IRI>
    void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment, tag::value::none val);
    template<class IRI>
    void set(tag::attribute::stroke tag, IRI const &, tag::value::currentColor val);
    template<class IRI>
    void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment, tag::value::currentColor val);
    template<class IRI>
    void set(tag::attribute::stroke tag, IRI const &, color_t val, tag::skip_icc_color = tag::skip_icc_color());
    template<class IRI>
    void set(tag::attribute::stroke tag, tag::iri_fragment, IRI const & fragment, color_t val, tag::skip_icc_color = tag::skip_icc_color());

Default IRI Policy is used that distinguishes absolute IRIs and local IRI references to fragments in same SVG document.

Source code: src/samples/sample01g.cpp.

Note

`svgpp_parser_impl.cpp` file was added to the project and a couple of macros was added at the start of the `sample01g.cpp` to get around Visual C++ 2015 “compiler out of memory” problem. See description of this solution.

## Custom Color Factory

Suppose that default SVG++ color presentation as 8 bit per channel RGB value packed in `int` doesn’t suit our needs. We prefer to use some custom type, e.g. `boost::tuple` (same as C++11 `std::tuple`):

    typedef boost::tuple<unsigned char, unsigned char, unsigned char> color_t;

In this case we need our own Color Factory, that creates our custom color from components values, that was read from SVG:

    struct ColorFactoryBase
    {
      typedef color_t color_type;

      static color_type create(unsigned char r, unsigned char g, unsigned char b)
      {
        return color_t(r, g, b);
      }
    };

    typedef factory::color::percentage_adapter<ColorFactoryBase> ColorFactory;

    document_traversal<
      /* ... */
      color_factory<ColorFactory>
    > /* ... */

Usage of `factory::color::percentage_adapter` frees us from implementing `create_from_percent` method in our Color Factory.

Source file: src/samples/sample01h.cpp.

## Correct Length Handling

On next step (src/samples/sample01i.cpp) of sample evolution we will add correct handling of length, that takes in account device resolution (dpi) and changes of viewport size by svg and symbol elements, that affects lengths, which are set in percent. So we:

> - Add to `BaseContext` class constructor that receives device resolution in dpi (this constructor is only called by ourselves from `loadSvg` function).

> - Add `length_factory_` field and access function. `length_factory_` settings (resolution, viewport size) will be passed to child contexts in copy constructor.

> - In `BaseContext::set_viewport` and `BaseContext::set_viewbox_size` methods pass viewport size to the Length Factory.

> - Set Length Policy, that will ask `BaseContext` class for Length Factory instance:

>       document_traversal<
>         /* ... */
>         length_policy<policy::length::forward_to_method<BaseContext> >
>       > /* ... */;

    class BaseContext: public StylableContext
    {
    public:
      BaseContext(double resolutionDPI)
      {
        length_factory_.set_absolute_units_coefficient(resolutionDPI, tag::length_units::in());
      }

      /* ... */

      // Viewport Events Policy
      void set_viewport(double viewport_x, double viewport_y, double viewport_width, double viewport_height)
      {
        length_factory_.set_viewport_size(viewport_width, viewport_height);
      }

      void set_viewbox_size(double viewbox_width, double viewbox_height)
      {
        length_factory_.set_viewport_size(viewbox_width, viewbox_height);
      }

      // Length Policy interface
      typedef factory::length::unitless<> length_factory_type;

      length_factory_type const & length_factory() const
      { return length_factory_; }

    private:
      length_factory_type length_factory_;
    };

According to SVG Specification, the size of the new viewport affects attributes of element that establish new viewport (except x, y, width and height attributes). As our Length Factory converts lengths to numbers immediately, we need to pass new viewport size to Length Factory before processing other attributes. To do so we will use get_priority_attributes_by_element parameter of Attribute Traversal Policy:

    struct AttributeTraversal: policy::attribute_traversal::default_policy
    {
      typedef boost::mpl::if_<
        // If element is 'svg' or 'symbol'...
        boost::mpl::has_key<
          boost::mpl::set<
            tag::element::svg,
            tag::element::symbol
          >,
          boost::mpl::_1
        >,
        boost::mpl::vector<
          // ... load viewport-related attributes first ...
          tag::attribute::x,
          tag::attribute::y,
          tag::attribute::width,
          tag::attribute::height,
          tag::attribute::viewBox,
          tag::attribute::preserveAspectRatio,
          // ... notify library, that all viewport attributes that are present was loaded.
          // It will result in call to BaseContext::set_viewport and BaseContext::set_viewbox_size
          notify_context<tag::event::after_viewport_attributes>
        >::type,
        boost::mpl::empty_sequence
      > get_priority_attributes_by_element;
    };

    document_traversal<
      /* ... */
      attribute_traversal_policy<AttributeTraversal>
    > /* ... */;

Now we are sure that `BaseContext::set_viewport` (and `BaseContext::set_viewbox_size`) will be called before other attributes are processed.

## Text Handling

On the next step (src/samples/sample01j.cpp) we will implement basic handling of text elements:

> - Create new `TextContext` child of `BaseContext` that will receive text element data. `set_text` method will be called by SVG++ to pass character data content of element:

>       template<class Range>
>       void set_text(Range const & text)
>       {
>         text_content_.append(boost::begin(text), boost::end(text));
>       }

> - Add specialization of ChildContextFactories class that will create `TextContext` class for text elements (`tag::element::text`).

> - Add `tag::element::text` to the list of processed elements `processed_elements_t`.