=============
Line Patterns
=============

Visualize supports an advanced feature set for line patterns. You can use one of the :doc:`pre-defined line patterns <appendix_default_line_patterns>` by defining it in the active portfolio and instructing the segment to use that pattern. For example, to set the "dashdot" line pattern, you could use the following code:
 
.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [basic_example]
		   :end-before: //! [basic_example]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [basic_example]
		   :end-before: //! [basic_example]
		   
For a list of all pre-defined line patterns, as well as their names, see the :doc:`appendix section on lines <appendix_default_line_patterns>`.

Custom line patterns are also available. To define a custom pattern, it is necessary to understand the hierarchy involved. Line patterns are comprised of one or more parallels. Each parallel describes a set of elements which will be drawn along the path of a line. The elements can be solid pixels, blank pixels, or glyphs. The object hierarchy is shown below:

.. image:: images/line_pattern_hierarchy.png

The procedure for building these objects is described in the steps below:


Step 1: Initialize the LinePatternElements
------------------------------------------

For this example, a double line composed of two parallels will be built: a solid blue and a dashed orange line. Working from the bottom of the hierarchy to the top, the first step is to initialize each ``HPS::LinePatternElement``. The code below initializes the individual line patterns for use within the line as a whole. Note that a dashed line is actually made of two elements: a repeating pattern of solids and blanks.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [line_patterns_step1]
		   :end-before: //! [line_patterns_step1]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [line_patterns_step1]
		   :end-before: //! [line_patterns_step1]
		   
		   
Step 2: Combine the LinePatternElements into an Array
-----------------------------------------------------

Now that the ``HPS::LinePatternElement`` objects are initialized, the next step is to assemble them into a collection. Like the ``HPS::GlyphElement`` objects discussed in :doc:`this section <0405_glyphs>`, they all need to be combined into an array. Since a line made of two parallels is desired, two arrays are needed. The order of the elements in the array will determine their order in the rendered line.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [line_patterns_step2]
		   :end-before: //! [line_patterns_step2]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [line_patterns_step2]
		   :end-before: //! [line_patterns_step2]
		   
		   
Step 3: Set Up the LinePatternParallels
---------------------------------------

Each ``HPS::LinePatternElementArray`` now needs to be made into a parallel. The parallel objects allow the offset (distance between the parallels and the line path) and weight to be set. The parallels live inside a ``HPS::LinePatternParallelKitArray``.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [line_patterns_step3]
		   :end-before: //! [line_patterns_step3]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [line_patterns_step3]
		   :end-before: //! [line_patterns_step3]
		   

Step 4: Add the Parallels to the Line Pattern Itself
----------------------------------------------------

A ``HPS::LinePatternKit`` is used to conglomerate all of the line pattern data. After the kit is built, the construction phase of the line pattern is complete.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [line_patterns_step4]
		   :end-before: //! [line_patterns_step4]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [line_patterns_step4]
		   :end-before: //! [line_patterns_step4]
		   
		   
Step 5: Add Line Pattern to a Portfolio
---------------------------------------

Before using the line pattern, it must be defined in a portfolio. Don't forget to set the portfolio on the segment you intend to use it on. Portfolios are introduced :doc:`here <0401_portfolios_introduction>`.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [line_patterns_step5]
		   :end-before: //! [line_patterns_step5]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [line_patterns_step5]
		   :end-before: //! [line_patterns_step5]
		   

Step 6: Line Pattern is Ready to Be Set On a Line
-------------------------------------------------

At this point, the line pattern is defined and ready to use. As line patterns are controlled at the segment level, the pattern must be set there. 

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [line_patterns_step6]
		   :end-before: //! [line_patterns_step6]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [line_patterns_step6]
		   :end-before: //! [line_patterns_step6]

.. image:: images/custom_line_pattern.png

*The completed custom line pattern*


Using Glyphs in a Line Pattern
------------------------------

Glyphs can also be used as elements in a line pattern. To do so, the glyph must be already defined (see :doc:`this section <0405_glyphs>` for a discussion on defining glyphs). The steps for using glyphs follow the same basic principles as other types of line pattern elements:

#. Using a ``GlyphLinePatternElement``, set the source glyph.
#. Add the ``GlyphLinePatternElement`` to the ``LinePatternParallel`` as you would any other line pattern element.
#. Define the line pattern in the portfolio, and make it the active line pattern.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_line_patterns.cpp
		   :start-after: //! [glyph_line_pattern]
		   :end-before: //! [glyph_line_pattern]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_line_patterns.cs
		   :start-after: //! [glyph_line_pattern]
		   :end-before: //! [glyph_line_pattern]
		   
The remaining steps are nearly identical to building a normal line pattern. Note the call to ``SetInsetBehavior``. The inset behavior will determine whether the glyph is drawn as a distinct element (``Inline``), overlapping the line elements (``Overlap``), or a length-trimmed hybrid (``Trim``). The screenshot below shows an example of all three behaviors.

.. image:: images/glyph_line_pattern.png

*The default inset behavior is ``Overlap``.*
