OLD | NEW |
| (Empty) |
1 // Copyright (c) 2011 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 // OwnedWigetGtk 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 UI_BASE_GTK_OWNED_WIDGET_GTK_H_ | |
50 #define UI_BASE_GTK_OWNED_WIDGET_GTK_H_ | |
51 | |
52 #include "base/basictypes.h" | |
53 #include "ui/base/ui_base_export.h" | |
54 | |
55 typedef struct _GtkWidget GtkWidget; | |
56 | |
57 namespace ui { | |
58 | |
59 class UI_BASE_EXPORT OwnedWidgetGtk { | |
60 public: | |
61 // Create an instance that isn't managing any ownership. | |
62 OwnedWidgetGtk() : widget_(NULL) { } | |
63 // Create an instance that owns |widget|. | |
64 explicit OwnedWidgetGtk(GtkWidget* widget) : widget_(NULL) { Own(widget); } | |
65 | |
66 ~OwnedWidgetGtk(); | |
67 | |
68 // Return the currently owned widget, or NULL if no widget is owned. | |
69 GtkWidget* get() const { return widget_; } | |
70 GtkWidget* operator->() const { return widget_; } | |
71 | |
72 // Takes ownership of a widget, by taking the initial floating reference of | |
73 // the GtkWidget. It is expected that Own() is called right after the widget | |
74 // has been created, and before any other references to the widget might have | |
75 // been added. It is valid to never call Own(), in which case Destroy() will | |
76 // do nothing. If Own() has been called, you must explicitly call Destroy(). | |
77 void Own(GtkWidget* widget); | |
78 | |
79 // You may call Destroy() after you have called Own(). Calling Destroy() | |
80 // will call gtk_widget_destroy(), and drop our reference to the widget. | |
81 // Destroy() is also called in this object's destructor. | |
82 // After a call to Destroy(), you may call Own() again. NOTE: It is expected | |
83 // that after gtk_widget_destroy we will be holding the only reference left | |
84 // on the object. We assert this in debug mode to help catch any leaks. | |
85 void Destroy(); | |
86 | |
87 private: | |
88 GtkWidget* widget_; | |
89 | |
90 DISALLOW_COPY_AND_ASSIGN(OwnedWidgetGtk); | |
91 }; | |
92 | |
93 } // namespace ui | |
94 | |
95 #endif // UI_BASE_GTK_OWNED_WIDGET_GTK_H_ | |
OLD | NEW |