============
Leader Lines
============

Anchored leader lines have a number of applications, but they're especially useful for text annotations. In this tutorial, we'll use the ShapeKit class to build a simple text annotation with an anchored leader line that points to a vertex on a cube. Before we begin, be sure that you've set the namespace declaration in your code ("using namespace HPS;" in C++ or "using HPS;" in C#).

.. image:: images/05/5_1_SampleOutput.png

*A textbox with a leader line pointing to a vertex on a cube*


.. _0501:

5.1 Set Up the Scene
====================

Let's start off by setting up a basic scene (including colors, font size, handedness, and camera position) and creating a portfolio where we'll store definitions that our segments will access throughout this program.


.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [basic_setup]
		   :end-before: //! [basic_setup]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [basic_setup]
		   :end-before: //! [basic_setup]
		   

.. _0502:

5.2 Insert a Cube
=================

Next we'll insert a basic cube and position it at the point (0, 1, 0) in world space. This is the object that the leader line will be pointing to. (The code for creating a cube is outside the scope of this discussion, but you can find a sample of the InsertCube function in the Appendix below.)

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [insert_cube]
		   :end-before: //! [insert_cube]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [insert_cube]
		   :end-before: //! [insert_cube]
		   

.. _0503:

5.3 Define the Annotation Shape
===============================

Our textbox will be in the shape of a rectangle, so we'll create a rectangle by defining each of the four vertices with a ``ShapePoint``. A rectangle is, of course, a polygon, so we'll add these vertices to a ``PolygonShapeElement`` that will serve as the background element on top of which our annotation text will be positioned.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [create_textbox]
		   :end-before: //! [create_textbox]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [create_textbox]
		   :end-before: //! [create_textbox]
		   

.. _0504:

5.4 Define Leader Line Anchor and Intermediate Points
=====================================================

Next, we'll create an ``AnchorShapeElement`` for our leader line and set the anchor point to the top right of our textbox rectangle. We'll also create an intermediate point where the leader line will bend (see the image at the beginning of this tutorial for reference).

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [create_line_anchor]
		   :end-before: //! [create_line_anchor]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [create_line_anchor]
		   :end-before: //! [create_line_anchor]
		   

.. _0505:

5.5 Define a ShapeKit and Add Text
==================================

A ``ShapeKit`` object will contain our rectangle shape along with the anchor and intermediate points of our leader line. We'll add the ``ShapeKit`` to our portfolio, insert our text into the rectangle segment, and define the coordinates where the leader line will point.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [create_shapekit]
		   :end-before: //! [create_shapekit]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [create_shapekit]
		   :end-before: //! [create_shapekit]
		   

.. _0506:

5.6 Create the Leader Line
==========================

Our leader line will be a solid line, so we'll define it using a ``SolidLinePatternElement`` and add it to a ``LinePatternParallelKit``, which we can later add to our portfolio and access in our segments.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [line_pattern]
		   :end-before: //! [line_pattern]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [line_pattern]
		   :end-before: //! [line_pattern]
		   
		   
.. _0507:

5.7 Add the Arrowhead
=====================

The arrowhead of our leader line is a simple triangle glyph. Define the glyph in the portfolio and give it a name. Then create a ``GlyphLinePatternElement`` to set the attributes of the glyph.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [add_arrowhead]
		   :end-before: //! [add_arrowhead]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [add_arrowhead]
		   :end-before: //! [add_arrowhead]
		   

.. _0508:

5.8 Bringing It All Together
============================

Add the line pattern parallel kit to a line pattern kit using the ``SetParallels`` function. Then, we'll define the line pattern in our portfolio, where it can be accessed by our rectangle segment key.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [wrap_up]
		   :end-before: //! [wrap_up]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [wrap_up]
		   :end-before: //! [wrap_up]
		   
Your scene is now complete and should match the image at the start of this tutorial. This is just a simple demonstration of the annotation and leader line features. Feel free to expand the program by adding multiple leader lines and intermediate points or by trying out different shapes for your annotations.


.. _0509:

Appendices
==========

Full source code for this program is available here, including the program described above and a function for creating a cube from a ``Shell`` object.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [full_program]
		   :end-before: //! [full_program]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [full_program]
		   :end-before: //! [full_program]
		   
		  
Source Code for InsertCube Function
-----------------------------------

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00730_tutorial5_1.cpp
		   :start-after: //! [cube_program]
		   :end-before: //! [cube_program]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00730_tutorial5_1.cs
		   :start-after: //! [cube_program]
		   :end-before: //! [cube_program]

