[gtkmm-documentation] Custom widget example: Use Gtk::StyleProperty

[Kjell Ahlstedt <kjellahl src gnome org>]

commit a1e70cf5d4b6834eb1a5c6703fd7ba7ca29deccb
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Mon Dec 22 16:42:12 2014 +0100

    Custom widget example: Use Gtk::StyleProperty
    
    * docs/tutorial/C/index-in.docbook: Add the "Custom Style Properties"
    subsection. In the "Contributing" chapter, update the filename
    gtkmm-tutorial-in.xml to index-in.docbook.
    * examples/book/custom/custom_widget/mywidget.[cc|h]: Use Gtk::StyleProperty
    and Gtk::CssProvider::signal_parsing_error().

 docs/tutorial/C/index-in.docbook               |   19 ++++++++-
 examples/book/custom/custom_widget/mywidget.cc |   51 +++++++++++++++---------
 examples/book/custom/custom_widget/mywidget.h  |    9 +++-
 3 files changed, 56 insertions(+), 23 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 89b5aec..775f9fe 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -7205,6 +7205,23 @@ instance, you cannot use the copyright sign (&copy;).
       <methodname>Gtk::Widget::set_realized()</methodname> and
       <methodname>Gtk::Widget::set_window()</methodname> from there.</para>
 
+<sect2 id="custom-style-properties">
+<title>Custom Style Properties</title>
+
+<para>You can add style properties to your widget class, whether it's derived directly
+from <classname>Gtk::Widget</classname> or from another widget class. The values of
+the style properties can be read from a CSS (Cascading Style Sheets) file. The users
+of your widget, or the users of an application program with your widget, can then
+modify the style of your widget without modifying the source code.
+Useful classes are <classname>Gtk::StyleProperty</classname> and <classname>Gtk::CssProvider</classname>.
+With <methodname>Gtk::Widget::get_style_property()</methodname> you can read the values
+of both your own style properties and those of your widget's base class. Note that style
+properties are not wrapped in &gtkmm;. See <application>GTK+</application>'s
+documentation for lists of existing style properties.
+The following example shows a simple use of a custom style property.
+</para>
+</sect2>
+
 <sect2 id="custom-widget-example"><title>Example</title>
 
 <para>This example implements a widget which draws a Penrose triangle.</para>
@@ -7597,7 +7614,7 @@ consider contributing to this document.
 </para>
 <para>
 Ideally, we would like you to <ulink url="http://www.gtkmm.org/bugs.shtml";>provide a patch</ulink> to the
-<filename>docs/tutorial/C/gtkmm-tutorial-in.xml</filename> file. This file is currently
+<filename>docs/tutorial/C/index-in.docbook</filename> file. This file is currently
 in the <literal>gtkmm-documentation</literal> module in GNOME git.
 </para>
 
diff --git a/examples/book/custom/custom_widget/mywidget.cc b/examples/book/custom/custom_widget/mywidget.cc
index 57a0fe4..01c78d5 100644
--- a/examples/book/custom/custom_widget/mywidget.cc
+++ b/examples/book/custom/custom_widget/mywidget.cc
@@ -1,5 +1,3 @@
-//$Id: mywidget.cc 836 2007-05-09 03:02:38Z jjongsma $ -*- c++ -*-
-
 /* gtkmm example Copyright (C) 2004 gtkmm development team
  *
  * This program is free software; you can redistribute it and/or modify
@@ -22,11 +20,17 @@
 //#include <gtk/gtkwidget.h> //For GTK_IS_WIDGET()
 #include <cstring>
 
+// The MyWidget class uses API which was added in gtkmm 3.15.3 (Gtk::CssProviderError,
+// Gtk::CssProvider::signal_parsing_error() and Gtk::CssSection) and in gtkmm 3.15.2
+// (Gtk::StyleProperty).
 
 MyWidget::MyWidget() :
   //The GType name will actually be gtkmm__CustomObject_mywidget
   Glib::ObjectBase("mywidget"),
   Gtk::Widget(),
+  //Install a style property so that an aspect of this widget may be themed
+  //via a CSS style sheet file:
+  m_scale_prop(*this, "example_scale", 500),
   m_scale(1000)
 {
   set_has_window(true);
@@ -37,30 +41,26 @@ MyWidget::MyWidget() :
   //This shows that the GType still derives from GtkWidget:
   //std::cout << "Gtype is a GtkWidget?:" << GTK_IS_WIDGET(gobj()) << std::endl;
 
-  //Install a style so that an aspect of this widget may be themed via a CSS
-  //style sheet file:
-  gtk_widget_class_install_style_property(GTK_WIDGET_CLASS(
-              G_OBJECT_GET_CLASS(gobj())),
-      g_param_spec_int("example_scale",
-        "Scale of Example Drawing",
-        "The scale to use when drawing. This is just a silly example.",
-        G_MININT,
-        G_MAXINT,
-        500,
-        G_PARAM_READABLE) );
-
-  m_refStyleProvider = Gtk::CssProvider::create();
+  m_refCssProvider = Gtk::CssProvider::create();
   Glib::RefPtr<Gtk::StyleContext> refStyleContext = get_style_context();
-  refStyleContext->add_provider(m_refStyleProvider, 
+  refStyleContext->add_provider(m_refCssProvider,
     GTK_STYLE_PROVIDER_PRIORITY_APPLICATION);
+  m_refCssProvider->signal_parsing_error().connect(
+    sigc::mem_fun(*this, &MyWidget::on_parsing_error));
     
   try
   {
-    m_refStyleProvider->load_from_path("custom_gtk.css");
+    m_refCssProvider->load_from_path("custom_gtk.css");
+  }
+  catch(const Gtk::CssProviderError& ex)
+  {
+    std::cerr << "CssProviderError, Gtk::CssProvider::load_from_path() failed: "
+              << ex.what() << std::endl;
   }
   catch(const Glib::Error& ex)
   {
-    std::cerr << "Gtk::CssProvider::load_from_path() failed: " << ex.what() << std::endl;
+    std::cerr << "Error, Gtk::CssProvider::load_from_path() failed: "
+              << ex.what() << std::endl;
   }
 }
 
@@ -140,7 +140,7 @@ void MyWidget::on_realize()
   set_realized();
 
   //Get the themed style from the CSS file:
-  get_style_property("example_scale", m_scale);
+  m_scale = m_scale_prop.get_value();
   std::cout << "m_scale (example_scale from the theme/css-file) is: "
       << m_scale << std::endl;
 
@@ -217,3 +217,16 @@ bool MyWidget::on_draw(const Cairo::RefPtr<Cairo::Context>& cr)
 
   return true;
 }
+
+void MyWidget::on_parsing_error(const Glib::RefPtr<const Gtk::CssSection>& section, const Glib::Error& error)
+{
+  std::cerr << "on_parsing_error(): " << error.what() << std::endl;
+  if (section)
+  {
+    std::cerr << "  URI = " << section->get_file()->get_uri() << std::endl;
+    std::cerr << "  start_line = " << section->get_start_line()+1
+              << ", end_line = " << section->get_end_line()+1 << std::endl;
+    std::cerr << "  start_position = " << section->get_start_position()
+              << ", end_position = " << section->get_end_position() << std::endl;
+  }
+}
diff --git a/examples/book/custom/custom_widget/mywidget.h b/examples/book/custom/custom_widget/mywidget.h
index ed78dc1..e6f79e8 100644
--- a/examples/book/custom/custom_widget/mywidget.h
+++ b/examples/book/custom/custom_widget/mywidget.h
@@ -1,5 +1,3 @@
-//$Id: mywidget.h 834 2007-05-08 01:09:32Z jjongsma $ -*- c++ -*-
-
 /* gtkmm example Copyright (C) 2004 gtkmm development team
  *
  * This program is free software; you can redistribute it and/or modify
@@ -21,6 +19,7 @@
 
 #include <gtkmm/widget.h>
 #include <gtkmm/cssprovider.h>
+#include <gtkmm/styleproperty.h>
 
 class MyWidget : public Gtk::Widget
 {
@@ -43,8 +42,12 @@ protected:
   virtual void on_unrealize();
   virtual bool on_draw(const Cairo::RefPtr<Cairo::Context>& cr);
 
+  //Signal handler:
+  void on_parsing_error(const Glib::RefPtr<const Gtk::CssSection>& section, const Glib::Error& error);
+
+  Gtk::StyleProperty<int> m_scale_prop;
   Glib::RefPtr<Gdk::Window> m_refGdkWindow;
-  Glib::RefPtr<Gtk::CssProvider> m_refStyleProvider;
+  Glib::RefPtr<Gtk::CssProvider> m_refCssProvider;
 
   int m_scale;
 };