c++-gtk-utils
widget.h
Go to the documentation of this file.
1 /* Copyright (C) 2005 to 2011 Chris Vine
2 
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public License
9  as published by the Free Software Foundation; either version 2.1 of
10  the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful, but
13  WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License, version 2.1, for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License, version 2.1, along with this library (see the file LGPL.TXT
19  which came with this source code package in the c++-gtk-utils
20  sub-directory); if not, write to the Free Software Foundation, Inc.,
21  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22 
23 */
24 
25 #ifndef CGU_WIDGET_H
26 #define CGU_WIDGET_H
27 
28 #include <gtk/gtk.h>
29 
31 
32 namespace Cgu {
33 
34 /**
35  * @class MainWidgetBase widget.h c++-gtk-utils/widget.h
36  * @brief This is a class to manage the lifetime of widgets which are
37  * not top-level widgets (ie which are not derived from GtkWindow).
38  * @sa WinBase GobjHandle
39  *
40  * Normally you will not need this class, because the GObject
41  * reference counting system coupled with the WinBase class will
42  * provide for lifetime management and exception safety, provided that
43  * widgets are placed in their containers on a "top-down" basis and
44  * the top-level window is managed by a WinBase object.
45  *
46  * However, sometimes it is convenient for a class to encapsulate only
47  * part of the implementation of a top level window, and for there to
48  * be automatic lifetime management of a widget before it is placed in
49  * a GTK+ container.
50  *
51  * The MainWidgetBase class is intended to achieve this, by managing
52  * references with g_object_ref_sink() such that the widget managed by
53  * the class and its children are correctly destroyed when the
54  * MainWidgetBase class goes out of scope or is deleted even if they
55  * are not subsequently placed in another GTK+ container object which
56  * calls g_object_ref_sink() on the widget.
57  *
58  * This class therefore represents a safety feature which can be used
59  * simply by inheriting from it. It also enables a widget to be
60  * placed in and removed from a GTK+ container without it being
61  * destroyed by the removal, since it is owned by the MainWidgetBase
62  * class object.
63  *
64  * A similar effect could be achieved by managing a widget with
65  * GobjHandle, but MainWidgetBase enables, by inheritance,
66  * encapsulation of supplementary operations on the contained widget.
67  *
68  * See @ref Threading for particulars about GTK+ thread safety (and so
69  * MainWidgetBase thread safety).
70  *
71  * MainWidgetBase objects can be used with widget heirarchies created
72  * using GtkBuilder. See @ref GtkBuilder for particulars about that.
73  */
74 
76  // main widget object
77  GtkWidget* g_widget_p;
78 
79 public:
80  /**
81  * Returns the GtkWidget object managed by this class. This method
82  * will not throw.
83  * @return The managed GtkWidget object.
84  */
85  GtkWidget* get_main_widget() const {return g_widget_p;}
86 
87  /**
88  * The constructor will not throw. It calls g_object_ref_sink() to
89  * take ownership of the object to be managed.
90  * @param widget The GtkWidget object to be managed by this class.
91  */
92  MainWidgetBase(GtkWidget* widget);
93 
94 /**
95  * This class cannot be copied. The copy constructor is deleted.
96  */
97  MainWidgetBase(const MainWidgetBase&) = delete;
98 
99 /**
100  * This class cannot be copied. The assignment operator is deleted.
101  */
102  MainWidgetBase& operator=(const MainWidgetBase&) = delete;
103 
104 /**
105  * This class requires initialisation with a GtkWidget object. The
106  * default constructor is deleted.
107  */
108  MainWidgetBase() = delete;
109 
110  /**
111  * The destructor will not throw. It calls g_object_unref() to
112  * relinquish ownership of the managed object.
113  */
114  virtual ~MainWidgetBase();
115 
116 /* Only has effect if --with-glib-memory-slices-compat or
117  * --with-glib-memory-slices-no-compat option picked */
119 };
120 
121 } // namespace Cgu
122 
123 #endif