c++-gtk-utils
|
00001 /* Copyright (C) 2005 to 2011 Chris Vine 00002 00003 The library comprised in this file or of which this file is part is 00004 distributed by Chris Vine under the GNU Lesser General Public 00005 License as follows: 00006 00007 This library is free software; you can redistribute it and/or 00008 modify it under the terms of the GNU Lesser General Public License 00009 as published by the Free Software Foundation; either version 2.1 of 00010 the License, or (at your option) any later version. 00011 00012 This library is distributed in the hope that it will be useful, but 00013 WITHOUT ANY WARRANTY; without even the implied warranty of 00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00015 Lesser General Public License, version 2.1, for more details. 00016 00017 You should have received a copy of the GNU Lesser General Public 00018 License, version 2.1, along with this library (see the file LGPL.TXT 00019 which came with this source code package in the c++-gtk-utils 00020 sub-directory); if not, write to the Free Software Foundation, Inc., 00021 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 00022 00023 */ 00024 00025 #ifndef CGU_WIDGET_H 00026 #define CGU_WIDGET_H 00027 00028 #include <gtk/gtk.h> 00029 00030 #include <c++-gtk-utils/cgu_config.h> 00031 00032 namespace Cgu { 00033 00034 /** 00035 * @class MainWidgetBase widget.h c++-gtk-utils/widget.h 00036 * @brief This is a class to manage the lifetime of widgets which are 00037 * not top-level widgets (ie which are not derived from GtkWindow). 00038 * @sa WinBase GobjHandle 00039 * 00040 * Normally you will not need this class, because the GObject 00041 * reference counting system coupled with the WinBase class will 00042 * provide for lifetime management and exception safety, provided that 00043 * widgets are placed in their containers on a "top-down" basis and 00044 * the top-level window is managed by a WinBase object. 00045 * 00046 * However, sometimes it is convenient for a class to encapsulate only 00047 * part of the implementation of a top level window, and for there to 00048 * be automatic lifetime management of a widget before it is placed in 00049 * a GTK+ container. 00050 * 00051 * The MainWidgetBase class is intended to achieve this, by managing 00052 * references with g_object_ref_sink() such that the widget managed by 00053 * the class and its children are correctly destroyed when the 00054 * MainWidgetBase class goes out of scope or is deleted even if they 00055 * are not subsequently placed in another GTK+ container object which 00056 * calls g_object_ref_sink() on the widget. 00057 * 00058 * This class therefore represents a safety feature which can be used 00059 * simply by inheriting from it. It also enables a widget to be 00060 * placed in and removed from a GTK+ container without it being 00061 * destroyed by the removal, since it is owned by the MainWidgetBase 00062 * class object. 00063 * 00064 * A similar effect could be achieved by managing a widget with 00065 * GobjHandle, but MainWidgetBase enables, by inheritance, 00066 * encapsulation of supplementary operations on the contained widget. 00067 * 00068 * See @ref Threading for particulars about GTK+ thread safety (and so 00069 * MainWidgetBase thread safety). 00070 * 00071 * MainWidgetBase objects can be used with widget heirarchies created 00072 * using GtkBuilder. See @ref GtkBuilder for particulars about that. 00073 */ 00074 00075 class MainWidgetBase { 00076 // main widget object 00077 GtkWidget* g_widget_p; 00078 00079 public: 00080 /** 00081 * Returns the GtkWidget object managed by this class. This method 00082 * will not throw. 00083 * @return The managed GtkWidget object. 00084 */ 00085 GtkWidget* get_main_widget() const {return g_widget_p;} 00086 00087 /** 00088 * The constructor will not throw. It calls g_object_ref_sink() to 00089 * take ownership of the object to be managed. 00090 * @param widget The GtkWidget object to be managed by this class. 00091 */ 00092 MainWidgetBase(GtkWidget* widget); 00093 00094 /** 00095 * This class cannot be copied. The copy constructor is deleted. 00096 */ 00097 MainWidgetBase(const MainWidgetBase&) = delete; 00098 00099 /** 00100 * This class cannot be copied. The assignment operator is deleted. 00101 */ 00102 MainWidgetBase& operator=(const MainWidgetBase&) = delete; 00103 00104 /** 00105 * This class requires initialisation with a GtkWidget object. The 00106 * default constructor is deleted. 00107 */ 00108 MainWidgetBase() = delete; 00109 00110 /** 00111 * The destructor will not throw. It calls g_object_unref() to 00112 * relinquish ownership of the managed object. 00113 */ 00114 virtual ~MainWidgetBase(); 00115 00116 /* Only has effect if --with-glib-memory-slices-compat or 00117 * --with-glib-memory-slices-no-compat option picked */ 00118 CGU_GLIB_MEMORY_SLICES_FUNCS 00119 }; 00120 00121 } // namespace Cgu 00122 00123 #endif