[gtkmm] Gtk::TextBuffer: Wrap the serialize()/deserialize() methods

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 26d51ed042b2b515999be86a4e933e798f22f995
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Wed Jan 21 15:39:35 2015 +0100

    Gtk::TextBuffer: Wrap the serialize()/deserialize() methods
    
    * gtk/src/textbuffer.[ccg|hg]: Add SlotSerialize, SlotDeserialize,
    register_serialize_format(), register_deserialize_format(), serialize(),
    deserialize(). Bug #694250.

 gtk/src/textbuffer.ccg |   55 +++++++++++++++++--------------
 gtk/src/textbuffer.hg  |   83 ++++++++++++++++++++++++++++++-----------------
 2 files changed, 83 insertions(+), 55 deletions(-)
---
diff --git a/gtk/src/textbuffer.ccg b/gtk/src/textbuffer.ccg
index 01999a4..0a2e93e 100644
--- a/gtk/src/textbuffer.ccg
+++ b/gtk/src/textbuffer.ccg
@@ -22,25 +22,28 @@
 #include <gtkmm/textmark.h>
 #include <gtkmm/textiter.h>
 
+namespace // anonymous
+{
+extern "C"
+{
 
-/*
-static guint8* SignalProxy_Serialize(GtkTextBuffer* , GtkTextBuffer* content_buffer,
-                                                   const GtkTextIter* start, const GtkTextIter* end,
-                                                   gsize* length,
-                                                   gpointer user_data)
+static guint8* SignalProxy_Serialize(GtkTextBuffer* /* register_buffer */,
+                                     GtkTextBuffer* content_buffer,
+                                     const GtkTextIter* start, const GtkTextIter* end,
+                                     gsize* length,
+                                     gpointer user_data)
 {
   Gtk::TextBuffer::SlotSerialize* the_slot = static_cast<Gtk::TextBuffer::SlotSerialize*>(user_data);
 
   try
   {
-    return (*the_slot)(Glib::wrap(content_buffer), Glib::wrap(start), Glib::wrap(end), *length);
+    return (*the_slot)(Glib::wrap(content_buffer, true), Glib::wrap(start), Glib::wrap(end), *length);
   }
-  catch(...)
+  catch (...)
   {
     Glib::exception_handlers_invoke();
   }
-
-  return 0; // arbitrary value
+  return 0;
 }
 
 static void SignalProxy_Serialize_gtk_callback_destroy(void* user_data)
@@ -48,33 +51,37 @@ static void SignalProxy_Serialize_gtk_callback_destroy(void* user_data)
   delete static_cast<Gtk::TextBuffer::SlotSerialize*>(user_data);
 }
 
-static gboolean SignalProxy_Deserialize(GtkTextBuffer* , GtkTextBuffer* content_buffer,
-                                                   GtkTextIter* iter, const guint8* data,
-                                                   gsize length, gboolean create_tags,
-                                                   gpointer user_data,
-                                                   GError** )
+static gboolean SignalProxy_Deserialize(GtkTextBuffer* /* register_buffer */,
+                                        GtkTextBuffer* content_buffer,
+                                        GtkTextIter* iter, const guint8* data,
+                                        gsize length, gboolean create_tags,
+                                        gpointer user_data,
+                                        GError** error)
 {
   Gtk::TextBuffer::SlotDeserialize* the_slot = static_cast<Gtk::TextBuffer::SlotDeserialize*>(user_data);
 
   try
   {
-    (*the_slot)(Glib::wrap(content_buffer, true), Glib::wrap(iter), data, length, create_tags);
-
+    return (*the_slot)(Glib::wrap(content_buffer, true), Glib::wrap(iter), data, length, create_tags);
   }
-  catch(...)
+  catch (Glib::Error& err)
+  {
+    err.propagate(error);
+  }
+  catch (...)
   {
-    //TODO: Fill the error parameter.
     Glib::exception_handlers_invoke();
   }
-
-  return 0; // arbitrary value
+  return false;
 }
 
 static void SignalProxy_Deserialize_gtk_callback_destroy(void* user_data)
 {
   delete static_cast<Gtk::TextBuffer::SlotDeserialize*>(user_data);
 }
-*/
+
+} // extern "C"
+} // anonymous namespace
 
 namespace Gtk
 {
@@ -534,7 +541,6 @@ std::vector<Glib::ustring> TextBuffer::get_deserialize_formats() const
   return Glib::ArrayHandler<Glib::ustring, Gdk::AtomUstringTraits>::array_to_vector(atoms, n_atoms, 
Glib::OWNERSHIP_SHALLOW);
 }
 
-/*
 Glib::ustring TextBuffer::register_serialize_format(const Glib::ustring& mime_type, const SlotSerialize& 
slot)
 {
   SlotSerialize* slot_copy = new SlotSerialize(slot);
@@ -544,7 +550,7 @@ Glib::ustring TextBuffer::register_serialize_format(const Glib::ustring& mime_ty
   //Convert the atom to a string:
   Glib::ustring atom_as_string;
   char* atom_name = gdk_atom_name(atom);
-  if(atom_name)
+  if (atom_name)
   {
     atom_as_string = atom_name;
     g_free(atom_name);
@@ -562,7 +568,7 @@ Glib::ustring TextBuffer::register_deserialize_format(const Glib::ustring& mime_
   //Convert the atom to a string:
   Glib::ustring atom_as_string;
   char* atom_name = gdk_atom_name(atom);
-  if(atom_name)
+  if (atom_name)
   {
     atom_as_string = atom_name;
     g_free(atom_name);
@@ -570,6 +576,5 @@ Glib::ustring TextBuffer::register_deserialize_format(const Glib::ustring& mime_
 
   return atom_as_string;
 }
-*/
 
 } // namespace Gtk
diff --git a/gtk/src/textbuffer.hg b/gtk/src/textbuffer.hg
index 3060e6a..f72b06b 100644
--- a/gtk/src/textbuffer.hg
+++ b/gtk/src/textbuffer.hg
@@ -485,26 +485,60 @@ public:
   _WRAP_METHOD(Glib::RefPtr<TargetList> get_copy_target_list() const, gtk_text_buffer_get_copy_target_list, 
refreturn)
   _WRAP_METHOD(Glib::RefPtr<TargetList> get_paste_target_list() const, 
gtk_text_buffer_get_paste_target_list, refreturn)
 
-//TODO: I have commented these out for now because I don't understand what the register_buffer and 
content_buffer are. murrayc.
- //TODO: Documentation.
- // typedef sigc::slot<guint8*, const Glib::RefPtr<TextBuffer>& /* content_buffer */, const iterator& /* 
start */, const iterator& /* end */, gsize& /* length */> SlotSerialize;
-
-
-//TODO: Use ArrayHandle, or just use guint8* to be more efficient?
-// TODO: Or rather - vector utils.
-  // typedef sigc::slot<bool, const Glib::RefPtr<TextBuffer>& /* content_buffer */, iterator& /* iter */, 
const guint8*  /* data */, gsize /* length */, bool /* create_tags */> SlotDeserialize;
+  /** For instance,<br>
+   * guint8* on_serialize(const Glib::RefPtr<TextBuffer>& content_buffer, const iterator& start, const 
iterator& end, gsize& length);
+   *
+   * @param content_buffer The TextBuffer to serialize. It may be different from
+   *        the TextBuffer where the serialize format is registered.
+   * @param start Start of the block of text to serialize.
+   * @param end End of the block of text to serialize.
+   * @param[out] length The length of the serialized data.
+   * @return A newly-allocated array of guint8 which contains the serialized data, or <tt>0</tt> if an error 
occurred.
+   */
+ typedef sigc::slot<guint8*, const Glib::RefPtr<TextBuffer>&, const iterator&, const iterator&, gsize&> 
SlotSerialize;
+
+  /** For instance,<br>
+   * bool on_deserialize(const Glib::RefPtr<TextBuffer>& content_buffer, iterator& iter, const guint8* data, 
gsize length, bool create_tags);
+   *
+   * @param content_buffer The TextBuffer to deserialize into. It may be different
+   *        from the TextBuffer where the deserialize format is registered.
+   * @param iter Insertion point for the deserialized text.
+   * @param data Data to deserialize.
+   * @param length Length of data.
+   * @param create_tags <tt>true</tt> if deserializing may create tags.
+   * @return <tt>true</tt> on success, <tt>false</tt> otherwise.
+   * @throw Glib::Error If the deserialize slot throws a Glib::Error or an object
+   *        derived from Glib::Error, the exception will be propagated out from
+   *        the calling deserialize() method.
+   */
+  typedef sigc::slot<bool, const Glib::RefPtr<TextBuffer>&, iterator&, const guint8*, gsize, bool> 
SlotDeserialize;
 
-/*
+  /** This function registers a rich text serialization @a slot along with
+   * its @a mime_type with this TextBuffer.
+   *
+   * @newin{3,16}
+   *
+   * @param mime_type The format’s mime-type.
+   * @param slot The serialize slot to register.
+   * @return The newly registered format’s mime-type.
+   */
   Glib::ustring register_serialize_format(const Glib::ustring& mime_type, const SlotSerialize& slot);
   _IGNORE(gtk_text_buffer_register_serialize_format)
-*/
 
   _WRAP_METHOD(Glib::ustring register_serialize_tagset(const Glib::ustring& tagset_name), 
gtk_text_buffer_register_serialize_tagset)
 
-/*
+  /** This function registers a rich text deserialization @a slot along with
+   * its @a mime_type with this TextBuffer.
+   *
+   * @newin{3,16}
+   *
+   * @param mime_type The format’s mime-type.
+   * @param slot The deserialize slot to register.
+   * @return The newly registered format’s mime-type.
+   */
   Glib::ustring register_deserialize_format(const Glib::ustring& mime_type, const SlotDeserialize& slot);
   _IGNORE(gtk_text_buffer_register_deserialize_format)
-*/
+
   _WRAP_METHOD(Glib::ustring register_deserialize_tagset(const Glib::ustring& tagset_name), 
gtk_text_buffer_register_deserialize_tagset)
 
   _WRAP_METHOD(void unregister_serialize_format(const Glib::ustring& format), 
gtk_text_buffer_unregister_serialize_format)
@@ -519,27 +553,16 @@ public:
   std::vector<Glib::ustring> get_deserialize_formats() const;
   _IGNORE(gtk_text_buffer_get_deserialize_formats)
 
-/*
-//TODO: I have commented these out for now because I don't understand what the register_buffer and 
content_buffer are. murrayc.
-
-//TODO: Use something other than gsize?
-#m4 _CONVERSION(`const iterator&', `GtkTextIter*',`($3).gobj()')
   _WRAP_METHOD(guint8* serialize(const Glib::RefPtr<TextBuffer>& content_buffer,
-                                                       const Glib::ustring& format,
-                                                       const iterator& iterstart,
-                                                       const iterator& iterend,
-                                                       gsize& length), gtk_text_buffer_serialize)
+                                 const Glib::ustring& format,
+                                 const iterator& start,
+                                 const iterator& end,
+                                 gsize& length), gtk_text_buffer_serialize)
 
-//TODO: Is the bool superfluous?
-//TODO: Use an ArrayHandle? Or rather - vector utils.
   _WRAP_METHOD(bool deserialize(const Glib::RefPtr<TextBuffer>& content_buffer,
-                                                       const Glib::ustring& format,
-                                                       const iterator& iter, const guint8* data,
-                                                       gsize length), gtk_text_buffer_deserialize, errthrow)
-*/
-
-
-
+                                const Glib::ustring& format,
+                                iterator& iter, const guint8* data,
+                                gsize length), gtk_text_buffer_deserialize, errthrow)
 
 #m4begin
 dnl // HACK: Override the default conversion to deal correctly