[gtkmm-documentation] Started a ToolPalette chapter.

[Murray Cumming <murrayc src gnome org>]

commit c270b074f6664c92a1af0e2c2c6738e1d3c34ef2
Author: Murray Cumming <murrayc murrayc com>
Date:   Sat Jan 16 14:11:34 2010 +0100

    Started a ToolPalette chapter.
    
    * docs/tutorial/C/gtkmm-tutorial-in.xml: Add the beginnings of a ToolPallette
    chapter.
    * examples/book/toolpalette/examplewindow.cc: Use the latest gtkmm API.

 ChangeLog                                  |    8 ++++
 docs/tutorial/C/gtkmm-tutorial-in.xml      |   51 +++++++++++++++++++++++++++-
 examples/book/toolpalette/examplewindow.cc |   20 +++++-----
 3 files changed, 68 insertions(+), 11 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 27dfb4f..2c86af7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2010-01-16  Murray Cumming  <murrayc murrayc com>
+
+  Started a ToolPalette chapter.
+  
+	* docs/tutorial/C/gtkmm-tutorial-in.xml: Add the beginnings of a ToolPallette 
+	chapter.
+	* examples/book/toolpalette/examplewindow.cc: Use the latest gtkmm API.
+
 2009-12-30  Murray Cumming  <murrayc murrayc com>
 
 	Do not use deprecated API.
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index d8e0507..84990a6 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -3895,8 +3895,57 @@ signal, which you will need to handle anyway. For instance:
 
 </chapter>
 
+<chapter id="chapter-toolpalette">
+<title>ToolPalette</title>
+
+<para>A <classname>ToolPalette</classname> is similar to a <classname>Toolbar</classname> but can contain a grid of items, categorized into groups. The user may hide or expand each group. As in a toolbar, the items may be displayed as only icons, as only text, or as icons with text.
+</para>
+<para>The <classname>ToolPalette</classname>'s items might be dragged or simply activated. For instance, the user might drag objects to a canvas to create new items there. Or the user might click an item to activate a certain brush size in a drawing application.</para>
+<para><classname>ToolItemGroup</classname>s should be added to the tool pallete via the base class's <function>Gtk::Container::add()</function> method, for instance like so:
+</para>
+<para>
+<programlisting>
+Gtk::ToolItemGroup* group_brushes = 
+  Gtk::manage(new Gtk::ToolItemGroup("Brushes"));
+m_ToolPalette.add(*group_brushes);
+</programlisting>
+</para>
+<para>
+<classname>Gtk::ToolItem</classname>s can then be added to the group. For instance, like so:
+</para>
+<para>
+<programlisting>
+Gtk::ToolButton* button = Gtk::manage(new Gtk::ToolButton(icon, "Big"));
+button->set_tooltip_text("Big Brush);
+group_brushes->insert(*button);
+</programlisting>
+</para>
+<para>You might then handle the <classname>ToolButton</classname>'s <literal>clicked</literal> signal. Alternatively, you could allow the item to be dragged to another widget, by calling <methodname>Gtk::ToolPalette::add_drag_dest()</methodname> and then using <methodname>Gtk::ToolPalette::get_drag_item()</methodname> in the other widget's <literal>drag_data_received</literal> signal handler.</para>
+
+<para><ulink url="&url_refdocs_base_gtk;ToolPalette.html">ToolPalette Reference</ulink></para>
+<para><ulink url="&url_refdocs_base_gtk;ToolItemGroup.html">ToolItemGroup Reference</ulink></para>
+<para><ulink url="&url_refdocs_base_gtk;ToolItem.html">ToolItem Reference</ulink></para>
+
+
+<sect1 id="toolpalette-example"><title>ToolPalette Example</title>
+
+<para>This example adds a <classname>ToolPalette</classname> and a <classname>DrawingArea</classname> to a window and allows the user to drag icons from the tool palette to the drawing area. The tool palette contains several groups of items. The combo boxes allow the user to change the style and orientation of the tool palette.</para>
+
+<figure id="figure-toolpalette">
+  <title>ToolPalette</title>
+  <screenshot>
+    <graphic format="PNG" fileref="&url_figures_base;toolpalette.png"/>
+  </screenshot>
+</figure>
+
+<para><ulink url="&url_examples_base;toolpalette/">Source Code</ulink></para>
+
+</sect1>
+
+</chapter>
+
 <chapter id="chapter-adjustment">
-<title>Adjustments </title>
+<title>Adjustments</title>
 
 <para>
 &gtkmm; has various widgets that can be visually adjusted using the mouse or
diff --git a/examples/book/toolpalette/examplewindow.cc b/examples/book/toolpalette/examplewindow.cc
index 52e2832..67085cb 100644
--- a/examples/book/toolpalette/examplewindow.cc
+++ b/examples/book/toolpalette/examplewindow.cc
@@ -81,7 +81,7 @@ void ExampleWindow::load_stock_items()
     Gtk::ToolButton* button = Gtk::manage(new Gtk::ToolButton(stockid));
     button->set_tooltip_text(str);
     button->set_is_important();
-    group->insert(*button, -1);
+    group->insert(*button);
 
     Gtk::StockItem stockitem;
     if(!Gtk::StockItem::lookup(stockid, stockitem) || 
@@ -106,7 +106,7 @@ void ExampleWindow::load_toggle_items()
     button->set_group(radio_group);
     button->set_label(label);
    
-    group->insert(*button, -1);
+    group->insert(*button);
   }
 }
 
@@ -133,42 +133,42 @@ void ExampleWindow::load_special_items()
   m_ToolPalette.add(*group);
 
   Gtk::ToolItem* item = create_entry_item ("homogeneous=false");
-  group->insert(*item, -1);
+  group->insert(*item);
   //TODO: Add Gtk::Container::set_child_property().
   gtk_container_child_set (GTK_CONTAINER (group->gobj()), GTK_WIDGET (item->gobj()),
                            "homogeneous", FALSE, NULL);
 
   item = create_entry_item ("homogeneous=FALSE, expand=TRUE");
-  group->insert(*item, -1);
+  group->insert(*item);
   gtk_container_child_set (GTK_CONTAINER (group->gobj()), GTK_WIDGET (item->gobj()),
                            "homogeneous", FALSE, "expand", TRUE,
                            NULL);
 
   item = create_entry_item ("homogeneous=FALSE, expand=TRUE, fill=FALSE");
-  group->insert(*item, -1);
+  group->insert(*item);
   gtk_container_child_set (GTK_CONTAINER (group->gobj()), GTK_WIDGET (item->gobj()),
                            "homogeneous", FALSE, "expand", TRUE,
                            "fill", FALSE, NULL);
 
   item = create_entry_item ("homogeneous=FALSE, expand=TRUE, new-row=TRUE");
-  group->insert(*item, -1);
+  group->insert(*item);
   gtk_container_child_set (GTK_CONTAINER (group->gobj()), GTK_WIDGET (item->gobj()),
                            "homogeneous", FALSE, "expand", TRUE,
                            "new-row", TRUE, NULL);
 
   item = Gtk::manage(new Gtk::ToolButton(Gtk::Stock::GO_UP));
   item->set_tooltip_text("Show on vertical palettes only");
-  group->insert(*item, -1);
+  group->insert(*item);
   item->set_visible_horizontal(false);
 
   item = Gtk::manage(new Gtk::ToolButton(Gtk::Stock::GO_FORWARD));
   item->set_tooltip_text("Show on horizontal palettes only");
-  group->insert(*item, -1);
+  group->insert(*item);
   item->set_visible_vertical(false);
 
   item = Gtk::manage(new Gtk::ToolButton(Gtk::Stock::FULLSCREEN));
   item->set_tooltip_text("Expanded this item");
-  group->insert(*item, -1);
+  group->insert(*item);
   gtk_container_child_set (GTK_CONTAINER (group->gobj()), GTK_WIDGET (item->gobj()),
                            "homogeneous", FALSE,
                            "expand", TRUE,
@@ -176,7 +176,7 @@ void ExampleWindow::load_special_items()
 
   item = Gtk::manage(new Gtk::ToolButton(Gtk::Stock::HELP));
   item->set_tooltip_text("A regular item");
-  group->insert(*item, -1);
+  group->insert(*item);
 }
 
 ExampleWindow::ExampleWindow()