1999-08-16 17:58:30 +00:00
|
|
|
<!-- ##### SECTION Title ##### -->
|
|
|
|
Miscellaneous Macros
|
|
|
|
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
2000-09-07 16:36:56 +00:00
|
|
|
specialised macros which are not used often.
|
1999-08-16 17:58:30 +00:00
|
|
|
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
These macros provide more specialized features which are not needed so often
|
|
|
|
by application programmers.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_INLINE_FUNC ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Used to declare inline functions. If inline functions are not supported on
|
|
|
|
the particular platform, the macro evaluates to the empty string.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_STMT_START ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Used within multi-statement macros so that they can be used in places where
|
|
|
|
only one statement is expected by the compiler.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_STMT_END ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Used within multi-statement macros so that they can be used in places where
|
|
|
|
only one statement is expected by the compiler.
|
2000-09-06 00:04:49 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
added newly added gobject/ headers.
Tue Oct 24 22:09:14 2000 Tim Janik <timj@gtk.org>
* glib-object.h: added newly added gobject/ headers.
* gmesage.c: print g_message() output to stderr instead of stdout.
Wed Oct 25 20:27:02 2000 Tim Janik <timj@gtk.org>
* gtype.c (g_type_free_instance): for the moment, freeing object
structures will fill their memory portion with 0xAA. there's a
FIXME there, remove this line at a later point.
Tue Oct 24 23:10:26 2000 Tim Janik <timj@gtk.org>
* glib-genmarshal.1:
* glib-genmarshal.c: added publically installed marshaller generator.
* gtype.h: added G_TYPE_INSTANCE_GET_INTERFACE() to retrive a certain
interface VTable from instances.
Mon Oct 23 08:28:15 2000 Tim Janik <timj@gtk.org>
* gobject.[hc]: new functions for closure maintenance:
(g_object_watch_closure): maintain validity of the object and
the closure for objects that are used as data part of a closure.
(g_cclosure_new_object): convenience function to create C closures
that have an object as data argument.
(g_closure_new_object): convenience function to create closures
that have an object as data argument.
* gclosure.[hc]: implementation of GClosure mechanism.
a closure is basically an encapsulation of a callback function
and its environment. ideally, most places supporting callback
functions will simply take a GClosure* pointer and thus unify
callback environments wrg destroy notification etc.
GClosure provides destroy notifiers for arbitrary data pointers,
reference counting, invalidation notification (it can be invalidated
which is merely a deactivate state) and a marshallinbg abstraction.
GCClosure is also provided in these files, they present a specialized
GClosure implementation for C language callbacks.
* genum.c: macro cleanups.
* gboxed.[hc]: new files, for boxed type abstraction.
(g_boxed_copy): copy a boxed structure
(g_boxed_free): free a boxed structure
(g_value_set_boxed):
(g_value_get_boxed): standard GValue functions for boxed types
(g_boxed_type_register_static): convenience function for easy
introduction of new G_TYPE_BOXED derivatives.
* gparam.[hc]: introduced g_param_type_register_static(), a short hand
for creation of new GParamSpec derived types.
* gtype.[hc]: many fixes, introduced ability to flag individual
type nodes as ABSTRACT upon registration, added value_peek_pointer()
to the value table to peek at GValue contents as a pointer for types
that support this. fixed up GValue checks.
* gvalue.[hc]: added g_value_fits_pointer() and g_value_get_as_pointer()
to peek at the value contents as pointer.
* *.[hc]: adaptions to type macro fixes and changes in the type
registration API.
* many const corrections over the place.
Sat Oct 21 02:49:56 2000 Tim Janik <timj@gtk.org>
* gtype.c (g_type_conforms_to): this function basically behaves like
and is_a check, except that it _additionally_ features interfaces
for instantiatable types. enforce this in the second branch as well
(`type' conforms_to `type') even if `type' is not an interface type.
Fri Oct 20 15:31:04 2000 Tim Janik <timj@gtk.org>
* gvaluetypes.[hc]: added G_TYPE_POINTER implementation from jrb.
* gtype.[hc]:
* gobject.c:
* gvaluetypes.c: added GTypeValueTable.value_peek_pointer and
suitable implementations of this for G_TYPE_STRING, G_TYPE_OBJECT
and G_TYPE_POINTER.
Mon Aug 21 04:13:37 2000 Tim Janik <timj@gtk.org>
* gbsearcharray.[hc]: long standing needed generic implementation
of a binary searchable, sorted and dynamically sized array.
2000-10-25 20:36:35 +00:00
|
|
|
<!-- ##### MACRO G_BEGIN_DECLS ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_END_DECLS ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
2000-09-06 00:04:49 +00:00
|
|
|
<!-- ##### MACRO G_N_ELEMENTS ##### -->
|
|
|
|
<para>
|
|
|
|
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
2000-09-06 00:04:49 +00:00
|
|
|
@arr:
|
1999-08-16 17:58:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_VA_COPY ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Portable way to copy <type>va_list</type> variables.
|
2000-09-06 00:04:49 +00:00
|
|
|
</para>
|
|
|
|
|
2000-10-27 16:48:11 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
2000-09-07 16:36:56 +00:00
|
|
|
@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
|
|
|
|
@ap2: a <type>va_list</type>.
|
2000-09-06 00:04:49 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_STRINGIFY ##### -->
|
|
|
|
<para>
|
|
|
|
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
2000-09-06 00:04:49 +00:00
|
|
|
@macro_or_string:
|
1999-08-16 17:58:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to "__extension__" when GNU C is used as the compiler.
|
|
|
|
This simply tells GNU C not to warn about the following non-standard code
|
|
|
|
when compiling with the -pedantic option.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_CONST ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C const function attribute if the compiler is GNU C.
|
|
|
|
This enables optimization of the function.
|
|
|
|
See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C noreturn function attribute if the compiler is GNU C.
|
|
|
|
It is used for declaring functions which never return.
|
|
|
|
It enables optimization of the function, and avoids possible compiler
|
|
|
|
warnings. See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C unused function attribute if the compiler is GNU C.
|
|
|
|
It is used for declaring functions which may never be used.
|
|
|
|
It avoids possible compiler warnings. See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
added newly added gobject/ headers.
Tue Oct 24 22:09:14 2000 Tim Janik <timj@gtk.org>
* glib-object.h: added newly added gobject/ headers.
* gmesage.c: print g_message() output to stderr instead of stdout.
Wed Oct 25 20:27:02 2000 Tim Janik <timj@gtk.org>
* gtype.c (g_type_free_instance): for the moment, freeing object
structures will fill their memory portion with 0xAA. there's a
FIXME there, remove this line at a later point.
Tue Oct 24 23:10:26 2000 Tim Janik <timj@gtk.org>
* glib-genmarshal.1:
* glib-genmarshal.c: added publically installed marshaller generator.
* gtype.h: added G_TYPE_INSTANCE_GET_INTERFACE() to retrive a certain
interface VTable from instances.
Mon Oct 23 08:28:15 2000 Tim Janik <timj@gtk.org>
* gobject.[hc]: new functions for closure maintenance:
(g_object_watch_closure): maintain validity of the object and
the closure for objects that are used as data part of a closure.
(g_cclosure_new_object): convenience function to create C closures
that have an object as data argument.
(g_closure_new_object): convenience function to create closures
that have an object as data argument.
* gclosure.[hc]: implementation of GClosure mechanism.
a closure is basically an encapsulation of a callback function
and its environment. ideally, most places supporting callback
functions will simply take a GClosure* pointer and thus unify
callback environments wrg destroy notification etc.
GClosure provides destroy notifiers for arbitrary data pointers,
reference counting, invalidation notification (it can be invalidated
which is merely a deactivate state) and a marshallinbg abstraction.
GCClosure is also provided in these files, they present a specialized
GClosure implementation for C language callbacks.
* genum.c: macro cleanups.
* gboxed.[hc]: new files, for boxed type abstraction.
(g_boxed_copy): copy a boxed structure
(g_boxed_free): free a boxed structure
(g_value_set_boxed):
(g_value_get_boxed): standard GValue functions for boxed types
(g_boxed_type_register_static): convenience function for easy
introduction of new G_TYPE_BOXED derivatives.
* gparam.[hc]: introduced g_param_type_register_static(), a short hand
for creation of new GParamSpec derived types.
* gtype.[hc]: many fixes, introduced ability to flag individual
type nodes as ABSTRACT upon registration, added value_peek_pointer()
to the value table to peek at GValue contents as a pointer for types
that support this. fixed up GValue checks.
* gvalue.[hc]: added g_value_fits_pointer() and g_value_get_as_pointer()
to peek at the value contents as pointer.
* *.[hc]: adaptions to type macro fixes and changes in the type
registration API.
* many const corrections over the place.
Sat Oct 21 02:49:56 2000 Tim Janik <timj@gtk.org>
* gtype.c (g_type_conforms_to): this function basically behaves like
and is_a check, except that it _additionally_ features interfaces
for instantiatable types. enforce this in the second branch as well
(`type' conforms_to `type') even if `type' is not an interface type.
Fri Oct 20 15:31:04 2000 Tim Janik <timj@gtk.org>
* gvaluetypes.[hc]: added G_TYPE_POINTER implementation from jrb.
* gtype.[hc]:
* gobject.c:
* gvaluetypes.c: added GTypeValueTable.value_peek_pointer and
suitable implementations of this for G_TYPE_STRING, G_TYPE_OBJECT
and G_TYPE_POINTER.
Mon Aug 21 04:13:37 2000 Tim Janik <timj@gtk.org>
* gbsearcharray.[hc]: long standing needed generic implementation
of a binary searchable, sorted and dynamically sized array.
2000-10-25 20:36:35 +00:00
|
|
|
<!-- ##### MACRO G_GNUC_PURE ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
1999-08-16 17:58:30 +00:00
|
|
|
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C format function attribute if the compiler is GNU C.
|
|
|
|
This is used for declaring functions which take a variable number of
|
|
|
|
arguments, with the same syntax as <function>printf()</function>.
|
|
|
|
It allows the compiler to type-check the arguments passed to the function.
|
|
|
|
See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
2000-09-07 16:36:56 +00:00
|
|
|
@format_idx: the index of the argument corresponding to the format string.
|
|
|
|
(The arguments are numbered from 1).
|
|
|
|
@arg_idx: the index of the first of the format arguments.
|
1999-08-16 17:58:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_SCANF ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C format function attribute if the compiler is GNU C.
|
|
|
|
This is used for declaring functions which take a variable number of
|
|
|
|
arguments, with the same syntax as <function>scanf()</function>.
|
|
|
|
It allows the compiler to type-check the arguments passed to the function.
|
|
|
|
See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
2000-09-07 16:36:56 +00:00
|
|
|
@format_idx: the index of the argument corresponding to the format string.
|
|
|
|
(The arguments are numbered from 1).
|
|
|
|
@arg_idx: the index of the first of the format arguments.
|
1999-08-16 17:58:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C format_arg function attribute if the compiler is GNU C.
|
|
|
|
This is used for declaring functions which take a variable number of
|
|
|
|
parameters, like <function>printf()</function> and
|
|
|
|
<function>scanf()</function>. See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
|
2000-09-07 16:36:56 +00:00
|
|
|
FIXME: I can't find this in my GNU C documentation. Take out?
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
2000-09-07 16:36:56 +00:00
|
|
|
@arg_idx: the index of the argument.
|
1999-08-16 17:58:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C,
|
|
|
|
or "" if it isn't.
|
|
|
|
The GNU C __FUNCTION__ variable contains the name of the current function.
|
|
|
|
See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
|
|
|
|
<para>
|
2000-09-07 16:36:56 +00:00
|
|
|
Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C,
|
|
|
|
or "" if it isn't.
|
|
|
|
The GNU C __PRETTY_FUNCTION__ variable contains the name of the current
|
|
|
|
function. For a C program this is the same as the __FUNCTION__ variable
|
|
|
|
but for C++ it also includes extra information such as the class
|
|
|
|
and function prototype. See the GNU C documentation for details.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
2000-09-06 00:04:49 +00:00
|
|
|
<!-- ##### MACRO G_STRLOC ##### -->
|
1999-08-16 17:58:30 +00:00
|
|
|
<para>
|
2000-09-06 00:04:49 +00:00
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GINT16_FORMAT ##### -->
|
|
|
|
<para>
|
2000-10-30 16:08:23 +00:00
|
|
|
This is the platform dependent conversion specifier for scanning and
|
|
|
|
printing values of type #gint16. It is a string literal, but doesn't
|
|
|
|
include the percent-sign, such that you can add precision and length
|
|
|
|
modifiers between percent-sign and conversion specifier.
|
|
|
|
</para>
|
2000-09-06 00:04:49 +00:00
|
|
|
|
2000-10-30 16:08:23 +00:00
|
|
|
<para>
|
|
|
|
<informalexample>
|
|
|
|
<programlisting>
|
|
|
|
gint16 in;
|
|
|
|
gint32 out;
|
|
|
|
sscanf ("42", "%" G_GINT16_FORMAT, &in)
|
|
|
|
out = in * 1000;
|
|
|
|
g_print ("%" G_GINT32_FORMAT, out);
|
|
|
|
</programlisting>
|
|
|
|
</informalexample>
|
2000-09-06 00:04:49 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GUINT16_FORMAT ##### -->
|
|
|
|
<para>
|
2000-10-30 16:08:23 +00:00
|
|
|
This is the platform dependent conversion specifier for scanning and
|
|
|
|
printing values of type #guint16. See also #G_GINT16_FORMAT.
|
2000-09-06 00:04:49 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GINT32_FORMAT ##### -->
|
|
|
|
<para>
|
2000-10-30 16:08:23 +00:00
|
|
|
This is the platform dependent conversion specifier for scanning and
|
|
|
|
printing values of type #gint32. See also #G_GINT16_FORMAT.
|
2000-09-06 00:04:49 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GUINT32_FORMAT ##### -->
|
|
|
|
<para>
|
2000-10-30 16:08:23 +00:00
|
|
|
This is the platform dependent conversion specifier for scanning and
|
|
|
|
printing values of type #guint32. See also #G_GINT16_FORMAT.
|
2000-09-06 00:04:49 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GINT64_FORMAT ##### -->
|
|
|
|
<para>
|
2000-10-30 16:08:23 +00:00
|
|
|
This is the platform dependent conversion specifier for scanning and
|
|
|
|
printing values of type #gint64. See also #G_GINT16_FORMAT.
|
|
|
|
</para>
|
2000-09-06 00:04:49 +00:00
|
|
|
|
2000-10-30 16:08:23 +00:00
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
Some platforms do not support scanning and printing 64 bit integers,
|
|
|
|
even though the types are supported. On such platforms G_GINT64_FORMAT
|
|
|
|
is not defined.
|
2000-09-06 00:04:49 +00:00
|
|
|
</para>
|
2000-10-30 16:08:23 +00:00
|
|
|
</note>
|
2000-09-06 00:04:49 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_GUINT64_FORMAT ##### -->
|
|
|
|
<para>
|
2000-10-30 16:08:23 +00:00
|
|
|
This is the platform dependent conversion specifier for scanning and
|
|
|
|
printing values of type #guint64. See also #G_GINT16_FORMAT.
|
|
|
|
</para>
|
2000-09-06 00:04:49 +00:00
|
|
|
|
2000-10-30 16:08:23 +00:00
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
Some platforms do not support scanning and printing 64 bit integers,
|
|
|
|
even though the types are supported. On such platforms G_GUINT64_FORMAT
|
|
|
|
is not defined.
|
1999-08-16 17:58:30 +00:00
|
|
|
</para>
|
2000-10-30 16:08:23 +00:00
|
|
|
</note>
|
1999-08-16 17:58:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
|