chrome/browser/ui/libgtk2ui/owned_widget_gtk2.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This class assists you in dealing with a specific situation when managing
   6 // ownership between a C++ object and a GTK widget.  It is common to have a
   7 // C++ object which encapsulates a GtkWidget, and that widget is exposed from
   8 // the object for use outside of the class.  In this situation, you commonly
   9 // want the GtkWidget's lifetime to match its C++ object's lifetime.  Using an
  10 // OwnedWidgetGtk will take ownership over the initial reference of the
  11 // GtkWidget, so that it is "owned" by the C++ object.  Example usage:
  12 //
  13 // class FooViewGtk() {
  14 //  public:
  15 //   FooViewGtk() { }
  16 //   ~FooViewGtk() { }
  17 //   void Init() { vbox_.Own(gtk_vbox_new()); }
  18 //   GtkWidget* widget() { return vbox_.get() };  // Host my widget!
  19 //  private:
  20 //   OwnedWidgetGtk vbox_;
  21 // };
  22 //
  23 // This design will ensure that the widget stays alive from the call to Own()
  24 // until the call to Destroy().
  25 //
  26 // - Details of the problem and OwnedWidgetGtk's solution:
  27 // In order to make passing ownership more convenient for newly created
  28 // widgets, GTK has a concept of a "floating" reference.  All GtkObjects (and
  29 // thus GtkWidgets) inherit from GInitiallyUnowned.  When they are created, the
  30 // object starts with a reference count of 1, but has its floating flag set.
  31 // When it is put into a container for the first time, that container will
  32 // "sink" the floating reference, and the count will still be 1.  Now the
  33 // container owns the widget, and if we remove the widget from the container,
  34 // the widget is destroyed.  This style of ownership often causes problems when
  35 // you have an object encapsulating the widget.  If we just use a raw
  36 // GtkObject* with no specific ownership management, we push the widget's
  37 // ownership onto the user of the class.  Now the C++ object can't depend on
  38 // the widget being valid, since it doesn't manage its lifetime.  If the widget
  39 // was removed from a container, removing its only reference, it would be
  40 // destroyed (from the C++ object's perspective) unexpectedly destroyed.  The
  41 // solution is fairly simple, make sure that the C++ object owns the widget,
  42 // and thus it is also responsible for destroying it.  This boils down to:
  43 //   GtkWidget* widget = gtk_widget_new();
  44 //   g_object_ref_sink(widget);  // Claim the initial floating reference.
  45 //   ...
  46 //   gtk_destroy_widget(widget);  // Ask all code to destroy their references.
  47 //   g_object_unref(widget);  // Destroy the initial reference we had claimed.
  48
  49 #ifndef CHROME_BROWSER_UI_LIBGTK2UI_OWNED_WIDGET_GTK2_H_
  50 #define CHROME_BROWSER_UI_LIBGTK2UI_OWNED_WIDGET_GTK2_H_
  51
  52 #include "base/basictypes.h"
  53
  54 typedef struct _GtkWidget GtkWidget;
  55
  56 namespace libgtk2ui {
  57
  58 class OwnedWidgetGtk {
  59  public:
  60   // Create an instance that isn't managing any ownership.
  61   OwnedWidgetGtk() : widget_(NULL) { }
  62   // Create an instance that owns |widget|.
  63   explicit OwnedWidgetGtk(GtkWidget* widget) : widget_(NULL) { Own(widget); }
  64
  65   ~OwnedWidgetGtk();
  66
  67   // Return the currently owned widget, or NULL if no widget is owned.
  68   GtkWidget* get() const { return widget_; }
  69   GtkWidget* operator->() const { return widget_; }
  70
  71   // Takes ownership of a widget, by taking the initial floating reference of
  72   // the GtkWidget. It is expected that Own() is called right after the widget
  73   // has been created, and before any other references to the widget might have
  74   // been added. It is valid to never call Own(), in which case Destroy() will
  75   // do nothing. If Own() has been called, you must explicitly call Destroy().
  76   void Own(GtkWidget* widget);
  77
  78   // You may call Destroy() after you have called Own(). Calling Destroy()
  79   // will call gtk_widget_destroy(), and drop our reference to the widget.
  80   // Destroy() is also called in this object's destructor.
  81   // After a call to Destroy(), you may call Own() again. NOTE: It is expected
  82   // that after gtk_widget_destroy we will be holding the only reference left
  83   // on the object. We assert this in debug mode to help catch any leaks.
  84   void Destroy();
  85
  86  private:
  87   GtkWidget* widget_;
  88
  89   DISALLOW_COPY_AND_ASSIGN(OwnedWidgetGtk);
  90 };
  91
  92 }  // namespace libgtk2ui
  93
  94 #endif  // CHROME_BROWSER_UI_LIBGTK2UI_OWNED_WIDGET_GTK2_H_