Re: Update for the gtkmm tutorial about Debian

[Murray Cumming <murrayc murrayc com>]

On Sat, 2006-01-21 at 19:28 +0100, Pierre THIERRY wrote:
> Scribit Jonathon Jongsma dies 21/01/2006 hora 09:28:
> > While I can't speak for anybody else, I've found that contributions
> > and criticisms are quite welcome.
> 
> OK, great.
> 
> > Like all open-source projects, there's a shortage of manpower so
> > obviously bugs with a patch attached are likely to be implemented more
> > quickly.
> 
> I'll try to give such patches ASAP.
> 
> > As you're learning, feel free to suggest ways that the documentation
> > is unclear or could be improved as well.
> 
> Here we go: I'm on the page of the radio buttons, and I have a couple of
> difficulties.
> 
> First, I can't understand why
> 
> 	m_rb2.set_group(m_rb1.get_group())
> 
> can't work...

I guess you are referring to this in the tutorial:

"
Note that you can't just do
m_rb2.set_group(m_rb1.get_group()); //doesn't work
because the group is modified by set_group() and therefore non-const.
"

In future, please do include URLs of the parts of the manual that you
are discussing, so we don't have to guess.

>  Especially if it is because the group returned by
> get_group() is modified by set_group().

set_group(get_group()) would create a temporary instance. Temporary
instances in C++ are const.

>  If modification by the second or
> third button has an impact on the group of the first, I would presume
> the data returned is a reference or a pointer.

It is not, as the reference documentation shows. The manual gives you
that hint about that, in case you expect it to be a reference or
pointer.

The Group acts a bit like a smart-pointer. The underlying implementation
is shared. That's not so unusual, and this is a very simple part of the
API so I think it's OK for the documentation to just say how it should
be used, without worrying about how it is implemented. It does that in
the class documentation for RadioButton.

> The problem is, you tell something not obvious but there is no link to
> an explanation. Going to the reference is of no help because the
> get_group() method has absolutely no documentation.

I have now added reference documentation for get_group() and set_group()
in RadioButton, repeating this information. Thanks for the bug report.

> Second, you continue the tutorial and instead of giving the OO-expected
> group.add(m_rb1) or something like, you use Gtk::manage(), of which we
> only only know it has a memory management purpose. Again, going to the
> reference is of no help, because that function too has absolutely no
> documentation...

It's mentioned in the Basics chapter in the book. I guess that's how you
know that it has a memory management purpose. What more do you need to
know?

I also recently added reference documentation for it, in case anybody
finds their way to this page:
http://www.gtkmm.org/docs/gtkmm-2.4/docs/reference/html/namespaceGtk.html#85d08eef743328ffebac2647a9c7f183

> Why not use:
> 
> RadioButtons::RadioButtons()
> {
>       Gtk::RadioButton::Group group;
>       Gtk::RadioButton m_rb1(group,"button1"),
>       		 m_rb2(group,"button2"),
> 		 m_rb3(group,"button3");
> }

Yes, I think that works.

> The problem here is the curious beginner will encounter too many
> pedagogical pitfalls, IMHO.
> 
> BTW, why do the example use:
> 
> Gtk::Main kit(argc, argv);
> Gtk::Window window;
> Gtk::Main::run(window);
> 
> Instead of:
> 
> Gtk::Main kit(argc, argv);
> Gtk::Window window;
> kit.run(window);

At the moment, it should probably be:

Gtk::Main::init(argc, argv);
Gtk::Window window;
Gtk::Main::run(window);

because Gtk::Main::Main() actually does not allow a second instance to
be instantiated.

That probably doesn't work at the moment, but probably could be made to
work.

> The latter syntax is more object oriented, and moreover enables one to
> enhance or adapt the event loop by using another object (probably
> derived from Gtk::Main).

I'm not sure about that. I don't see a need to initialize gtkmm or GTK+
twice. You can already run Gtk::Main::run() twice - it doesn't need an
extra Main object.

Glib::Main might be a bit different.

> Curiously,
> Nowhere man
>  
> PS: for the beginner willing to send patches for the doc, a link to the
> CVS or Subversion repository in the beginning of the tutorial would be
> great...

There's already a bugs page with clear instructions about making
patches. I don't think we need to repeat all the information everywhere.
I have added a link to the bugs page in the Contributing appendix, which
is already linked from the introduction.

-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com