added suptitle

jdh2358 · jdh2358 · commit 0728c5532a0c · 2008-06-04T19:11:16.000Z
svn path=/trunk/matplotlib/; revision=5390
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,6 @@
+2006-06-04 Added a figure title command subtitle as a Figure method
+           and pyplot command -- see examples/figure_title.py - JDH
+
 2008-06-02 Added support for log to hist with histtype='step' and fixed
            a bug for log-scale stacked histograms - MM
 
diff --git a/examples/pylab_examples/figtext.py b/examples/pylab_examples/figtext.py
@@ -16,10 +16,7 @@ def f(t):
 plot(t1, f(t1), 'bo', t2, f(t2), 'k')
 title('subplot 1')
 ylabel('Damped oscillation')
-figtitle = 'This is a somewhat long figure title'
-t = gcf().text(0.5, 0.95, figtitle,
-               horizontalalignment='center',
-               fontproperties=FontProperties(size=16))
+suptitle('This is a somewhat long figure title', fontsize=16)
 
 
 subplot(122)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -313,6 +313,35 @@ def get_window_extent(self, *args, **kwargs):
         'get the figure bounding box in display space; kwargs are void'
         return self.bbox
 
+    def suptitle(self, t, **kwargs):
+        """
+        add a centered title to the figure
+
+        kwargs are matplotlib.text.Text properties.  Using figure
+        coordinates, the defaults are
+
+          x = 0.5
+          y = 0.98
+          horizontalalignment = 'center'
+          verticalalignment = 'top'
+
+        The matplotlib.text.Text instance is returned
+
+        Example:
+
+          fig.subtitle('this is the figure title', fontsize=12)
+        """
+        x = kwargs.pop('x', 0.5)
+        y = kwargs.pop('y', 0.98)
+        if ('horizontalalignment' not in kwargs) and ('ha' not in kwargs):
+            kwargs['horizontalalignment'] = 'center'
+
+        if ('verticalalignment' not in kwargs) and ('va' not in kwargs):
+            kwargs['verticalalignment'] = 'top'
+
+        t = self.text(x, y, t, **kwargs)
+        return t
+
     def set_canvas(self, canvas):
         """
         Set the canvas the contains the figure
diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py
@@ -78,6 +78,7 @@
   subplot  - make a subplot (numrows, numcols, axesnum)
   subplots_adjust - change the params controlling the subplot positions of current figure
   subplot_tool - launch the subplot configuration tool
+  suptitle   - add a figure title
   table    - add a table to the plot
   text     - add some text at location x,y to the current axes
   thetagrids - customize the radial theta grids and labels for polar
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -303,6 +303,13 @@ def figtext(*args, **kwargs):
 if Figure.text.__doc__ is not None:
     figtext.__doc__ = dedent(Figure.text.__doc__)
 
+def suptitle(*args, **kwargs):
+    ret =  gcf().suptitle(*args, **kwargs)
+    draw_if_interactive()
+    return ret
+if Figure.suptitle.__doc__ is not None:
+    suptitle.__doc__ = dedent(Figure.suptitle.__doc__)
+
 def figimage(*args, **kwargs):
     # allow callers to override the hold state by passing hold=True|False
     ret =  gcf().figimage(*args, **kwargs)
