##########################
Overlays: Axis, Grid, etc.
##########################

Overlays are elements that decorate plots, like for example
axes, legends, grids, etc.

Overlays are very similar to regular plot elements, and share most
of their interface with :ref:`plot renderers <plot_renderers>`
(both are subclasses of :class:`chaco.plot_component.PlotComponent`).

In addition, they have a lightweight interface defined in
:class:`chaco.abstract_overlay.AbstractOverlay`: the additional
features are that

1. they keep a reference to the plot they are decorating in
   :attr:`~chaco.abstract_overlay.AbstractOverlay.component`;
2. the background color :attr:`~chaco.abstract_overlay.AbstractOverlay.bgcolor`
   is 'transparent' by default;
3. they plot :ref:`on the 'overlay' layer <plot_layers>` by default.

.. TODO: explain how to attach an overlay to an existing plot renderer

=============
Core Overlays
=============

There are three important classes of overlays defined in Chaco:
:ref:`axes <axis>`, :ref:`legends <legend>`, and :ref:`grids <grid>`.

.. _axes:

Axes
====

The Chaco overlay representing a plot axis is defined in the class
:class:`~chaco.axis.PlotAxis`.

A new axis is created by passing a
mapper, usually the mapper defined for the corresponding plot data coordinate.
:class:`~chaco.axis.PlotAxis` also defines a range of attributes to customize
the appearance of labels, ticks, and other axis elements. For example,
given an X-Y plot renderer, ``plot``, we can define a new x-axis as: ::

    AXIS_DEFAULTS = {
        'axis_line_weight': 2,
        'tick_weight': 2,
        'tick_label_font': 'modern 16',
        'title_font': 'modern 20',
    }

    x_axis = PlotAxis(
        orientation='bottom',
        title='My x axis',
        mapper=plot.x_mapper,
        component=plot,
        **AXIS_DEFAULTS,
    )

The newly created axis can then be attached to the plot renderer by
appending it to its underlays layer: ::

    plot.underlays.append(x_axis)

Minor Axes Ticks
----------------

The Chaco overlay representing a *minor* plot axis is defined in the class
:class:`~chaco.axis.MinorPlotAxis` (a subclass of
:class:`~chaco.axis.PlotAxis`). This overlay adds minor tick marks to an axis.

A :class:`~chaco.axis.MinorPlotAxis` should be added along with a
:class:`~chaco.axis.PlotAxis`. For example, minor axis tick marks can be
added with: ::

    x_major_axis = PlotAxis(
        orientation='bottom',
        title='My x axis',
        mapper=plot.x_mapper,
        component=plot,
    )
    plot.underlays.append(x_major_axis)

    x_minor_axis = MinorPlotAxis(
        orientation='bottom',
        mapper=plot.x_mapper,
        component=plot,
    )
    plot.underlays.append(x_minor_axis)

Attributes
----------

These attributes control the appearance of the axis:

:attr:`~chaco.axis.PlotAxis.title`, :attr:`~chaco.axis.PlotAxis.title_font`, :attr:`~chaco.axis.PlotAxis.title_color`, :attr:`~chaco.axis.PlotAxis.title_spacing` :attr:`~chaco.axis.PlotAxis.title_angle`
  Define the axis label. :attr:`title` is a string or unicode object
  that is rendered using the given font and color. :attr:`title_font` is
  a string describing a font (e.g. '12 pt bold italic',
  'swiss family Arial' or 'default 12'; see
  :class:`~kiva.kiva_font_trait.TraitKivaFont` for details).
  Finally, :attr:`title_spacing` is the space between the axis line and the
  title (either the number of pixels or 'auto', default) and
  :attr:`title_angle` can be overridden to change the rotation angle (in deg,
  wrt horizontal).


:attr:`~chaco.axis.PlotAxis.tick_weight`, :attr:`~chaco.axis.PlotAxis.tick_color`, :attr:`~chaco.axis.PlotAxis.tick_in`, :attr:`~chaco.axis.PlotAxis.tick_out`, :attr:`~chaco.axis.PlotAxis.tick_visible`,
  These attributes control the aspect of the ticks on the axis.
  If :attr:`tick_visible` is True, ticks are represented as lines of
  color :attr:`tick_color` (default is black) and thickness
  :attr:`tick_weight` (in pixels, default is 1). Each line extends into the
  plot area by :attr:`tick_in` pixels and into the label area by
  :attr:`tick_out` pixels (default is 5).


:attr:`~chaco.axis.PlotAxis.tick_label_font`, :attr:`~chaco.axis.PlotAxis.tick_label_color`, :attr:`~chaco.axis.PlotAxis.tick_label_rotate_angle`, :attr:`~chaco.axis.PlotAxis.tick_label_alignment`, :attr:`~chaco.axis.PlotAxis.tick_label_margin`, :attr:`~chaco.axis.PlotAxis.tick_label_offset`, :attr:`~chaco.axis.PlotAxis.tick_label_position`,
  These attributes allow to fine-tune the aspect of the tick labels:
  first of all, the font (e.g. '12 pt bold italic') and color of the
  labels. The position and orientation of the label can be also be
  closely controlled: :attr:`tick_label_rotate_angle` give the rotation
  angle (only multiples of 90 degrees are supported);
  :attr:`tick_label_alignment` selects whether the corner ('corner') or center
  ('edge', default) of the label are aligned to the corresponding tick
  ('corner' is better for 45 degrees rotation); :attr:`tick_label_margin`
  and :attr:`tick_label_offset` control the margin around the
  tick labels, and their distance from the axis; finally,
  :attr:`tick_label_position` can be set to either 'outside' (default)
  or 'inside' depending on whether the labels should be displayed inside
  or outside the plot area.


:attr:`~chaco.axis.PlotAxis.tick_label_formatter`
  By default, tick labels are assumed to be floating point numbers, and are
  displayed as such after removing trailing zeros and the decimal dot if
  necessary (e.g., '10.000' will be displayed as '10', and '21.10' as '21.1').
  The default behavior can be changed by setting :attr:`tick_label_formatter`
  to a callable that takes the value of the tick label and returns a
  formatted string.


:attr:`~chaco.axis.PlotAxis.tick_interval`, :attr:`~chaco.axis.PlotAxis.tick_generator`,
  Locations and distances of ticks are controlled by the attribute
  :attr:`tick_generator`

  Default is chaco.ticks.auto_ticks or chaco.ticks.log_auto_ticks

:attr:`~chaco.axis.PlotAxis.`
:attr:`~chaco.axis.PlotAxis.`

Events
------

:attr:`~chaco.axis.PlotAxis.updated`
  Fired when the axis's range bounds change.

.. todo:: Fill in the below sections

..    .. _legend:

..    Legend
..    ======

..    .. _grid:

..    Grid
..    ====

..    ===================
..    Annotation Overlays
..    ===================

..    PointMarker
..    ===========

..    DataBox
..    =======

.. _tools/text_box_overlay:

TextBoxOverlay
==============
The :class:`chaco.overlays.api.TextBoxOverlay` is the base class of
the overlay component of several inspector type tools (see above). It is
designed to draw a text box over the plots to display custom information.

The rendering of the text can be customized with the following attributes:

* :attr:`bgcolor` and :attr:`border_visible` to control the styling of the box,
* :attr:`alpha` to control the transparency of the text box,
* :attr:`text_color` and :attr:`font` to control how the text looks like,
* :attr:`align` to control what corner of the plot the text box should appear,

.. note:: The overlay can also be used directly by any custom tool that needs
          to display information upon an event. It should be done by
          subclassing the overlay and defining a listener on the inspector's
          state which will modify the overlay's :attr:`text` (and optionally
          visibility) attribute(s). After a `text` update, the component's
          :meth:`request_redraw` should be called. Good examples include
          :class:`chaco.overlays.api.ImageInspectorOverlay`.

.. todo:: Fill in the below sections

..    ToolTip
..    =======

..    PlotLabel
..    =========