c++-gtk-utils: widget.h Source File

c++-gtk-utils

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

widget.h
Go to the documentation of this file.
1 /* Copyright (C) 2005 to 2011 and 2013 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 <c++-gtk-utils/cgu_config.h>
29
30 #ifdef CGU_USE_GTK
31 #include <gtk/gtk.h>
32 #endif
33
34 namespace Cgu {
35
36 #if defined(DOXYGEN_PARSING) || defined(CGU_USE_GTK)
37
38 /**
39 * @class MainWidgetBase widget.h c++-gtk-utils/widget.h
40 * @brief This is a class to manage the lifetime of widgets which are
41 * not top-level widgets (ie which are not derived from GtkWindow).
42 * @sa WinBase GobjHandle
43 *
44 * Normally you will not need this class, because the GObject
45 * reference counting system coupled with the WinBase class will
46 * provide for lifetime management and exception safety, provided that
47 * widgets are placed in their containers on a "top-down" basis and
48 * the top-level window is managed by a WinBase object.
49 *
50 * However, sometimes it is convenient for a class to encapsulate only
51 * part of the implementation of a top level window, and for there to
52 * be automatic lifetime management of a widget before it is placed in
53 * a GTK+ container.
54 *
55 * The MainWidgetBase class is intended to achieve this, by managing
56 * references with g_object_ref_sink() such that the widget managed by
57 * the class and its children are correctly destroyed when the
58 * MainWidgetBase class goes out of scope or is deleted even if they
59 * are not subsequently placed in another GTK+ container object which
60 * calls g_object_ref_sink() on the widget.
61 *
62 * This class therefore represents a safety feature which can be used
63 * simply by inheriting from it. It also enables a widget to be
64 * placed in and removed from a GTK+ container without it being
65 * destroyed by the removal, since it is owned by the MainWidgetBase
66 * class object.
67 *
68 * A similar effect could be achieved by managing a widget with
69 * GobjHandle, but MainWidgetBase enables, by inheritance,
70 * encapsulation of supplementary operations on the contained widget.
71 *
72 * See @ref Threading for particulars about GTK+ thread safety (and so
73 * MainWidgetBase thread safety).
74 *
75 * MainWidgetBase objects can be used with widget heirarchies created
76 * using GtkBuilder. See @ref GtkBuilder for particulars about that.
77 *
78 * This class is not compiled into the library if the library is built
79 * with the \--without-gtk configuration option.
80 */
81
82 class MainWidgetBase {
83 // main widget object
84 GtkWidget* g_widget_p;
85
86 public:
87 /**
88 * Returns the GtkWidget object managed by this class. This method
89 * will not throw.
90 * @return The managed GtkWidget object.
91 */
92 GtkWidget* get_main_widget() const {return g_widget_p;}
93
94 /**
95 * The constructor will not throw. It calls g_object_ref_sink() to
96 * take ownership of the object to be managed.
97 * @param widget The GtkWidget object to be managed by this class.
98 */
99 MainWidgetBase(GtkWidget* widget);
100
101 /**
102 * This class cannot be copied. The copy constructor is deleted.
103 */
104 MainWidgetBase(const MainWidgetBase&) = delete;
105
106 /**
107 * This class cannot be copied. The copy assignment operator is
108 * deleted.
109 */
110 MainWidgetBase& operator=(const MainWidgetBase&) = delete;
111
112 /**
113 * The default constructor is deleted. This class requires
114 * initialisation with a GtkWidget object or to be moved to - it is
115 * intended that a MainWidgetBase object will always be managing a
116 * valid GtkWidget object unless it has been moved from and is
117 * therefore awaiting destruction.
118 */
119 MainWidgetBase() = delete;
120
121 /**
122 * The move constructor will not throw.
123 *
124 * @param obj The MainWidgetBase object to be moved.
125 *
126 * Since 2.0.19/2.2.2
127 */
128 MainWidgetBase(MainWidgetBase&& obj);
129
130 /**
131 * The move assignment operator will not throw. It will call
132 * g_object_unref() on the previously managed GtkWidget object, if
133 * any.
134 *
135 * @param obj The MainWidgetBase object to be moved.
136 *
137 * Since 2.0.19/2.2.2
138 */
139 MainWidgetBase& operator=(MainWidgetBase&& obj);
140
141 /**
142 * The destructor will not throw. It calls g_object_unref() to
143 * relinquish ownership of the managed object.
144 */
145 virtual ~MainWidgetBase();
146
147 /* Only has effect if --with-glib-memory-slices-compat or
148 * --with-glib-memory-slices-no-compat option picked */
149 CGU_GLIB_MEMORY_SLICES_FUNCS
150 };
151
152 #endif // CGU_USE_GTK
153
154 } // namespace Cgu
155
156 #endif // CGU_WIDGET_H