Re: libglade frustration redux

[Michael Torrie <torriem chem byu edu>]

On Sat, 2007-02-17 at 11:49 -0500, Gerald I. Evenden wrote:
> > From a gnome.org web page there are four example programs from which I will 
> select example2 as an sample of incomplete/non-existant documentation.  See

Having addressed your points below, I have to disagree that the
documentation is non-existent.  In fact I found the information you
required solely from a few simple google queries.  As for the
documentation being incomplete, documentation can always be more
complete, cover more of the corner cases, etc.  But as far as coverage
goes, GTK documentation is amazingly complete, given that it is
essentially created for free by volunteers.  I guess it comes down to
personal opinion.  I will address your points below.

Just a humorous aside, but compared to documentation in the Windows
world (despite the apparent depth of MSDN), things in the Linux world
are wonderfully documented.  I think that's largely due to the overall
open source nature of things.

> http://www.gnome.org/~newren/tutorials/developing-with-gnome/html/apcs02.html#libglade-example-2-gtk
>
> for the C code.
>
> On line 72 in module main there is a reference to function g_signal_connect.  
> I cannot find any reference to this entry in the index
>
> http://developer.gnome.org/doc/API/2.0/gtk/ix01.html
>     or
> http://developer.gnome.org/doc/API/2.0/glib/ix01.html

I see how you are frustrated, as you are looking in the wrong place.
And I also see how you could be led to look in the wrong places.  But if
you go back to first principles, you can avoid getting lost.  

However a quick google search reveals that the documentation on signals
can be found here (google for "g_signal_coonect"):

http://developer.gnome.org/doc/API/2.0/gobject/gobject-Signals.html


Sounds also like you missed this document:

http://www.gtk.org/tutorial/

and

http://www.gtk.org/tutorial/x159.html

The latter two links are really prerequisites for understanding any part
of GTK including libglade.

> By following the glib.h include at the beginning of the example-1.c file I 
> managed to grep out a definition in /usr/include/glib-2.0/gobject/g_signal.h 
> which is a redefinition of the entry g_signal_connect_data.
>
> If the *.h files are any indication there is a whole group of g_signal_* 
> entries BUT I cannot find any description of their usage, even in a printed 
> manual on GTK+.

Have you done any searches on google on "g_signal_connect?"  I believe
you'll find this is the most-used, essential API call in all of GTK.
*All* gtk apps will use it in some way.  Any gtk example at all will
have this.  Can you not also infer usage of this function from example
code, as well as from the API docs?  

g_signal_connect is mentioned by *every* GTK tutorial I have ever seen.
You have gone through the GTK tutorials, haven't you?  They are
prerequisites for using libglade.  I mean how can you possibly hope to
use libglade without having first at least understood basic GTK
concepts?

> The author of example2.c is probably a GTK guru who (as has been suggested) 
> digested all of the sources of GTK/Glib and thus new how to include this 
> statement and assumed that everyone else was equally conversant with GTK, et 
> al..  But for wet-behind-the-ears beginners the example is of dubious value 
> when the documentation of the usage of ALL the GTK/Glib functions included in 
> the program is incomplete.

I'm sorry, but your veiled sarcasm doesn't come across well in the
e-mail.  I am not a GTK guru, but found the API to be incredibly easy to
understand and use, and it is improved by leaps and bounds.

> Do I blame the author of example1.c or the authors of the GTK manual?  Someone 
> is surely deserving a thousand lashes of a wet noodle.

Sure, if you have a problem with his example, send him an e-mail.  But
be sure to send him a constructive e-mail, rather than just a rant about
how much effort you're having to go through.  

> The reason I was researching this example was that I felt that the example's 
> usage of the progress bar widget was not functioning properly; the pulse 
> operation does not create any visible effect.

The example works just as it is supposed to.  I get a pulsing progress
bar which, on my GTK theme, is a small blue rectangle that moves back
and forth in the progress bar.  How the pulsing progress bar looks is
entirely dependent on the theme.  In some themes, you get an effect
similar to a barber shop pole across the entire width of the progress
bar.  

What were you expecting to see?  

Anyway, I hope this addresses your concerns.  

Michael


>