[gtkmm-documentation] Add the ListModel example

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 61f38f4cd535efeea0f41e8faad0dd00a3f983a6
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Thu Jun 30 09:59:29 2016 +0200

    Add the ListModel example
    
    * examples/MakeFile.am: Add book/listmodel.
    * examples/book/listmodel/main.cc:
    * examples/book/listmodel/examplewindow.[h|cc]:
    * examples/book/listmodel/myobject.[h|cc]: New files.
    This example is similar to gtk+/tests/listmodel.c. Bug #755149

 examples/Makefile.am                     |    8 ++
 examples/book/listmodel/examplewindow.cc |  137 ++++++++++++++++++++++++++++++
 examples/book/listmodel/examplewindow.h  |   49 +++++++++++
 examples/book/listmodel/main.cc          |   27 ++++++
 examples/book/listmodel/myobject.cc      |   46 ++++++++++
 examples/book/listmodel/myobject.h       |   40 +++++++++
 6 files changed, 307 insertions(+), 0 deletions(-)
---
diff --git a/examples/Makefile.am b/examples/Makefile.am
index 2f839e3..9683d81 100644
--- a/examples/Makefile.am
+++ b/examples/Makefile.am
@@ -77,6 +77,7 @@ check_PROGRAMS =                                      \
        book/keyboard_events/propagation/example        \
        book/label/example                              \
        book/listbox/example                            \
+       book/listmodel/example                  \
        book/menus/main_menu/main_menu                  \
        book/menus/popup/popup                          \
        book/menus_and_toolbars/example                 \
@@ -500,6 +501,13 @@ book_listbox_example_SOURCES =             \
        book/listbox/examplerow.h       \
        book/listbox/main.cc
 
+book_listmodel_example_SOURCES =               \
+       book/listmodel/examplewindow.cc \
+       book/listmodel/examplewindow.h  \
+       book/listmodel/myobject.cc      \
+       book/listmodel/myobject.h       \
+       book/listmodel/main.cc
+
 book_menus_main_menu_main_menu_SOURCES =       \
        book/menus/main_menu/exampleapplication.cc      \
        book/menus/main_menu/exampleapplication.h       \
diff --git a/examples/book/listmodel/examplewindow.cc b/examples/book/listmodel/examplewindow.cc
new file mode 100644
index 0000000..ac6b747
--- /dev/null
+++ b/examples/book/listmodel/examplewindow.cc
@@ -0,0 +1,137 @@
+/* gtkmm example Copyright (C) 2016 gtkmm development team
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "examplewindow.h"
+#include <iostream>
+#include <ctime>
+#include <cstdlib> // std::rand()
+#include <algorithm> // std::max()
+
+ExampleWindow::ExampleWindow()
+:
+m_store(Gio::ListStore<MyObject>::create()),
+m_button_add_some("_Add some", true),
+m_button_remove_some("_Remove some", true),
+m_button_quit("_Quit", true)
+{
+  set_title("ListBox and FlowBox with ListModel");
+  set_border_width(5);
+  set_default_size(300, 300);
+
+  for (int i = 0; i < 20; ++i)
+  {
+    const Glib::ustring label = Glib::ustring::format("Item ", i);
+    m_store->append(MyObject::create(i, label));
+  }
+
+  // Use current time as seed for random number generator.
+  std::srand(std::time(nullptr));
+
+  add(m_grid);
+
+  // Select bind_model() or bind_list_store() randomly.
+  const bool use_bind_model = std::rand() & 2;
+  std::cout << "Using bind_" << (use_bind_model ? "model" : "list_store") << std::endl;
+
+  // A ListBox to the left.
+  m_scrolled_window_list_box.set_policy(Gtk::POLICY_AUTOMATIC, Gtk::POLICY_AUTOMATIC);
+  m_scrolled_window_list_box.set_hexpand(true);
+  m_scrolled_window_list_box.set_vexpand(true);
+  m_grid.attach(m_scrolled_window_list_box, 0, 0, 1 ,1);
+  m_scrolled_window_list_box.add(m_list_box);
+  if (use_bind_model)
+    m_list_box.bind_model(m_store, sigc::ptr_fun(&ExampleWindow::on_create_widget1));
+  else
+    m_list_box.bind_list_store(m_store, sigc::ptr_fun(&ExampleWindow::on_create_widget2));
+
+  // A FlowBox to the right.
+  m_scrolled_window_flow_box.set_policy(Gtk::POLICY_AUTOMATIC, Gtk::POLICY_AUTOMATIC);
+  m_scrolled_window_flow_box.set_hexpand(true);
+  m_scrolled_window_flow_box.set_vexpand(true);
+  m_grid.attach(m_scrolled_window_flow_box, 1, 0, 1 ,1);
+  m_scrolled_window_flow_box.add(m_flow_box);
+  if (use_bind_model)
+    m_flow_box.bind_model(m_store, sigc::ptr_fun(&ExampleWindow::on_create_widget1));
+  else
+    m_flow_box.bind_list_store(m_store, sigc::ptr_fun(&ExampleWindow::on_create_widget2));
+
+  // Buttons at the bottom.
+  m_button_add_some.signal_clicked().connect(sigc::mem_fun(*this, &ExampleWindow::on_add_some));
+  m_grid.attach(m_button_add_some, 0, 1, 2, 1);
+  m_button_remove_some.signal_clicked().connect(sigc::mem_fun(*this, &ExampleWindow::on_remove_some));
+  m_grid.attach(m_button_remove_some, 0, 2, 2, 1);
+  m_button_quit.signal_clicked().connect(sigc::mem_fun(*this, &ExampleWindow::on_quit));
+  m_grid.attach(m_button_quit, 0, 3, 2, 1);
+
+  show_all_children();
+}
+
+// static
+Gtk::Widget* ExampleWindow::on_create_widget1(const Glib::RefPtr<Glib::Object>& item)
+{
+  auto obj = Glib::RefPtr<MyObject>::cast_dynamic(item);
+  if (!obj)
+  {
+    std::cout << "on_create_widget1(): item is not a MyObject" << std::endl;
+    return nullptr;
+  }
+  auto label = Gtk::manage(new Gtk::Label());
+  Glib::Binding::bind_property(obj->property_label(), label->property_label(),
+    Glib::BINDING_SYNC_CREATE);
+  return label;
+}
+
+// static
+Gtk::Widget* ExampleWindow::on_create_widget2(const Glib::RefPtr<MyObject>& item)
+{
+  if (!item)
+  {
+    std::cout << "on_create_widget2(): item is empty" << std::endl;
+    return nullptr;
+  }
+  auto label = Gtk::manage(new Gtk::Label());
+  Glib::Binding::bind_property(item->property_label(), label->property_label(),
+    Glib::BINDING_SYNC_CREATE);
+  return label;
+}
+
+void ExampleWindow::on_add_some()
+{
+  for (int n = 0; n < 10; ++n)
+  {
+    const auto n_items = m_store->get_n_items();
+    const auto i = std::rand() % std::max(2*n_items, 4u);
+    const Glib::ustring label = Glib::ustring::format("Added ", i);
+    m_store->insert_sorted(MyObject::create(i, label),
+      sigc::ptr_fun(&MyObject::compare));
+  }
+}
+
+void ExampleWindow::on_remove_some()
+{
+  for (int n = 0; n < 10; ++n)
+  {
+    const auto n_items = m_store->get_n_items();
+    if (n_items == 0)
+      return;
+    const auto i = std::rand() % n_items;
+    m_store->remove(i);
+  }
+}
+
+void ExampleWindow::on_quit()
+{
+  hide();
+}
diff --git a/examples/book/listmodel/examplewindow.h b/examples/book/listmodel/examplewindow.h
new file mode 100644
index 0000000..1e7305e
--- /dev/null
+++ b/examples/book/listmodel/examplewindow.h
@@ -0,0 +1,49 @@
+/* gtkmm example Copyright (C) 2016 gtkmm development team
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef GTKMM_EXAMPLEWINDOW_H
+#define GTKMM_EXAMPLEWINDOW_H
+
+#include <gtkmm.h>
+#include "myobject.h"
+
+class ExampleWindow : public Gtk::Window
+{
+public:
+  ExampleWindow();
+
+private:
+  // Callback functions.
+  static Gtk::Widget* on_create_widget1(const Glib::RefPtr<Glib::Object>& item);
+  static Gtk::Widget* on_create_widget2(const Glib::RefPtr<MyObject>& item);
+
+  // Signal handlers.
+  void on_add_some();
+  void on_remove_some();
+  void on_quit();
+
+  // Member data.
+  Glib::RefPtr<Gio::ListStore<MyObject>> m_store;
+  Gtk::Grid m_grid;
+  Gtk::ScrolledWindow m_scrolled_window_list_box;
+  Gtk::ScrolledWindow m_scrolled_window_flow_box;
+  Gtk::ListBox m_list_box;
+  Gtk::FlowBox m_flow_box;
+  Gtk::Button m_button_add_some;
+  Gtk::Button m_button_remove_some;
+  Gtk::Button m_button_quit;
+};
+
+#endif // GTKMM_EXAMPLEWINDOW_H
diff --git a/examples/book/listmodel/main.cc b/examples/book/listmodel/main.cc
new file mode 100644
index 0000000..1d3ed65
--- /dev/null
+++ b/examples/book/listmodel/main.cc
@@ -0,0 +1,27 @@
+/* gtkmm example Copyright (C) 2016 gtkmm development team
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "examplewindow.h"
+#include <gtkmm/application.h>
+
+int main (int argc, char* argv[])
+{
+  auto app = Gtk::Application::create(argc, argv, "org.gtkmm.example");
+
+  ExampleWindow window;
+
+  //Shows the window and returns when it is closed.
+  return app->run(window);
+}
diff --git a/examples/book/listmodel/myobject.cc b/examples/book/listmodel/myobject.cc
new file mode 100644
index 0000000..3c28fd7
--- /dev/null
+++ b/examples/book/listmodel/myobject.cc
@@ -0,0 +1,46 @@
+/* gtkmm example Copyright (C) 2016 gtkmm development team
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "myobject.h"
+#include <iostream>
+
+MyObject::MyObject(int id, const Glib::ustring& label)
+:
+Glib::ObjectBase(typeid(MyObject)), // because MyObject contains Glib::Property<>
+m_id(id),
+m_property_label(*this, "label", label)
+{
+}
+
+Glib::RefPtr<MyObject> MyObject::create(int id, const Glib::ustring& label)
+{
+  return Glib::RefPtr<MyObject>(new MyObject(id, label));
+}
+
+Glib::PropertyProxy<Glib::ustring> MyObject::property_label()
+{
+  return m_property_label.get_proxy();
+}
+
+int MyObject::compare(const Glib::RefPtr<const MyObject>& a,
+  const Glib::RefPtr<const MyObject>& b)
+{
+  if (!a || !b)
+  {
+    std::cout << "MyObject::compare(): Empty RefPtr" << std::endl;
+    return 0;
+  }
+  return a->get_id() - b->get_id();
+}
diff --git a/examples/book/listmodel/myobject.h b/examples/book/listmodel/myobject.h
new file mode 100644
index 0000000..5393f9b
--- /dev/null
+++ b/examples/book/listmodel/myobject.h
@@ -0,0 +1,40 @@
+/* gtkmm example Copyright (C) 2016 gtkmm development team
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef GTKMM_EXAMPLE_MYOBJECT_H
+#define GTKMM_EXAMPLE_MYOBJECT_H
+
+#include <glibmm.h>
+
+class MyObject : public Glib::Object
+{
+protected:
+  MyObject(int id, const Glib::ustring& label);
+
+public:
+  static Glib::RefPtr<MyObject> create(int id, const Glib::ustring& label);
+
+  int get_id() const { return m_id; }
+  Glib::PropertyProxy<Glib::ustring> property_label();
+
+  static int compare(const Glib::RefPtr<const MyObject>& a,
+    const Glib::RefPtr<const MyObject>& b);
+
+private:
+  int m_id;
+  Glib::Property<Glib::ustring> m_property_label;
+};
+
+#endif //GTKMM_EXAMPLE_MYOBJECT_H