<commit_before>'''
Backend Kivy
=====

.. versionadded:: 1.9.1

.. image:: images/backend_kivy_example.jpg
    :align: right

The :class:`FigureCanvasKivy` widget is used to create a matplotlib graph.
This widget has the same properties as
:class:`kivy.ext.mpl.backend_kivyagg.FigureCanvasKivyAgg`. FigureCanvasKivy
instead of rendering a static image, uses the kivy graphics instructions
:class:`kivy.graphics.Line` and :class:`kivy.graphics.Mesh` to render on the
canvas.

Installation
------------

The matplotlib backend for kivy can be used by using the garden extension in
kivy following this .. _link: http://kivy.org/docs/api-kivy.garden.html ::

    garden install matplotlib

Or if you want to include it directly on your application ::

    cd myapp
    garden install --app graph


Initialization
--------------

A backend can be initialized in two ways. The first one is using pure pyplot
as explained
.. _here: http://matplotlib.org/faq/usage_faq.html#what-is-a-backend::

    import matplotlib
    matplotlib.use('module://kivy.garden.matplotlib.backend_kivy')

Once this is done, any figure instantiated after will be wrapped by a
:class:`FigureCanvasKivy` ready to use. From here there are two options to
continue with the development.

1. Use the :class:`FigureCanvasKivy` attribute defined as canvas from Figure,
to embed your matplotlib graph in your own Kivy application as can be seen in
the first example in the following section.

.. warning::

    One can create a matplotlib widget by importing FigureCanvas::

        from kivy.garden.matplotlib.backend_kivyagg import FigureCanvas
        or
        from kivy.garden.matplotlib.backend_kivy import FigureCanvas

    and then instantiate an object::

        fig, ax = plt.subplots()
        my_mpl_kivy_widget = FigureCanvas(fig)

    which will certainly work but a problem will arise if events were connected
    before the FigureCanvas is instantiated. If this approach is taken please
    connect matplotlib events after generating the matplotlib kivy widget
    object ::

        fig, ax = plt.subplots()
        fig.canvas.mpl_connect('button_press_event', callback_handler)
        my_mpl_kivy_widget = FigureCanvas(fig)

    In this scenario button_press_event won't be connected with the object
    being created in line 3, because will be connected to the default canvas
    set by matplotlib. If this approach is taken be sure of connecting the
    events after instantiation. ::

        fig, ax = plt.subplots()
        fig.canvas.mpl_connect('button_press_event', callback_handler)
        my_mpl_kivy_widget = FigureCanvas(fig)

2. Use pyplot to write the application following matplotlib sintax as can be
seen in the second example below. In this case a Kivy application will be
created automatically from the matplotlib instructions and a NavigationToolbar
will be added to the main canvas.


Examples
--------

1. Example of a simple Hello world matplotlib App::

    fig, ax = plt.subplots()
    ax.text(0.6, 0.5, "hello", size=50, rotation=30.,
            ha="center", va="center",
            bbox=dict(boxstyle="round",
                      ec=(1., 0.5, 0.5),
                      fc=(1., 0.8, 0.8),
                      )
            )
    ax.text(0.5, 0.4, "world", size=50, rotation=-30.,
            ha="right", va="top",
            bbox=dict(boxstyle="square",
                      ec=(1., 0.5, 0.5),
                      fc=(1., 0.8, 0.8),
                      )
            )
    canvas = fig.canvas

The object canvas can be added as a widget into the kivy tree widget.
If a change is done on the figure an update can be performed using
:meth:`~kivy.ext.mpl.backend_kivyagg.FigureCanvasKivyAgg.draw`.::

    # update graph
    canvas.draw()

The plot can be exported to png with
:meth:`~kivy.ext.mpl.backend_kivyagg.FigureCanvasKivyAgg.print_png`, as an
argument receives the `filename`.::

    # export to png
    canvas.print_png("my_plot.png")

2. Example of a pyplot application using matplotlib instructions::

    import numpy as np
    import matplotlib.pyplot as plt

    N = 5
    menMeans = (20, 35, 30, 35, 27)
    menStd = (2, 3, 4, 1, 2)
    ind = np.arange(N)  # the x locations for the groups
    width = 0.35       # the width of the bars
    figure, ax = plt.subplots()

    rects1 = ax.bar(ind, menMeans, width, color='r', yerr=menStd)
    womenMeans = (25, 32, 34, 20, 25)
    womenStd = (3, 5, 2, 3, 3)
    rects2 = ax.bar(ind + width, womenMeans, width, color='y', yerr=womenStd)

    ax.set_ylabel('----------------------Scores------------------')
    ax.set_title('Scores by group and gender')
    ax.set_xticks(ind + width)
    ax.set_yticklabels(('Ahh', '--G1--', 'G2', 'G3', 'G4', 'G5', 'G5',
                        'G5', 'G5'), rotation=90)
    ax.legend((rects1[0], rects2[0]), ('Men', 'Women'))
    plt.draw()
    plt.savefig("test.png")
    plt.show()


Naviation Toolbar
-----------------

If initialized by the first step a :class:`NavigationToolbarKivy` widget can be
created as well by instantiating an object with a :class:`FigureCanvasKivy` as
parameter. The actual widget is stored in its actionbar attribute.
This can be seen in test_backend.py example ::

    bl = BoxLayout(orientation="vertical")
    my_mpl_kivy_widget1 = FigureCanvasKivy(fig1)
    my_mpl_kivy_widget2 = FigureCanvasKivy(fig2)
    nav1 = NavigationToolbar2Kivy(my_mpl_kivy_widget1)
    nav2 = NavigationToolbar2Kivy(my_mpl_kivy_widget2)
    bl.add_widget(nav1.actionbar)
    bl.add_widget(nav2.actionbar)


Connecting Matplotlib events to Kivy Events
-----------------------

All ten matplotlib events are available: `button_press_event` which is raised
on a mouse button clicked or on touch down, `button_release_event` which is
raised when a click button is released or on touch up, `key_press_event` which
is raised when a key is pressed, `key_release_event` which is raised when a key
is released, `motion_notify_event` which is raised when the mouse is on motion,
`resize_event` which is raised when the dimensions of the widget change,
`scroll_event` which is raised when the mouse scroll wheel is rolled,<commit_msg>Last commit for revision making sure examples run in python2, python3, matplotlib 1.4.3 and matplotlib 1.5dev1<commit_after>'''
Backend Kivy
=====

.. versionadded:: 1.9.1

.. image:: images/backend_kivy_example.jpg
    :align: right

The :class:`FigureCanvasKivy` widget is used to create a matplotlib graph.
This widget has the same properties as
:class:`kivy.ext.mpl.backend_kivyagg.FigureCanvasKivyAgg`. FigureCanvasKivy
instead of rendering a static image, uses the kivy graphics instructions
:class:`kivy.graphics.Line` and :class:`kivy.graphics.Mesh` to render on the
canvas.

Installation
------------

The matplotlib backend for kivy can be used by using the garden extension in
kivy following this .. _link: http://kivy.org/docs/api-kivy.garden.html ::

    garden install matplotlib

Or if you want to include it directly on your application ::

    cd myapp
    garden install --app graph


Initialization
--------------

A backend can be initialized in two ways. The first one is using pure pyplot
as explained
.. _here: http://matplotlib.org/faq/usage_faq.html#what-is-a-backend::

    import matplotlib
    matplotlib.use('module://kivy.garden.matplotlib.backend_kivy')

Once this is done, any figure instantiated after will be wrapped by a
:class:`FigureCanvasKivy` ready to use. From here there are two options to
continue with the development.

1. Use the :class:`FigureCanvasKivy` attribute defined as canvas from Figure,
to embed your matplotlib graph in your own Kivy application as can be seen in
the first example in the following section.

.. warning::

    One can create a matplotlib widget by importing FigureCanvas::

        from kivy.garden.matplotlib.backend_kivyagg import FigureCanvas
        or
        from kivy.garden.matplotlib.backend_kivy import FigureCanvas

    and then instantiate an object::

        fig, ax = plt.subplots()
        my_mpl_kivy_widget = FigureCanvas(fig)

    which will certainly work but a problem will arise if events were connected
    before the FigureCanvas is instantiated. If this approach is taken please
    connect matplotlib events after generating the matplotlib kivy widget
    object ::

        fig, ax = plt.subplots()
        fig.canvas.mpl_connect('button_press_event', callback_handler)
        my_mpl_kivy_widget = FigureCanvas(fig)

    In this scenario button_press_event won't be connected with the object
    being created in line 3, because will be connected to the default canvas
    set by matplotlib. If this approach is taken be sure of connecting the
    events after instantiation like the following: ::

        fig, ax = plt.subplots()
        my_mpl_kivy_widget = FigureCanvas(fig)
        fig.canvas.mpl_connect('button_press_event', callback_handler)

2. Use pyplot to write the application following matplotlib sintax as can be
seen in the second example below. In this case a Kivy application will be
created automatically from the matplotlib instructions and a NavigationToolbar
will be added to the main canvas.


Examples
--------

1. Example of a simple Hello world matplotlib App::

    fig, ax = plt.subplots()
    ax.text(0.6, 0.5, "hello", size=50, rotation=30.,
            ha="center", va="center",
            bbox=dict(boxstyle="round",
                      ec=(1., 0.5, 0.5),
                      fc=(1., 0.8, 0.8),
                      )
            )
    ax.text(0.5, 0.4, "world", size=50, rotation=-30.,
            ha="right", va="top",
            bbox=dict(boxstyle="square",
                      ec=(1., 0.5, 0.5),
                      fc=(1., 0.8, 0.8),
                      )
            )
    canvas = fig.canvas

The object canvas can be added as a widget into the kivy tree widget.
If a change is done on the figure an update can be performed using
:meth:`~kivy.ext.mpl.backend_kivyagg.FigureCanvasKivyAgg.draw`.::

    # update graph
    canvas.draw()

The plot can be exported to png with
:meth:`~kivy.ext.mpl.backend_kivyagg.FigureCanvasKivyAgg.print_png`, as an
argument receives the `filename`.::

    # export to png
    canvas.print_png("my_plot.png")

2. Example of a pyplot application using matplotlib instructions::

    import numpy as np
    import matplotlib.pyplot as plt

    N = 5
    menMeans = (20, 35, 30, 35, 27)
    menStd = (2, 3, 4, 1, 2)
    ind = np.arange(N)  # the x locations for the groups
    width = 0.35       # the width of the bars
    figure, ax = plt.subplots()

    rects1 = ax.bar(ind, menMeans, width, color='r', yerr=menStd)
    womenMeans = (25, 32, 34, 20, 25)
    womenStd = (3, 5, 2, 3, 3)
    rects2 = ax.bar(ind + width, womenMeans, width, color='y', yerr=womenStd)

    ax.set_ylabel('----------------------Scores------------------')
    ax.set_title('Scores by group and gender')
    ax.set_xticks(ind + width)
    ax.set_yticklabels(('Ahh', '--G1--', 'G2', 'G3', 'G4', 'G5', 'G5',
                        'G5', 'G5'), rotation=90)
    ax.legend((rects1[0], rects2[0]), ('Men', 'Women'))
    plt.draw()
    plt.savefig("test.png")
    plt.show()


Naviation Toolbar
-----------------

If initialized by the first step a :class:`NavigationToolbarKivy` widget can be
created as well by instantiating an object with a :class:`FigureCanvasKivy` as
parameter. The actual widget is stored in its actionbar attribute.
This can be seen in test_backend.py example ::

    bl = BoxLayout(orientation="vertical")
    my_mpl_kivy_widget1 = FigureCanvasKivy(fig1)
    my_mpl_kivy_widget2 = FigureCanvasKivy(fig2)
    nav1 = NavigationToolbar2Kivy(my_mpl_kivy_widget1)
    nav2 = NavigationToolbar2Kivy(my_mpl_kivy_widget2)
    bl.add_widget(nav1.actionbar)
    bl.add_widget(my_mpl_kivy_widget1)
    bl.add_widget(nav2.actionbar)
    bl.add_widget(my_mpl_kivy_widget2)


Connecting Matplotlib events to Kivy Events
-----------------------

All ten matplotlib events are available: `button_press_event` which is raised
on a mouse button clicked or on touch down, `button_release_event` which is
raised when a click button is released or on touch up, `key_press_event` which
is raised when a key is pressed, `key_release_event` which is raised when a key
is released, `motion_notify_event` which is raised when the mouse is on motion,
`resize_event` which is raised when the dimensions of the widget change,
`scroll_event` which is raised when the mouse scroll wheel is rolled,
{'fraction_non_alphanumeric': 0.10525052024971987, 'fraction_numerical': 0.017768528893869057, 'mean_word_length': 3.018977163074944, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5274139', 'n_tokens_mistral': 4047, 'n_tokens_neox': 3822, 'n_words': 1347}