freeze-break: gtkmm RecentAction constructors

[Murray Cumming <murrayc murrayc com>]

release-team, may I have an API-freeze break (or hard-code-freeze break,
depending on when this break is approved) for the attached patch, which
has this ChangeLog entry?

2007-09-10  Murray Cumming  <murrayc murrayc com>

	* gtk/src/recentaction.ccg:
	* gtk/src/recentaction.hg: Make the constructors use the same 
	parameter order as the other action classes. Remove the comment 
	about the default constructor, now that the GTK+ C documentation 
	is clearer in bug #450032.
	* gtk/src/action.hg:
	* gtk/src/radioaction.hg:
	* gtk/src/toggleaction.hg: Deprecate the default constructors, 
	because they cannot work. We could maybe remove them, but maybe 
	they are used in the build of some applications, but never used 
	at runtime.
	Added default values for the StockID parameters, now that we 
	know that we know that this is OK - see bug #450032.


Gtk::RecentAction is a new class in gtkmm 2.12 and is unlikely to be
used yet by any applications. Not committing this would leave us with a
slightly confusing API that we couldn't change later.

The other changes (deprecation and adding default values) are more API
additions than API breaks.

-- 
murrayc murrayc com
www.murrayc.com
www.openismus.com

Index: gtk/src/recentaction.hg
===================================================================
--- gtk/src/recentaction.hg	(revision 900)
+++ gtk/src/recentaction.hg	(working copy)
@@ -47,15 +47,27 @@
   _CLASS_GOBJECT(RecentAction, GtkRecentAction, GTK_RECENT_ACTION, Gtk::Action, GtkAction)
 
 protected:
-  //TODO: See bug #450032: _CTOR_DEFAULT()
-  _WRAP_CTOR(RecentAction(const Glib::ustring& name, const Glib::ustring& label, const Glib::ustring& tooltip = Glib::ustring(), const Gtk::StockID& stock_id = Gtk::StockID()), gtk_recent_action_new)
-  _WRAP_CTOR(RecentAction(const Glib::ustring& name, const Glib::ustring& label, const Glib::ustring& tooltip, const Gtk::StockID& stock_id, const Glib::RefPtr<RecentManager>& manager), gtk_recent_action_new_for_manager )
+  _CTOR_DEFAULT
 
+//Make sure that we use NULL instead of empty strings for the constructors:
+#m4 _CONVERSION(`const Glib::ustring&',`const char*',`$3.empty() ? 0 : $3.c_str()')
+
+  //Note that the order of the parameters is not the same as gtk_recent_action_new(), because 
+  //a) we want to be consistent with Action, ToggleAction, etc.
+  //b) this allows us to use the StockID parameter to distinguish the create() overloads.
+  _WRAP_CTOR(RecentAction(const Glib::ustring& name, const StockID& stock_id = StockID(), const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring()), gtk_recent_action_new)
+  _WRAP_CTOR(RecentAction(const Glib::ustring& name, const StockID& stock_id, const Glib::ustring& label, const Glib::ustring& tooltip, const Glib::RefPtr<RecentManager>& manager), gtk_recent_action_new_for_manager )
+
 public:
-  //TODO: See bug #450032: _WRAP_CREATE()
-  _WRAP_CREATE(const Glib::ustring& name, const Glib::ustring& label, const Glib::ustring& tooltip = Glib::ustring(), const Gtk::StockID& stock_id = Gtk::StockID())
-  _WRAP_CREATE(const Glib::ustring& name, const Glib::ustring& label, const Glib::ustring& tooltip, const Gtk::StockID& stock_id, const Glib::RefPtr<RecentManager>& manager)
+  //Note that gtk_recent_action_new() does not allow name to be NULL, which suggests that we should not have a default constructor,
+  //but it's OK to set the name later:
+  _WRAP_CREATE()
 
+  static Glib::RefPtr<RecentAction> create(const Glib::ustring& name, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
+  _WRAP_CREATE(const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring())
+  _WRAP_CREATE(const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label, const Glib::ustring& tooltip, const Glib::RefPtr<RecentManager>& manager)
+
+
   _WRAP_METHOD(bool get_show_numbers(), gtk_recent_action_get_show_numbers)
   _WRAP_METHOD(void set_show_numbers(bool show_numbers = true), gtk_recent_action_set_show_numbers)
 
Index: gtk/src/recentaction.ccg
===================================================================
--- gtk/src/recentaction.ccg	(revision 900)
+++ gtk/src/recentaction.ccg	(working copy)
@@ -24,5 +24,11 @@
 namespace Gtk
 {
 
+Glib::RefPtr<RecentAction> RecentAction::create(const Glib::ustring& name, const Glib::ustring& label, const Glib::ustring& tooltip)
+{
+  return Glib::RefPtr<RecentAction>( new RecentAction(name, StockID(), label, tooltip) );
+}
+
+
 } // namespace Gtk
 
Index: gtk/src/action.hg
===================================================================
--- gtk/src/action.hg	(revision 900)
+++ gtk/src/action.hg	(working copy)
@@ -69,13 +69,16 @@
  
 protected:
  _CTOR_DEFAULT
-  explicit Action(const Glib::ustring& name, const StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
+  explicit Action(const Glib::ustring& name, const StockID& stock_id = StockID(), const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
 
 public:
+  //Note that gtk_action_new() does not allow name to be NULL, which suggests that we should not have a default constructor,
+  //but it's OK to set the name later:
   _WRAP_CREATE()
-  static Glib::RefPtr<Action> create(const Glib::ustring& name, const Glib::ustring& label =  Glib::ustring(), const Glib::ustring& tooltip =  Glib::ustring());
-  static Glib::RefPtr<Action> create(const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label =  Glib::ustring(), const Glib::ustring& tooltip =  Glib::ustring());
 
+  static Glib::RefPtr<Action> create(const Glib::ustring& name, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
+  static Glib::RefPtr<Action> create(const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
+
   _WRAP_METHOD(Glib::ustring get_name() const, gtk_action_get_name)
 
   _WRAP_METHOD(bool is_sensitive() const, gtk_action_is_sensitive)
Index: gtk/src/radioaction.hg
===================================================================
--- gtk/src/radioaction.hg	(revision 900)
+++ gtk/src/radioaction.hg	(working copy)
@@ -40,11 +40,15 @@
   typedef RadioButtonGroup Group;
   
 protected:
+  //TODO: Remove the default constructor, because name may not be NULL.
   _CTOR_DEFAULT
-  explicit RadioAction(Group& group, const Glib::ustring& name, const StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
+  explicit RadioAction(Group& group, const Glib::ustring& name, const StockID& stock_id = StockID(), const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
 
 public:
+  //Note that gtk_recent_action_new() does not allow name to be NULL, which suggests that we should not have a default constructor,
+  //but it's OK to set the name later:
   _WRAP_CREATE()
+
   static Glib::RefPtr<RadioAction> create(Group& group, const Glib::ustring& name, const Glib::ustring& label =  Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
   static Glib::RefPtr<RadioAction> create(Group& group, const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip =  Glib::ustring());
 
Index: gtk/src/toggleaction.hg
===================================================================
--- gtk/src/toggleaction.hg	(revision 900)
+++ gtk/src/toggleaction.hg	(working copy)
@@ -38,12 +38,15 @@
 
 protected:
   _CTOR_DEFAULT
-   explicit ToggleAction(const Glib::ustring& name, const StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring(), bool is_active = false);
+   explicit ToggleAction(const Glib::ustring& name, const StockID& stock_id = StockID(), const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring(), bool is_active = false);
 
 public:
+  //Note that gtk_toggle_action_new() does not allow name to be NULL, which suggests that we should not have a default constructor,
+  //but it's OK to set the name later:
   _WRAP_CREATE()
+
    static Glib::RefPtr<ToggleAction> create(const Glib::ustring& name, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip =  Glib::ustring(), bool is_active = false);
-   static Glib::RefPtr<ToggleAction> create(const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label =  Glib::ustring(), const Glib::ustring& tooltip =  Glib::ustring(), bool is_active = false);
+   static Glib::RefPtr<ToggleAction> create(const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring(), bool is_active = false);
 
   _WRAP_METHOD(void toggled(), gtk_toggle_action_toggled)
   _WRAP_METHOD(void set_active(bool is_active = true), gtk_toggle_action_set_active)
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 902)
+++ ChangeLog	(working copy)
@@ -1,3 +1,19 @@
+2007-09-10  Murray Cumming  <murrayc murrayc com>
+
+	* gtk/src/recentaction.ccg:
+	* gtk/src/recentaction.hg: Make the constructors use the same 
+	parameter order as the other action classes. Remove the comment 
+	about the default constructor, now that the GTK+ C documentation 
+	is clearer in bug #450032.
+	* gtk/src/action.hg:
+	* gtk/src/radioaction.hg:
+	* gtk/src/toggleaction.hg: Deprecate the default constructors, 
+	because they cannot work. We could maybe remove them, but maybe 
+	they are used in the build of some applications, but never used 
+	at runtime.
+	Added default values for the StockID parameters, now that we 
+	know that we know that this is OK - see bug #450032.
+
 2.11.8:
 
 2007-08-31  Murray Cumming  <murrayc murrayc com>