Menu
▾
▴
SF.net SVN: matplotlib: [5463] trunk/matplotlib
|
From: <jd...@us...> - 2008-06-10 18:10:15
|
Revision: 5463
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5463&view=rev
Author: jdh2358
Date: 2008-06-10 11:08:50 -0700 (Tue, 10 Jun 2008)
Log Message:
-----------
added backend bases api
Modified Paths:
--------------
trunk/matplotlib/CHANGELOG
trunk/matplotlib/doc/api/index.rst
trunk/matplotlib/doc/users/event_handling.rst
trunk/matplotlib/doc/users/figures/text_commands.py
trunk/matplotlib/lib/matplotlib/backend_bases.py
trunk/matplotlib/lib/matplotlib/text.py
Added Paths:
-----------
trunk/matplotlib/doc/api/backend_api.rst
Modified: trunk/matplotlib/CHANGELOG
===================================================================
--- trunk/matplotlib/CHANGELOG 2008-06-10 15:53:19 UTC (rev 5462)
+++ trunk/matplotlib/CHANGELOG 2008-06-10 18:08:50 UTC (rev 5463)
@@ -1,6 +1,8 @@
-2008-06-10 Bar now applies the label only to the frist patch, and
- sets _nolegend_ for the other patch labels. This let's
- autolegend work as expected for hist and bar
+2008-06-10 Bar now applies the label only to the first patch only, and
+ sets '_nolegend_' for the other patch labels. This lets
+ autolegend work as expected for hist and bar - see
+ https://sourceforge.net/tracker/index.php?func=detail&aid=1986597&group_id=80706&atid=560720
+ JDH
2008-06-10 Fix text baseline alignment bug. [ 1985420 ] Repair of
baseline alignment in Text._get_layout. Thanks Stan West -
Added: trunk/matplotlib/doc/api/backend_api.rst
===================================================================
--- trunk/matplotlib/doc/api/backend_api.rst (rev 0)
+++ trunk/matplotlib/doc/api/backend_api.rst 2008-06-10 18:08:50 UTC (rev 5463)
@@ -0,0 +1,11 @@
+*******************
+matplotlib backends
+*******************
+
+
+:mod:`matplotlib.backend_bases`
+================================
+
+.. automodule:: matplotlib.backend_bases
+ :members:
+ :undoc-members:
Modified: trunk/matplotlib/doc/api/index.rst
===================================================================
--- trunk/matplotlib/doc/api/index.rst 2008-06-10 15:53:19 UTC (rev 5462)
+++ trunk/matplotlib/doc/api/index.rst 2008-06-10 18:08:50 UTC (rev 5463)
@@ -7,11 +7,9 @@
:Release: |version|
:Date: |today|
-Introduction to developer's guide here **TODO**.
-
.. toctree::
artist_api.rst
axes_api.rst
pyplot_api.rst
-
+ backend_api.rst
Modified: trunk/matplotlib/doc/users/event_handling.rst
===================================================================
--- trunk/matplotlib/doc/users/event_handling.rst 2008-06-10 15:53:19 UTC (rev 5462)
+++ trunk/matplotlib/doc/users/event_handling.rst 2008-06-10 18:08:50 UTC (rev 5463)
@@ -13,9 +13,10 @@
handling API is GUI neutral, it is based on the GTK model, which was
the first user interface matplotlib supported. The events that are
triggered are also a bit richer vis-a-vis matplotlib than standard GUI
-events, including information like which Axes the event occurred in.
-The events also understand the matplotlib coordinate system, and
-report event locations in both pixel and data coordinates.
+events, including information like which :class:`matplotlib.axes.Axes`
+the event occurred in. The events also understand the matplotlib
+coordinate system, and report event locations in both pixel and data
+coordinates.
.. _event-connections:
@@ -24,8 +25,9 @@
To receive events, you need to write a callback function and then
connect your function to the event manager, which is part of the
-FigureCanvas. Here is a simple example that prints the location of
-the mouse click and which button was pressed::
+:class:`~matplotlib.backend_bases.FigureCanvasBase`. Here is a simple
+example that prints the location of the mouse click and which button
+was pressed::
fig = plt.figure()
ax = fig.add_subplot(111)
@@ -37,9 +39,10 @@
cid = fig.canvas.mpl_connect('button_press_event', onclick)
-The FigureCanvas method mpl_connect returns a connection id which is
-simply an integer. When you want to disconnect the callback, just
-call::
+The ``FigureCanvas`` method
+:meth:`~matplotlib.backend_bases.FigureCanvasBase.mpl_connect` returns
+a connection id which is simply an integer. When you want to
+disconnect the callback, just call::
fig.canvas.mpl_disconnect(cid)
@@ -47,19 +50,19 @@
are sent back to you when the event occurs, and the event descriptions
-===================== =========== ===================================
-Event name Class Description
-===================== =========== ===================================
-button_press_event MouseEvent mouse button is pressed
-button_release_event MouseEvent mouse button is released
-draw_event DrawEvent canvas draw
-key_press_event KeyEvent key is pressed
-key_release_event KeyEvent key is released
-motion_notify_event MouseEvent mouse motion
-pick_event PickEvent an object in the canvas is selected
-resize_event ResizeEvent figure canvas is resized
-scroll_event MouseEvent mouse scroll wheel is rolled
-===================== =========== ===================================
+======================= ======================================================================================
+Event name Class and description
+======================= ======================================================================================
+'button_press_event' :class:`~matplotlib.backend_bases.MouseEvent` - mouse button is pressed
+'button_release_event' :class:`~matplotlib.backend_bases.MouseEvent` - mouse button is released
+'draw_event' :class:`~matplotlib.backend_bases.DrawEvent` - canvas draw
+'key_press_event' :class:`~matplotlib.backend_bases.KeyEvent` - key is pressed
+'key_release_event' :class:`~matplotlib.backend_bases.KeyEvent` - key is released
+'motion_notify_event' :class:`~matplotlib.backend_bases.MouseEvent` - mouse motion
+'pick_event' :class:`~matplotlib.backend_bases.PickEvent` - an object in the canvas is selected
+'resize_event' :class:`~matplotlib.backend_bases.ResizeEvent` - figure canvas is resized
+'scroll_event' :class:`~matplotlib.backend_bases.MouseEvent` - mouse scroll wheel is rolled
+======================= ======================================================================================
.. _event-attributes:
@@ -67,31 +70,32 @@
================
All matplotlib events inherit from the base class
-matplotlib.backend_bases.Event, which store the attributes
+:class:`matplotlib.backend_bases.Event`, which store the attributes
=============== =================================================
Event attribute Description
=============== =================================================
-name the event name
-canvas the FigureCanvas instance generating the event
-guiEvent the GUI event that triggered the matplotlib event
+``name`` the event name
+``canvas`` the FigureCanvas instance generating the event
+``guiEvent`` the GUI event that triggered the matplotlib event
=============== =================================================
The most common events that are the bread and butter of event handling
are key press/release events and mouse press/release and movement
-events. The KeyEvent and MouseEvent classes that handle these events
-are both derived from the LocationEvent, which has the following
-attributes
+events. The :class:`~matplotlib.backend_bases.KeyEvent` and
+:class:`~matplotlib.backend_bases.MouseEvent` classes that handle
+these events are both derived from the LocationEvent, which has the
+following attributes
======================= ========================================
LocationEvent attribute Description
======================= ========================================
-x x position - pixels from left of canvas
-y y position - pixels from right of canvas
-button button pressed None, 1, 2, 3
-inaxes the Axes instance if mouse us over axes
-xdata x coord of mouse in data coords
-ydata y coord of mouse in data coords
+``x`` x position - pixels from left of canvas
+``y`` y position - pixels from right of canvas
+``button`` button pressed None, 1, 2, 3
+``inaxes`` the Axes instance if mouse us over axes
+``xdata`` x coord of mouse in data coords
+``ydata`` y coord of mouse in data coords
======================= ========================================
Let's look a simple example of a canvas, where a simple line segment
@@ -120,31 +124,33 @@
-The MouseEvent that we just used is a LocationEvent, so we have access
-to the data and pixel coordinates in event.x and event.xdata. In
-addition to the LocationEvent attributes, it has
+The :class:`~matplotlib.backend_bases.MouseEvent` that we just used is a
+:class:`~matplotlib.backend_bases.LocationEvent`, so we have access to
+the data and pixel coordinates in event.x and event.xdata. In
+addition to the ``LocationEvent`` attributes, it has
==================== ==============================================================
MouseEvent attribute Description
==================== ==============================================================
-button button pressed None, 1, 2, 3
-key the key pressed: None, chr(range(255)), shift, win, or control
+``button`` button pressed None, 1, 2, 3
+``key`` the key pressed: None, chr(range(255)), shift, win, or control
==================== ==============================================================
Draggable Rectangle Exercise
----------------------------
-Write draggable rectangle class that is initialized with a Rectangle
-instance but will move its x,y location when dragged. Hint: you will
-need to store the orginal xy location of the rectangle which is stored
-as rect.xy and connect to the press, motion and release mouse events.
-When the mouse is pressed, check to see if the click occurs over your
-rectangle (see rect.contains) and if it does, store the rectangle xy
-and the location of the mouse click in data coords. In the motion
-event callback, compute the deltax and deltay of the mouse movement,
-and add those deltas to the origin of the rectangle you stored. The
-redraw the figure. On the button release event, just reset all the
-button press data you stored as None.
+Write draggable rectangle class that is initialized with a
+:class:`~matplotlib.patches.Rectangle` instance but will move its x,y
+location when dragged. Hint: you will need to store the orginal
+``xy`` location of the rectangle which is stored as rect.xy and
+connect to the press, motion and release mouse events. When the mouse
+is pressed, check to see if the click occurs over your rectangle (see
+:meth:`matplotlib.patches.Rectangle.contains`) and if it does, store
+the rectangle xy and the location of the mouse click in data coords.
+In the motion event callback, compute the deltax and deltay of the
+mouse movement, and add those deltas to the origin of the rectangle
+you stored. The redraw the figure. On the button release event, just
+reset all the button press data you stored as None.
Here is the solution::
@@ -212,8 +218,9 @@
plt.show()
-**Extra credit**: use the animation blit techniques discussed at
-http://www.scipy.org/Cookbook/Matplotlib/Animations to make the
+**Extra credit**: use the animation blit techniques discussed in the
+`animations recipe
+<http://www.scipy.org/Cookbook/Matplotlib/Animations>`_ to make the
animated drawing faster and smoother.
Extra credit solution::
@@ -325,30 +332,32 @@
Object Picking
==============
-You can enable picking by setting the ``picker`` property of an Artist
-(eg a matplotlib Line2D, Text, Patch, Polygon, AxesImage,
-etc...)
+You can enable picking by setting the ``picker`` property of an
+:class:`~matplotlib.artist.Artist` (eg a matplotlib
+:class:`~matplotlib.lines.Line2D`, :class:`~matplotlib.text.Text`,
+:class:`~matplotlib.patches.Patch`, :class:`~matplotlib.patches.Polygon`,
+:class:`~matplotlib.patches.AxesImage`, etc...)
-There are a variety of meanings of the picker property:
+There are a variety of meanings of the ``picker`` property:
-- None : picking is disabled for this artist (default)
+- ``None`` : picking is disabled for this artist (default)
-- boolean : if True then picking will be enabled and the artist will
+- ``boolean`` : if True then picking will be enabled and the artist will
fire a pick event if the mouse event is over the artist
-- float : if picker is a number it is interpreted as an epsilon
+- ``float`` : if picker is a number it is interpreted as an epsilon
tolerance in points and the the artist will fire off an event if its
data is within epsilon of the mouse event. For some artists like
lines and patch collections, the artist may provide additional data
to the pick event that is generated, eg the indices of the data
within epsilon of the pick event.
-- function : if picker is callable, it is a user supplied function
+- ``function`` : if picker is callable, it is a user supplied function
which determines whether the artist is hit by the mouse event. The
signature is ``hit, props = picker(artist, mouseevent)`` to
determine the hit test. If the mouse event is over the artist,
- return hit=True and props is a dictionary of properties you want
- added to the PickEvent attributes
+ return ``hit=True`` and props is a dictionary of properties you want
+ added to the :class:`~matplotlib.backend_bases.PickEvent` attributes
After you have enabled an artist for picking by setting the ``picker``
@@ -361,22 +370,24 @@
# now do something with this...
-The pick event (matplotlib.backend_bases.PickEvent) which is passed to
+The :class:`~matplotlib.backend_bases.PickEvent` which is passed to
your callback is always fired with two attributes:
-- mouseevent : the mouse event that generate the pick event. The
- mouse event in turn has attributes like x and y (the coords in
+- ``mouseevent`` : the mouse event that generate the pick event. The
+ mouse event in turn has attributes like ``x`` and ``y`` (the coords in
display space, eg pixels from left, bottom) and xdata, ydata (the
coords in data space). Additionally, you can get information about
which buttons were pressed, which keys were pressed, which Axes the
- mouse is over, etc. See matplotlib.backend_bases.MouseEvent for
+ mouse is over, etc. See :class:`matplotlib.backend_bases.MouseEvent` for
details.
-- artist : the matplotlib.artist that generated the pick event.
+- ``artist`` : the :class:`matplotlib.artist.Artist` that generated
+ the pick event.
-Additionally, certain artists like Line2D and PatchCollection may
-attach additional meta data like the indices into the data that meet
-the picker criteria (eg all the points in the line that are within the
+Additionally, certain artists like :class:`~matplotlib.lines.Line2D`
+and :class:`~matplotlib.collections.PatchCollection` may attach
+additional meta data like the indices into the data that meet the
+picker criteria (eg all the points in the line that are within the
specified epsilon tolerance)
Simple picking example
@@ -389,10 +400,10 @@
vertices that are within the pick distance tolerance. Our onpick
callback function simply prints the data that are under the pick
location. Different matplotlib Artists can attach different data to
-the PickEvent. For example, Line2D attaches the ind property, which
-are the indices into the line data under the pick point. See
-Line2D.pick for details on the PickEvent properties of the line. Here
-is the code::
+the PickEvent. For example, ``Line2D`` attaches the ind property,
+which are the indices into the line data under the pick point. See
+:meth:`~matplotlib.lines.Line2D.pick` for details on the ``PickEvent``
+properties of the line. Here is the code::
import numpy as np
import matplotlib.pyplot as plt
Modified: trunk/matplotlib/doc/users/figures/text_commands.py
===================================================================
--- trunk/matplotlib/doc/users/figures/text_commands.py 2008-06-10 15:53:19 UTC (rev 5462)
+++ trunk/matplotlib/doc/users/figures/text_commands.py 2008-06-10 18:08:50 UTC (rev 5463)
@@ -10,10 +10,15 @@
ax.set_xlabel('xlabel')
ax.set_ylabel('ylabel')
-ax.text(5, 8, 'italics text in data coords', style='italic')
+
+ax.text(5, 8, 'boxed italics text in data coords', style='italic',
+ bbox={'facecolor':'red', 'alpha':0.5, 'pad':10})
+
ax.text(2, 6, r'an equation: $E=mc^2$', fontsize=20)
-ax.text(0.95, 0.01, 'text in axes coords',
+ax.text(4, 3, unicode('unicode: Institut f\374r Festk\366rperphysik', 'latin-1'))
+
+ax.text(0.95, 0.01, 'colored text in axes coords',
verticalalignment='bottom', horizontalalignment='right',
transform=ax.transAxes,
color='green', fontsize=20)
Modified: trunk/matplotlib/lib/matplotlib/backend_bases.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/backend_bases.py 2008-06-10 15:53:19 UTC (rev 5462)
+++ trunk/matplotlib/lib/matplotlib/backend_bases.py 2008-06-10 18:08:50 UTC (rev 5463)
@@ -1,6 +1,24 @@
"""
Abstract base classes define the primitives that renderers and
graphics contexts must implement to serve as a matplotlib backend
+
+:class:`RendererBase`
+ An abstract base class to handle drawing/rendering operations.
+
+:class:`FigureCanvasBase`
+ The abstraction layer that separates the
+ :class:`matplotlib.figure.Figure` from the backend specific
+ details like a user interface drawing area
+
+:class:`GraphicsContextBase`
+ An abstract base class that provides color, line styles, etc...
+
+:class:`Event`
+ The base class for all of the matplotlib event
+ handling. Derived classes suh as :class:`KeyEvent` and
+ :class:`MouseEvent` store the meta data like keys and buttons
+ pressed, x and y locations in pixel and
+ :class:`~matplotlib.axes.Axes` coordinates.
"""
from __future__ import division
@@ -20,36 +38,39 @@
The following methods *must* be implemented in the backend:
- draw_path
- draw_image
- draw_text
- get_text_width_height_descent
+ * draw_path
+ * draw_image
+ * draw_text
+ * get_text_width_height_descent
The following methods *should* be implemented in the backend for
optimization reasons:
- draw_markers
- draw_path_collection
- draw_quad_mesh
+ * draw_markers
+ * draw_path_collection
+ * draw_quad_mesh
"""
def __init__(self):
self._texmanager = None
def open_group(self, s):
- """open a grouping element with label s
- Is only currently used by backend_svg
"""
+ Open a grouping element with label ``s.`` Is only currently used by
+ :mod:`~matplotlib.backends.backend_svg`
+ """
pass
def close_group(self, s):
- """close a grouping element with label s
- Is only currently used by backend_svg
"""
+ Close a grouping element with label ``s``
+ Is only currently used by :mod:`~matplotlib.backends.backend_svg`
+ """
pass
def draw_path(self, gc, path, transform, rgbFace=None):
"""
- Draws a Path instance using the given affine transform.
+ Draws a :class:`~matplotlib.path.Path` instance using the
+ given affine transform.
"""
raise NotImplementedError
@@ -60,13 +81,14 @@
that behavior, those vertices should be removed before calling
this function.
- marker_trans is an affine transform applied to the marker.
- trans is an affine transform applied to the path.
+ ``marker_trans`` is an affine transform applied to the marker.
+ ``trans`` is an affine transform applied to the path.
This provides a fallback implementation of draw_markers that
- makes multiple calls to draw_path. Some backends may want to
- override this method in order to draw the marker only once and
- reuse it multiple times.
+ makes multiple calls to
+ :meth:`draw_path`. Some
+ backends may want to override this method in order to draw the
+ marker only once and reuse it multiple times.
"""
tpath = trans.transform_path(path)
for x, y in tpath.vertices:
@@ -80,20 +102,24 @@
linestyles, antialiaseds):
"""
Draws a collection of paths, selecting drawing properties from
- the lists facecolors, edgecolors, linewidths, linestyles and
- antialiaseds. offsets is a list of offsets to apply to each
- of the paths. The offsets in offsets are first transformed by
- offsetTrans before being applied.
+ the lists ``facecolors``, ``edgecolors``, ``linewidths``,
+ ``linestyles`` and ``antialiaseds``. `` offsets`` is a list of
+ offsets to apply to each of the paths. The offsets in
+ ``offsets`` are first transformed by ``offsetTrans`` before
+ being applied.
This provides a fallback implementation of
draw_path_collection that makes multiple calls to draw_path.
Some backends may want to override this in order to render
each set of path data only once, and then reference that path
multiple times with the different offsets, colors, styles etc.
- The generator methods _iter_collection_raw_paths and
- _iter_collection are provided to help with (and standardize)
- the implementation across backends. It is highly recommended
- to use those generators, so that changes to the behavior of
+ The generator methods
+ :meth:`_iter_collection_raw_paths`
+ and
+ :meth:`_iter_collection`
+ are provided to help with (and standardize) the implementation
+ across backends. It is highly recommended to use those
+ generators, so that changes to the behavior of
draw_path_collection can be made globally.
"""
path_ids = []
@@ -115,7 +141,7 @@
showedges):
"""
This provides a fallback implementation of draw_quad_mesh that
- generates paths and then calls draw_path_collection.
+ generates paths and then calls :meth:`draw_path_collection`.
"""
from matplotlib.collections import QuadMesh
paths = QuadMesh.convert_mesh_to_paths(
@@ -135,8 +161,8 @@
def _iter_collection_raw_paths(self, master_transform, paths, all_transforms):
"""
- This is a helper method (along with _iter_collection) to make
- it easier to write a space-efficent draw_path_collection
+ This is a helper method (along with :meth:`_iter_collection`) to make
+ it easier to write a space-efficent :meth:`draw_path_collection`
implementation in a backend.
This method yields all of the base path/transform
@@ -144,7 +170,7 @@
list of transforms.
The arguments should be exactly what is passed in to
- draw_path_collection.
+ :meth:`draw_path_collection`.
The backend should take each yielded path and transform and
create an object can be referenced (reused) later.
@@ -168,8 +194,8 @@
linewidths, linestyles, antialiaseds):
"""
This is a helper method (along with
- _iter_collection_raw_paths) to make it easier to write a
- space-efficent draw_path_collection implementation in a
+ :meth:`_iter_collection_raw_paths`) to make it easier to write
+ a space-efficent :meth:`draw_path_collection` implementation in a
backend.
This method yields all of the path, offset and graphics
@@ -237,7 +263,7 @@
def get_image_magnification(self):
"""
- Get the factor by which to magnify images passed to draw_image.
+ Get the factor by which to magnify images passed to :meth:`draw_image`.
Allows a backend to have images at a different resolution to other
artists.
"""
@@ -245,13 +271,13 @@
def draw_image(self, x, y, im, bbox, clippath=None, clippath_trans=None):
"""
- Draw the Image instance into the current axes; x is the
- distance in pixels from the left hand side of the canvas. y is
- the distance from the origin. That is, if origin is upper, y
- is the distance from top. If origin is lower, y is the
- distance from bottom
+ Draw the :class:`~matplotlib.image.Image` instance into the
+ current axes; ``x`` is the distance in pixels from the left
+ hand side of the canvas. ``y`` is the distance from the
+ origin. That is, if origin is upper, y is the distance from
+ top. If origin is lower, y is the distance from bottom
- bbox is a matplotlib.transforms.BBox instance for clipping, or
+ bbox is a :class:`~matplotlib.transforms.Bbox` instance for clipping, or
None
"""
raise NotImplementedError
@@ -268,8 +294,10 @@
def draw_text(self, gc, x, y, s, prop, angle, ismath=False):
"""
- Draw the text.Text instance s at x,y (display coords) with font
- properties instance prop at angle in degrees, using GraphicsContext gc
+ Draw the :class:`~matplotlib.text.Text` instance s at ``x``,
+ ``y`` (display coords) with
+ :class:`~matplotlib.font_manager.FontProperties` instance
+ ``prop`` at ``angle`` in degrees, using :class:`GraphicsContextBase` gc
**backend implementers note**
@@ -285,9 +313,11 @@
raise NotImplementedError
def flipy(self):
- """return true if y small numbers are top for renderer
- Is used for drawing text (text.py) and images (image.py) only
"""
+ Return true if y small numbers are top for renderer Is used
+ for drawing text (:mod:`matplotlib.text`) and images
+ (:mod:`matplotlib.image`) only
+ """
return True
def get_canvas_width_height(self):
@@ -295,6 +325,9 @@
return 1, 1
def get_texmanager(self):
+ """
+ return the :class:matplotlib.texmanager.TexManager` instance
+ """
if self._texmanager is None:
from matplotlib.texmanager import TexManager
self._texmanager = TexManager()
@@ -304,13 +337,13 @@
"""
get the width and height, and the offset from the bottom to the
baseline (descent), in display coords of the string s with
- FontPropertry prop
+ :class:`~matplotlib.font_manager.FontProperties` prop
"""
raise NotImplementedError
def new_gc(self):
"""
- Return an instance of a GraphicsContextBase
+ Return an instance of a :class:`GraphicsContextBase`
"""
return GraphicsContextBase()
@@ -322,8 +355,9 @@
You need to override this function (unless your backend doesn't have a
dpi, eg, postscript or svg).
- Some imaging systems assume some value for pixels per inch.
- points to pixels = points * pixels_per_inch/72.0 * dpi/72.0
+ Some imaging systems assume some value for pixels per inch""
+
+ points to pixels = points * pixels_per_inch/72.0 * dpi/72.0
"""
return points
@@ -338,8 +372,9 @@
class GraphicsContextBase:
- """An abstract base class that provides color, line styles, etc...
"""
+ An abstract base class that provides color, line styles, etc...
+ """
# a mapping from dash styles to suggested offset, dash pairs
dashd = {
@@ -395,15 +430,15 @@
def get_clip_rectangle(self):
"""
- Return the clip rectangle as a Bbox instance
+ Return the clip rectangle as a :class:`~matplotlib.transforms.Bbox` instance
"""
return self._cliprect
def get_clip_path(self):
"""
Return the clip path in the form (path, transform), where path
- is a path.Path instance, and transform as an affine transform
- to apply to the path before clipping.
+ is a :class:`~matplotlib.path.Path` instance, and transform as
+ an affine transform to apply to the path before clipping.
"""
if self._clippath is not None:
return self._clippath.get_transformed_path_and_affine()
@@ -413,7 +448,9 @@
"""
Return the dash information as an offset dashlist tuple The
dash list is a even size list that gives the ink on, ink off
- in pixels. See p107 of to postscript BLUEBOOK for more info
+ in pixels. See p107 of to postscript `BLUEBOOK
+ <http://www-cdf.fnal.gov/offline/PostScript/BLUEBOOK.PDF>`_
+ for more info
Default value is None
"""
@@ -479,7 +516,7 @@
def set_clip_path(self, path):
"""
Set the clip path and transformation. Path should be a
- transforms.TransformedPath instance.
+ :class:`~matplotlib.transforms.TransformedPath` instance.
"""
assert path is None or isinstance(path, transforms.TransformedPath)
self._clippath = path
@@ -487,9 +524,12 @@
def set_dashes(self, dash_offset, dash_list):
"""
Set the dash style for the gc.
- dash_offset is the offset (usually 0).
- dash_list specifies the on-off sequence as points
- (None, None) specifies a solid line
+
+ ``dash_offset``
+ is the offset (usually 0).
+
+ ``dash_list``
+ specifies the on-off sequence as points. ``(None, None)`` specifies a solid line
"""
self._dashes = dash_offset, dash_list
@@ -499,8 +539,8 @@
html hex color string, an rgb unit tuple, or a float between 0
and 1. In the latter case, grayscale is used.
- The GraphicsContext converts colors to rgb internally. If you
- know the color is rgb already, you can set isRGB to True to
+ The :class:`GraphicsContextBase` converts colors to rgb internally. If you
+ know the color is rgb already, you can set ``isRGB=True`` to
avoid the performace hit of the conversion
"""
if isRGB:
@@ -510,7 +550,7 @@
def set_graylevel(self, frac):
"""
- Set the foreground color to be a gray level with frac frac
+ Set the foreground color to be a gray level with ``frac`` frac
"""
self._rgb = (frac, frac, frac)
@@ -556,11 +596,15 @@
class Event:
"""
A matplotlib event. Attach additional attributes as defined in
- FigureCanvas.connect. The following attributes are defined and
+ :meth:`FigureCanvasBase.connect`. The following attributes are defined and
shown with their default values
- name # the event name
- canvas # the FigureCanvas instance generating the event
+ ``name``
+ the event name
+
+ ``canvas``
+ the FigureCanvas instance generating the event
+
"""
def __init__(self, name, canvas,guiEvent=None):
self.name = name
@@ -572,10 +616,10 @@
"""
An event triggered by a draw operation on the canvas
- Attributes are
- name
- canvas
- renderer - the Renderer instance
+ In addition to the :class`Event` attributes, the following event attributes are defined:
+
+ ``renderer``
+ the :class:`RendererBase` instance for the draw event
"""
def __init__(self, name, canvas, renderer):
Event.__init__(self, name, canvas)
@@ -585,11 +629,13 @@
"""
An event triggered by a canvas resize
- Attributes are
- name
- canvas
- width # width of the canvas in pixels
- height # height of the canvas in pixels
+ In addition to the :class`Event` attributes, the following event attributes are defined:
+
+ ``width``
+ width of the canvas in pixels
+
+ ``height``
+ height of the canvas in pixels
"""
def __init__(self, name, canvas):
Event.__init__(self, name, canvas)
@@ -602,24 +648,33 @@
The following additional attributes are defined and shown with
their default values
- x = None # x position - pixels from left of canvas
- y = None # y position - pixels from bottom of canvas
- inaxes = None # the Axes instance if mouse us over axes
- xdata = None # x coord of mouse in data coords
- ydata = None # y coord of mouse in data coords
+ In addition to the :class`Event` attributes, the following event attributes are defined:
+ ``x``
+ x position - pixels from left of canvas
+
+ ``y``
+ y position - pixels from bottom of canvas
+
+ ``inaxes``
+ the :class:`~matplotlib.axes.Axes` instance if mouse is over axes
+
+ ``xdata``
+ x coord of mouse in data coords
+
+ ``ydata``
+ y coord of mouse in data coords
+
"""
x = None # x position - pixels from left of canvas
y = None # y position - pixels from right of canvas
- button = None # button pressed None, 1, 2, 3
inaxes = None # the Axes instance if mouse us over axes
xdata = None # x coord of mouse in data coords
ydata = None # y coord of mouse in data coords
def __init__(self, name, canvas, x, y,guiEvent=None):
"""
- x, y in figure coords, 0,0 = bottom, left
- button pressed None, 1, 2, 3
+ ``x``, ``y`` in figure coords, 0,0 = bottom, left
"""
Event.__init__(self, name, canvas,guiEvent=guiEvent)
self.x = x
@@ -653,20 +708,16 @@
class MouseEvent(LocationEvent):
"""
- A mouse event (button_press_event, button_release_event, scroll_event,
- motion_notify_event).
+ A mouse event ('button_press_event', 'button_release_event', 'scroll_event',
+ 'motion_notify_event').
- The following attributes are defined and shown with their default
- values
+ In addition to the :class`Event` and :class:`LocationEvent`
+ attributes, the following attributes are defined:
- x = None # x position - pixels from left of canvas
- y = None # y position - pixels from bottom of canvas
- button = None # button pressed None, 1, 2, 3, 'up', 'down'
- (up and down are used for scroll events)
- key = None # the key pressed: None, chr(range(255), shift, win, or control
- inaxes = None # the Axes instance if mouse us over axes
- xdata = None # x coord of mouse in data coords
- ydata = None # y coord of mouse in data coords
+ ``button``
+ button pressed None, 1, 2, 3, 'up', 'down' (up and down are used for scroll events)
+ ``key``
+ the key pressed: None, chr(range(255), shift, win, or control
"""
x = None # x position - pixels from left of canvas
@@ -691,12 +742,18 @@
a pick event, fired when the user picks a location on the canvas
sufficiently close to an artist.
- Attrs: all the Event attrs plus
- mouseevent : the MouseEvent that generated the pick
- artist : the artist picked
+ Attrs: all the :class:`Event` attributes plus
- extra class dependent attrs -- eg a Line2D pick may define
- different extra attributes than a PatchCollection pick event
+ ``mouseevent``
+ the :class:`MouseEvent` that generated the pick
+
+ ``artist``
+ the :class:`~matplotlib.artist.Artist` picked
+
+ extra class dependent attrs -- eg a
+ :class:`~matplotlib.lines.Line2D` pick may define different extra
+ attributes than a :class:`~matplotlib.collections.PatchCollection`
+ pick event
"""
def __init__(self, name, canvas, mouseevent, artist, guiEvent=None, **kwargs):
Event.__init__(self, name, canvas, guiEvent)
@@ -710,17 +767,13 @@
A key event (key press, key release).
Attach additional attributes as defined in
- FigureCanvas.connect.
+ :meth:`FigureCanvasBase.connect`.
- The following attributes are defined and shown with their default
- values
+ In addition to the :class`Event` and :class:`LocationEvent`
+ attributes, the following attributes are defined:
- x = None # x position - pixels from left of canvas
- y = None # y position - pixels from bottom of canvas
- key = None # the key pressed: None, chr(range(255), shift, win, or control
- inaxes = None # the Axes instance if mouse us over axes
- xdata = None # x coord of mouse in data coords
- ydata = None # y coord of mouse in data coords
+ ``key``
+ the key pressed: None, chr(range(255), shift, win, or control
This interface may change slightly when better support for
modifier keys is included
@@ -735,9 +788,10 @@
"""
The canvas the figure renders into.
- Public attribute
+ Public attributes
- figure - A Figure instance
+ ``figure``
+ A :class:`matplotlib.figure.Figure` instance
"""
events = (
@@ -775,8 +829,10 @@
def onRemove(self, ev):
"""
Mouse event processor which removes the top artist
- under the cursor. Connect this to the mouse_press_event
- using canvas.mpl_connect('mouse_press_event',canvas.onRemove)
+ under the cursor. Connect this to the 'mouse_press_event'
+ using::
+
+ canvas.mpl_connect('mouse_press_event',canvas.onRemove)
"""
def sort_artists(artists):
# This depends on stable sort and artists returned
@@ -807,8 +863,10 @@
def onHilite(self, ev):
"""
Mouse event processor which highlights the artists
- under the cursor. Connect this to the motion_notify_event
- using canvas.mpl_connect('motion_notify_event',canvas.onHilite)
+ under the cursor. Connect this to the 'motion_notify_event'
+ using::
+
+ canvas.mpl_connect('motion_notify_event',canvas.onHilite)
"""
if not hasattr(self,'_active'): self._active = dict()
@@ -862,22 +920,40 @@
pass
def draw_event(self, renderer):
+ """
+ This method will be call all functions connected to the
+ 'draw_event' with a :class:`DrawEvent`
+ """
+
s = 'draw_event'
event = DrawEvent(s, self, renderer)
self.callbacks.process(s, event)
def resize_event(self):
+ """
+ This method will be call all functions connected to the
+ 'resize_event' with a :class:`ResizeEvent`
+ """
+
s = 'resize_event'
event = ResizeEvent(s, self)
self.callbacks.process(s, event)
def key_press_event(self, key, guiEvent=None):
+ """
+ This method will be call all functions connected to the
+ 'key_press_event' with a :class:`KeyEvent`
+ """
self._key = key
s = 'key_press_event'
event = KeyEvent(s, self, key, self._lastx, self._lasty, guiEvent=guiEvent)
self.callbacks.process(s, event)
def key_release_event(self, key, guiEvent=None):
+ """
+ This method will be call all functions connected to the
+ 'key_release_event' with a :class:`KeyEvent`
+ """
s = 'key_release_event'
event = KeyEvent(s, self, key, self._lastx, self._lasty, guiEvent=guiEvent)
self.callbacks.process(s, event)
@@ -886,7 +962,7 @@
def pick_event(self, mouseevent, artist, **kwargs):
"""
This method will be called by artists who are picked and will
- fire off PickEvent callbacks registered listeners
+ fire off :class:`PickEvent` callbacks registered listeners
"""
s = 'pick_event'
event = PickEvent(s, self, mouseevent, artist, **kwargs)
@@ -896,7 +972,10 @@
"""
Backend derived classes should call this function on any
scroll wheel event. x,y are the canvas coords: 0,0 is lower,
- left. button and key are as defined in MouseEvent
+ left. button and key are as defined in MouseEvent.
+
+ This method will be call all functions connected to the
+ 'scroll_event' with a :class:`MouseEvent` instance.
"""
self._button = button
s = 'scroll_event'
@@ -908,7 +987,11 @@
"""
Backend derived classes should call this function on any mouse
button press. x,y are the canvas coords: 0,0 is lower, left.
- button and key are as defined in MouseEvent
+ button and key are as defined in :class:`MouseEvent`.
+
+ This method will be call all functions connected to the
+ 'button_press_event' with a :class:`MouseEvent` instance.
+
"""
self._button = button
s = 'button_press_event'
@@ -919,7 +1002,11 @@
"""
Backend derived classes should call this function on any mouse
button release. x,y are the canvas coords: 0,0 is lower, left.
- button and key are as defined in MouseEvent
+ button and key are as defined in :class:`MouseEvent`
+
+ This method will be call all functions connected to the
+ 'button_release_event' with a :class:`MouseEvent` instance.
+
"""
s = 'button_release_event'
event = MouseEvent(s, self, x, y, button, self._key, guiEvent=guiEvent)
@@ -931,6 +1018,10 @@
Backend derived classes should call this function on any
motion-notify-event. x,y are the canvas coords: 0,0 is lower, left.
button and key are as defined in MouseEvent
+
+ This method will be call all functions connected to the
+ 'motion_notify_event' with a :class:`MouseEvent` instance.
+
"""
self._lastx, self._lasty = x, y
s = 'motion_notify_event'
@@ -940,13 +1031,13 @@
def draw(self, *args, **kwargs):
"""
- Render the figure
+ Render the :class:`~matplotlib.figure.Figure`
"""
pass
def draw_idle(self, *args, **kwargs):
"""
- draw only if idle; defaults to draw but backends can overrride
+ :meth:`draw` only if idle; defaults to draw but backends can overrride
"""
self.draw(*args, **kwargs)
@@ -958,8 +1049,10 @@
pass
def get_width_height(self):
- """return the figure width and height in points or pixels
- (depending on the backend), truncated to integers"""
+ """
+ return the figure width and height in points or pixels
+ (depending on the backend), truncated to integers
+ """
return int(self.figure.bbox.width), int(self.figure.bbox.height)
filetypes = {
@@ -1038,13 +1131,28 @@
face color background and you'll probably want to override this on
hardcopy.
- filename - can also be a file object on image backends
- orientation - only currently applies to PostScript printing.
- dpi - the dots per inch to save the figure in; if None, use savefig.dpi
- facecolor - the facecolor of the figure
- edgecolor - the edgecolor of the figure
- orientation - 'landscape' | 'portrait' (not supported on all backends)
- format - when set, forcibly set the file format to save to
+ Arguments are:
+
+ ``filename``
+ can also be a file object on image backends
+
+ ``orientation``
+ only currently applies to PostScript printing.
+
+ ``dpi``
+ the dots per inch to save the figure in; if None, use savefig.dpi
+
+ ``facecolor``
+ the facecolor of the figure
+
+ ``edgecolor``
+ the edgecolor of the figure
+
+ ``orientation`` '
+ landscape' | 'portrait' (not supported on all backends)
+
+ ``format``
+ when set, forcibly set the file format to save to
"""
if format is None:
if cbook.is_string_like(filename):
@@ -1123,24 +1231,24 @@
where event is a MplEvent. The following events are recognized
- * 'resize_event'
- * 'draw_event'
- * 'key_press_event'
- * 'key_release_event'
- * 'button_press_event'
- * 'button_release_event'
- * 'scroll_event'
- * 'motion_notify_event'
- * 'pick_event'
+ - 'button_press_event'
+ - 'button_release_event'
+ - 'draw_event'
+ - 'key_press_event'
+ - 'key_release_event'
+ - 'motion_notify_event'
+ - 'pick_event'
+ - 'resize_event'
+ - 'scroll_event'
For the three events above, if the mouse is over the axes,
the variable event.inaxes will be set to the axes it is over,
and additionally, the variables event.xdata and event.ydata
will be defined. This is the mouse location in data coords.
- See backend_bases.MplEvent.
+ See :class`MplEvent`
return value is a connection id that can be used with
- mpl_disconnect
+ :meth:`mpl_disconnect`
"""
return self.callbacks.connect(s, func)
@@ -1162,9 +1270,13 @@
"""
Helper class for matlab mode, wraps everything up into a neat bundle
- Public attibutes
- canvas - A FigureCanvas instance
- num - The figure number
+ Public attibutes:
+
+ ``canvas``
+ A :class:`FigureCanvasBase` instance
+
+ ``num``
+ The figure nuamber
"""
def __init__(self, canvas, num):
self.canvas = canvas
@@ -1248,7 +1360,7 @@
backends must implement a canvas that handles connections for
'button_press_event' and 'button_release_event'. See
- FigureCanvas.connect for more information
+ :meth:`FigureCanvasBase.connect` for more information
They must also define
@@ -1262,18 +1374,18 @@
* draw_rubberband (optional) : draw the zoom to rect
"rubberband" rectangle
- * press : (optional) whenever a mouse button is pressed, you'll be
+ * press : (optional) whenever a mouse button is pressed, you'll be
notified with the event
- * release : (optional) whenever a mouse button is released,
- you'll be notified with the event
+ * release : (optional) whenever a mouse button is released,
+ you'll be notified with the event
- * dynamic_update (optional) dynamically update the window while
- navigating
+ * dynamic_update (optional) dynamically update the window while
+ navigating
- * set_message (optional) - display message
+ * set_message (optional) - display message
- * set_history_buttons (optional) - you can change the history
+ * set_history_buttons (optional) - you can change the history
back / forward buttons to indicate disabled / enabled state.
That's it, we'll do the rest!
@@ -1332,8 +1444,8 @@
def _init_toolbar(self):
"""
This is where you actually build the GUI widgets (called by
- __init__). The icons home.xpm, back.xpm, forward.xpm,
- hand.xpm, zoom_to_rect.xpm and filesave.xpm are standard
+ __init__). The icons ``home.xpm``, ``back.xpm``, ``forward.xpm``,
+ ``hand.xpm``, ``zoom_to_rect.xpm`` and ``filesave.xpm`` are standard
across backends (there are ppm versions in CVS also).
You just need to set the callbacks
@@ -1647,7 +1759,7 @@
def set_cursor(self, cursor):
"""
- Set the current cursor to one of the backend_bases.Cursors
+ Set the current cursor to one of the :class:`Cursors`
enums values
"""
pass
Modified: trunk/matplotlib/lib/matplotlib/text.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/text.py 2008-06-10 15:53:19 UTC (rev 5462)
+++ trunk/matplotlib/lib/matplotlib/text.py 2008-06-10 18:08:50 UTC (rev 5463)
@@ -42,35 +42,38 @@
# class is build so we define an initial set here for the init
# function and they will be overridden after object defn
artist.kwdocd['Text'] = """\
- alpha: float
- animated: [True | False]
- backgroundcolor: any matplotlib color
- bbox: rectangle prop dict plus key 'pad' which is a pad in points
- clip_box: a matplotlib.transform.Bbox instance
- clip_on: [True | False]
- color: any matplotlib color
- family: [ 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
- figure: a matplotlib.figure.Figure instance
- fontproperties: a matplotlib.font_manager.FontProperties instance
- horizontalalignment or ha: [ 'center' | 'right' | 'left' ]
- label: any string
- linespacing: float
- lod: [True | False]
- multialignment: ['left' | 'right' | 'center' ]
- name or fontname: string eg, ['Sans' | 'Courier' | 'Helvetica' ...]
- position: (x,y)
- rotation: [ angle in degrees 'vertical' | 'horizontal'
- size or fontsize: [ size in points | relative size eg 'smaller', 'x-large' ]
- style or fontstyle: [ 'normal' | 'italic' | 'oblique']
- text: string
- transform: a matplotlib.transform transformation instance
- variant: [ 'normal' | 'small-caps' ]
- verticalalignment or va: [ 'center' | 'top' | 'bottom' | 'baseline' ]
- visible: [True | False]
- weight or fontweight: [ 'normal' | 'bold' | 'heavy' | 'light' | 'ultrabold' | 'ultralight']
- x: float
- y: float
- zorder: any number
+ ========================== =========================================================================
+ alpha float
+ ========================== =========================================================================
+ animated [True | False]
+ backgroundcolor any matplotlib color
+ bbox rectangle prop dict plus key 'pad' which is a pad in points
+ clip_box a matplotlib.transform.Bbox instance
+ clip_on [True | False]
+ color any matplotlib color
+ family [ 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
+ figure a matplotlib.figure.Figure instance
+ fontproperties a matplotlib.font_manager.FontProperties instance
+ horizontalalignment or ha [ 'center' | 'right' | 'left' ]
+ label any string
+ linespacing float
+ lod [True | False]
+ multialignment ['left' | 'right' | 'center' ]
+ name or fontname string eg, ['Sans' | 'Courier' | 'Helvetica' ...]
+ position (x,y)
+ rotation [ angle in degrees 'vertical' | 'horizontal'
+ size or fontsize [ size in points | relative size eg 'smaller', 'x-large' ]
+ style or fontstyle [ 'normal' | 'italic' | 'oblique']
+ text string
+ transform a matplotlib.transform transformation instance
+ variant [ 'normal' | 'small-caps' ]
+ verticalalignment or va [ 'center' | 'top' | 'bottom' | 'baseline' ]
+ visible [True | False]
+ weight or fontweight [ 'normal' | 'bold' | 'heavy' | 'light' | 'ultrabold' | 'ultralight']
+ x float
+ y float
+ zorder any number
+ ========================== =========================================================================
"""
class Text(Artist):
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
