GNOME Bugzilla – Bug 658265
The gtkmm tutorial is not fully in line with gtkmm3
Last modified: 2011-10-12 17:21:26 UTC
There are still some remains from gtkmm2 in the gtkmm tutorial. And a few details that could have been improved in gtkmm2 too. gtkmm-tutorial-in.xml contains descriptions of some classes and methods that don't exist in gtkmm3. All example programs that are mentioned in the tutorial compile and link with no problem, but during execution some of them don't behave as well as you would like. Some example programs have printed warnings similar to this one: (example:2546): Gtk-WARNING **: gtk_widget_size_allocate(): attempt to underallocate gtkmm__GtkWindow's child gtkmm__GtkBox 0x9aa2910. Allocation is 326x221, but minimum required size is 374x238. This warning was introduced in gtk+ 3.1, but it was then removed from non-debug builds 2011-08-30. It's not mentioned further in this bug report. Chapter 6. Range Widgets book/range_widgets/example: Some of the widgets are too small to be useful. Chapter 7. Miscellaneous Widgets book/label/example: "Fourth line, (j/k)" shall be "Third line". For quite some time underlining has not worked. Fixed by gtk+ bug 658111 2011-09-04. book/progressbar/example: "Show text" does not work. No text is shown. Chapter 8. Container Widgets book/scrolledwindow/example: Stopped working in gtkmm 3.1 when Gtk::Dialog::get_vbox() was replaced by get_content_area() in examplewindow.cc 2011-07-19. Fixed by bug 657751 2011-09-02. Chapter 9. The TreeView widget book/treeview/editable_cells/example: Lots of messages are printed when the window is closed. Examples: (example:2354): GLib-GObject-WARNING **: invalid (NULL) pointer instance (example:2354): GLib-GObject-CRITICAL **: g_signal_handler_block: assertion `G_TYPE_CHECK_INSTANCE (instance)' failed (example:2354): Gtk-CRITICAL **: gtk_cell_area_context_reset: assertion `GTK_IS_CELL_AREA_CONTEXT (context)' failed book/treeview/popup/example: The popup menu is extremely small, much too small to show any text. Chapter 16. Dialogs book/dialogs/fontchooserdialog/example: When the font chooser dialog is shown for the first time, the following warning is printed, perhaps because no font size is specified: (example:2441): Pango-WARNING **: failed to choose a font, expect ugly output. engine-type='PangoRenderFc', script='common' As mentioned in examplewindow.cc: "This is not actually a FontChooserDialog example." It's rather an example of FontButton. gtkmm-tutorial-in.xml still talks about FontSelectionDialog which has been replaced by FontChooserDialog. book/dialogs/colorselectiondialog/example is really an example of ColorButton. Chapter 17. The Drawing Area Widget GtkDrawingArea::on_expose_event() has been replaced by GtkDrawingArea::on_draw() in gtkmm3. This has been changed in the example programs, but not in gtkmm-tutorial-in.xml. In section "Drawing Images", the removed classes Gdk::Bitmap and Gdk::Pixmap are mentioned. book/drawingarea/curve/drawingareacurve: Probably "cr->rectangle(); cr->clip()" shall be removed here, as has been done in the other example programs. Chapter 21. Recently Used Documents book/recent_files/example: "Recent Files Dialog" produces the warning: (example:2369): Gtk-WARNING **: GtkRecentChooserWidget 0x92af890 is mapped but visible=1 child_visible=1 parent GtkBox 0x9218320 mapped=0 This comment in examplewindow.cc deserves investigation: //TODO: Shouldn't this have a default constructor?: //See bug #450032. There are two FIXME comments in gtkmm-tutorial-in.xml, section "Looking up Items in the List of Recent Files". Perhaps they can be fixed. Chapter 22. Plugs and Sockets book/socket/plug and book/socket/socket: When the window is closed this warning is printed: (plug:2424): Gtk-WARNING **: gtkmm__GtkLabel 0x992d848 is mapped but visible=1 child_visible=1 parent gtkmm__GtkPlug 0x9923000 mapped=0 Chapter 24. Memory management The removed classes Gdk::Bitmap and Gdk::Pixmap are mentioned. Shall be replaced by Gdk::Pixbuf. Chapter 25. Glade and Gtk::Builder book/builder/derived/example: The file basic.ui is the same as in book/builder/basic. Appendix A. The RefPtr smartpointer The removed classes Gdk::Bitmap and Gdk::Pixmap are mentioned. Shall be replaced by Gdk::Pixbuf. Appendix F. Working with gtkmm's Source Code moduleset = 'gnome-2.30' is wrong. Shall be moduleset = 'gnome-suites-core-deps-3.2'. The default installation folder is said to be /opt/gnome2. Is /opt/gnome. Appendix G. Wrapping C Libraries with gmmproc Section "The .hg and .ccg files": GtkObject is mentioned. That class has been removed. Gdk::Region is mentioned. That class has been removed. Gtk::StockItem can be mentioned as an example of _CLASS_OPAQUE_COPYABLE. dialog.hg does not contain any _MEMBER_GET_PTR. pangomm/pango/src/item.hg contains _MEMBER_GET_PTR, but they are commented out. progress.hg has been removed. pangomm/pango/src/layoutline.hg contains _MEMBER_GET_GOBJECT. _WRAP_VFUNC is not described. Is the omission deliberate? Build date and platform: Ubuntu 11.04, source code of gtkmm, gtk+, etc. built with jhbuild on 2011-09-05 (some packages were built somewhat earlier) I plan to make some patches. If someone wants to contribute by making patches for some of the issues, I would not mind.
Created attachment 195721 [details] [review] patch: Range Widgets example: Fix size and orientation of widgets. Here's the first patch. It fixes the Range Widgets example in Chapter 6. Is it ok if I push patches as simple as this one without waiting for confirmation? I think that some patches (but not all) will be this simple. Is one patch per chapter a reasonable rule of thumb? (With exceptions, like removing all mentioning of Gdk::Bitmap and Gdk::Pixmap in one patch.) Or only one example program in each patch?
(In reply to comment #1) > Created an attachment (id=195721) [details] [review] > patch: Range Widgets example: Fix size and orientation of widgets. > > Here's the first patch. It fixes the Range Widgets example in Chapter 6. Why do we need this? m_VScale.set_size_request(40, 100); I don't think it's generally a good idea to hard-code sizes of child widgets. Thanks for catching some stuff that I must have left over when removing HBox and VBox. > Is it ok if I push patches as simple as this one without waiting for > confirmation? I think that some patches (but not all) will be this simple. Generally, yes, please. I can check them afterwards, particularly if there is explanation in the ChangeLog. > Is one patch per chapter a reasonable rule of thumb? (With exceptions, like > removing all mentioning of Gdk::Bitmap and Gdk::Pixmap in one patch.) Yes, you have the right idea.
Created attachment 195813 [details] [review] patch: Range Widgets example: Fix size and orientation of widgets. Here's the second version of the patch that fixes the Range Widgets example in Chapter 6. I have pushed this patch. I have removed both the new set_size_request() that I added in comment 1, and a set_size_request() that existed before. I also made some other changes, otherwise the vertical scale widget would have been too short.
Created attachment 195845 [details] [review] patch: Label and ProgressBar examples: Fix text. Fix orientation of a Box. This patch fixes the Label and ProgressBar examples in Chapter 7. A VBox in the Label example had become horizontal. I hadn't noticed that when I filed this bug. Now it's vertical again. I have pushed this patch.
Both look fine. Thanks.
Created attachment 196211 [details] [review] TreeView Popup example: Make sure the menu items are shown. I have pushed this patch. It fixes the TreeView Popup example in Chapter 9. Now the menu items are shown when the menu pops up. Widget::show() or Widget::show_all() must be called. The TreeView Editable Cells example is more difficult. I don't think the bug is in the example code. Rather it's in Gtk::TreeViewColumn or GtkTreeViewColumn. An excerpt from treeview/editable_cells/examplewindow.h: class ExampleWindow : public Gtk::Window { ...... Gtk::TreeView m_TreeView; ..... Gtk::TreeView::Column m_treeviewcolumn_validated; Gtk::CellRendererText m_cellrenderer_validated; When the ExampleWindow is destructed, m_treeviewcolumn_validated is destructed before m_TreeView where it has been inserted. That shouldn't be a problem. It's done all the time with widgets: A widget in a container is destructed before the container. Then gtk_widget_dispose() removes the widget from the container. But gtk_tree_view_column_dispose() does not remove the tree view column from the tree view, although the tree view column has a pointer to the tree view, where it's inserted. gtk_tree_view_column_dispose() unrefs some stuff that the tree view column has used (such as a GtkCellArea), and clears the corresponding pointers, making the tree view column more or less unusable. When m_TreeView is destructed, the C object that m_treeviewcolumn_validated wrapped still exists and is one of the columns in m_TreeView, but it's in a state that makes it unusable. That's why lots of warnings and critical messages are printed when m_TreeView is being destructed. Gtk::TreeViewColumn is one of the few classes that are still derived from Gtk::Object. GtkTreeViewColumn is derived from GInitiallyUnowned. The destructor of Gtk::TreeViewColumn calls g_object_run_dispose() (via some methods in Gtk::Object). That's what makes the GtkTreeViewColumn object unusable. Who is to blame? 1. Shall gtk_tree_view_column_dispose() remove the tree view column from the tree view before it makes the tree view column unusable? 2. Is the wrapping of GtkTreeViewColumn wrong? Should Gtk::TreeViewColumn be derived from Glib::Object instead of Gtk::Object, thus avoiding the call to g_object_run_dispose()? This problem deserves a separate bug report, but I don't know if it shall be a gtk+ bug or a gtkmm bug. I have tested 1. changing gtk_tree_view_column_dispose(). It works. 2. adding code to the destructor Gtk::TreeViewColumn::~TreeViewColumn() instead of adding it to gtk_tree_view_column_dispose(). It also works. If the right cure is to change the base class of Gtk::TreeViewColumn, I suppose that can't be done until gtkmm 4.
Created attachment 196386 [details] [review] patch: Dialogs chapter and examples: Finish replacement of FontSelectionDialog This patch enhances the ColorSelectionDialog example and the FontChooserDialog example in Chapter 16. It also contains some changes to Chapter 16 in gtkmm-tutorial-in.xml. I will not push this patch immediately. I'll give people a chance to comment on it first. The warning Pango-WARNING **: failed to choose a font, expect ugly output. ... from the FontChooserDialog example remains. It turned out to be caused by Pango not liking the Ubuntu font in my Ubuntu system. I will probably not dig further into that problem. Anyway it has nothing to do with gtkmm. I have added a 'Choose Color' button to the ColorSelectionDialog example and a 'Choose Font' button to the FontChooserDialog example, showing how those dialogs can be opened without using ColorButton and FontButton. In gtkmm-tutorial-in.xml i have replaced get_vbox() by get_content_area() and replaced FontSelectionDialog by FontChooserDialog where it had not been done previously. In the ColorSelectionDialog example it took me several hours to understand why the DrawingArea was black instead of blue when the window was opened. And the answer is terribly simple: Add 'm_Color.set_alpha(1.0);' The default constructor of Gdk::RGBA creates a transparent white color.
(In reply to comment #7) > The default constructor of Gdk::RGBA creates a transparent white color. Shall be "transparent black color". But as long as m_Color is transparent the DrawingArea will remain black, whatever the color of m_Color.
I am not sure if a new bug should be reported, or I should add to this one - apologies if I made the wrong decision! Figure 6.1 in the tutorial on range widgets has two spin buttons (labelled "Scale Value Position" and "Scale Update Policy") which are not set up in the code, although the menu choices for one of them is. I suggest this image is corrected!
(In reply to comment #9) > I am not sure if a new bug should be reported, or I should add to this one It's OK to report the erroneous figure here. Figure 6.1 is not the only screenshot which is out of date. The screenshots have not been updated for gtkmm3. Hopefully it will be done soon.
Yes. I'd do it but some examples are not working correctly so I decided to wait until this bug is resolved (ie. the examples run correctly and then I can take accurate screenshots).
Review of attachment 196386 [details] [review]: Apart from those minor indentation issues, it looks fine. ::: examples/book/dialogs/colorselectiondialog/examplewindow.cc @@ -31,3 +31,3 @@ - m_VBox.pack_start(m_Button, Gtk::PACK_SHRINK); - m_Button.signal_color_set().connect(sigc::mem_fun(*this, - &ExampleWindow::on_button_color_set) ); + m_VBox.pack_start(m_ColorButton, Gtk::PACK_SHRINK); + m_ColorButton.signal_color_set().connect(sigc::mem_fun(*this, + &ExampleWindow::on_color_button_color_set) ); Please use 2 spaces for indentation. @@ -31,3 +31,7 @@ - m_VBox.pack_start(m_Button, Gtk::PACK_SHRINK); - m_Button.signal_color_set().connect(sigc::mem_fun(*this, - &ExampleWindow::on_button_color_set) ); + m_VBox.pack_start(m_ColorButton, Gtk::PACK_SHRINK); + m_ColorButton.signal_color_set().connect(sigc::mem_fun(*this, + &ExampleWindow::on_color_button_color_set) ); ... 4 more ... Please use 2 spaces for indentation. ::: examples/book/dialogs/fontchooserdialog/examplewindow.cc @@ -29,3 +29,7 @@ - add(m_Button); - m_Button.signal_font_set().connect(sigc::mem_fun(*this, - &ExampleWindow::on_button_font_set) ); + add(m_ButtonBox); + + m_ButtonBox.pack_start(m_FontButton); ... 4 more ... Please use 2 spaces for indentation. @@ -33,0 +37,3 @@ + m_ButtonBox.pack_start(m_Button_Dialog); + m_Button_Dialog.signal_clicked().connect(sigc::mem_fun(*this, + &ExampleWindow::on_button_dialog_clicked) ); Please use 2 spaces for indentation.
> The default constructor of Gdk::RGBA creates a transparent white color. Is that different to the C API?
(In reply to comment #11) > Yes. I'd do it but some examples are not working correctly so I decided to > wait until this bug is resolved (ie. the examples run correctly and then I can > take accurate screenshots). I guess some automated way to do this would be nice.
I've pushed the Dialogs chapter patch in comment 7, with changed indentations as suggested in comment 12. And I replaced FontChooser::[set|get]_font_name() by [set|get]_font(), otherwise the font chooser dialog does not compile today, although it did last week. http://git.gnome.org/browse/gtkmm-documentation/commit/?id=062755c4f8c912a4084867dbf9788497baac483a (In reply to comment #13) The last sentence in comment 7 was not really meant as a criticism of RGBA's constructor. The C struct GdkRGBA is just a plain struct. There is no constructor (no gdk_rgba_new()). If it's declared as a static variable without explicit intializer, it will be initialized the same way as Gdk::RGBA, i.e. as transparent black.
Created attachment 196975 [details] [review] patch: Drawing Area Widget chapter: Replace on_expose_event() by on_draw(). This patch fixes most of the problems in Chapter 17. The exception is the Drawing Images section, which I have not changed yet. I will make another patch where I change all text that discusses Gdk::Bitmap and Gdk::Pixmap in this and other chapters. I will not push this patch immediately. I'll give people a chance to comment on it first. (In reply to comment #15) > I replaced FontChooser::[set|get]_font_name() by [set|get]_font() This sentence is badly worded. Hope no one misunderstands. Of course I changed fontchooserdialog/examplewindow.cc, and not fontchooser.hg.
Created attachment 197257 [details] [review] patch: Replace Bitmap and Pixmap by Pixbuf. This patch replaces all occurrences of Gdk::Bitmap and Pixmap by Pixbuf (except in the "Changes in gtkmm 3" chapter). The Drawing Images section in Chapter 17 has been changed quite a bit. Many removed functions were mentioned there. Comments in gtkmm-tutorial-in.xml showed that someone planned to have the two subsections "Drawing Images with Gdk" and "Drawing Images with Cairo". I removed these subsection headings, as I got the impression that such a division is not useful now. I also added a new example that shows how to draw a png file in a DrawingArea. A question concerning the copyright comment in the new source code files: This comment ends with the address of the Free Software Foundation. When I looked in other source code files I saw at least three different addresses. The one I chose is the one at http://www.gnu.org/licenses/gpl-2.0.html. GPL v3 mentions a web address (http://www.gnu.org/licenses/) instead of a paper mail address. Much better, but perhaps it's illegal to use in connection with GPL v2? Does anyone know? Is it important? I have filed two GTK+ bugs: Bug 659672 for the critical messages from book/treeview/editable_cells/example mentioned in comment 6. Let's see if it's accepted as a bug in gtk+. Otherwise we'll have to add some code to Gtk::TreeViewColumn's destructor, I think. Bug 659257 for the warning from book/recent_files/example (chapter 21). This is definitely a bug in gtk+. There was a similar warning from book/socket/plug (chapter 22). That bug was fixed 2011-09-03. Someone else had noticed it and fixed it.
(In reply to comment #17) > Created an attachment (id=197257) [details] [review] > patch: Replace Bitmap and Pixmap by Pixbuf. > > This patch replaces all occurrences of Gdk::Bitmap and Pixmap by Pixbuf (except > in the "Changes in gtkmm 3" chapter). The Drawing Images section in Chapter 17 > has been changed quite a bit. It's looks good. Please push. > Many removed functions were mentioned there. > Comments in gtkmm-tutorial-in.xml showed that someone planned to have the two > subsections "Drawing Images with Gdk" and "Drawing Images with Cairo". > I removed these subsection headings, as I got the impression that such a > division is not useful now. Yes, we should not mention drawing with Gdk at all. I think I removed that recently, but maybe I did not, or didn't do it properly. Thanks. > > I also added a new example that shows how to draw a png file in a DrawingArea. > > A question concerning the copyright comment in the new source code files: > This comment ends with the address of the Free Software Foundation. When I > looked in other source code files I saw at least three different addresses. > The one I chose is the one at http://www.gnu.org/licenses/gpl-2.0.html. > GPL v3 mentions a web address (http://www.gnu.org/licenses/) instead of a > paper mail address. Much better, but perhaps it's illegal to use in connection > with GPL v2? Does anyone know? Is it important? In general, please just use whatever is in some existing file, rather than inventing something new. We can, and maybe should update them all. But that's a separate issue. Note that at least some of the files mention GPL2 without mentioning "or later" so we maybe can't go to GLP3. But I'm not very worried about that.
I have pushed the patches in comment 16 and comment 17. Murray, when you removed the Gtk::Application example, you also removed all entries in ChangeLog, added since 2011-08-03. I assume that it's a mistake. I re-inserted those entries.
(In reply to comment #19) > I re-inserted those entries. Thanks.
Created attachment 197735 [details] [review] patch: Update the Recently Used Documents chapter to gtkmm3 status. Yet another patch! This patch updates the description in the Recently Used Documents chapter. It also adds a signal handler in the recent_files example. I deleted these comments from examples/book/recent_files/examplewindow.cc: //TODO: Shouldn't this have a default constructor?: //See bug #450032. //m_refActionGroup->add( Gtk::RecentAction::create() ); The conclusion in bug #450032 is that a RecentAction (like any Action) must have a name, otherwise it's useless. Now it actually has a default constructor, but I think it's wise not to show it in the tutorial.
I've noticed a problem with the links to the source code of the examples in the generated html files. Since <!ENTITY url_examples_branchsuffix ""> in gtkmm-tutorial-in.xml, a typical link looks like <br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/ browse/gtkmm-documentation/tree/examples/book/custom/custom_container/?h=" target="_top">Source Code</a></p> I suppose "?h=" means that the example in the master branch shall be shown, but it's not. Instead of a file list, the text "Invalid branch:" is shown. The master branch is shown if either "?h=" is deleted, or if it's replaced by "?h=master". The links from http://developer.gnome.org/gtkmm-tutorial/stable/ and .../unstable/ suffer from the same problem. It's easy to fix by changing to <!ENTITY url_examples_branchsuffix "master"> in gtkmm-tutorial-in.xml. Shall I do that? Is it the right way to fix this problem? Or is it a bug at git.gnome.org? Shall it understand "?h="? Or shall the Perl script insert_example_code.pl refrain from adding "?h=&url_examples_branchsuffix;" when url_examples_branchsuffix is empty?
(In reply to comment #22) > It's easy to fix by changing to > <!ENTITY url_examples_branchsuffix "master"> > in gtkmm-tutorial-in.xml. Shall I do that? Yes, please. I guess that git.gnome.org changed its "API".
Created attachment 198198 [details] [review] patch: Gtk::Builder examples: Update the Glade files. The Glade files have been updated with Glade 3.8.0. (That's not the latest version, it's the version that happened to be installed on my PC.) Those files have been renamed to basic.glade and derived.glade. The label texts have been updated, mentioning Glade and Gtk::Builder instead of libglademm. The refcounting of objects received from a Gtk::Builder are confusing. Gtk::Builder::get_object() returns a RefPtr with the refcount increased. Gtk::Builder::get_widget() returns a Widget* with the refcount unconditionally increased. Gtk::Builder::get_widget_derived() returns a Widget* with the refcount increased only if a new C++ wrapper was created for the GtkWidget. Gtk::UIManager::get_widget() returns a Widget* without increasing the refcount. I doubt that all of this is correct, but it's beyond the scope of this bug report to sort out what's correct. I have pushed the change <!ENTITY url_examples_branchsuffix "master"> as requested in comment 23. http://git.gnome.org/browse/gtkmm-documentation/commit/?id=925cdc8c5e30a83998090b3dbe43b29d00a88f88 In a few days I will push the patch in comment 21 (recently used documents) and the patch in this comment, unless someone objects.
(In reply to comment #24) > Created an attachment (id=198198) [details] [review] > patch: Gtk::Builder examples: Update the Glade files. > > The Glade files have been updated with Glade 3.8.0. (That's not the latest > version, it's the version that happened to be installed on my PC.) Those files > have been renamed to basic.glade and derived.glade. The label texts have been > updated, mentioning Glade and Gtk::Builder instead of libglademm. > > The refcounting of objects received from a Gtk::Builder are confusing. > > Gtk::Builder::get_object() returns a RefPtr with the refcount increased. > Gtk::Builder::get_widget() returns a Widget* with the refcount unconditionally > increased. > Gtk::Builder::get_widget_derived() returns a Widget* with the refcount > increased only if a new C++ wrapper was created for the GtkWidget. > Gtk::UIManager::get_widget() returns a Widget* without increasing the refcount. It doesn't seem particular odd to me. The inconsistency is probably in the C API, and we are probably just making it consistent.
Thanks. Please push everything.
I have pushed the patch in comment 21, and a slightly extended version of the patch in comment 24, where examples/Makefile.am is updated with the new names of the renamed Glade files. (In reply to comment #11) > I'd do it but some examples are not working correctly so I decided to wait > until this bug is resolved (ie. the examples run correctly and then I can > take accurate screenshots). What remains for me now is to update two appendices that don't contain screenshots. José, if you still plan to update all screenshots, you don't need to wait for more updates in this bug report. Two example programs produce unwanted console messages, but that does not affect the screenshots. It has been reported in gtk+ bugs (see comment 17).
> (In reply to comment #11) > What remains for me now is to update two appendices that don't contain > screenshots. José, if you still plan to update all screenshots, you don't need > to wait for more updates in this bug report. Two example programs produce > unwanted console messages, but that does not affect the screenshots. It has > been reported in gtk+ bugs (see comment 17). Thanks. I'll be trying to find an automated solution, if possible, and filing a separate bug with a patch.
Created attachment 198539 [details] [review] patch: Update Appendix F and G to gtkmm3 status. This is probably the last patch in this bug report. In Appendix G (Wrapping C Libraries with gmmproc), section "The .hg and .ccg files" I have added descriptions of _WRAP_VFUNC and _IMPLEMENTS_INTERFACE. I have made quite a few changes all over appendix G, and some in appendix F. It would be fine if someone finds the time to check at least some of my changes and additions. E.g. the difference between _CLASS_GOBJECT and _CLASS_GTKOBJECT is more difficult to understand now that there is no GtkObject to refer to.
(In reply to comment #29) > Created an attachment (id=198539) [details] [review] > patch: Update Appendix F and G to gtkmm3 status. That all looks fine. Please push. > E.g. the difference between _CLASS_GOBJECT and _CLASS_GTKOBJECT is more difficult to understand now that there is no GtkObject to refer to. Yes, that needs a clearer statement. Let's keep this bug open until I have done that.
I have pushed the patch in comment 29, with one addition: I added a paragraph at the end of the description of _WRAP_VFUNC. If you find it more confusing than helpful, please change it or remove it when you improve the description of _CLASS_GOBJECT and _CLASS_GTKOBJECT.
I have added a little text in the _CLASS_GTKOBJECT section. So, is there anything left to do for this bug?
(In reply to comment #32) > So, is there anything left to do for this bug? No, now this bug is fixed.