libgnome* API review from LB perspective

[James Henstridge <james daa com au>]

Maciej asked me to do a review of the 2.0 libgnome and libgnomeui APIs
from the perspective of someone writing a language binding.  Below are my
comments so far.

I can't guarantee that I have caught everything, but hopefully I have
caught the most noticable ones (there aren't very many).

I also may have missed issues that are important to other language
bindings.  It would be good for the author of a totally different LB (eg.
C++ or objc) to also go through the APIs and see if there are problems
from their pov.

Hopefully the comments will also help other maintainers identify issues in
their libraries that may affect LBs.

James.

-- 
Email: james daa com au
WWW:   http://www.daa.com.au/~james/

--
This document is a review of the libgnome and libgnomeui APIs from the
point of view of a language binding (LB) writer.  I don't guarantee
that it is complete, and it may miss issues that are important to
language bindings with requirements that differ significantly from my
python binding (C++ or objc are examples of bindings with
significantly different requirements).

The review is broken down by the header.  When I say a function is not
needed, I mean that it probably wouldn't be used from a program
written in some other language (usually due to it duplicating standard
functionality).  This is not the same as it being useless to a C
programmer.

I may occasionally throw in a general API comment :)


LIBGNOME
========

gnome-config.h
	API is very similar to 1.x API, which had no obvious problems.
	Shouldn't be a problem.

gnome-exec.h
	No obvious problems wrapping these, however I would think that
	most LBs would use the equivalent functions in their standard
	library.

gnome-gconf.h
	simple functions, easily wrapped.  If
	gnome_gconf_get_app_settings_relative is meant to act as a
	method of the GnomeProgram object, then maybe it should have
	the gnome_program_ prefix rather than gnome_gconf_ though.
	This is the maintainers call though, and not a big deal. (this
	is a convenience for defs file generators mainly).

gnome-help.h
	Same as above: no real problem wrapping these functions, but
	if they are GnomeProgram methods, maybe they should have a
	gnome_program_ prefix.

gnome-i18n.h
	gnome_i18n_get_language_list() shouldn't cause much of a
	problem (and is probably the only useful function in this
	header for language bindings).  Most language bindings
	ignore locale info and/or have a setlocale() wrapper and ref
	counted strings, so the push/pop_c_numeric_locale functions
	probably wouldn't be needed.

gnome-init.h
	discussion of GnomeModuleInfo stuff covered in GnomeProgram
	discussion.

gnome-macros.h
	convenience code for C programmers.

gnome-preferences.h
	not sure whether these functios are of any use to LB writers.
	They look more like for internal use.  In any case, they are
	the same as the 1.x versions, which no one complained about
	much.

gnome-program.h
	GnomeProgram object being a GObject should make it fairly easy
	to wrap.

	I would expect most bindings to probably use some custom code
	to call gnome_program_module_register() when the programmer
	loads some library, so that they all get initialised when the
	GnomeProgram.init() function is called.

	Note that in general, implicit library initialisation or no
	argument library initialisation is nicer, but this should be
	fine since the libs want to see the arguments.

	Haven't looked at what is required for argument parsing.  Is
	it an error if it finds unknown arguments?

	Is GnomeProgram meant to be a singleton?  If so,
	gnome_program_get() should probably create the GnomeProgram
	object if it hasn't been yet, and gnome_program_init* should
	set properties on that object, rather than creating a new one.
	The gnome_program_initv function shouldn't take a GType
	argument if this is the case, as subclassing wouldn't make
	sense.

	Registering GnomeModuleInfo as a boxed types gets a thumbs up.

gnome-score.h
	same API as 1.x, which had no obvious problems.

gnome-sound.h
	looks same as 1.x API.  No problems.  I haven't reviewed the
	esound API though.

gnome-triggers.h
	same API as before.  Possibly the GTRIG_* constants should be
	changed to GNOME_TRIGGERS_* constants.  I doubt this would
	cause much breakage, as I don't know of any programs that
	added triggers (should gnome_triggers_add_trigger be
	deprecated/removed?).

gnome-url.h
	looks fine.

gnome-util.h
	most functions here would probably not be wrapped by a
	language binding, as they would be handled by the standard
	library of the language.

libgnometypebuiltins.h
	Providing GTypes for enums/flags is very helpful (the
	constants provided by pygtk are generated from the information
	registered with glib).  The glib-mkenums calls in the makefile
	look correct.


LIBGNOMEUI
==========

gnome-about.h
	API has not changed substantially from 1.x, so no problems
	here.

gnome-app-helper.h
	This hasn't changed substantially from 1.x, and appears to
	have the same issues as before.  Can be wrapped (as it was in
	the 1.x version of pygtk for instance), but is a bit hackish.

gnome-app-util.h
	same as 1.x.  No destroy notify for user data arguments, so
	can't be used without leaking.  These are mostly as a
	convenience for C programmers though, and are deprecated.

gnome-app.h
	same API as 1.x.  No problems here.

gnome-appbar.h
	The StudlyCapTypeName -> lower_case_with_underscores
	translation of this typename doesn't follow the rules.  It
	should either be renamed to GnomeAppbar, or the functions
	should be changed to gnome_app_bar_*.

	No other obvious API problems (same as 1.x).

gnome-client.h
	gnome_client_request_interaction_interp should be replaced
	with one that takes a closure.  The code for handling the
	interp case isn't even correct by the old GtkArg handling code
	(it is doing the equivalent of the GTK_RETLOC_* macros, rather
	than GTK_VALUE_* macros.  The closure option is recommended.

gnome-color-picker.h
	no real API problems here.

	However, it seems a bit confusing to provide so many get/set
	options.  Maybe providing the same sort of functions as
	GtkColorSel would be good.

gnome-dateedit.h
	looks same as 1.x API.  no obvious problems.

gnome-dialog-util.h
	same issues as gnome-app-utils.h.  Deprecated, so not an
	issue.

gnome-dialog.h
	looks same as 1.x API, which had no big problems.

gnome-druid-page-edge.h
	no problems here.

gnome-druid-page-standard.h
	no problems here.

gnome-druid-page.h
	no problems in the header.

	"back" signal incorrectly states that its argument is a
	GTK_TYPE_POINTER, rather than GTK_TYPE_WIDGET.

gnome-druid.h
	no problems here.

gnome-entry.h
	no problems here.

gnome-file-entry.h
	no problems in header.

	The gnome_entry and gtk_entry args are listed as being of type
	GTK_TYPE_POINTER, when they should probably be
	GNOME_TYPE_ENTRY and GTK_TYPE_ENTRY respectively.

gnome-font-picker.h
	same as 1.x API.

gnome-gconf-ui.h
	looks to be internal.

gnome-href.h
	same as 1.x API.

gnome-ice.h
	internal.

gnome-icon-entry.h
	no problems in header.

	"pick_dialog" property listed as GTK_TYPE_POINTER, rather than
	GTK_TYPE_WIDGET.

gnome-icon-list.h
	no major problems in header.

	"text_changed" signal lists second argument as being a
	GTK_TYPE_POINTER, when it should be GTK_TYPE_STRING.

gnome-icon-sel.h
	looks fine.

gnome-mdi-child.h
	This type has the same problems w.r.t. LBs as it did in 1.x,
	which is what GnomeMDIGenericChild was designed to work
	around.

gnome-mdi-generic-child.h
	This object should be updated to use closures rather than the
	older GtkArg based callbacks.

	Uses GTK_TYPE_POINTER for handling the GList return of the
	create_menus function.

gnome-mdi-session.h
	no obvious problems here.

gnome-mdi.h
	gnome_mdi_set_{menubar,toolbar}_template functions have the
	same issues as in 1.x -- an LB ends up leaking the GnomeUIInfo
	structures.

gnome-messagebox.h
	no obvious problems here (same as 1.x API)

gnome-pixmap-entry.h
	no obvious problems here (same as 1.x API)

gnome-pixmap.h
	no obvious problems here.  This widget is deprecated by
	GtkImage.

gnome-popup-menu.h
	This widget is language binding unfriendly, as it overrides
	the signal connection handling done by the LB.

gnome-propertybox.h
	no problems here.

gnome-scores.h
	no problems here.

gnome-stock-icons.h
	just #defines.  no problems here.

gnome-types.h
	just typedefs.  Maybe these should be with the code that uses
	them?

gnome-ui-init.h
	see GnomeProgram comments above.

gnome-uidefs.h
	#defines here again.

gnome-vfs-util.h
	gnome_gdk_pixbuf_new_from_uri should be fine.

	gnome_gdk_pixbuf_new_from_uri_async may leak callback_data (no
	destroy notify).  Does done_callback always get called (even
	if canceled?).  Would it make sense to add a closure version?

gnome-window-icon.h
	look like convenience wrappers for gtk_window_set_icon, etc,
	except that they take filenames instead.  Not sure how much
	extra value this has for LB's.

gnome-window.h
	no problem here (although it is a bit weird having a method of
	GtkWindow defined in libgnomeui.  Possibly a make_title()
	function would make more sense?)

gnometypebuiltins.h
	The code used to generate the enum/flags defs looks good.