Add clear warning about lifetime of UserFontFace objects

Also include examples in doxygen documentation

3 files changed, 66 insertions, 3 deletions

diff --git a/ChangeLog b/ChangeLog
index 3fab6cd..c4e70ef 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2008-12-12  Jonathon Jongsma  <jonathon@quotidian.org>
+
+	* cairomm/fontface.h: add more documentation about UserFontFace, including a
+	warning about needing to keep the UserFontFace wrapper around as long as we're
+	rendering text with that face.
+	Include the user-font.cc and toy-text.cc examples in the doxygen reference
+	documentation
+	* docs/reference/Doxyfile.in: set EXAMPLE_PATH
+
 2008-12-11  Jonathon Jongsma  <jonathon@quotidian.org>
 
 	* examples/text/user-font.cc: enhanced the UserFontFace example quite a bit so
diff --git a/cairomm/fontface.h b/cairomm/fontface.h
index 6c7e1fd..cbd0813 100644
--- a/cairomm/fontface.h
+++ b/cairomm/fontface.h
@@ -96,6 +96,10 @@ protected:
 };
 
 
+ /** @example toy-text.cc
+  * A relatively simple example of using Cairo::ToyFontFace
+  */
+
 /**
  * A simple font face used for the cairo 'toy' font API.
  * @since 1.8
@@ -141,6 +145,10 @@ protected:
 };
 
 
+ /** @example user-font.cc
+  * A relatively simple example of using Cairo::UserFontFace
+  */
+
 /** Font support with font data provided by the user.
  *
  * The user-font feature allows the cairo user to provide drawings for glyphs in
@@ -150,7 +158,52 @@ protected:
  *
  * To use user fonts, you must derive from this class and implement the virtual
  * functions below.  The only virtual function that absolutely must be
- * implemented is render_glyph().
+ * implemented is render_glyph().  You should make the constructor protected and
+ * provide a factory function that returns a new object in a RefPtr since it is
+ * a refcounted object
+ *
+ * @code
+ * class MyUserFont : public UserFontFace {
+ *
+ * public:
+ *   static Cairo::RefPtr<MyUserFont> create() {
+ *     return Cairo::RefPtr<MyUserFont>(new MyUserFont);
+ *
+ * protected:
+ *   // implement render_glyph() and any other virtual functions you want to override
+ *   ErrorStatus render_glyph(const RefPtr<ScaledFont>& scaled_font,
+ *                            unsigned long glyph,
+ *                            const RefPtr<Context>& cr,
+ *                            TextExtents& metrics) {
+ *     // render the glyph into cr here
+ *   }
+ *
+ *   MyUserFont() : UserFontFace() {
+ *     // constructor implementation
+ *   }
+ * };
+ * @endcode
+ *
+ * @warning
+ * Because of a design flaw in cairomm, it is currently necessary to keep the
+ * the UserFontFace object around until as long as you are rendering text with
+ * the user font.  The following code illustrates the issue:
+ *
+ * @code
+ * {
+ *   Cairo::RefPtr<MyUserFont> face = MyUserFont::create();
+ *   cr->set_font_face(face);
+ * }  // scope for demonstration purposes
+ *
+ * // the following call will cause a crash because your user font is no longer
+ * // in scope but it needs to call the virtual functions in face
+ * cr->show_text("hello, world");
+ * @endcode
+ *
+ * The preceding is obviously a very contrived example, but the important thing
+ * to know is that you *must* cache all userfont objects yourself as long as you
+ * intend to render text with that font.  A future release of cairomm will fix
+ * this requirement, but that will require ABI-incompatible changes.
  *
  * @since 1.8
  */
@@ -343,6 +396,7 @@ private:
                      cairo_text_cluster_flags_t *cluster_flags);
 };
 
+
 // font system support
 #ifdef CAIRO_HAS_FT_FONT
 
diff --git a/docs/reference/Doxyfile.in b/docs/reference/Doxyfile.in
index 35cd395..6e44b49 100644
--- a/docs/reference/Doxyfile.in
+++ b/docs/reference/Doxyfile.in
@@ -83,9 +83,9 @@ EXCLUDE                = @top_srcdir@/cairomm/private.h @top_srcdir@/cairomm/con
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = 
 EXCLUDE_SYMBOLS        = 
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = @top_srcdir@/examples
 EXAMPLE_PATTERNS       = 
-EXAMPLE_RECURSIVE      = NO
+EXAMPLE_RECURSIVE      = YES
 IMAGE_PATH             = 
 INPUT_FILTER           = 
 FILTER_PATTERNS        =