libs/glibmm2/glib/glibmm/object.h

   1 // -*- c++ -*-
   2 #ifndef _GLIBMM_OBJECT_H
   3 #define _GLIBMM_OBJECT_H
   4 /* $Id: object.h 369 2007-01-20 10:19:33Z daniel $ */
   5
   6 /* Copyright 2002 The gtkmm Development Team
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the Free
  20  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  21  */
  22
  23 //X11 defines DestroyNotify and some other non-prefixed stuff, and it's too late to change that now,
  24 //so let's give people a clue about the compilation errors that they will see:
  25 #ifdef DestroyNotify
  26 # error "X11/Xlib.h seems to have been included before this header. Due to some commonly-named macros in X11/Xlib.h, it may only be included after any glibmm, gdkmm, or gtkmm headers."
  27 #endif
  28
  29 #include <glib/gmacros.h> /* for G_GNUC_NULL_TERMINATED */
  30 #include <glibmm/objectbase.h>
  31 #include <glibmm/wrap.h>
  32 #include <glibmm/quark.h>
  33 #include <glibmm/refptr.h>
  34 #include <glibmm/utility.h> /* Could be private, but that would be tedious. */
  35 #include <glibmm/containerhandle_shared.h> /* Because its specializations may be here. */
  36 #include <glibmm/value.h>
  37
  38 #include <glibmmconfig.h>
  39
  40 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  41 extern "C"
  42 {
  43 typedef struct _GObject GObject;
  44 typedef struct _GObjectClass GObjectClass;
  45 }
  46 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  47
  48
  49 namespace Glib
  50 {
  51
  52 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  53
  54 class Class;
  55 class Object_Class;
  56 class GSigConnectionNode;
  57
  58 /* ConstructParams::ConstructParams() takes a varargs list of properties
  59  * and values, like g_object_new() does.  This list will then be converted
  60  * to a GParameter array, for use with g_object_newv().  No overhead is
  61  * involved, since g_object_new() is just a wrapper around g_object_newv()
  62  * as well.
  63  *
  64  * The advantage of an auxiliary ConstructParams object over g_object_new()
  65  * is that the actual construction is always done in the Glib::Object ctor.
  66  * This allows for neat tricks like easy creation of derived custom types,
  67  * without adding special support to each ctor of every class.
  68  *
  69  * The comments in object.cc and objectbase.cc should explain in detail
  70  * how this works.
  71  */
  72 class ConstructParams
  73 {
  74 public:
  75   const Glib::Class&  glibmm_class;
  76   unsigned int        n_parameters;
  77   GParameter*         parameters;
  78
  79   explicit ConstructParams(const Glib::Class& glibmm_class_);
  80   ConstructParams(const Glib::Class& glibmm_class_, const char* first_property_name, ...)
  81     G_GNUC_NULL_TERMINATED; // warn if called without a trailing NULL pointer
  82   ~ConstructParams();
  83
  84   // The copy constructor is semantically required by the C++ compiler
  85   // (since g++ 3.4) to be able to create temporary instances, depending
  86   // on the usage context.  Apparently the compiler will actually optimize
  87   // away the copy, though.  See bug #132300.
  88   ConstructParams(const ConstructParams& other);
  89
  90 private:
  91   // no copy assignment
  92   ConstructParams& operator=(const ConstructParams&);
  93 };
  94
  95 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  96
  97
  98 class GLIBMM_API Object : virtual public ObjectBase
  99 {
 100 public:
 101 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 102   typedef Object       CppObjectType;
 103   typedef Object_Class CppClassType;
 104   typedef GObject      BaseObjectType;
 105   typedef GObjectClass BaseClassType;
 106 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 107
 108 protected:
 109   Object(); //For use by C++-only sub-types.
 110   explicit Object(const Glib::ConstructParams& construct_params);
 111   explicit Object(GObject* castitem);
 112   virtual ~Object(); //It should only be deleted by the callback.
 113
 114 public:
 115   //static RefPtr<Object> create(); //You must reimplement this in each derived class.
 116
 117 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 118   static GType get_type()      G_GNUC_CONST;
 119   static GType get_base_type() G_GNUC_CONST;
 120 #endif
 121
 122   //GObject* gobj_copy(); //Give a ref-ed copy to someone. Use for direct struct access.
 123
 124   // Glib::Objects contain a list<Quark, pair<void*, DestroyNotify> >
 125   // to store run time data added to the object at run time.
 126   //TODO: Use slots instead:
 127   void* get_data(const QueryQuark &key);
 128   void set_data(const Quark &key, void* data);
 129   typedef void (*DestroyNotify) (gpointer data);
 130   void set_data(const Quark &key, void* data, DestroyNotify notify);
 131   void remove_data(const QueryQuark& quark);
 132   // same as remove without notifying
 133   void* steal_data(const QueryQuark& quark);
 134
 135   // convenience functions
 136   //template <class T>
 137   //void set_data_typed(const Quark& quark, const T& data)
 138   //  { set_data(quark, new T(data), delete_typed<T>); }
 139
 140   //template <class T>
 141   //T& get_data_typed(const QueryQuark& quark)
 142   //  { return *static_cast<T*>(get_data(quark)); }
 143
 144 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 145
 146 private:
 147   friend class Glib::Object_Class;
 148   static CppClassType object_class_;
 149
 150   // noncopyable
 151   Object(const Object&);
 152   Object& operator=(const Object&);
 153
 154 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 155
 156   // Glib::Object can not be dynamic because it lacks a float state.
 157   //virtual void set_manage();
 158 };
 159
 160
 161 //For some (proably, more spec-compliant) compilers, these specializations must
 162 //be next to the objects that they use.
 163 #ifndef GLIBMM_CAN_USE_DYNAMIC_CAST_IN_UNUSED_TEMPLATE_WITHOUT_DEFINITION
 164 # ifndef DOXYGEN_SHOULD_SKIP_THIS /* hide the specializations */
 165
 166 namespace Container_Helpers
 167 {
 168
 169 /** Partial specialization for pointers to GObject instances.
 170  * @ingroup ContHelpers
 171  * The C++ type is always a Glib::RefPtr<>.
 172  */
 173 template <class T>
 174 struct TypeTraits< Glib::RefPtr<T> >
 175 {
 176   typedef Glib::RefPtr<T>              CppType;
 177   typedef typename T::BaseObjectType * CType;
 178   typedef typename T::BaseObjectType * CTypeNonConst;
 179
 180   static CType   to_c_type  (const CppType& ptr) { return Glib::unwrap(ptr); }
 181   static CType   to_c_type  (CType          ptr) { return ptr;               }
 182   static CppType to_cpp_type(CType          ptr)
 183   {
 184     //return Glib::wrap(ptr, true);
 185
 186     //We copy/paste the wrap() implementation here,
 187     //because we can not use a specific Glib::wrap(CType) overload here,
 188     //because that would be "dependent", and g++ 3.4 does not allow that.
 189     //The specific Glib::wrap() overloads don't do anything special anyway.
 190     GObject* cobj = (GObject*)const_cast<CTypeNonConst>(ptr);
 191     return Glib::RefPtr<T>( dynamic_cast<T*>(Glib::wrap_auto(cobj, true /* take_copy */)) );
 192     //We use dynamic_cast<> in case of multiple inheritance.
 193   }
 194
 195   static void release_c_type(CType ptr)
 196   {
 197     GLIBMM_DEBUG_UNREFERENCE(0, ptr);
 198     g_object_unref(ptr);
 199   }
 200 };
 201
 202 //This confuses the SUN Forte compiler, so we ifdef it out:
 203 #  ifdef GLIBMM_HAVE_DISAMBIGUOUS_CONST_TEMPLATE_SPECIALIZATIONS
 204
 205 /** Partial specialization for pointers to const GObject instances.
 206  * @ingroup ContHelpers
 207  * The C++ type is always a Glib::RefPtr<>.
 208  */
 209 template <class T>
 210 struct TypeTraits< Glib::RefPtr<const T> >
 211 {
 212   typedef Glib::RefPtr<const T>              CppType;
 213   typedef const typename T::BaseObjectType * CType;
 214   typedef typename T::BaseObjectType *       CTypeNonConst;
 215
 216   static CType   to_c_type  (const CppType& ptr) { return Glib::unwrap(ptr); }
 217   static CType   to_c_type  (CType          ptr) { return ptr;               }
 218   static CppType to_cpp_type(CType          ptr)
 219   {
 220     //return Glib::wrap(ptr, true);
 221
 222     //We copy/paste the wrap() implementation here,
 223     //because we can not use a specific Glib::wrap(CType) overload here,
 224     //because that would be "dependent", and g++ 3.4 does not allow that.
 225     //The specific Glib::wrap() overloads don't do anything special anyway.
 226     GObject* cobj = (GObject*)(ptr);
 227     return Glib::RefPtr<const T>( dynamic_cast<const T*>(Glib::wrap_auto(cobj, true /* take_copy */)) );
 228     //We use dynamic_cast<> in case of multiple inheritance.
 229   }
 230
 231   static void release_c_type (CType ptr)
 232   {
 233     GLIBMM_DEBUG_UNREFERENCE(0, ptr);
 234     g_object_unref(const_cast<CTypeNonConst>(ptr));
 235   }
 236 };
 237
 238 #  endif /* GLIBMM_HAVE_DISAMBIGUOUS_CONST_TEMPLATE_SPECIALIZATIONS */
 239
 240 } //namespace Container_Helpers
 241
 242
 243 template <class T, class PtrT> inline
 244 PtrT Value_Pointer<T,PtrT>::get_(Glib::Object*) const
 245 {
 246   return dynamic_cast<T*>(get_object());
 247 }
 248
 249
 250 /** Partial specialization for RefPtr<> to Glib::Object.
 251  * @ingroup glibmmValue
 252  */
 253 template <class T>
 254 class Value< Glib::RefPtr<T> > : public ValueBase_Object
 255 {
 256 public:
 257   typedef Glib::RefPtr<T>             CppType;
 258   typedef typename T::BaseObjectType* CType;
 259
 260   static GType value_type() { return T::get_base_type(); }
 261
 262   void set(const CppType& data) { set_object(data.operator->()); }
 263   CppType get() const           { return Glib::RefPtr<T>::cast_dynamic(get_object_copy()); }
 264 };
 265
 266 //The SUN Forte Compiler has a problem with this:
 267 #  ifdef GLIBMM_HAVE_DISAMBIGUOUS_CONST_TEMPLATE_SPECIALIZATIONS
 268
 269 /** Partial specialization for RefPtr<> to const Glib::Object.
 270  * @ingroup glibmmValue
 271  */
 272 template <class T>
 273 class Value< Glib::RefPtr<const T> > : public ValueBase_Object
 274 {
 275 public:
 276   typedef Glib::RefPtr<const T>       CppType;
 277   typedef typename T::BaseObjectType* CType;
 278
 279   static GType value_type() { return T::get_base_type(); }
 280
 281   void set(const CppType& data) { set_object(const_cast<T*>(data.operator->())); }
 282   CppType get() const           { return Glib::RefPtr<T>::cast_dynamic(get_object_copy()); }
 283 };
 284 #  endif /* GLIBMM_HAVE_DISAMBIGUOUS_CONST_TEMPLATE_SPECIALIZATIONS */
 285
 286 # endif /* DOXYGEN_SHOULD_SKIP_THIS */
 287 #endif /* GLIBMM_CAN_USE_DYNAMIC_CAST_IN_UNUSED_TEMPLATE_WITHOUT_DEFINITION */
 288
 289 } // namespace Glib
 290
 291 #endif /* _GLIBMM_OBJECT_H */
 292