Pileus Git - ~andy/gtk/blob - gtk/gtkobject.h

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19 #ifndef __GTK_OBJECT_H__
  20 #define __GTK_OBJECT_H__
  21
  22
  23 #include <gtk/gtkenums.h>
  24 #include <gtk/gtktypeutils.h>
  25 #include <gtk/gtkdebug.h>
  26
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #pragma }
  31 #endif /* __cplusplus */
  32
  33
  34
  35 /* The debugging versions of the casting macros make sure the cast is "ok"
  36  *  before proceeding, but they are definately slower than their less
  37  *  careful counterparts as they involve no less than 3 function calls.
  38  */
  39 #ifdef GTK_NO_CHECK_CASTS
  40
  41 #define GTK_CHECK_CAST(obj,cast_type,cast)         ((cast*) (obj))
  42 #define GTK_CHECK_CLASS_CAST(klass,cast_type,cast) ((cast*) (klass))
  43
  44 #else /* !GTK_NO_CHECK_CASTS */
  45
  46 #define GTK_CHECK_CAST(obj,cast_type,cast) \
  47   ((cast*) gtk_object_check_cast ((GtkObject*) (obj), (cast_type)))
  48
  49 #define GTK_CHECK_CLASS_CAST(klass,cast_type,cast) \
  50   ((cast*) gtk_object_check_class_cast ((GtkObjectClass*) (klass), (cast_type)))
  51
  52 #endif /* GTK_NO_CHECK_CASTS */
  53
  54
  55 /* Determines whether `obj' and `klass' are a type of `otype'.
  56  */
  57 #define GTK_CHECK_TYPE(obj,otype)          ( \
  58   gtk_type_is_a (((GtkObject*) (obj))->klass->type, (otype)) \
  59 )
  60 #define GTK_CHECK_CLASS_TYPE(klass,otype)  ( \
  61   gtk_type_is_a (((GtkObjectClass*) (klass))->type, (otype)) \
  62 )
  63
  64 /* Macro for casting a pointer to a GtkObject or GtkObjectClass pointer.
  65  * The second portion of the ?: statments are just in place to offer
  66  * descriptive warning message.
  67  */
  68 #define GTK_OBJECT(object)              ( \
  69   GTK_IS_OBJECT (object) ? \
  70     (GtkObject*) (object) : \
  71     (GtkObject*) gtk_object_check_cast ((GtkObject*) (object), GTK_TYPE_OBJECT) \
  72 )
  73 #define GTK_OBJECT_CLASS(klass)         ( \
  74   GTK_IS_OBJECT_CLASS (klass) ? \
  75     (GtkObjectClass*) (klass) : \
  76     (GtkObjectClass*) gtk_object_check_class_cast ((GtkObjectClass*) (klass), GTK_TYPE_OBJECT) \
  77 )
  78
  79 /* Macro for testing whether `object' and `klass' are of type GTK_TYPE_OBJECT.
  80  */
  81 #define GTK_IS_OBJECT(object)           ( \
  82   (object) != NULL && \
  83   GTK_IS_OBJECT_CLASS (((GtkObject*) (object))->klass) \
  84 )
  85 #define GTK_IS_OBJECT_CLASS(klass)      ( \
  86   (klass) != NULL && \
  87   GTK_FUNDAMENTAL_TYPE (((GtkObjectClass*) (klass))->type) == GTK_TYPE_OBJECT \
  88 )
  89
  90 /* Macros for extracting various fields from GtkObject and GtkObjectClass.
  91  */
  92 #define GTK_OBJECT_TYPE(obj)              (GTK_OBJECT (obj)->klass->type)
  93 #define GTK_OBJECT_SIGNALS(obj)           (GTK_OBJECT (obj)->klass->signals)
  94 #define GTK_OBJECT_NSIGNALS(obj)          (GTK_OBJECT (obj)->klass->nsignals)
  95
  96 /* GtkObject only uses the first 4 bits of the flags field.
  97  * Derived objects may use the remaining bits. Though this
  98  * is a kinda nasty break up, it does make the size of
  99  * derived objects smaller.
 100  */
 101 typedef enum
 102 {
 103   G_NV (GTK_DESTROYED,          destroyed,              1 << 0),
 104   G_NV (GTK_FLOATING,           floating,               1 << 1),
 105   G_NV (GTK_CONNECTED,          connected,              1 << 2),
 106   GTK_RESERVED_2,
 107   G_NV (GTK_OBJECT_FLAG_LAST,   object-flag-last,       GTK_RESERVED_2)
 108 } G_FLAGS (GtkObjectFlags);
 109
 110 /* Macros for extracting the object_flags from GtkObject.
 111  */
 112 #define GTK_OBJECT_FLAGS(obj)             (GTK_OBJECT (obj)->flags)
 113 #define GTK_OBJECT_DESTROYED(obj)         (GTK_OBJECT_FLAGS (obj) & GTK_DESTROYED)
 114 #define GTK_OBJECT_FLOATING(obj)          (GTK_OBJECT_FLAGS (obj) & GTK_FLOATING)
 115 #define GTK_OBJECT_CONNECTED(obj)         (GTK_OBJECT_FLAGS (obj) & GTK_CONNECTED)
 116
 117 /* Macros for setting and clearing bits in the object_flags field of GtkObject.
 118  */
 119 #define GTK_OBJECT_SET_FLAGS(obj,flag)    G_STMT_START{ (GTK_OBJECT_FLAGS (obj) |= (flag)); }G_STMT_END
 120 #define GTK_OBJECT_UNSET_FLAGS(obj,flag)  G_STMT_START{ (GTK_OBJECT_FLAGS (obj) &= ~(flag)); }G_STMT_END
 121
 122 /* GtkArg flag bits for gtk_object_add_arg_type
 123  */
 124 typedef enum
 125 {
 126   G_NV (GTK_ARG_READABLE,       readable,       1 << 0),
 127   G_NV (GTK_ARG_WRITABLE,       writable,       1 << 1),
 128   G_NV (GTK_ARG_CONSTRUCT,      construct,      1 << 2),
 129   G_NV (GTK_ARG_MASK,           mask,           0x03),
 130   /* aliases
 131    */
 132   G_NV (GTK_ARG_READWRITE,      readwrite,      GTK_ARG_READABLE | GTK_ARG_WRITABLE)
 133 } G_FLAGS (GtkArgFlags);
 134
 135
 136 typedef struct _GtkObjectClass  GtkObjectClass;
 137
 138
 139 /* GtkObject is the base of the object hierarchy. It defines
 140  *  the few basic items that all derived classes contain.
 141  */
 142 struct _GtkObject
 143 {
 144   /* A pointer to the objects class. This will actually point to
 145    *  the derived objects class struct (which will be derived from
 146    *  GtkObjectClass).
 147    */
 148   GtkObjectClass *klass;
 149
 150   /* 32 bits of flags. GtkObject only uses 4 of these bits and
 151    *  GtkWidget uses the rest. This is done because structs are
 152    *  aligned on 4 or 8 byte boundaries. If a new bitfield were
 153    *  used in GtkWidget much space would be wasted.
 154    */
 155   guint32 flags;
 156
 157   /* reference count.
 158    * refer to the file REFCOUNTING on this issue.
 159    */
 160   guint ref_count;
 161
 162   /* The list of signal handlers and other data
 163    *  fields for this object.
 164    */
 165   gpointer object_data;
 166 };
 167
 168 /* GtkObjectClass is the base of the class hierarchy. It defines
 169  *  the basic necessities for the class mechanism to work. Namely,
 170  *  the "type", "signals" and "nsignals" fields.
 171  */
 172 struct _GtkObjectClass
 173 {
 174   /* The type identifier for the objects class. There is
 175    *  one unique identifier per class.
 176    */
 177   GtkType type;
 178
 179   /* The signals this object class handles. "signals" is an
 180    *  array of signal ID's.
 181    */
 182   guint *signals;
 183
 184   /* The number of signals listed in "signals".
 185    */
 186   guint nsignals;
 187
 188   /* The number of arguments per class.
 189    */
 190   guint n_args;
 191
 192   /* The functions that will end an objects life time. In one way ore
 193    *  another all three of them are defined for all objects. If an
 194    *  object class overrides one of the methods in order to perform class
 195    *  specific destruction then it must still invoke its superclass'
 196    *  implementation of the method after it is finished with its
 197    *  own cleanup. (See the destroy function for GtkWidget for
 198    *  an example of how to do this).
 199    */
 200   void (* shutdown) (GtkObject *object);
 201   void (* destroy) (GtkObject *object);
 202
 203   void (* finalize) (GtkObject *object);
 204 };
 205
 206
 207 /* For the purpose of user signals we need the signal function
 208  * and signal marshaller signatures already in this place.
 209  */
 210 #define GTK_SIGNAL_FUNC(f)  ((GtkSignalFunc) f)
 211
 212 typedef void (*GtkSignalFunc)       (void);
 213 typedef void (*GtkSignalMarshaller) (GtkObject      *object,
 214                                      GtkSignalFunc   func,
 215                                      gpointer        func_data,
 216                                      GtkArg         *args);
 217
 218
 219 /* Get the type identifier for GtkObject's.
 220  */
 221 GtkType gtk_object_get_type             (void);
 222
 223 /* Append "signals" to those already defined in "class".
 224  */
 225 void    gtk_object_class_add_signals    (GtkObjectClass *klass,
 226                                          guint          *signals,
 227                                          guint           nsignals);
 228
 229 /* Append a user defined signal without default handler to a class.
 230  */
 231 guint   gtk_object_class_user_signal_new  (GtkObjectClass     *klass,
 232                                            const gchar        *name,
 233                                            GtkSignalRunType    signal_flags,
 234                                            GtkSignalMarshaller marshaller,
 235                                            GtkType             return_val,
 236                                            guint               nparams,
 237                                            ...);
 238 guint   gtk_object_class_user_signal_newv (GtkObjectClass     *klass,
 239                                            const gchar        *name,
 240                                            GtkSignalRunType    signal_flags,
 241                                            GtkSignalMarshaller marshaller,
 242                                            GtkType             return_val,
 243                                            guint               nparams,
 244                                            GtkType            *params);
 245 /* Outdated */
 246 guint   gtk_object_class_add_user_signal (GtkObjectClass        *klass,
 247                                           const gchar           *name,
 248                                           GtkSignalMarshaller    marshaller,
 249                                           GtkType                return_val,
 250                                           guint                  nparams,
 251                                           ...);
 252
 253 GtkObject*      gtk_object_new          (GtkType        type,
 254                                          ...);
 255
 256 GtkObject*      gtk_object_newv         (GtkType        type,
 257                                          guint          nargs,
 258                                          GtkArg         *args);
 259 void gtk_object_sink      (GtkObject        *object);
 260 void gtk_object_ref       (GtkObject        *object);
 261 void gtk_object_unref     (GtkObject        *object);
 262
 263 void gtk_object_weakref   (GtkObject        *object,
 264                            GtkDestroyNotify  notify,
 265                            gpointer          data);
 266 void gtk_object_weakunref (GtkObject        *object,
 267                            GtkDestroyNotify  notify,
 268                            gpointer          data);
 269
 270 void gtk_object_destroy   (GtkObject *object);
 271
 272 /* gtk_object_getv() sets an arguments type and value, or just
 273  * its type to GTK_TYPE_INVALID.
 274  * if arg->type == GTK_TYPE_STRING, it's the callers response to
 275  * do a g_free (GTK_VALUE_STRING (arg));
 276  */
 277 void    gtk_object_getv         (GtkObject      *object,
 278                                  guint          nargs,
 279                                  GtkArg         *args);
 280
 281 /* gtk_object_set() takes a variable argument list of the form:
 282  * (..., gchar *arg_name, ARG_VALUES, [repeatedly name/value pairs,] NULL)
 283  * where ARG_VALUES type depend on the argument and can consist of
 284  * more than one c-function argument.
 285  */
 286 void    gtk_object_set          (GtkObject      *object,
 287                                  ...);
 288
 289 void    gtk_object_setv         (GtkObject      *object,
 290                                  guint          nargs,
 291                                  GtkArg         *args);
 292
 293 /* Allocate a GtkArg array of size nargs that hold the
 294  * names and types of the args that can be used with
 295  * gtk_object_set/gtk_object_get. if (arg_flags!=NULL),
 296  * (*arg_flags) will be set to point to a newly allocated
 297  * guint array that holds the flags of the args.
 298  * It is the callers response to do a
 299  * g_free (returned_args); g_free (*acess_masks).
 300  */
 301 GtkArg* gtk_object_query_args   (GtkType        class_type,
 302                                  guint32        **arg_flags,
 303                                  guint          *nargs);
 304
 305 void    gtk_object_add_arg_type (const gchar    *arg_name,
 306                                  GtkType        arg_type,
 307                                  guint          arg_flags,
 308                                  guint          arg_id);
 309
 310 GtkType gtk_object_get_arg_type (const gchar    *arg_name);
 311
 312 /* Set 'data' to the "object_data" field of the object. The
 313  *  data is indexed by the "key". If there is already data
 314  *  associated with "key" then the new data will replace it.
 315  *  If 'data' is NULL then this call is equivalent to
 316  *  'gtk_object_remove_data'.
 317  */
 318 void gtk_object_set_data       (GtkObject   *object,
 319                                 const gchar *key,
 320                                 gpointer     data);
 321
 322 /* Like gtk_object_set_data, but takes an additional argument
 323  * which is a function to be called when the data is removed.
 324  */
 325 void gtk_object_set_data_full       (GtkObject   *object,
 326                                      const gchar *key,
 327                                      gpointer     data,
 328                                      GtkDestroyNotify destroy);
 329
 330 /* Get the data associated with "key".
 331  */
 332 gpointer gtk_object_get_data       (GtkObject   *object,
 333                                     const gchar *key);
 334
 335 /* Remove the data associated with "key". This call is
 336  *  equivalent to 'gtk_object_set_data' where 'data' is NULL.
 337  */
 338 void gtk_object_remove_data       (GtkObject   *object,
 339                                    const gchar *key);
 340
 341 /* Object data functions that operate on key ids.
 342  *  These functions are meant for *internal* use only.
 343  */
 344 void gtk_object_set_data_by_id      (GtkObject       *object,
 345                                      guint            data_id,
 346                                      gpointer         data);
 347 void gtk_object_set_data_by_id_full (GtkObject       *object,
 348                                      guint            data_id,
 349                                      gpointer         data,
 350                                      GtkDestroyNotify destroy);
 351 gpointer gtk_object_get_data_by_id  (GtkObject       *object,
 352                                      guint            data_id);
 353 void  gtk_object_remove_data_by_id  (GtkObject       *object,
 354                                      guint            data_id);
 355 #define gtk_object_data_try_key     g_dataset_try_key
 356 #define gtk_object_data_force_id    g_dataset_force_id
 357
 358 /* Set the "user_data" object data field of "object". It should
 359  *  be noted that this is no different than calling 'gtk_object_set_data'
 360  *  with a key of "user_data". It is merely provided as a convenience.
 361  */
 362 void gtk_object_set_user_data (GtkObject *object,
 363                                gpointer   data);
 364
 365 /* Get the "user_data" object data field of "object". It should
 366  *  be noted that this is no different than calling 'gtk_object_get_data'
 367  *  with a key of "user_data". It is merely provided as a convenience.
 368  */
 369 gpointer gtk_object_get_user_data (GtkObject *object);
 370
 371 GtkObject* gtk_object_check_cast (GtkObject *obj,
 372                                   GtkType    cast_type);
 373
 374 GtkObjectClass* gtk_object_check_class_cast (GtkObjectClass *klass,
 375                                              GtkType         cast_type);
 376
 377 void    gtk_trace_referencing   (GtkObject   *object,
 378                                  const gchar *func,
 379                                  guint        dummy,
 380                                  guint        line,
 381                                  gboolean     do_ref);
 382
 383 #if G_ENABLE_DEBUG
 384 #  define gtk_object_ref(o)   G_STMT_START{gtk_trace_referencing((o),G_GNUC_PRETTY_FUNCTION,0,__LINE__,1);}G_STMT_END
 385 #  define gtk_object_unref(o) G_STMT_START{gtk_trace_referencing((o),G_GNUC_PRETTY_FUNCTION,0,__LINE__,0);}G_STMT_END
 386 #endif  /* G_ENABLE_DEBUG && __GNUC__ */
 387
 388
 389
 390 #ifdef __cplusplus
 391 }
 392 #endif /* __cplusplus */
 393
 394
 395 #endif /* __GTK_OBJECT_H__ */