API Fragmentation and Cleanup

[Kenny Graunke <kenny whitecape org>]

Hello all,

(Disclaimer: I am not a hacker. I do not wish to be a "back seat coder",
 but I feel these issues are important enough that someone needs to bring
 them up...)

I feel that GNOME's API is becoming increasingly fragmented. At least
in GNOME 1.x, there are becoming more and more ways to do things, each
of which comes with it's own set of advantages, limitations, quirks,
and problems.

A case in point, ways to make a basic menubar and fill it:

(1) Plain GtkMenuBar, GtkMenuItem, and GtkMenu widgets (2) GTK's
    "MenuFactory", as mentioned on http://www.gtk.org/faq (3) GTK using
    the "GtkPixmapMenuItem" widget from gnome-libs (Which is also
    confusingly prefixed with "Gtk", when it is in gnome-libs...)
(4) GNOME_UIINFO in a GnomeApp (5) Bonobo's menubar/toolbar handling
(6) The panel's Scrolling Menu widgets, and "foobar" widgets

These come from: gtk+, gnome-libs, bonobo, and gnome-core. We also have
custom widgetry in gal, eel, and other modules these days.

These are just ways that I have encountered as someone trying to start
hacking. My pet project has been a menubar applet, and I have had lots
of trouble.  Problems I have had with each method:

(1) No readily apparent way to add pixmaps.
(2) Haven't tried this, as I only recently heard about it.
(3) Does not appear to be used by most programs directly (and has no
    obvious way of setting the label, at least to me)
(4) Appears to only be used in GnomeApps, not standalone - and I haven't
    managed to cram a GnomeApp into an applet... ;-)
(5) Using bonobo seems overkill for a simple starting project, though
    it might be a good idea when I have more experience...
(6) These are hacks in *one program*.

Problems like this where there are many ways to do more or less the same
basic purpose have two main problems:

(1) Hackers who come from other systems and are interested in hacking
    on GNOME code may be confused and frustrated by the apparent lack of
    organization. This becomes even more of a problem for people who
    are just learning to write GNOME software, who may have little prior
    programming experience (at least in a traditional *NIX environment),
    or are otherwise rusty. I fall into this category, so I know from
    first-hand experience.

    Now, you could attack me and say that only experienced people should
    be coding such projects and that I should start somewhere else, if
    you think that, then that's fine with me; I'll cheerfully ignore such
    criticism. I believe that things like this are going to frustrate
    and confuse people to the point where they get discouraged and just
    turn away, when they otherwise may have become very helpful people
    who could have improved GNOME substantially in the long run. While
    experienced hackers can deal with this, for new hackers, this can
    much harder.

    Also, I hear flames from certain people (usually non-hackers) who push
    for people to just use GTK, and not use that "bloated" GNOME. While
    I personally just brush these flamers aside, as they generally used
    flawed arguments and invalid data, I do believe they have a point,
    in a way:

    The GNOME API is much more complicated than plain GTK. When there
    are suddenly this many more ways to do such a seemingly simple task,
    it may seem like GNOME is fragmented and just too confusing, they
    do not want to have to deal with it.

    And now, on to my second point, taking an opposite point of view...

(2) The fragmentation of widgets is leading to a fragmented user interface.

    Using menus and toolbars as an example, let's examine a random
    sampling of GTK+/GNOME programs I find myself using on a daily basis:

    * Panel

    The panel is the only program which has "scrolling menus", which
    allows people to use menus larger than their screen, rather than just
    cutting them off like standard GTK does. No other program I know of
    does this, although perhaps bonobo menus do - I am not sure. This
    really is something that belongs as the default behavior of all
    menus in GTK+, for *all* programs; it has absolutely no business in
    the panel whatsoever. The panel may be a common place where this is
    needed, but I can think of others, and this is really only leading
    to inconsistency.

    * GIMP

    The GIMP has no handleboxes on its menubar, regardless of the GNOME
    setting.  It also has no pixmaps, due to it using only GTK for menus.

    * Gabber (GNOME Jabber Client)

    Gabber has toolboxes on its toolbars regardless of the setting. It
    uses libglade for this, and I believe the author is unsure how to
    make it respect the GNOME setting.

    * Nautilus (Using bonobo menu/toolbar handling)

    When you resize the window to be smaller than the toolbars, bonobo
    toolbars will add an arrow which makes a popout of all the items
    which did not fit.  Stock GNOME toolbars do not allow this, they
    simply cut off any items, sometimes in the middle of the item.

    * Evolution

    Last I tried Evolution (a few days ago), it had text labels to the
    right of the icons. Stock GNOME toolbars do not support this, and no
    other GNOME program I have seen has text labels on the right. This
    is not to say that it is a bad thing to have such a choice, but it
    *is* bad to have only one program that does this, and only a few
    (those that use bonobo) which *can*.

Basically, until we get our APIs de-fragmented, new developers are going
to be frustrated, and users will have to deal with lots of inconsistency,
the bane of good UI Design. We must begin to address this.

I propose organizing a team of hackers representing various "interests"
module-wise and company wise (people who hack on gtk+, gnome-libs,
bonobo, gal, eel, and so on - this will already assure that we get
a mix from RHAD Labs, Eazel, Ximian, and independent hackers.) This
team would examine basic tasks in GNOME development, our current APIs,
and the status of all these modules. Their goal would be to find places
where these modules overlap, and to decide where APIs should be merged,
moved between modules, cleaned up, depricated, or entirely removed.

Hopefully GNOME 2.x already addresses some of these issues, I am only
familiar with the state of 1.x - but I think as we move on to 2.x
and to future releases, we must keep a handle on this so it does not
get out of control. I doubt most people would disagree with my strong
belief that having a few *solid* ways to do a simple development task
is much better than having 6 ways to do the same thing, none of which
are optimal solutions.

I do realize that many of these problems stem from backwards compatibility
and the simple fact that these newer solutions simply did not exist
back when the older ones were used. However, at the moment it's gotten
pretty messy, so I want to be sure people are working on these issues
for the future.

Thanks,

Kenny Graunke <kenny whitecape org>