c++-gtk-utils
widget.h
Go to the documentation of this file.
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