Merge pull request matplotlib#1644 from ajdawson/left-right-titles

NF - Left and right side axes titles

Author: dmcdougall

CHANGELOG

@@ -1,3 +1,7 @@
+2013-01-08 Added two extra titles to axes which are flush with the left and
+           right edges of the plot respectively.
+           Andrew Dawson
+
 2013-01-07 Add framealpha keyword argument to legend - PO
 
 2012-12-22 Added classes for interpolation within triangular grids

doc/users/whats_new.rst

@@ -56,6 +56,12 @@ Ian Thomas added classes to perform interpolation within triangular grids
 the triangles in which points lie (
 :class:`~matplotlib.tri.TrapezoidMapTriFinder`).
 
+Left and right side axes titles
+-------------------------------
+Andrew Dawson added the ability to add axes titles flush with the left and
+right sides of the top of the axes using a new keyword argument `loc` to
+:func:`~matplotlib.pyplot.title`.
+
 .. _whats-new-1-2:
 
 new in matplotlib-1.2

examples/pylab_examples/titles_demo.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python
+"""
+matplotlib can display plot titles centered, flush with the left side of
+a set of axes, and flush with the right side of a set of axes.
+
+"""
+import matplotlib.pyplot as plt
+
+plt.plot(range(10))
+
+plt.title('Center Title')
+plt.title('Left Title', loc='left')
+plt.title('Right Title', loc='right')
+
+plt.show()

lib/matplotlib/axes.py

@@ -932,10 +932,23 @@ def cla(self):
             verticalalignment='baseline',
             horizontalalignment='center',
             )
-        self.title.set_transform(self.transAxes + self.titleOffsetTrans)
-        self.title.set_clip_box(None)
+        self._left_title = mtext.Text(
+            x=0.0, y=1.0, text='',
+            fontproperties=props,
+            verticalalignment='baseline',
+            horizontalalignment='left',
+            )
+        self._right_title = mtext.Text(
+            x=1.0, y=1.0, text='',
+            fontproperties=props,
+            verticalalignment='baseline',
+            horizontalalignment='right',
+            )
 
-        self._set_artist_props(self.title)
+        for _title in (self.title, self._left_title, self._right_title):
+            _title.set_transform(self.transAxes + self.titleOffsetTrans)
+            _title.set_clip_box(None)
+            self._set_artist_props(_title)
 
         # the patch draws the background of the axes.  we want this to
         # be below the other artists; the axesPatch name is
@@ -1990,6 +2003,8 @@ def draw(self, renderer=None, inframe=False):
             artists.extend([self.xaxis, self.yaxis])
         if not inframe:
             artists.append(self.title)
+            artists.append(self._left_title)
+            artists.append(self._right_title)
         artists.extend(self.tables)
         if self.legend_ is not None:
             artists.append(self.legend_)
@@ -3100,6 +3115,8 @@ def get_children(self):
             children.append(self.legend_)
         children.extend(self.collections)
         children.append(self.title)
+        children.append(self._left_title)
+        children.append(self._right_title)
         children.append(self.patch)
         children.extend(self.spines.itervalues())
         return children
@@ -3137,43 +3154,82 @@ def pick(self, *args):
 
     ### Labelling
 
-    def get_title(self):
-        """
-        Get the title text string.
-        """
-        return self.title.get_text()
-
-    @docstring.dedent_interpd
-    def set_title(self, label, fontdict=None, **kwargs):
-        """
-        Call signature::
+    def get_title(self, loc="center"):
+        """Get an axes title.
 
-          set_title(label, fontdict=None, **kwargs):
+        Get one of the three available axes titles. The available titles
+        are positioned above the axes in the center, flush with the left
+        edge, and flush with the right edge.
 
-        Set the title for the axes.
+        Parameters
+        ----------
+        loc : {'center', 'left', 'right'}, str, optional
+            Which title to get, defaults to 'center'
 
-        kwargs are Text properties:
-        %(Text)s
+        Returns
+        -------
+        text : :class:`~matplotlib.text.Text`
+            The matplotlib text instance representing the title
 
-        ACCEPTS: str
+        """
+        try:
+            title = {'left': self._left_title,
+                     'center': self.title,
+                     'right': self._right_title}[loc.lower()]
+        except KeyError:
+            raise ValueError("'%s' is not a valid location" % loc)
+        return title
 
-        .. seealso::
+    @docstring.dedent_interpd
+    def set_title(self, label, loc="center", fontdict=None, **kwargs):
+        """Set a title for the axes.
+
+        Set one of the three available axes titles. The available titles
+        are positioned above the axes in the center, flush with the left
+        edge, and flush with the right edge.
+
+        Parameters
+        ----------
+        label : str
+            Text to use for the title
+        loc : {'center', 'left', 'right'}, str, optional
+            Which title to set, defaults to 'center'
+        fontdict : dict
+            A dictionary controlling the appearance of the title text,
+            the default `fontdict` is:
+            {'fontsize': rcParams['axes.titlesize'],
+             'verticalalignment': 'baseline',
+             'horizontalalignment': loc}
+
+        Returns
+        -------
+        text : :class:`~matplotlib.text.Text`
+            The matplotlib text instance representing the title
+
+        Other parameters
+        ----------------
+        Other keyword arguments are text properties, see
+        :class:`~matplotlib.text.Text` for a list of valid text
+        properties.
 
-            :meth:`text`
-                for information on how override and the optional args work
         """
+        try:
+            title = {'left': self._left_title,
+                     'center': self.title,
+                     'right': self._right_title}[loc.lower()]
+        except KeyError:
+            raise ValueError("'%s' is not a valid location" % loc)
         default = {
             'fontsize': rcParams['axes.titlesize'],
             'verticalalignment': 'baseline',
-            'horizontalalignment': 'center'
+            'horizontalalignment': loc.lower()
             }
-
-        self.title.set_text(label)
-        self.title.update(default)
+        title.set_text(label)
+        title.update(default)
         if fontdict is not None:
-            self.title.update(fontdict)
-        self.title.update(kwargs)
-        return self.title
+            title.update(fontdict)
+        title.update(kwargs)
+        return title
 
     def get_xlabel(self):
         """
@@ -8839,6 +8895,10 @@ def get_tightbbox(self, renderer, call_axes_locator=True):
 
         if self.title.get_visible():
             bb.append(self.title.get_window_extent(renderer))
+        if self._left_title.get_visible():
+            bb.append(self._left_title.get_window_extent(renderer))
+        if self._right_title.get_visible():
+            bb.append(self._right_title.get_window_extent(renderer))
 
         bb_xaxis = self.xaxis.get_tightbbox(renderer)
         if bb_xaxis:

lib/matplotlib/pyplot.py

@@ -1171,28 +1171,51 @@ def box(on=None):
     ax.set_frame_on(on)
     draw_if_interactive()
 
+
 def title(s, *args, **kwargs):
     """
-    Set the title of the current axis.
+    title(label, loc='center', fontdict=None, **kwargs)
 
-    Default font override is::
+    Set a title of the current axes.
 
-      override = {'fontsize': 'medium',
-                  'verticalalignment': 'baseline',
-                  'horizontalalignment': 'center'}
+    Set one of the three available axes titles. The available titles are
+    positioned above the axes in the center, flush with the left edge,
+    and flush with the right edge.
 
-    .. seealso::
+    Parameters
+    ----------
+    label : str
+        Text to use for the title
+    loc : {'center', 'left', 'right'}, str, optional
+        Which title to set, defaults to 'center'
+    fontdict : dict
+        A dictionary controlling the appearance of the title text,
+        the default `fontdict` is:
+        {'fontsize': rcParams['axes.titlesize'],
+         'verticalalignment': 'baseline',
+         'horizontalalignment': loc}
+
+    Returns
+    -------
+    text : :class:`~matplotlib.text.Text`
+        The matplotlib text instance representing the title
+
+    Other parameters
+    ----------------
+    Other keyword arguments are text properties, see
+    :class:`~matplotlib.text.Text` for a list of valid text
+    properties.
+
+    See also
+    --------
+    :func:`~matplotlib.pyplot.text` : Add text to the current axes
 
-       :func:`~matplotlib.pyplot.text`
-           for information on how override and the optional args work.
     """
     l =  gca().set_title(s, *args, **kwargs)
     draw_if_interactive()
     return l
 
 
-
-
 ## Axis ##
 
 def axis(*v, **kwargs):