Re: The flexibility of printed information

[Murray Cumming <murrayc murrayc com>]

On Thu, 2006-01-12 at 14:39 -0700, Ed Leaver wrote:
> More depth:
>    1. For a start, signal handlers. Ask Glade to add you a widget, and
> glade asks you what signal handler you would like it to connect.

Note that this feature of Glade is useless for us until someone figures
out what we would want it to do.

>  Glade then gives you a list of maybe three dozen possibilities. Go to
> the online Doxygen generated docs, and not one of them is documented.

Yes, signals are not well documented. However, that is 
a) something for the reference documentation at first, not a book.
b) something for GTK+. Before it's documented in GTK+ we can't really
document it in gtkmm.

>  Not one. I discovered that I usually wanted a "clicked" or "activate"
> method by trial-and-error.

The most important signals, such as "clicked" for Gtk::Button, of each
widget should indeed be mentioned in 
a) The class documentation for the class in the reference documentation
b) The book.

I think that's been done quite often, but feel free to submit patches.
It should be quite easy.

>  And Signal handlers aren't the only methods not documented. But these
> documentation shortcomings could be addressed in the source code. For
> the most part the Gtkmm Doxygen framework is quite well laid out. It
> just needs to be much better filled in.

Yes.

>   2. More thorough discussion of signals and threads. I've got a
> stinker of a problem I'm dealing with at present: I've written a
> specialized archival program that contains a function that traverses
> several or more *nix filesystems, and stores information on each file
> and directory in a TreeModel. Sort of like a super "find." But like
> find, it is recursive and can be quite time consuming, and I'd like to
> allow the user to break out of the traversal if he discovers he's
> started maybe a bit higher than necessary. It "would be nice" if I
> could just emit a signal at the end of each level (row) in the
> hierarchy, allow the main event loop to spin for a moment, then
> re-enter the recursive function at the point the signal was emitted.
> Can't see how to do that however, and unless someone can please "show
> me the stepping stones", I'm pretty much resigned to running the tree
> traversal function in a separate thread.

This sounds like an example that we should have. This non-threading
example might be suitable:
http://www.gtkmm.org/docs/gtkmm-2.4/examples/book/update_ui/
though I'd like an example using threads, where that makes sense.

I know that regexxer allows you to stop a search for files.

>  And tracking down every single point the TreeView might access the
> TreeModel, every place any of my custom InfoWindow's might access the
> TreeModel, any place any other widget might access the TreeModel, and
> protect with Mutexes appropriately. TANSTAAFL.

In general, we advise that only one thread deals with the user
interface, and that other threads communicate with that thread.

> 3. Slots and binding additional parameters to slots. There seems to be
> at least two syntaxes: sigc and SigC,

No, sigc:: is the libsigc++ 2.0 namespace (with the gtkmm-2.4 API), and
SigC:: is the libsigc++ 1.2 namespace (with the gtkmm-2.0 API).

>  slot and Slot, and its never clear which is appropriate, or how in
> the world bind() or Bind() actually work.

It's in the Basics chapter:
http://www.gtkmm.org/docs/gtkmm-2.4/docs/tutorial/html/apbs05.html

>  Its enough to drive one blind() or Blind(). Or to Qt.
> 4. Your work here on Gtkmm really is very much appreciated, but I
> agree that a nice glossy professional C++ Gtkmm-specific dead-tree
> User's Guide, along the lines of the best of those available for Qt,
> would go a *loooong* ways towards gaining Gtkmm (and Gtk+ in general)
> wider credibility and acceptance as a programming environment. There
> is a wealth of decent printed Gtk+ programming guides, and there are
> enough widgets on the Gnome desktop that I guess someone must be
> buying them. Its just hard for C++ programmers to go back, is all. Or
> to see the point. THANKS!
> 
> On Sun, 2006-01-08 at 05:18, Murray Cumming wrote: 
> > On Sat, 2006-01-07 at 21:08 -0500, jalqadir netscape net wrote:
> > > Ah! Yes, this is the book that comes with the documentation. No, what
> > > I mean by a book is something that can be printed 
> > 
> > See my previous reply.
> > 
> > > and that would cover the many and different areas of GTKmm in more
> > > depth.
> > 
> > What should it cover in more depth? You don't need a new book just add
> > stuff to the existing book.
-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com