================
XyPlot (hwx.gui)
================

Creates a 2D plot.

Inherits:
  - :ref:`Frame (hwx.gui)`

----------
Properties
----------

  +------------+------------+------------+
  | bgColor_   | border_    | fontSize_  |
  +------------+------------+------------+
  | footer_    | title_     | xlabel_    |
  +------------+------------+------------+
  | xlimits_   | ylabel_    | ylimits_   |
  +------------+------------+------------+
  | zeroLines_ |                         |
  +------------+-------------------------+

--------------
Public Methods
--------------

  +-----------------------------------------------------------------------+
  | addCurve_ (self, y=[0], x=None, fit=True, **kwds)                     |
  +-----------------------------------------------------------------------+
  | addEventHandler_ (self, tool)                                         |
  +-----------------------------------------------------------------------+
  | addXslider_ (self, x=0, **kwds)                                       |
  +-----------------------------------------------------------------------+
  | addYslider_ (self, y=0, **kwds)                                       |
  +-----------------------------------------------------------------------+
  | clear_ (self)                                                         |
  +-----------------------------------------------------------------------+
  | ensureVisible_ (self, x=None, y=None, points=None)                    |
  +-----------------------------------------------------------------------+
  | fit_ (self, zoom=None, larger=False)                                  |
  +-----------------------------------------------------------------------+
  | formatNumber_ (self, value, format=None)                              |
  +-----------------------------------------------------------------------+
  | getPointUnderMouse_ (self, event, curves=None, tolerance=None)        |
  +-----------------------------------------------------------------------+
  | getSelectedPoints_ (self)                                             |
  +-----------------------------------------------------------------------+
  | getTheClosestPoint_ (self, x, y)                                      |
  +-----------------------------------------------------------------------+
  | pan_ (self, dx, dy)                                                   |
  +-----------------------------------------------------------------------+
  | redrawPlot_ (self, obj=None, name=None)                               |
  +-----------------------------------------------------------------------+
  | selectPoints_ (self, points)                                          |
  +-----------------------------------------------------------------------+
  | setCursor_ (self, cursor, iconStrip=False, x=-1, y=-1)                |
  +-----------------------------------------------------------------------+
  | setSnapping_ (self, on=True, xgrid=None, ygrid=None, snapPoints=None) |
  +-----------------------------------------------------------------------+
  | zoom_ (self, factor=1.5, point=None, axis='both')                     |
  +-----------------------------------------------------------------------+

----------------
Property Details
----------------

.. _bgColor:
.. method:: bgColor

Specifies the background color of the plot.

.. _border:
.. method:: border

Size of the border around the plot.

.. _fontSize:
.. method:: fontSize

Size of the font in points.

.. _footer:
.. method:: footer

Text at the bottom of the figure.

.. _title:
.. method:: title

Text on top of the plot.

.. _xlabel:
.. method:: xlabel

Text along the x-axis.

.. _xlimits:
.. method:: xlimits

Min and max limits of the x-axis.

.. _ylabel:
.. method:: ylabel

Text along the y-axis.

.. _ylimits:
.. method:: ylimits

Min and max limits of the y-axis.

.. _zeroLines:
.. method:: zeroLines

Highlights the axes.

--------------
Method Details
--------------

.. _addCurve:
.. method:: addCurve(self, y=[0], x=None, fit=True, **kwds)

Adds a curve to the plot.

In case `x` is None, it is set to x = list(range(len(y)))

:param y: The y values of the curve.
:type y: list[float]
:param x: The x values of the curve.
:type x: list[float]
:param fit: Determines if curve gets fitted inside the plot.
:type fit: bool

:returns: The newly added Curve object.
:rtype: Curve


.. _addEventHandler:
.. method:: addEventHandler(self, tool)

Adds a custom event handler to define the method associated to an event.

If the action returns True, other event handlers for the same event will
be blocked.

This is useful if you want to listen for a mouse release and get the plot
value instead of the mouse x/y.

.. _addXslider:
.. method:: addXslider(self, x=0, **kwds)

Adds a movable vertical line to the plot.

:param x: The value where the slider will start from on the x-axis.
:type x: float

:returns: The new added XSlider object.
:rtype: XSlider


.. _addYslider:
.. method:: addYslider(self, y=0, **kwds)

Adds a movable horizontal line to the plot.

:param y: The value where the slider will start from on the y-axis.
:type y: float

:returns: The new added YSlider object.
:rtype: YSlider


.. _clear:
.. method:: clear(self)

Resets the title, x-y labels and footer and remove all curves,
sliders and tools, from the plot.

.. _ensureVisible:
.. method:: ensureVisible(self, x=None, y=None, points=None)

Scales the axes so they contains the x, y and points.

:param x: Specified x value.
:type x: float
:param y: Specified y value.
:type y: float
:param points: Points to make visible.
            Points can be  a list of CurvePoints of set to 'selected'.
:type points: Union[list[CurvePoints], str]

:returns: A reference to the instance XyPlot object on which it was called.
:rtype: XyPlot


.. _fit:
.. method:: fit(self, zoom=None, larger=False)

Rescales the axes so all curves are visible.

:param zoom: Padding scale factor around the curves.
:type zoom: float
:param larger: Determines if it will be fitted only in the case
            the computed scale exceeds the current.
:type larger: bool

:returns: A reference to the instance XyPlot object on which it was called.
:rtype: XyPlot


.. _formatNumber:
.. method:: formatNumber(self, value, format=None)

Formats the axis tick values using Inspire number formatting.

:param value: The value to be formatted
:type value: float
:param format: The format to be followed.
:type format: str

:returns: formatted axis tick values.
:rtype: str


.. _getPointUnderMouse:
.. method:: getPointUnderMouse(self, event, curves=None, tolerance=None)

Gets a CurvePoint under the mouse if a point could be found or None.

:param event: The event to get the mouse cursor location.
:type event: MouseEvent
:param curves: The curves to consider to get the point from.
            Defaults to None, considering all the curves in the plot.
:type curves: list[Curve]
:param tolerance: The tolerance value to set the pick radius.
               Defaults to None, considering line maker radius only.
:type tolerance: float

:returns: The CurvePoint under the mouse.
:rtype: CurvePoint


.. _getSelectedPoints:
.. method:: getSelectedPoints(self)

Returns all the selected points from plot.

.. _getTheClosestPoint:
.. method:: getTheClosestPoint(self, x, y)

Gets the CurvePoint closest to specified x, y for all visible curves.

:param x: The x value.
:type x: float
:param y: The y value.
:type y: float

:returns: The closet CurvePoint to the specified x, y values.
:rtype: CurvePoint


.. _pan:
.. method:: pan(self, dx, dy)

Translate the axes by the specified dx, dy.

:param dx: Differential x value to pan the x-axis by.
:type dx: float
:param dy: Differential y value to pan the y-axis by.
:type dy: float

:returns: A reference to the instance XyPlot object on which it was called.
:rtype: XyPlot


.. _redrawPlot:
.. method:: redrawPlot(self, obj=None, name=None)

Refreshes the plot in gui idle.

.. _selectPoints:
.. method:: selectPoints(self, points)

Selects the specified points in the plot.

:param points: The list of points to be selected.
:type points: list[Point]


.. _setCursor:
.. method:: setCursor(self, cursor, iconStrip=False, x=-1, y=-1)

Sets the mouse cursor at specified x, y location inside the plot.

:param cursor: Cursor file name
:type cursor: str
:param iconStrip:
:type iconStrip: bool
:param x: The x location in the plot, to set the cursor at.
:type x: float
:param y: The y location in the plot, to set the cursor at.
:type y: float


.. _setSnapping:
.. method:: setSnapping(self, on=True, xgrid=None, ygrid=None, snapPoints=None)

Snap mouse moves to points/lines as the user moves the mouse.

:param on: Determines the state of snapping.
:type on: bool
:param xgrid: Determines whether it snaps to x-axis
:type xgrid: bool
:param ygrid: Determines whether it snaps to y-axis.
:type ygrid: bool
:param snapPoints: The points/lines to snap to.
:type snapPoints: list[CurvePoints]

:returns: A reference to the instance XyPlot object on which it was called.
:rtype: XyPlot


.. _zoom:
.. method:: zoom(self, factor=1.5, point=None, axis='both')

Rescales the axes by the specified factor at the specified point.

:param factor: The zoom factor.
            if factor > 1 the plot is zoomed out.
            If factor < 1 the plot is zoomed in.
:type factor: float
:param point: Specified point to zoom into.
           Defaults to None, and the plot is scaled at the center.
:type point: Point
:param axis: The axis to be zoomed into.
          Defaults to "both", valid choices are 'x' and 'y'.
:type axis: str

:returns: A reference to the instance XyPlot object on which it was called.
:rtype: XyPlot