.. _tut_layers:

Tutorial for Layers
===================

If you are not familiar with the concept of layers, please read this first: :ref:`layer_concept`

Create a Layer Definition
-------------------------

.. code-block:: python

    import ezdxf

    doc = ezdxf.new(setup=True)  # setup required line types
    msp = doc.modelspace()
    doc.layers.add(name="MyLines", color=7, linetype="DASHED")

The advantage of assigning a linetype and a color to a layer is that entities
on this layer can inherit this properties by using ``"BYLAYER"`` as linetype
string and ``256`` as color, both values are default values for new entities
so you can leave off these assignments:

.. code-block:: python

    msp.add_line((0, 0), (10, 0), dxfattribs={"layer": "MyLines"})

The new created line will be drawn with color ``7`` and linetype ``"DASHED"``.

Changing Layer State
--------------------

Get the layer definition object:

.. code-block:: python

    my_lines = doc.layers.get('MyLines')

Check the state of the layer:

.. code-block:: python

    my_lines.is_off()  # True if layer is off
    my_lines.is_on()   # True if layer is on
    my_lines.is_locked()  # True if layer is locked
    layer_name = my_lines.dxf.name  # get the layer name

Change the state of the layer:

.. code-block:: python

    # switch layer off, entities at this layer will not shown in CAD applications/viewers
    my_lines.off()

    # lock layer, entities at this layer are not editable in CAD applications
    my_lines.lock()

Get/set default color of a layer by property :attr:`Layer.color`, because the
DXF attribute :attr:`Layer.dxf.color` is misused for switching the layer on and
off, layer is off if the color value is negative.

Changing the default layer values:

.. code-block:: python

    my_lines.dxf.linetype = "DOTTED"
    my_lines.color = 13  # preserves on/off state of layer

.. seealso::

    For all methods and attributes see class :class:`~ezdxf.entities.Layer`.

Check Available Layers
----------------------

The layers object supports some standard Python protocols:

.. code-block:: python

    # iteration
    for layer in doc.layers:
        if layer.dxf.name != "0":
            layer.off()  # switch all layers off except layer "0"

    # check for existing layer definition
    if "MyLines" in doc.layers:
        layer = doc.layers.get("MyLines")

    layer_count = len(doc.layers) # total count of layer definitions

Deleting a Layer
----------------

Delete a layer definition:

.. code-block:: python

    doc.layers.remove("MyLines")

This just deletes the layer definition, all DXF entities with the DXF attribute
layer set to ``"MyLines"`` are still there, but if they inherit color and/or
linetype from the layer definition they will be drawn now with linetype
``"Continuous"`` and color ``1``.

