source: trunk/third/gtk/gtk/gtkobject.h @ 17071

Revision 17071, 12.8 KB checked in by ghudson, 23 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r17070, which included commits to RCS files with non-trunk default branches.
Line 
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
20/*
21 * Modified by the GTK+ Team and others 1997-1999.  See the AUTHORS
22 * file for a list of people on the GTK+ Team.  See the ChangeLog
23 * files for a list of changes.  These files are distributed with
24 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
25 */
26
27#ifndef __GTK_OBJECT_H__
28#define __GTK_OBJECT_H__
29
30
31#include <gtk/gtkarg.h>
32#include <gtk/gtkenums.h>
33#include <gtk/gtktypeutils.h>
34#include <gtk/gtkdebug.h>
35
36
37#ifdef __cplusplus
38extern "C" {
39#endif /* __cplusplus */
40
41
42
43/* Macro for casting a pointer to a GtkObject or GtkObjectClass pointer.
44 * The second portion of the ?: statments are just in place to offer
45 * descriptive warning message.
46 */
47#define GTK_OBJECT(object)              ( \
48  GTK_IS_OBJECT (object) ? \
49    (GtkObject*) (object) : \
50    (GtkObject*) gtk_type_check_object_cast ((GtkTypeObject*) (object), GTK_TYPE_OBJECT) \
51)
52#define GTK_OBJECT_CLASS(klass)         ( \
53  GTK_IS_OBJECT_CLASS (klass) ? \
54    (GtkObjectClass*) (klass) : \
55    (GtkObjectClass*) gtk_type_check_class_cast ((GtkTypeClass*) (klass), GTK_TYPE_OBJECT) \
56)
57
58/* Macro for testing whether `object' and `klass' are of type GTK_TYPE_OBJECT.
59 */
60#define GTK_IS_OBJECT(object)           ( \
61  (object) != NULL && \
62  GTK_IS_OBJECT_CLASS (((GtkObject*) (object))->klass) \
63)
64#define GTK_IS_OBJECT_CLASS(klass)      ( \
65  (klass) != NULL && \
66  GTK_FUNDAMENTAL_TYPE (((GtkObjectClass*) (klass))->type) == GTK_TYPE_OBJECT \
67)
68
69/* Macros for extracting various fields from GtkObject and GtkObjectClass.
70 */
71#define GTK_OBJECT_TYPE(obj)              (GTK_OBJECT (obj)->klass->type)
72#define GTK_OBJECT_SIGNALS(obj)           (GTK_OBJECT (obj)->klass->signals)
73#define GTK_OBJECT_NSIGNALS(obj)          (GTK_OBJECT (obj)->klass->nsignals)
74
75/* GtkObject only uses the first 4 bits of the flags field.
76 * Derived objects may use the remaining bits. Though this
77 * is a kinda nasty break up, it does make the size of
78 * derived objects smaller.
79 */
80typedef enum
81{
82  GTK_DESTROYED         = 1 << 0,
83  GTK_FLOATING          = 1 << 1,
84  GTK_CONNECTED         = 1 << 2,
85  GTK_CONSTRUCTED       = 1 << 3
86} GtkObjectFlags;
87
88/* Macros for extracting the object_flags from GtkObject.
89 */
90#define GTK_OBJECT_FLAGS(obj)             (GTK_OBJECT (obj)->flags)
91#define GTK_OBJECT_DESTROYED(obj)         ((GTK_OBJECT_FLAGS (obj) & GTK_DESTROYED) != 0)
92#define GTK_OBJECT_FLOATING(obj)          ((GTK_OBJECT_FLAGS (obj) & GTK_FLOATING) != 0)
93#define GTK_OBJECT_CONNECTED(obj)         ((GTK_OBJECT_FLAGS (obj) & GTK_CONNECTED) != 0)
94#define GTK_OBJECT_CONSTRUCTED(obj)       ((GTK_OBJECT_FLAGS (obj) & GTK_CONSTRUCTED) != 0)
95
96/* Macros for setting and clearing bits in the object_flags field of GtkObject.
97 */
98#define GTK_OBJECT_SET_FLAGS(obj,flag)    G_STMT_START{ (GTK_OBJECT_FLAGS (obj) |= (flag)); }G_STMT_END
99#define GTK_OBJECT_UNSET_FLAGS(obj,flag)  G_STMT_START{ (GTK_OBJECT_FLAGS (obj) &= ~(flag)); }G_STMT_END
100
101/* GtkArg flag bits for gtk_object_add_arg_type
102 */
103typedef enum
104{
105  GTK_ARG_READABLE       = 1 << 0,
106  GTK_ARG_WRITABLE       = 1 << 1,
107  GTK_ARG_CONSTRUCT      = 1 << 2,
108  GTK_ARG_CONSTRUCT_ONLY = 1 << 3,
109  GTK_ARG_CHILD_ARG      = 1 << 4,
110  GTK_ARG_MASK           = 0x1f,
111 
112  /* aliases
113   */
114  GTK_ARG_READWRITE      = GTK_ARG_READABLE | GTK_ARG_WRITABLE
115} GtkArgFlags;
116
117typedef struct _GtkObjectClass  GtkObjectClass;
118
119
120/* The GtkObject structure is the base of the Gtk+ objects hierarchy,
121 * it ``inherits'' from the GtkTypeObject by mirroring its fields,
122 * which must always be kept in sync completely. The GtkObject defines
123 * the few basic items that all derived classes contain.
124 */
125struct _GtkObject
126{
127  /* GtkTypeObject related fields: */
128  GtkObjectClass *klass;
129 
130 
131  /* 32 bits of flags. GtkObject only uses 4 of these bits and
132   *  GtkWidget uses the rest. This is done because structs are
133   *  aligned on 4 or 8 byte boundaries. If a new bitfield were
134   *  used in GtkWidget much space would be wasted.
135   */
136  guint32 flags;
137 
138  /* reference count.
139   * refer to the file docs/refcounting.txt on this issue.
140   */
141  guint ref_count;
142 
143  /* A list of keyed data pointers, used for e.g. the list of signal
144   * handlers or an object's user_data.
145   */
146  GData *object_data;
147};
148
149/* The GtkObjectClass is the base of the Gtk+ objects classes hierarchy,
150 * it ``inherits'' from the GtkTypeClass by mirroring its fields, which
151 * must always be kept in sync completely. The GtkObjectClass defines
152 * the basic necessities for the object inheritance mechanism to work.
153 * Namely, the `signals' and `nsignals' fields as well as the function
154 * pointers, required to end an object's lifetime.
155 */
156struct _GtkObjectClass
157{
158  /* GtkTypeClass fields: */
159  GtkType type;
160 
161 
162  /* The signals this object class handles. "signals" is an
163   *  array of signal ID's.
164   */
165  guint *signals;
166 
167  /* The number of signals listed in "signals".
168   */
169  guint nsignals;
170 
171  /* The number of arguments per class.
172   */
173  guint n_args;
174  GSList *construct_args;
175 
176  /* Non overridable class methods to set and get per class arguments */
177  void (*set_arg) (GtkObject *object,
178                   GtkArg    *arg,
179                   guint      arg_id);
180  void (*get_arg) (GtkObject *object,
181                   GtkArg    *arg,
182                   guint      arg_id);
183 
184  /* The functions that will end an objects life time. In one way ore
185   *  another all three of them are defined for all objects. If an
186   *  object class overrides one of the methods in order to perform class
187   *  specific destruction then it must still invoke its superclass'
188   *  implementation of the method after it is finished with its
189   *  own cleanup. (See the destroy function for GtkWidget for
190   *  an example of how to do this).
191   */
192  void (* shutdown) (GtkObject *object);
193  void (* destroy)  (GtkObject *object);
194 
195  void (* finalize) (GtkObject *object);
196};
197
198
199
200/* Application-level methods */
201
202GtkType gtk_object_get_type             (void);
203
204/* Append a user defined signal without default handler to a class. */
205guint   gtk_object_class_user_signal_new  (GtkObjectClass     *klass,
206                                           const gchar        *name,
207                                           GtkSignalRunType    signal_flags,
208                                           GtkSignalMarshaller marshaller,
209                                           GtkType             return_val,
210                                           guint               nparams,
211                                           ...);
212guint   gtk_object_class_user_signal_newv (GtkObjectClass     *klass,
213                                           const gchar        *name,
214                                           GtkSignalRunType    signal_flags,
215                                           GtkSignalMarshaller marshaller,
216                                           GtkType             return_val,
217                                           guint               nparams,
218                                           GtkType            *params);
219GtkObject*      gtk_object_new            (GtkType             type,
220                                           const gchar        *first_arg_name,
221                                           ...);
222GtkObject*      gtk_object_newv           (GtkType             object_type,
223                                           guint               n_args,
224                                           GtkArg             *args);
225void gtk_object_default_construct         (GtkObject          *object);
226void gtk_object_constructed               (GtkObject          *object);
227void gtk_object_sink      (GtkObject        *object);
228void gtk_object_ref       (GtkObject        *object);
229void gtk_object_unref     (GtkObject        *object);
230void gtk_object_weakref   (GtkObject        *object,
231                           GtkDestroyNotify  notify,
232                           gpointer          data);
233void gtk_object_weakunref (GtkObject        *object,
234                           GtkDestroyNotify  notify,
235                           gpointer          data);
236void gtk_object_destroy   (GtkObject *object);
237
238/* gtk_object_getv() sets an arguments type and value, or just
239 * its type to GTK_TYPE_INVALID.
240 * if GTK_FUNDAMENTAL_TYPE (arg->type) == GTK_TYPE_STRING, it's
241 * the callers response to do a g_free (GTK_VALUE_STRING (arg));
242 */
243void    gtk_object_getv         (GtkObject      *object,
244                                 guint          n_args,
245                                 GtkArg         *args);
246/* gtk_object_get() sets the variable values pointed to by the adresses
247 * passed after the argument names according to the arguments value.
248 * if GTK_FUNDAMENTAL_TYPE (arg->type) == GTK_TYPE_STRING, it's
249 * the callers response to do a g_free (retrived_value);
250 */
251void    gtk_object_get          (GtkObject      *object,
252                                 const gchar    *first_arg_name,
253                                 ...);
254
255/* gtk_object_set() takes a variable argument list of the form:
256 * (..., gchar *arg_name, ARG_VALUES, [repeatedly name/value pairs,] NULL)
257 * where ARG_VALUES type depend on the argument and can consist of
258 * more than one c-function argument.
259 */
260void    gtk_object_set          (GtkObject      *object,
261                                 const gchar    *first_arg_name,
262                                 ...);
263void    gtk_object_setv         (GtkObject      *object,
264                                 guint          n_args,
265                                 GtkArg         *args);
266
267/* Allocate a GtkArg array of size nargs that hold the
268 * names and types of the args that can be used with
269 * gtk_object_set/gtk_object_get. if (arg_flags!=NULL),
270 * (*arg_flags) will be set to point to a newly allocated
271 * guint array that holds the flags of the args.
272 * It is the callers response to do a
273 * g_free (returned_args); g_free (*arg_flags).
274 */
275GtkArg* gtk_object_query_args   (GtkType          class_type,
276                                 guint32        **arg_flags,
277                                 guint           *n_args);
278
279/* Set 'data' to the "object_data" field of the object. The
280 *  data is indexed by the "key". If there is already data
281 *  associated with "key" then the new data will replace it.
282 *  If 'data' is NULL then this call is equivalent to
283 *  'gtk_object_remove_data'.
284 *  The gtk_object_set_data_full variant acts just the same,
285 *  but takes an additional argument which is a function to
286 *  be called when the data is removed.
287 *  `gtk_object_remove_data' is equivalent to the above,
288 *  where 'data' is NULL
289 *  `gtk_object_get_data' gets the data associated with "key".
290 */
291void     gtk_object_set_data         (GtkObject      *object,
292                                      const gchar    *key,
293                                      gpointer        data);
294void     gtk_object_set_data_full    (GtkObject      *object,
295                                      const gchar    *key,
296                                      gpointer        data,
297                                      GtkDestroyNotify destroy);
298void     gtk_object_remove_data      (GtkObject      *object,
299                                      const gchar    *key);
300gpointer gtk_object_get_data         (GtkObject      *object,
301                                      const gchar    *key);
302void     gtk_object_remove_no_notify (GtkObject      *object,
303                                      const gchar    *key);
304
305/* Set/get the "user_data" object data field of "object". It should
306 *  be noted that these functions are no different than calling
307 *  `gtk_object_set_data'/`gtk_object_get_data' with a key of "user_data".
308 *  They are merely provided as a convenience.
309 */
310void     gtk_object_set_user_data (GtkObject    *object,
311                                   gpointer      data);
312gpointer gtk_object_get_user_data (GtkObject    *object);
313
314
315/* Object-level methods */
316
317/* Append "signals" to those already defined in "class". */
318void    gtk_object_class_add_signals    (GtkObjectClass *klass,
319                                         guint          *signals,
320                                         guint           nsignals);
321/* the `arg_name' argument needs to be a const static string */
322void    gtk_object_add_arg_type         (const gchar    *arg_name,
323                                         GtkType         arg_type,
324                                         guint           arg_flags,
325                                         guint           arg_id);
326
327/* Object data method variants that operate on key ids. */
328void gtk_object_set_data_by_id          (GtkObject       *object,
329                                         GQuark           data_id,
330                                         gpointer         data);
331void gtk_object_set_data_by_id_full     (GtkObject       *object,
332                                         GQuark           data_id,
333                                         gpointer         data,
334                                         GtkDestroyNotify destroy);
335gpointer gtk_object_get_data_by_id      (GtkObject       *object,
336                                         GQuark           data_id);
337void  gtk_object_remove_data_by_id      (GtkObject       *object,
338                                         GQuark           data_id);
339void  gtk_object_remove_no_notify_by_id (GtkObject       *object,
340                                         GQuark           key_id);
341#define gtk_object_data_try_key     g_quark_try_string
342#define gtk_object_data_force_id    g_quark_from_string
343
344
345/* Non-public methods */
346
347void    gtk_object_arg_set      (GtkObject   *object,
348                                 GtkArg      *arg,
349                                 GtkArgInfo  *info);
350void    gtk_object_arg_get      (GtkObject   *object,
351                                 GtkArg      *arg,
352                                 GtkArgInfo  *info);
353gchar*  gtk_object_args_collect (GtkType      object_type,
354                                 GSList     **arg_list_p,
355                                 GSList     **info_list_p,
356                                 const gchar *first_arg_name,
357                                 va_list      var_args);
358gchar*  gtk_object_arg_get_info (GtkType      object_type,
359                                 const gchar *arg_name,
360                                 GtkArgInfo **info_p);
361void    gtk_trace_referencing   (GtkObject   *object,
362                                 const gchar *func,
363                                 guint        dummy,
364                                 guint        line,
365                                 gboolean     do_ref);
366#ifdef  G_ENABLE_DEBUG
367#  define gtk_object_ref(o)   G_STMT_START{gtk_trace_referencing((o),G_GNUC_PRETTY_FUNCTION,0,__LINE__,1);}G_STMT_END
368#  define gtk_object_unref(o) G_STMT_START{gtk_trace_referencing((o),G_GNUC_PRETTY_FUNCTION,0,__LINE__,0);}G_STMT_END
369#endif  /* G_ENABLE_DEBUG */
370
371
372
373
374
375
376
377
378#ifdef __cplusplus
379}
380#endif /* __cplusplus */
381
382
383#endif /* __GTK_OBJECT_H__ */
Note: See TracBrowser for help on using the repository browser.