/usr/share/doc/gtkmm-documentation/tutorial/html/sec-custom-widgets.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Custom Widgets</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Programming with gtkmm 3">
<link rel="up" href="chapter-customwidgets.html" title="Chapter 28. Custom Widgets">
<link rel="prev" href="chapter-customwidgets.html" title="Chapter 28. Custom Widgets">
<link rel="next" href="chapter-recommended-techniques.html" title="Chapter 29. Recommended Techniques">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Custom Widgets</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="chapter-customwidgets.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center">Chapter 28. Custom Widgets</th>
<td width="20%" align="right"> <a accesskey="n" href="chapter-recommended-techniques.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="Custom Widgets">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-custom-widgets"></a>Custom Widgets</h2></div></div></div>
<p>By deriving directly from <code class="classname">Gtk::Widget</code> you can
        do all the drawing for your widget directly, instead of just arranging
        child widgets. For instance, a <code class="classname">Gtk::Label</code> draws
        the text of the label, but does not do this by using other
        widgets.</p>
<p>When deriving from <code class="classname">Gtk::Widget</code>, you should
        override the following virtual methods. The methods marked (optional)
        need not be overridden in all custom widgets. The base class's methods
        may be appropriate.
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p><code class="methodname">get_request_mode_vfunc()</code>: (optional) Return what <code class="literal">Gtk::SizeRequestMode</code> is preferred by the widget.</p></li>
<li class="listitem"><p><code class="methodname">get_preferred_width_vfunc()</code>: Calculate the minimum and natural width of the widget.</p></li>
<li class="listitem"><p><code class="methodname">get_preferred_height_vfunc()</code>: Calculate the minimum and natural height of the widget.</p></li>
<li class="listitem"><p><code class="methodname">get_preferred_width_for_height_vfunc()</code>: Calculate the minimum and natural width of the widget, if it would be given the specified height.</p></li>
<li class="listitem"><p><code class="methodname">get_preferred_height_for_width_vfunc()</code>: Calculate the minimum and natural height of the widget, if it would be given the specified width.</p></li>
<li class="listitem"><p><code class="methodname">on_size_allocate()</code>: Position the widget, given the height and width that it has actually been given.</p></li>
<li class="listitem"><p><code class="methodname">on_realize()</code>: Associate a <code class="classname">Gdk::Window</code> with the widget.</p></li>
<li class="listitem"><p><code class="methodname">on_unrealize()</code>: (optional) Break the association with the <code class="classname">Gdk::Window</code>. </p></li>
<li class="listitem"><p><code class="methodname">on_map()</code>: (optional)</p></li>
<li class="listitem"><p><code class="methodname">on_unmap()</code>: (optional)</p></li>
<li class="listitem"><p><code class="methodname">on_draw()</code>: Draw on the supplied <code class="classname">Cairo::Context</code>.</p></li>
</ul></div>
<p>
    </p>
<p>The first 6 methods in the previous table are also overridden in custom
        containers. They are briefly described in the
        <a class="link" href="chapter-customwidgets.html#sec-custom-containers" title="Custom Containers">Custom Containers</a> section.
    </p>
<p>Most custom widgets need their own <code class="classname">Gdk::Window</code>
      to draw on. Then you can call
      <code class="methodname">Gtk::Widget::set_has_window(true)</code> in your
      constructor. (This is the default value.) If you do not call
      <code class="methodname">set_has_window(false)</code>, you must override
      <code class="methodname">on_realize()</code> and call
      <code class="methodname">Gtk::Widget::set_realized()</code> and
      <code class="methodname">Gtk::Widget::set_window()</code> from there.</p>
<div class="sect2" title="Example">
<div class="titlepage"><div><div><h3 class="title">
<a name="custom-widget-example"></a>Example</h3></div></div></div>
<p>This example implements a widget which draws a Penrose triangle.</p>
<div class="figure">
<a name="figure-custom-widget"></a><p class="title"><b>Figure 28.2. Custom Widget</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/custom_widget.png" alt="Custom Widget"></div></div></div>
</div>
<br class="figure-break"><p><a class="ulink" href="http://git.gnome.org/browse/gtkmm-documentation/tree/examples/book/custom/custom_widget/?h=master" target="_top">Source Code</a></p>
<p>File: <code class="filename">mywidget.h</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#ifndef GTKMM_CUSTOM_WIDGET_MYWIDGET_H
#define GTKMM_CUSTOM_WIDGET_MYWIDGET_H

#include &lt;gtkmm/widget.h&gt;
#include &lt;gtkmm/cssprovider.h&gt;

class MyWidget : public Gtk::Widget
{
public:
  MyWidget();
  virtual ~MyWidget();

protected:

  //Overrides:
  virtual Gtk::SizeRequestMode get_request_mode_vfunc() const;
  virtual void get_preferred_width_vfunc(int&amp; minimum_width, int&amp; natural_width) const;
  virtual void get_preferred_height_for_width_vfunc(int width, int&amp; minimum_height, int&amp; natural_height) const;
  virtual void get_preferred_height_vfunc(int&amp; minimum_height, int&amp; natural_height) const;
  virtual void get_preferred_width_for_height_vfunc(int height, int&amp; minimum_width, int&amp; natural_width) const;
  virtual void on_size_allocate(Gtk::Allocation&amp; allocation);
  virtual void on_map();
  virtual void on_unmap();
  virtual void on_realize();
  virtual void on_unrealize();
  virtual bool on_draw(const Cairo::RefPtr&lt;Cairo::Context&gt;&amp; cr);

  Glib::RefPtr&lt;Gdk::Window&gt; m_refGdkWindow;
  Glib::RefPtr&lt;Gtk::CssProvider&gt; m_refStyleProvider;

  int m_scale;
};

#endif //GTKMM_CUSTOM_WIDGET_MYWIDGET_H
</pre>
<p>File: <code class="filename">examplewindow.h</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include &lt;gtkmm.h&gt;
#include "mywidget.h"

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_button_quit();

  //Child widgets:
  Gtk::Box m_VBox;
  MyWidget m_MyWidget;
  Gtk::ButtonBox m_ButtonBox;
  Gtk::Button m_Button_Quit;
};

#endif //GTKMM_EXAMPLEWINDOW_H
</pre>
<p>File: <code class="filename">mywidget.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "mywidget.h"
#include &lt;gdkmm/general.h&gt;  // for cairo helper functions
#include &lt;iostream&gt;
//#include &lt;gtk/gtkwidget.h&gt; //For GTK_IS_WIDGET()
#include &lt;cstring&gt;


MyWidget::MyWidget() :
  //The GType name will actually be gtkmm__CustomObject_mywidget
  Glib::ObjectBase("mywidget"),
  Gtk::Widget(),
  m_scale(1000)
{
  set_has_window(true);

  //This shows the GType name, which must be used in the CSS file.
  std::cout &lt;&lt; "GType name: " &lt;&lt; G_OBJECT_TYPE_NAME(gobj()) &lt;&lt; std::endl;

  //This shows that the GType still derives from GtkWidget:
  //std::cout &lt;&lt; "Gtype is a GtkWidget?:" &lt;&lt; GTK_IS_WIDGET(gobj()) &lt;&lt; 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();
  Glib::RefPtr&lt;Gtk::StyleContext&gt; refStyleContext = get_style_context();
  refStyleContext-&gt;add_provider(m_refStyleProvider, 
    GTK_STYLE_PROVIDER_PRIORITY_APPLICATION);
    
  try
  {
    m_refStyleProvider-&gt;load_from_path("custom_gtk.css");
  }
  catch(const Glib::Error&amp; ex)
  {
    std::cerr &lt;&lt; "Gtk::CssProvider::load_from_path() failed: " &lt;&lt; ex.what() &lt;&lt; std::endl;
  }
}

MyWidget::~MyWidget()
{
}

Gtk::SizeRequestMode MyWidget::get_request_mode_vfunc() const
{
  //Accept the default value supplied by the base class.
  return Gtk::Widget::get_request_mode_vfunc();
}

//Discover the total amount of minimum space and natural space needed by
//this widget.
//Let's make this simple example widget always need minimum 60 by 50 and
//natural 100 by 70.
void MyWidget::get_preferred_width_vfunc(int&amp; minimum_width, int&amp; natural_width) const
{
  minimum_width = 60;
  natural_width = 100;
}

void MyWidget::get_preferred_height_for_width_vfunc(int /* width */,
   int&amp; minimum_height, int&amp; natural_height) const
{
  minimum_height = 50;
  natural_height = 70;
}

void MyWidget::get_preferred_height_vfunc(int&amp; minimum_height, int&amp; natural_height) const
{
  minimum_height = 50;
  natural_height = 70;
}

void MyWidget::get_preferred_width_for_height_vfunc(int /* height */,
   int&amp; minimum_width, int&amp; natural_width) const
{
  minimum_width = 60;
  natural_width = 100;
}

void MyWidget::on_size_allocate(Gtk::Allocation&amp; allocation)
{
  //Do something with the space that we have actually been given:
  //(We will not be given heights or widths less than we have requested, though
  //we might get more)

  //Use the offered allocation for this container:
  set_allocation(allocation);

  if(m_refGdkWindow)
  {
    m_refGdkWindow-&gt;move_resize( allocation.get_x(), allocation.get_y(),
            allocation.get_width(), allocation.get_height() );
  }
}

void MyWidget::on_map()
{
  //Call base class:
  Gtk::Widget::on_map();
}

void MyWidget::on_unmap()
{
  //Call base class:
  Gtk::Widget::on_unmap();
}

void MyWidget::on_realize()
{
  //Do not call base class Gtk::Widget::on_realize().
  //It's intended only for widgets that set_has_window(false).

  set_realized();

  //Get the themed style from the CSS file:
  get_style_property("example_scale", m_scale);
  std::cout &lt;&lt; "m_scale (example_scale from the theme/css-file) is: "
      &lt;&lt; m_scale &lt;&lt; std::endl;

  if(!m_refGdkWindow)
  {
    //Create the GdkWindow:

    GdkWindowAttr attributes;
    memset(&amp;attributes, 0, sizeof(attributes));

    Gtk::Allocation allocation = get_allocation();

    //Set initial position and size of the Gdk::Window:
    attributes.x = allocation.get_x();
    attributes.y = allocation.get_y();
    attributes.width = allocation.get_width();
    attributes.height = allocation.get_height();

    attributes.event_mask = get_events () | Gdk::EXPOSURE_MASK;
    attributes.window_type = GDK_WINDOW_CHILD;
    attributes.wclass = GDK_INPUT_OUTPUT;

    m_refGdkWindow = Gdk::Window::create(get_parent_window(), &amp;attributes,
            GDK_WA_X | GDK_WA_Y);
    set_window(m_refGdkWindow);

    //set colors
    override_background_color(Gdk::RGBA("red"));
    override_color(Gdk::RGBA("blue"));

    //make the widget receive expose events
    m_refGdkWindow-&gt;set_user_data(gobj());
  }
}

void MyWidget::on_unrealize()
{
  m_refGdkWindow.reset();

  //Call base class:
  Gtk::Widget::on_unrealize();
}

bool MyWidget::on_draw(const Cairo::RefPtr&lt;Cairo::Context&gt;&amp; cr)
{
  const double scale_x = (double)get_allocation().get_width() / m_scale;
  const double scale_y = (double)get_allocation().get_height() / m_scale;

  // paint the background
  Gdk::Cairo::set_source_rgba(cr, get_style_context()-&gt;get_background_color());
  cr-&gt;paint();

  // draw the foreground
  Gdk::Cairo::set_source_rgba(cr, get_style_context()-&gt;get_color());
  cr-&gt;move_to(155.*scale_x, 165.*scale_y);
  cr-&gt;line_to(155.*scale_x, 838.*scale_y);
  cr-&gt;line_to(265.*scale_x, 900.*scale_y);
  cr-&gt;line_to(849.*scale_x, 564.*scale_y);
  cr-&gt;line_to(849.*scale_x, 438.*scale_y);
  cr-&gt;line_to(265.*scale_x, 100.*scale_y);
  cr-&gt;line_to(155.*scale_x, 165.*scale_y);
  cr-&gt;move_to(265.*scale_x, 100.*scale_y);
  cr-&gt;line_to(265.*scale_x, 652.*scale_y);
  cr-&gt;line_to(526.*scale_x, 502.*scale_y);
  cr-&gt;move_to(369.*scale_x, 411.*scale_y);
  cr-&gt;line_to(633.*scale_x, 564.*scale_y);
  cr-&gt;move_to(369.*scale_x, 286.*scale_y);
  cr-&gt;line_to(369.*scale_x, 592.*scale_y);
  cr-&gt;move_to(369.*scale_x, 286.*scale_y);
  cr-&gt;line_to(849.*scale_x, 564.*scale_y);
  cr-&gt;move_to(633.*scale_x, 564.*scale_y);
  cr-&gt;line_to(155.*scale_x, 838.*scale_y);
  cr-&gt;stroke();

  return true;
}
</pre>
<p>File: <code class="filename">examplewindow.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "examplewindow.h"

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::ORIENTATION_VERTICAL),
  m_Button_Quit("Quit")
{
  set_title("Custom Widget example");
  set_border_width(6);
  set_default_size(400, 200);

  add(m_VBox);
  m_VBox.pack_start(m_MyWidget, Gtk::PACK_EXPAND_WIDGET);
  m_MyWidget.show();

  m_VBox.pack_start(m_ButtonBox, Gtk::PACK_SHRINK);

  m_ButtonBox.pack_start(m_Button_Quit, Gtk::PACK_SHRINK);
  m_ButtonBox.set_border_width(6);
  m_ButtonBox.set_layout(Gtk::BUTTONBOX_END);
  m_Button_Quit.signal_clicked().connect( sigc::mem_fun(*this, &amp;ExampleWindow::on_button_quit) );

  show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_quit()
{
  hide();
}
</pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "examplewindow.h"
#include &lt;gtkmm/main.h&gt;

int main(int argc, char *argv[])
{
  Gtk::Main kit(argc, argv);

  ExampleWindow window;
  //Shows the window and returns when it is closed.
  Gtk::Main::run(window);

  return 0;
}
</pre>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="chapter-customwidgets.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"><a accesskey="u" href="chapter-customwidgets.html"><img src="icons/up.png" alt="Up"></a></td>
<td width="40%" align="right"> <a accesskey="n" href="chapter-recommended-techniques.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 28. Custom Widgets </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> Chapter 29. Recommended Techniques</td>
</tr>
</table>
</div>
</body>
</html>
gtkmm-documentation 3.2.1-1 / usr / share / doc / gtkmm-documentation / tutorial / html / sec-custom-widgets.html
