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_ 95
