GNOME skeleton program thoughts

[Patanjali Somayaji <patanjali codito com>]

Hi,

I was trying to come up with a recommended skeleton for a GNOME
application. /cvs/gnome/gnome-hello seems to be out of date, or
recommends the use of APIs that might be potentially deprecated ...

>From the various API docs, gnome-hello, and source code of many
applications - that would look like: 

main (...)
{
    //  declare variables here 

    program = gnome_program_init (...);
    
    app = gnome_app_new (...);

    // lots of gtk_app_ () calls using "GNOME_APP (app)"
    // lots of gtk+ calls using "app" ...

    gtk.main ();
}

The call "app = gnome_app_new ()" intuitively indicates that some sort
of "Application" object is returned by gnome_app_new (), as does the use
of "_app_" in gnome_app_new (). Which could potentially lead to more
confusion - if gnome_program_init () returns a GnomeProgram, why is
there one more Application object ? 

gnome_app_new () actually just returns a GtkWidget thats sort of like
the root window of an application. Lots of gtk_app_ () calls are then
used to populate this widget with standard UI elements. 

The API docs for GnomeApp make it clear that GnomeApp is the main
application widget:
http://developer.gnome.org/doc/API/2.0/libgnomeui/GnomeApp.html

This scheme possibly lacks coherence or intuitiveness. A coherent API
would have - 

init_system ()
a = application_init (); // a is some application object
window = root_window (a, ...);  // a is used in some call to create
				// a window for the application

gnome_program_init () inits GNOME libraries and the run time environment
for the application, and not the application object itself. GnomeProgram
may not be the right thing to call it. The confusion is further
reinforced by the API doc:
http://developer.gnome.org/doc/API/2.0/libgnome/libgnome-gnome-program.html#gnome-program-init

which has, in the example for gnome_program_init ():
"GnomeProgram *my_app;"
and then proceeds to do a:
"my_app = gnome_program_init (...);"

Alternatives - 
1. Make gnome_app_new () -> gnome_app_main_widget_new ()
2. Make GnomeProgram some sort of application object with an init-ed
root window. 
3. Use the returned GnomeProgram in a function to create the root window
...
4. call both something else. 

It is difficult to define what the skeleton for a GNOME program should
be since there are a lot of alternatives. In fact, since libgnomeui
might be deprecated in the future, and because GtkUIManager has a lot of
the stuff from libgnomeui - the following is a current version of the 
skeleton (post GNOME 2.6/GTK+ 2.4): 

main (...)
{
    // declare variables 
    
    program = gnome_program_init ();
    
    window = gtk_window_new (GTK_WINDOW_TOP_LEVEL);
    
    // lots of GTK+ calls using window, including GTK+ UI manager calls
    
    gtk.main ();
}

Is this correct ? 

This potentially still has the problem that gnome_program_init () might
be init-ting some sort of application/program object that will be used
later. Another observation is that most apps don't need to use the
returned GnomeProgram, and proceed to making many gtk+ calls after that.

cheers,
Patanjali