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 > _______________________________________________ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list