Fixing warnings from 'use-fallback'

6 files changed, 76 insertions, 11 deletions

diff --git a/debian/changelog b/debian/changelog
index bb49428..3115eab 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -8,10 +8,11 @@ libdbusmenu (0.3.93-0ubuntu2~ppa1) UNRELEASED; urgency=low
       build functions
     * Fix critical message from being printed 
     * Fixing shutdown messages on destruction
+    * Fixing warnings from 'use-fallback'
     * Adding a parser
     * Adding a serializable menu item
 
- -- Ted Gould <ted@ubuntu.com>  Thu, 27 Jan 2011 14:08:02 -0600
+ -- Ted Gould <ted@ubuntu.com>  Thu, 27 Jan 2011 14:13:01 -0600
 
 libdbusmenu (0.3.93-0ubuntu1) natty; urgency=low
 
diff --git a/libdbusmenu-glib/client.h b/libdbusmenu-glib/client.h
index f371792..6d78edf 100644
--- a/libdbusmenu-glib/client.h
+++ b/libdbusmenu-glib/client.h
@@ -110,7 +110,28 @@ struct _DbusmenuClient {
 	DbusmenuClientPrivate * priv;
 };
 
+/**
+	DbusmenuClientTypeHandler:
+	@newitem: The #DbusmenuMenuitem that was created
+	@parent: The parent of @newitem or #NULL if none
+	@client: A pointer to the #DbusmenuClient
+	@user_data: The data you gave us
+
+	The type handler is called when a dbusmenu item is created
+	with a matching type as setup in #dbusmenu_client_add_type_handler
+*/
 typedef gboolean (*DbusmenuClientTypeHandler) (DbusmenuMenuitem * newitem, DbusmenuMenuitem * parent, DbusmenuClient * client, gpointer user_data);
+
+/**
+	DbusmenuClientTypeDestroyHandler:
+	@client: A pointer to the #DbusmenuClient
+	@type: The type that this handler was registered with
+	@user_data: The data you gave us
+
+	This handler is called when the type becomes unregistered by the
+	client.  This is usally caused by the #DbusmenuClient being destroyed
+	and should free memory or unref objects in @user_data.
+*/
 typedef void (*DbusmenuClientTypeDestroyHandler) (DbusmenuClient * client, const gchar * type, gpointer user_data);
 
 GType                dbusmenu_client_get_type          (void);
diff --git a/libdbusmenu-gtk/client.c b/libdbusmenu-gtk/client.c
index d957f25..7ab2fe9 100644
--- a/libdbusmenu-gtk/client.c
+++ b/libdbusmenu-gtk/client.c
@@ -42,6 +42,7 @@ struct _DbusmenuGtkClientPrivate {
 };
 
 #define DBUSMENU_GTKCLIENT_GET_PRIVATE(o) (DBUSMENU_GTKCLIENT(o)->priv)
+#define USE_FALLBACK_PROP  "use-fallback"
 
 /* Prototypes */
 static void dbusmenu_gtkclient_class_init (DbusmenuGtkClientClass *klass);
@@ -737,6 +738,29 @@ new_item_seperator (DbusmenuMenuitem * newitem, DbusmenuMenuitem * parent, Dbusm
 	return TRUE;
 }
 
+/* A little helper so we don't generate a bunch of warnings
+   about being able to set use-fallback */
+static void
+set_use_fallback (GtkWidget * widget)
+{
+	static gboolean checked = FALSE;
+	static gboolean available = FALSE;
+
+	if (!checked) {
+		available = (g_object_class_find_property(G_OBJECT_CLASS(GTK_IMAGE_GET_CLASS(widget)), USE_FALLBACK_PROP) != NULL);
+		if (!available) {
+			g_warning("The '" USE_FALLBACK_PROP "' is not available on GtkImage so icons may not show correctly.");
+		}
+		checked = TRUE;
+	}
+
+	if (available) {
+		g_object_set(G_OBJECT(widget), USE_FALLBACK_PROP, TRUE, NULL);
+	}
+
+	return;
+}
+
 /* This handler looks at property changes for items that are
    image menu items. */
 static void
@@ -789,7 +813,7 @@ image_property_handle (DbusmenuMenuitem * item, const gchar * property, GVariant
 			gtkimage = NULL;
 		} else if (g_strcmp0(iconname, DBUSMENU_MENUITEM_ICON_NAME_BLANK) == 0) {
 			gtkimage = gtk_image_new();
-			g_object_set(G_OBJECT(gtkimage), "use-fallback", TRUE, NULL);
+			set_use_fallback(gtkimage);
 		} else {
 			/* Look to see if we want to have an icon with the 'ltr' or
 			   'rtl' depending on what we're doing. */
@@ -808,7 +832,7 @@ image_property_handle (DbusmenuMenuitem * item, const gchar * property, GVariant
 			   can just convert it to this name. */
 			if (gtkimage == NULL) {
 				gtkimage = gtk_image_new_from_icon_name(finaliconname, GTK_ICON_SIZE_MENU);
-				g_object_set(G_OBJECT(gtkimage), "use-fallback", TRUE, NULL);
+				set_use_fallback(gtkimage);
 			} else {
 				gtk_image_set_from_icon_name(GTK_IMAGE(gtkimage), finaliconname, GTK_ICON_SIZE_MENU);
 			}
diff --git a/libdbusmenu-gtk/parser.c b/libdbusmenu-gtk/parser.c
index 9b132ce..5d71585 100644
--- a/libdbusmenu-gtk/parser.c
+++ b/libdbusmenu-gtk/parser.c
@@ -68,10 +68,22 @@ static void           menuitem_notify_cb       (GtkWidget *         widget,
                                                 GParamSpec *        pspec,
                                                 gpointer            data);
 
+/**
+	dbusmenu_gtk_parse_menu_structure:
+	@widget: A #GtkMenuItem or #GtkMenuShell to turn into a #DbusmenuMenuitem
 
+	Goes through the GTK structures and turns them into the appropraite
+	Dbusmenu structures along with setting up all the relationships
+	between the objects.  It also stores the dbusmenu items as a cache
+	on the GTK items so that they'll be reused if necissary.
+
+	Return value: A dbusmenu item representing the menu structure
+*/
 DbusmenuMenuitem *
 dbusmenu_gtk_parse_menu_structure (GtkWidget * widget)
 {
+  g_return_val_if_fail(GTK_IS_MENU_ITEM(widget) || GTK_IS_MENU_SHELL(widget), NULL);
+
   RecurseContext recurse = {0};
 
   recurse.toplevel = gtk_widget_get_toplevel(widget);
@@ -219,7 +231,7 @@ construct_dbusmenu_for_widget (GtkWidget * widget)
 	   use its own build function */
 	if (DBUSMENU_IS_GTK_SERIALIZABLE_MENU_ITEM(widget)) {
 		DbusmenuGtkSerializableMenuItem * smi = DBUSMENU_GTK_SERIALIZABLE_MENU_ITEM(widget);
-		return dbusmenu_gtk_serializable_menu_item_build_dbusmenu_menuitem(smi);
+		return dbusmenu_gtk_serializable_menu_item_build_menuitem(smi);
 	}
 
   /* If it's a standard GTK Menu Item we need to do some of our own work */
diff --git a/libdbusmenu-gtk/serializablemenuitem.c b/libdbusmenu-gtk/serializablemenuitem.c
index f67434e..cfd864d 100644
--- a/libdbusmenu-gtk/serializablemenuitem.c
+++ b/libdbusmenu-gtk/serializablemenuitem.c
@@ -166,7 +166,7 @@ get_property (GObject * obj, guint id, GValue * value, GParamSpec * pspec)
 }
 
 /**
-	dbusmenu_gtk_serializable_menu_item_build_dbusmenu_menuitem:
+	dbusmenu_gtk_serializable_menu_item_build_menuitem:
 	@smi: #DbusmenuGtkSerializableMenuItem to build a #DbusmenuMenuitem mirroring
 
 	This function is for menu items that are instanciated from
@@ -179,7 +179,7 @@ get_property (GObject * obj, guint id, GValue * value, GParamSpec * pspec)
 		set by this object.
 */
 DbusmenuMenuitem *
-dbusmenu_gtk_serializable_menu_item_build_dbusmenu_menuitem (DbusmenuGtkSerializableMenuItem * smi)
+dbusmenu_gtk_serializable_menu_item_build_menuitem (DbusmenuGtkSerializableMenuItem * smi)
 {
 	g_return_val_if_fail(DBUSMENU_IS_GTK_SERIALIZABLE_MENU_ITEM(smi), NULL);
 
@@ -207,7 +207,7 @@ type_handler (DbusmenuMenuitem * newitem, DbusmenuMenuitem * parent, DbusmenuCli
 	DbusmenuGtkSerializableMenuItem * smi = DBUSMENU_GTK_SERIALIZABLE_MENU_ITEM(g_object_new(th->type, NULL));
 	g_return_val_if_fail(smi != NULL, FALSE);
 
-	dbusmenu_gtk_serializable_menu_item_set_dbusmenu_menuitem(smi, newitem);
+	dbusmenu_gtk_serializable_menu_item_set_menuitem(smi, newitem);
 	dbusmenu_gtkclient_newitem_base(DBUSMENU_GTKCLIENT(client), newitem, GTK_MENU_ITEM(smi), parent);
 
 	return TRUE;
@@ -265,7 +265,7 @@ dbusmenu_gtk_serializable_menu_item_register_to_client (DbusmenuClient * client,
 }
 
 /**
-	dbusmenu_gtk_serializable_menu_item_set_dbusmenu_menuitem:
+	dbusmenu_gtk_serializable_menu_item_set_menuitem:
 	@smi: #DbusmenuGtkSerializableMenuItem to set the @DbusmenuGtkSerializableMenuItem::dbusmenu-menuitem of
 	@mi: Menuitem to get the properties from
 
@@ -276,7 +276,7 @@ dbusmenu_gtk_serializable_menu_item_register_to_client (DbusmenuClient * client,
 	pick up this property being set.
 */
 void
-dbusmenu_gtk_serializable_menu_item_set_dbusmenu_menuitem (DbusmenuGtkSerializableMenuItem * smi, DbusmenuMenuitem * mi)
+dbusmenu_gtk_serializable_menu_item_set_menuitem (DbusmenuGtkSerializableMenuItem * smi, DbusmenuMenuitem * mi)
 {
 	g_return_if_fail(DBUSMENU_IS_GTK_SERIALIZABLE_MENU_ITEM(smi));
 	g_return_if_fail(mi != NULL);
diff --git a/libdbusmenu-gtk/serializablemenuitem.h b/libdbusmenu-gtk/serializablemenuitem.h
index 1ca3ef8..db28a24 100644
--- a/libdbusmenu-gtk/serializablemenuitem.h
+++ b/libdbusmenu-gtk/serializablemenuitem.h
@@ -90,6 +90,13 @@ struct _DbusmenuGtkSerializableMenuItemClass {
 	DbusmenuGtkSerializableMenuItem:
 	@parent: Inherit from GtkMenuItem
 	@priv: Blind structure of private variables
+
+	The Serializable Menuitem provides a way for menu items to be created
+	that can easily be picked up by the Dbusmenu GTK Parser.  This way
+	you can create custom items, and transport them across dbusmenu to
+	your menus or the appmenu on the other side of the bus.  By providing
+	these function the parser has enough information to both serialize, and
+	deserialize on the other side, the menuitem you've so carefully created.
 */
 struct _DbusmenuGtkSerializableMenuItem {
 	GtkMenuItem parent;
@@ -99,9 +106,9 @@ struct _DbusmenuGtkSerializableMenuItem {
 
 GType dbusmenu_gtk_serializable_menu_item_get_type (void);
 
-DbusmenuMenuitem *  dbusmenu_gtk_serializable_menu_item_build_dbusmenu_menuitem (DbusmenuGtkSerializableMenuItem * smi);
+DbusmenuMenuitem *  dbusmenu_gtk_serializable_menu_item_build_menuitem (DbusmenuGtkSerializableMenuItem * smi);
 void                dbusmenu_gtk_serializable_menu_item_register_to_client (DbusmenuClient * client, GType item_type);
-void                dbusmenu_gtk_serializable_menu_item_set_dbusmenu_menuitem (DbusmenuGtkSerializableMenuItem * smi, DbusmenuMenuitem * mi);
+void                dbusmenu_gtk_serializable_menu_item_set_menuitem (DbusmenuGtkSerializableMenuItem * smi, DbusmenuMenuitem * mi);
 
 G_END_DECLS