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
54typedef struct _GtkWidget GtkWidget;
55
56namespace libgtk2ui {
57
58class 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_
95