diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/reference/ChangeLog | 10 | ||||
| -rw-r--r-- | docs/reference/glib/tmpl/glib-unused.sgml | 10 | ||||
| -rw-r--r-- | docs/reference/glib/tmpl/misc_utils.sgml | 11 | ||||
| -rw-r--r-- | docs/reference/glib/tmpl/strings.sgml | 6 | ||||
| -rw-r--r-- | docs/reference/gobject/Makefile.am | 97 | ||||
| -rw-r--r-- | docs/reference/gobject/gobject-sections.txt | 104 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/enumerations_flags.sgml | 4 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/gboxed.sgml | 11 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/generic_values.sgml | 300 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/gobject-unused.sgml | 344 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/objects.sgml | 160 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/param_specs.sgml | 4 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/signals.sgml | 25 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/standard_params.sgml | 35 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/types.sgml | 131 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/value_types.sgml | 70 |
16 files changed, 593 insertions, 729 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 98dad9239..5fcacd12b 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,13 @@ +Wed Mar 7 09:33:27 2001 Tim Janik <timj@gtk.org> + + * gobject/Makefile.am: shuffled rules to avoid excessive + rebuilds. + + * gobject/gobject-sections.txt: updates. + + * gobject/tmpl/*: bunch of updates, added another patch + from Eric Lemings <eric.b.lemings@lmco.com>. + 2001-03-07 Sebastian Wilhelmi <wilhelmi@ira.uka.de> * glib/glib-sections.txt, glib/tmpl/messages.sgml: Removed diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml index 1a46e2fa2..63b8f6d70 100644 --- a/docs/reference/glib/tmpl/glib-unused.sgml +++ b/docs/reference/glib/tmpl/glib-unused.sgml @@ -1,3 +1,13 @@ +<!-- ##### USER_FUNCTION GCompareFuncData ##### --> +<para> + +</para> + +@a: +@b: +@user_data: +@Returns: + <!-- ##### USER_FUNCTION GCompletionStrcmpFunc ##### --> <para> diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index 522d9bbf5..e95f0b0e9 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -278,17 +278,6 @@ and has no return value. It is not currently used in GLib or GTK+. @data: -<!-- ##### USER_FUNCTION GCompareFuncData ##### --> -<para> - -</para> - -@a: -@b: -@user_data: -@Returns: - - <!-- ##### FUNCTION g_qsort_with_data ##### --> <para> diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml index 23bfc3bc6..c096bb717 100644 --- a/docs/reference/glib/tmpl/strings.sgml +++ b/docs/reference/glib/tmpl/strings.sgml @@ -78,7 +78,7 @@ you do not have to worry about having enough space to copy the string. @Returns: the destination #GString. -<!-- ##### FUNCTION g_string_sprintf ##### --> +<!-- ##### MACRO g_string_sprintf ##### --> <para> Writes a formatted string into a #GString. This is similar to the standard <function>sprintf()</function> function, @@ -86,19 +86,21 @@ except that the GString buffer automatically expands to contain the results. The previous contents of the GString are destroyed. </para> +<!-- # Unused Parameters # --> @string: a #GString. @format: the string format. See the <function>sprintf()</function> documentation. @Varargs: the parameters to insert into the format string. -<!-- ##### FUNCTION g_string_sprintfa ##### --> +<!-- ##### MACRO g_string_sprintfa ##### --> <para> Appends a formatted string onto the end of a #GString. This function is is similar to g_string_sprintf() except that the text is appended to the GString. </para> +<!-- # Unused Parameters # --> @string: a #GString. @format: the string format. See the <function>sprintf()</function> documentation. diff --git a/docs/reference/gobject/Makefile.am b/docs/reference/gobject/Makefile.am index 82772f7a0..e515bf7fc 100644 --- a/docs/reference/gobject/Makefile.am +++ b/docs/reference/gobject/Makefile.am @@ -2,47 +2,36 @@ # The name of the module. DOC_MODULE=gobject - # The top-level SGML file. DOC_MAIN_SGML_FILE=gobject-docs.sgml - +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE) +EXTRA_DIST += # The directory containing the source code. Relative to $(srcdir) DOC_SOURCE_DIR=../../../gobject - # Extra options to supply to gtkdoc-scan SCAN_OPTIONS= - # Extra options to supply to gtkdoc-mkdb MKDB_OPTIONS= - # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS=--extra-dir=$(srcdir)/../glib/html +# Images to copy into HTML directory +HTML_IMAGES = # Used for dependencies HFILE_GLOB=$(top_srcdir)/gobject/*.h CFILE_GLOB=$(top_srcdir)/gobject/*.c - # Headers to ignore IGNORE_HFILES= \ + .saved \ + glib-genmarshal.c \ gbsearcharray.h - # Extra files to add when scanning EXTRA_HFILES= -# Images to copy into HTML directory -HTML_IMAGES = - -# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE) -content_files = - -# Other files to distribute -extra_files = - # CFLAGS and LDFLAGS for compiling scan program. Only needed # if $(DOC_MODULE).types is non-empty. GTKDOC_CFLAGS = GTKDOC_LIBS = - # Commands for compiling and linking GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC) GTKDOC_LD=$(LIBTOOL) --mode=link $(CC) @@ -54,29 +43,29 @@ GTKDOC_LD=$(LIBTOOL) --mode=link $(CC) TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) -EXTRA_DIST = \ - $(content_files) \ - $(extra_files) \ - $(HTML_IMAGES) \ - $(DOC_MAIN_SGML_FILE) \ - $(DOC_MODULE).types \ - $(DOC_MODULE)-sections.txt \ - $(DOC_MODULE)-overrides.txt +DOC_STAMPS = $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp \ + build-scan.stamp build-tmpl.stamp build-sgml.stamp build-html.stamp +# gtkdoc-mktmpl: creates, and on changes touches: tmpl.stamp +# gtkdoc-mkdb: creates, and on changes touches: sgml.stamp +# gtkdoc-mkhtml: creates, and on changes touches: html.stamp -DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp -if ENABLE_GTK_DOC -all-local: html-build.stamp +.PHONY: gtkdoc-build-all +if ENABLE_GTK_DOC SCANOBJ_FILES = \ $(DOC_MODULE).args \ $(DOC_MODULE).hierarchy \ $(DOC_MODULE).signal -scan-build.stamp: $(HFILE_GLOB) +all-local: gtkdoc-build-all + +gtkdoc-build-all: build-sgml.stamp build-html.stamp + @true +build-scan.stamp: $(HFILE_GLOB) @echo '*** Scanning header files ***' cd $(srcdir) && ( \ - if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \ + if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null 2>/dev/null ; then \ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \ else \ for i in $(SCANOBJ_FILES) ; do \ @@ -85,46 +74,32 @@ scan-build.stamp: $(HFILE_GLOB) fi ) cd $(srcdir) && \ gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) - touch scan-build.stamp - -check_scan: - $(MAKE) scan-build.stamp - -$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan - -tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + touch build-scan.stamp +build-tmpl.stamp: build-scan.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(srcdir)/tmpl/*.sgml @echo '*** Rebuilding template files ***' cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) - touch tmpl-build.stamp - -check_templates: - $(MAKE) tmpl-build.stamp - -tmpl.stamp: check_templates - -sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) + touch build-tmpl.stamp +tmpl.stamp: build-tmpl.stamp + @true +build-sgml.stamp: tmpl.stamp $(CFILE_GLOB) @echo '*** Building SGML ***' cd $(srcdir) && \ gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS) - touch sgml-build.stamp - -check_sgml: - $(MAKE) sgml-build.stamp - -sgml.stamp: check_sgml - -html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) + touch build-sgml.stamp +sgml.stamp: build-sgml.stamp + @true +build-html.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) @echo '*** Building HTML ***' test -d $(srcdir)/html || mkdir $(srcdir)/html cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) @echo '-- Fixing Crossreferences' cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) - touch html-build.stamp + touch build-html.stamp endif clean-local: - rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp + rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) maintainer-clean-local: clean cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt @@ -167,4 +142,12 @@ dist-hook: dist-check-gtkdoc dist-hook-local cp $(srcdir)/$$i $(distdir)/html ; \ done -.PHONY : check_sgml check_templates check_scan dist-hook-local +.PHONY: dist-hook-local + + +EXTRA_DIST = \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE).types \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt index 5c3106882..550c4c240 100644 --- a/docs/reference/gobject/gobject-sections.txt +++ b/docs/reference/gobject/gobject-sections.txt @@ -24,7 +24,6 @@ GTypeInstance GTypeInfo GTypeFundamentalInfo GInterfaceInfo -GTypeValueTable <TITLE>GType</TITLE> G_TYPE_FROM_INSTANCE @@ -141,45 +140,47 @@ GObjectClass GObjectConstructParam GObjectGetPropertyFunc GObjectSetPropertyFunc +GObjectFinalizeFunc +G_TYPE_IS_OBJECT G_OBJECT +G_IS_OBJECT +G_OBJECT_CLASS +G_IS_OBJECT_CLASS G_OBJECT_GET_CLASS G_OBJECT_TYPE G_OBJECT_TYPE_NAME G_OBJECT_CLASS_TYPE G_OBJECT_CLASS_NAME -G_IS_VALUE_OBJECT -G_TYPE_IS_OBJECT -G_IS_OBJECT -G_OBJECT_CLASS -G_IS_OBJECT_CLASS -GObjectFinalizeFunc +G_VALUE_HOLDS_OBJECT g_object_class_install_property g_object_class_find_property g_object_new -g_object_new_valist +g_object_ref +g_object_unref +g_object_connect +g_object_disconnect g_object_set g_object_get -g_object_set_valist -g_object_get_valist -g_object_set_property -g_object_get_property -g_object_freeze_notify g_object_notify +g_object_freeze_notify g_object_thaw_notify -g_object_ref -g_object_unref -g_object_get_qdata -g_object_set_qdata -g_object_set_qdata_full -g_object_steal_qdata g_object_get_data g_object_set_data g_object_set_data_full g_object_steal_data +g_object_get_qdata +g_object_set_qdata +g_object_set_qdata_full +g_object_steal_qdata +g_object_set_property +g_object_get_property +g_object_new_valist +g_object_set_valist +g_object_get_valist +g_object_watch_closure g_value_set_object g_value_get_object g_value_dup_object -g_object_watch_closure G_OBJECT_WARN_INVALID_PROPERTY_ID </SECTION> @@ -198,8 +199,8 @@ G_FLAGS_CLASS G_IS_FLAGS_CLASS G_FLAGS_CLASS_TYPE G_FLAGS_CLASS_TYPE_NAME -G_IS_VALUE_ENUM -G_IS_VALUE_FLAGS +G_VALUE_HOLDS_ENUM +G_VALUE_HOLDS_FLAGS GEnumValue GFlagsValue g_enum_get_value @@ -228,11 +229,12 @@ g_boxed_copy g_boxed_free g_value_set_boxed g_value_set_static_boxed +g_value_set_boxed_take_ownership g_value_get_boxed g_value_dup_boxed g_boxed_type_register_static <SUBSECTION Standard> -G_IS_VALUE_BOXED +G_VALUE_HOLDS_BOXED G_TYPE_IS_BOXED </SECTION> @@ -248,31 +250,48 @@ GValueExchange GValue g_value_init g_value_copy -g_value_convert g_value_reset g_value_unset g_value_fits_pointer +g_value_peek_pointer +g_value_convert g_values_exchange g_value_types_exchangable g_value_register_exchange_func +GTypeValueTable +</SECTION> + +<SECTION> +<TITLE>Value arrays</TITLE> +<FILE>value_types</FILE> +GValueArray +g_value_array_new +g_value_array_copy +g_value_array_free +g_value_array_index +g_value_array_append +g_value_array_prepend +g_value_array_insert +g_value_array_remove +g_value_array_sort +g_value_array_sort_with_data </SECTION> <SECTION> <TITLE>Standard value types</TITLE> <FILE>value_types</FILE> -G_IS_VALUE_CHAR -G_IS_VALUE_UCHAR -G_IS_VALUE_BOOLEAN -G_IS_VALUE_INT -G_IS_VALUE_UINT -G_IS_VALUE_LONG -G_IS_VALUE_ULONG -G_IS_VALUE_FLOAT -G_IS_VALUE_DOUBLE -G_IS_VALUE_STRING -G_IS_VALUE_POINTER -G_IS_VALUE_CCALLBACK -G_IS_VALUE_PARAM +G_VALUE_HOLDS_CHAR +G_VALUE_HOLDS_UCHAR +G_VALUE_HOLDS_BOOLEAN +G_VALUE_HOLDS_INT +G_VALUE_HOLDS_UINT +G_VALUE_HOLDS_LONG +G_VALUE_HOLDS_ULONG +G_VALUE_HOLDS_FLOAT +G_VALUE_HOLDS_DOUBLE +G_VALUE_HOLDS_STRING +G_VALUE_HOLDS_POINTER +G_VALUE_HOLDS_PARAM g_value_set_char g_value_get_char g_value_set_uchar @@ -293,16 +312,14 @@ g_value_set_double g_value_get_double g_value_set_string g_value_set_static_string +g_value_set_string_take_ownership g_value_get_string g_value_dup_string g_value_set_param g_value_get_param g_value_dup_param -g_value_get_ccallback g_value_get_pointer g_value_set_pointer -g_value_get_as_pointer -g_value_set_ccallback g_value_set_instance </SECTION> @@ -374,8 +391,6 @@ G_IS_PARAM_SPEC_POINTER G_PARAM_SPEC_POINTER G_IS_PARAM_SPEC_BOXED G_PARAM_SPEC_BOXED -G_IS_PARAM_SPEC_CCALLBACK -G_PARAM_SPEC_CCALLBACK G_IS_PARAM_SPEC_PARAM G_PARAM_SPEC_PARAM G_IS_PARAM_SPEC_OBJECT @@ -393,7 +408,6 @@ GParamSpecFloat GParamSpecDouble GParamSpecString GParamSpecBoxed -GParamSpecCCallback GParamSpecParam GParamSpecPointer GParamSpecObject @@ -411,7 +425,6 @@ g_param_spec_double g_param_spec_string g_param_spec_string_c g_param_spec_boxed -g_param_spec_ccallback g_param_spec_param g_param_spec_pointer g_param_spec_object @@ -435,6 +448,9 @@ GSignalEmissionHook GSignalFlags GSignalMatchType GSignalQuery +G_SIGNAL_TYPE_STATIC_SCOPE +G_SIGNAL_MATCH_MASK +G_SIGNAL_FLAGS_MASK g_signal_newc g_signal_newv g_signal_new_valist diff --git a/docs/reference/gobject/tmpl/enumerations_flags.sgml b/docs/reference/gobject/tmpl/enumerations_flags.sgml index 971195e5d..c72b7d3fb 100644 --- a/docs/reference/gobject/tmpl/enumerations_flags.sgml +++ b/docs/reference/gobject/tmpl/enumerations_flags.sgml @@ -106,7 +106,7 @@ Enumeration and Flag Types @class: -<!-- ##### MACRO G_IS_VALUE_ENUM ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_ENUM ##### --> <para> </para> @@ -114,7 +114,7 @@ Enumeration and Flag Types @value: -<!-- ##### MACRO G_IS_VALUE_FLAGS ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_FLAGS ##### --> <para> </para> diff --git a/docs/reference/gobject/tmpl/gboxed.sgml b/docs/reference/gobject/tmpl/gboxed.sgml index 1ffd58fb1..0e6835741 100644 --- a/docs/reference/gobject/tmpl/gboxed.sgml +++ b/docs/reference/gobject/tmpl/gboxed.sgml @@ -74,6 +74,15 @@ gboxed @boxed: +<!-- ##### FUNCTION g_value_set_boxed_take_ownership ##### --> +<para> +This is an internal function introduced mainly for C marshallers. +</para> + +@value: +@boxed: + + <!-- ##### FUNCTION g_value_get_boxed ##### --> <para> @@ -98,8 +107,10 @@ gboxed </para> @name: +@boxed_init: @boxed_copy: @boxed_free: +@is_refcounted: @Returns: diff --git a/docs/reference/gobject/tmpl/generic_values.sgml b/docs/reference/gobject/tmpl/generic_values.sgml index 099dd3f90..ab588ec97 100644 --- a/docs/reference/gobject/tmpl/generic_values.sgml +++ b/docs/reference/gobject/tmpl/generic_values.sgml @@ -1,58 +1,75 @@ <!-- ##### SECTION Title ##### --> -Generic values +Generic Values <!-- ##### SECTION Short_Description ##### --> - +A polymorphic type that can hold values of any other type. <!-- ##### SECTION Long_Description ##### --> <para> - +The #GValue structure is basically a variable container that consists +of a type identifier and a specific value of that type. +The type identifier within a #GValue structure always determines the +type of the associated value. +To create a undefined #GValue structure, simply create a zero-filled +#GValue structure. To intialize the #GValue, use the g_value_init() +function. A #GValue cannot be used until it is initialized. +The basic type operations (such as freeing and copying) are determined +by the #GTypeValueTable associated with the type ID stored in the #GValue. +Other #GValue operations (such as converting values between types) are +provided by this interface. </para> <!-- ##### SECTION See_Also ##### --> <para> - +The fundamental types which all support #GValue operations and thus +can be used as a type initializer for g_value_init() are defined by +a separate interface. See the Standard Values API for details. </para> <!-- ##### MACRO G_VALUE_HOLDS ##### --> <para> - +Returns #TRUE if @value holds (or contains) a value of @type. +This macro will also check for @value != #NULL and issue a +warning if the check fails. </para> @value: -@g_type: +@type: <!-- ##### MACRO G_VALUE_TYPE ##### --> <para> - +Returns the type identifier of @value. </para> -@value: +@value: A #GValue structure. <!-- ##### MACRO G_VALUE_TYPE_NAME ##### --> <para> - +Returns the type name of @value. </para> -@value: +@value: A #GValue structure. <!-- ##### MACRO G_TYPE_IS_VALUE ##### --> <para> - +Return whether the passed in type ID can be used for g_value_init(). +That is, this macro checks whether this type provides an implementation +of the #GTypeValueTable functions required for a type to create a #GValue of. </para> -@type: +@type: A #GType value. +@Returns: Whether @type is suitable as a #GValue type. <!-- ##### MACRO G_IS_VALUE ##### --> <para> - +Returns #TRUE if @value is a valid and initialized #GValue structure. </para> -@value: +@value: A #GValue structure. <!-- ##### USER_FUNCTION GValueExchange ##### --> @@ -66,90 +83,269 @@ Generic values <!-- ##### STRUCT GValue ##### --> <para> - +A mostly opaque structure used to hold a #GValue object. Mostly because +the data within the structure has protected scope: it is accessible only +to functions within a #GTypeValueTable structure, or implementations of +the g_value_*() API. </para> <!-- ##### FUNCTION g_value_init ##### --> <para> - +Initializes @value with the default value of @type. </para> -@value: -@g_type: +@value: A zero-filled (uninitialized) #GValue structure. +@g_type: Type the #GValue should hold values of. +@Returns: <!-- ##### FUNCTION g_value_copy ##### --> <para> - +Copies the value of @src_value into @dest_value. </para> -@src_value: -@dest_value: - - -<!-- ##### FUNCTION g_value_convert ##### --> -<para> - -</para> - -@src_value: -@dest_value: -@Returns: +@src_value: An initialized #GValue structure. +@dest_value: An initialized #GValue structure of the same type as @src_value. <!-- ##### FUNCTION g_value_reset ##### --> <para> - +Clears the current value in @value and resets it to the default value +(as if the value had just been initialized). </para> -@value: +@value: An initialized #GValue structure. +@Returns: <!-- ##### FUNCTION g_value_unset ##### --> <para> - +Clears the current value in @value and "unsets" the type, +this releases all resources associated with this GValue. +An unset value is the same as an uninitialized (zero-filled) +#GValue structure. </para> -@value: +@value: An initialized #GValue structure. <!-- ##### FUNCTION g_value_fits_pointer ##### --> <para> - +Determines if @value will fit inside the size of a pointer value. +This is an internal function introduced mainly for C marshallers. </para> -@value: -@Returns: +@value: An initialized #GValue structure. +@Returns: #TRUE if @value will fit inside a pointer value. -<!-- ##### FUNCTION g_values_exchange ##### --> +<!-- ##### FUNCTION g_value_peek_pointer ##### --> <para> - +Return the value contents as pointer. This function asserts that +g_value_fits_pointer() returned #TRUE for the passed in value. +This is an internal function introduced mainly for C marshallers. </para> -@value1: -@value2: -@Returns: +@value: An initialized #GValue structure. +@Returns: #TRUE if @value will fit inside a pointer value. -<!-- ##### FUNCTION g_value_types_exchangable ##### --> +<!-- ##### FUNCTION g_value_convert ##### --> <para> </para> -@value_type1: -@value_type2: +@src_value: +@dest_value: @Returns: -<!-- ##### FUNCTION g_value_register_exchange_func ##### --> +<!-- ##### STRUCT GTypeValueTable ##### --> <para> - +The #GTypeValueTable provides the functions required by the #GValue implementation, +to serve as a container for values of a type. </para> -@value_type1: -@value_type2: -@func: - +@value_init: Default initialize @values contents by poking values + directly into the value->data array. The data array of + the #GValue passed into this function was zero-filled + with memset, so no care has to be taken to free any + old contents. E.g. for the implementation of a string + value that may never be NULL, the implementation might + look like: +<msgtext><programlisting> +{ + value->data[0].v_pointer = g_strdup (""); +} +</programlisting></msgtext> +@value_free: Free any old contents that might be left in the + data array of the passed in @value. No resources may + remain allocated through the #GValue contents after + this function returns. E.g. for our above string type: +<msgtext><programlisting> +{ + /* only free strings without a specific flag for static storage */ + if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) + g_free (value->data[0].v_pointer); +} +</programlisting></msgtext> +@value_copy: @dest_value is a #GValue with zero-filled data section + and @src_value is a properly setup #GValue of same or + derived type. + The purpose of this function is to copy the contents of + @src_value into @dest_value in a way, that even after + @src_value has been freed, the contents of @dest_value + remain valid. String type example: +<msgtext><programlisting> +{ + dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); +} +</programlisting></msgtext> +@value_peek_pointer: If the value contents fit into a pointer, such as objects + or strings, return this pointer, so the caller can peek at + the current contents. To extend on our above string example: +<msgtext><programlisting> +{ + return value->data[0].v_pointer; +} +</programlisting></msgtext> +@collect_format: A string format describing how to collect the contents of + this value, bit-by-bit. Each character in the format represents + an argument to be collected, the characters themselves indicate + the type of the argument. Currently supported arguments are: +<msgtext><variablelist> + <varlistentry><term></term><listitem><para> + 'i' - Integers. passed as collect_values[].v_int. + </para></listitem></varlistentry> + <varlistentry><term></term><listitem><para> + 'l' - Longs. passed as collect_values[].v_long. + </para></listitem></varlistentry> + <varlistentry><term></term><listitem><para> + 'd' - Doubles. passed as collect_values[].v_double. + </para></listitem></varlistentry> + <varlistentry><term></term><listitem><para> + 'p' - Pointers. passed as collect_values[].v_pointer. + </para></listitem></varlistentry> +</variablelist></msgtext> + It should be noted, that for variable argument list construction, + ANSI C promotes every type smaller than an integer to an int, and + floats to doubles. So for collection of short int or char, 'i' + needs to be used, and for collection of floats 'd'. +@collect_value: The collect_value() function is responsible for converting the + values collected from a variable argument list into contents + suitable for storage in a GValue. This function should setup + @value similar to value_init(), e.g. for a string value that + does not allow NULL pointers, it needs to either spew an error, + or do an implicit conversion by storing an empty string. + The @value passed in to this function has a zero-filled data + array, so just like for @value_init it is guarranteed to not + contain any old contents that might need freeing. + @n_collect_values is exactly the string length of @collect_format, + and @collect_values is an array of unions #GTypeCValue with + length @n_collect_values, containing the collected values + according to @collect_format. + @collect_flags is an argument provided as a hint by the caller, + which may contain the flag #G_VALUE_NOCOPY_CONTENTS indicating, + that the collected value contents may be considered "static" + for the duration of the #@value lifetime. + Thus an extra copy of the contents stored in @collect_values is + not required for assignment to @value. + For our above string example, we continue with: +<msgtext><programlisting> +{ + if (!collect_values[0].v_pointer) + value->data[0].v_pointer = g_strdup (""); + else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) + { + value->data[0].v_pointer = collect_values[0].v_pointer; + /* keep a flag for the value_free() implementation to not free this string */ + value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; + } + else + value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); + + return NULL; +} +</programlisting></msgtext> + It should be noted, that it is generally a bad idea to follow the + #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to + reentrancy requirements and reference count assertions performed + by the GSignal code, reference counts should always be incremented + for reference counted contents stored in the value->data array. + To deviate from our string example for a moment, and taking a look + at an exemplary implementation for collect_value() of #GObject: +<msgtext><programlisting> +{ + if (collect_values[0].v_pointer) + { + GObject *object = G_OBJECT (collect_values[0].v_pointer); + + /* never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types */ + value->data[0].v_pointer = g_object_ref (object); + return NULL; + } + else + return g_strdup_printf ("Object passed as invalid NULL pointer"); +} +</programlisting></msgtext> + The reference count for valid objects is always incremented, + regardless of @collect_flags. For invalid objects, the example + returns a newly allocated string without altering @value. + Upon success, collect_value() needs to return NULL, if however + a malicious condition occoured, collect_value() may spew an + error by returning a newly allocated non-NULL string, giving + a suitable description of the error condition. + The calling code makes no assumptions about the @value + contents being valid upon error returns, @value + is simply thrown away without further freeing. As such, it is + a good idea to not allocate #GValue contents, prior to returning + an error, however, collect_values() is not obliged to return + a correctly setup @value for error returns, simply because + any non-NULL return is considered a fatal condition so further + program behaviour is undefined. +@lcopy_format: Format description of the arguments to collect for @lcopy_value, + analogous to @collect_format. Usually, @lcopy_format string consist + only of 'p's to provide lcopy_value() with pointers to storage locations. +@lcopy_value: This function is responsible for storing the @value contents into + arguments passed through a variable argument list which got + collected into @collect_values according to @lcopy_format. + @n_collect_values equals the string length of @lcopy_format, + and @collect_flags may contain #G_VALUE_NOCOPY_CONTENTS. + In contrast to collect_value(), lcopy_value() is obliged to + always properly support #G_VALUE_NOCOPY_CONTENTS. + Similar to collect_value() the function may prematurely abort + by returning a newly allocated string describing an error condition. + To complete the string example: +<msgtext><programlisting> +{ + gchar **string_p = collect_values[0].v_pointer; + + if (!string_p) + return g_strdup_printf ("string location passed as NULL"); + + if (collect_flags & G_VALUE_NOCOPY_CONTENTS) + *string_p = value->data[0].v_pointer; + else + *string_p = g_strdup (value->data[0].v_pointer); + +} +</programlisting></msgtext> + And an exemplary version of lcopy_value() for + reference-counted types: +<msgtext><programlisting> +{ + GObject **object_p = collect_values[0].v_pointer; + + if (!object_p) + return g_strdup_printf ("object location passed as NULL"); + if (!value->data[0].v_pointer) + *object_p = NULL; + else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ + *object_p = value->data[0].v_pointer; + else + *object_p = g_object_ref (value->data[0].v_pointer); + return NULL; +} +</programlisting></msgtext> diff --git a/docs/reference/gobject/tmpl/gobject-unused.sgml b/docs/reference/gobject/tmpl/gobject-unused.sgml index 8098c0650..1fe73b575 100644 --- a/docs/reference/gobject/tmpl/gobject-unused.sgml +++ b/docs/reference/gobject/tmpl/gobject-unused.sgml @@ -1,350 +1,36 @@ -<!-- ##### SECTION ./tmpl/closures.sgml:Long_Description ##### --> +<!-- ##### FUNCTION g_type_value_is_a ##### --> <para> - -</para> - - -<!-- ##### SECTION ./tmpl/closures.sgml:See_Also ##### --> -<para> - -</para> - - -<!-- ##### SECTION ./tmpl/closures.sgml:Short_Description ##### --> - - - -<!-- ##### SECTION ./tmpl/closures.sgml:Title ##### --> -Closures - - -<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Long_Description ##### --> -<para> - -</para> - - -<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:See_Also ##### --> -<para> - -</para> - - -<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Short_Description ##### --> - - - -<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Title ##### --> -gtypemodule.sgml - - -<!-- ##### SECTION ./tmpl/signals.sgml:Long_Description ##### --> -<para> -The basic concept of the signal system is that of the <emphasis>emission</emphasis> -of a signal. -Signals are introduced per-type and are identified through strings. -Signals introduced for a parent type are availale in derived types as well, -so basically they are a per-type facility that is inherited. -A signal emission mainly involves invocation of a certain set of callbacks in -precisely defined manner. There are two main categories of such callbacks, -per-object - <footnote><para> Although signals can deal with any kind of type, i'm - referring to those types as "object types" in the following, simply - because that is the context most users will encounter signals in. - </para></footnote> -ones and user provided ones. -The per-object callbacks are most often referred to as "object method -handler" or "default (signal) handler", while user provided callbacks are -usually just called "signal handler". -The object method handler is provided at signal creation time (this most -frequently happens at the end of an object class' creation), while user -provided handlers are frequently connected and disconnected to/from a certain -signal on certain object instances. -</para> -<para> -A signal emission consists of five stages, unless prematurely stopped: -<variablelist> - <varlistentry><term></term><listitem><para> - 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - </para></listitem></varlistentry> -</variablelist> -The user provided signal handlers are called in the order they were -connected in. -All handlers may prematurely stop a signal emission, and any number of -handlers may be connected, disconnected, blocked or unblocked during -a signal emission. -There are certain criteria for skipping user handlers in stages 2 and 4 -of a signal emission. -First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted -during callback invocation, to return from the "blocked" state, a -handler has to get unblocked exactly the same amount of times -it has been blocked before. -Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional -"detail" argument passed in to g_signal_emit() has to match the detail -argument of the signal handler currently subject to invocation. -Specification of no detail argument for signal handlers (omission of the -detail part of the signal specification upon connection) serves as a -wildcard and matches any detail argument passed in to emission. -</para> - - -<!-- ##### SECTION ./tmpl/signals.sgml:See_Also ##### --> -<para> - -</para> - - -<!-- ##### SECTION ./tmpl/signals.sgml:Short_Description ##### --> -Signals provide a means for customization of object behaviour and are used -as general purpose notification mechanism. - - -<!-- ##### SECTION ./tmpl/signals.sgml:Title ##### --> -Signals - - -<!-- ##### USER_FUNCTION GObjectGetParamFunc ##### --> -<para> - -</para> - -@object: -@param_id: -@value: -@pspec: -@trailer: - -<!-- ##### USER_FUNCTION GObjectSetParamFunc ##### --> -<para> - -</para> - -@object: -@param_id: -@value: -@pspec: -@trailer: - -<!-- ##### ENUM GSignalType ##### --> -<para> - -</para> - -@G_SIGNAL_RUN_FIRST: -@G_SIGNAL_RUN_LAST: -@G_SIGNAL_RUN_CLEANUP: -@G_SIGNAL_NO_RECURSE: -@G_SIGNAL_ACTION: -@G_SIGNAL_NO_HOOKS: - -<!-- ##### USER_FUNCTION GTypePluginFillInterfaceInfo ##### --> -<para> - -</para> - -@plugin: -@interface_type: -@instance_type: -@info: - -<!-- ##### USER_FUNCTION GTypePluginFillTypeInfo ##### --> -<para> - -</para> - -@plugin: -@g_type: -@info: -@value_table: - -<!-- ##### USER_FUNCTION GTypePluginRef ##### --> -<para> - -</para> - -@plugin: - -<!-- ##### USER_FUNCTION GTypePluginUnRef ##### --> -<para> - -</para> - -@plugin: - -<!-- ##### STRUCT GTypePluginVTable ##### --> -<para> - +Determines if @value is a #GValue whose type conforms to @type. </para> -@plugin_ref: -@plugin_unref: -@complete_type_info: -@complete_interface_info: +@value: A valid #GValue structure. +@type: A #GType value. +@Returns: #TRUE if @value is a #GValue of @type or #FALSE if not. -<!-- ##### MACRO G_IS_PARAM_VALUE ##### --> +<!-- ##### FUNCTION g_value_register_exchange_func ##### --> <para> </para> -@pspec: -@value: - -<!-- ##### MACRO G_NOTIFY_PRIORITY ##### --> -<para> - -</para> - - -<!-- ##### MACRO G_WARN_INVALID_PARAM_ID ##### --> -<para> - -</para> - -@object: -@param_id: -@pspec: - -<!-- ##### FUNCTION g_object_class_find_param_spec ##### --> -<para> - -</para> - -@oclass: -@param_name: -@Returns: - -<!-- ##### FUNCTION g_object_class_install_param ##### --> -<para> - -</para> - -@oclass: -@param_id: -@pspec: - -<!-- ##### FUNCTION g_object_get_param ##### --> -<para> - -</para> - -@object: -@param_name: -@value: - -<!-- ##### FUNCTION g_object_queue_param_changed ##### --> -<para> - -</para> - -@object: -@param_name: - -<!-- ##### FUNCTION g_object_set_param ##### --> -<para> - -</para> - -@object: -@param_name: -@value: - -<!-- ##### FUNCTION g_param_spec_hash_table_insert ##### --> -<para> - -</para> - -@hash_table: -@pspec: -@owner_type: - -<!-- ##### FUNCTION g_param_spec_hash_table_lookup ##### --> -<para> - -</para> - -@hash_table: -@param_name: -@owner_type: -@try_ancestors: -@trailer: -@Returns: - -<!-- ##### FUNCTION g_param_spec_hash_table_new ##### --> -<para> - -</para> - -@Returns: - -<!-- ##### FUNCTION g_param_spec_hash_table_remove ##### --> -<para> - -</para> - -@hash_table: -@pspec: - -<!-- ##### FUNCTION g_signal_type_closure_new ##### --> -<para> - -</para> - -@itype: -@struct_offset: -@Returns: - -<!-- ##### FUNCTION g_signals_destroy ##### --> -<para> - -</para> - -@itype: - -<!-- ##### FUNCTION g_type_conforms_to ##### --> -<para> - -</para> - -@type: -@iface_type: -@Returns: - -<!-- ##### FUNCTION g_type_instance_conforms_to ##### --> -<para> - -</para> - -@instance: -@iface_type: -@Returns: +@value_type1: +@value_type2: +@func: -<!-- ##### FUNCTION g_type_is_dynamic ##### --> +<!-- ##### FUNCTION g_value_types_exchangable ##### --> <para> </para> -@type: -@flags: +@value_type1: +@value_type2: @Returns: -<!-- ##### FUNCTION g_type_value_conforms_to ##### --> +<!-- ##### FUNCTION g_values_exchange ##### --> <para> </para> -@value: -@type: +@value1: +@value2: @Returns: diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml index 9cb7851c0..2e69507e1 100644 --- a/docs/reference/gobject/tmpl/objects.sgml +++ b/docs/reference/gobject/tmpl/objects.sgml @@ -34,7 +34,6 @@ The Base Object Type @pspec: @value: -@trailer: <!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### --> <para> @@ -45,6 +44,7 @@ The Base Object Type @property_id: @value: @pspec: +<!-- # Unused Parameters # --> @trailer: @@ -57,10 +57,11 @@ The Base Object Type @property_id: @value: @pspec: +<!-- # Unused Parameters # --> @trailer: -<!-- ##### MACRO G_OBJECT ##### --> +<!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### --> <para> </para> @@ -68,15 +69,15 @@ The Base Object Type @object: -<!-- ##### MACRO G_OBJECT_GET_CLASS ##### --> +<!-- ##### MACRO G_TYPE_IS_OBJECT ##### --> <para> </para> -@object: +@type: -<!-- ##### MACRO G_OBJECT_TYPE ##### --> +<!-- ##### MACRO G_OBJECT ##### --> <para> </para> @@ -84,7 +85,7 @@ The Base Object Type @object: -<!-- ##### MACRO G_OBJECT_TYPE_NAME ##### --> +<!-- ##### MACRO G_IS_OBJECT ##### --> <para> </para> @@ -92,7 +93,7 @@ The Base Object Type @object: -<!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### --> +<!-- ##### MACRO G_OBJECT_CLASS ##### --> <para> </para> @@ -100,7 +101,7 @@ The Base Object Type @class: -<!-- ##### MACRO G_OBJECT_CLASS_NAME ##### --> +<!-- ##### MACRO G_IS_OBJECT_CLASS ##### --> <para> </para> @@ -108,23 +109,23 @@ The Base Object Type @class: -<!-- ##### MACRO G_IS_VALUE_OBJECT ##### --> +<!-- ##### MACRO G_OBJECT_GET_CLASS ##### --> <para> </para> -@value: +@object: -<!-- ##### MACRO G_TYPE_IS_OBJECT ##### --> +<!-- ##### MACRO G_OBJECT_TYPE ##### --> <para> </para> -@type: +@object: -<!-- ##### MACRO G_IS_OBJECT ##### --> +<!-- ##### MACRO G_OBJECT_TYPE_NAME ##### --> <para> </para> @@ -132,7 +133,7 @@ The Base Object Type @object: -<!-- ##### MACRO G_OBJECT_CLASS ##### --> +<!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### --> <para> </para> @@ -140,7 +141,7 @@ The Base Object Type @class: -<!-- ##### MACRO G_IS_OBJECT_CLASS ##### --> +<!-- ##### MACRO G_OBJECT_CLASS_NAME ##### --> <para> </para> @@ -148,12 +149,12 @@ The Base Object Type @class: -<!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_OBJECT ##### --> <para> </para> -@object: +@value: <!-- ##### FUNCTION g_object_class_install_property ##### --> @@ -189,88 +190,88 @@ The Base Object Type @first_param_name: -<!-- ##### FUNCTION g_object_new_valist ##### --> +<!-- ##### FUNCTION g_object_ref ##### --> <para> </para> -@object_type: -@first_property_name: -@var_args: +@object: @Returns: -<!-- # Unused Parameters # --> -@first_param_name: -<!-- ##### FUNCTION g_object_set ##### --> +<!-- ##### FUNCTION g_object_unref ##### --> <para> </para> @object: -@first_property_name: + + +<!-- ##### FUNCTION g_object_connect ##### --> +<para> + +</para> + +@object: +@signal_spec: @Varargs: -<!-- # Unused Parameters # --> -@first_param_name: +@Returns: -<!-- ##### FUNCTION g_object_get ##### --> +<!-- ##### FUNCTION g_object_disconnect ##### --> <para> </para> @object: -@first_property_name: +@signal_spec: @Varargs: -<!-- # Unused Parameters # --> -@first_param_name: +@Returns: -<!-- ##### FUNCTION g_object_set_valist ##### --> +<!-- ##### FUNCTION g_object_set ##### --> <para> </para> @object: @first_property_name: -@var_args: +@Varargs: +@Returns: <!-- # Unused Parameters # --> @first_param_name: -<!-- ##### FUNCTION g_object_get_valist ##### --> +<!-- ##### FUNCTION g_object_get ##### --> <para> </para> @object: @first_property_name: -@var_args: +@Varargs: <!-- # Unused Parameters # --> @first_param_name: -<!-- ##### FUNCTION g_object_set_property ##### --> +<!-- ##### FUNCTION g_object_notify ##### --> <para> </para> @object: @property_name: -@value: -<!-- ##### FUNCTION g_object_get_property ##### --> +<!-- ##### FUNCTION g_object_freeze_notify ##### --> <para> </para> @object: -@property_name: -@value: -<!-- ##### FUNCTION g_object_freeze_notify ##### --> +<!-- ##### FUNCTION g_object_thaw_notify ##### --> <para> </para> @@ -278,38 +279,45 @@ The Base Object Type @object: -<!-- ##### FUNCTION g_object_notify ##### --> +<!-- ##### FUNCTION g_object_get_data ##### --> <para> </para> @object: -@property_name: +@key: +@Returns: -<!-- ##### FUNCTION g_object_thaw_notify ##### --> +<!-- ##### FUNCTION g_object_set_data ##### --> <para> </para> @object: +@key: +@data: -<!-- ##### FUNCTION g_object_ref ##### --> +<!-- ##### FUNCTION g_object_set_data_full ##### --> <para> </para> @object: -@Returns: +@key: +@data: +@destroy: -<!-- ##### FUNCTION g_object_unref ##### --> +<!-- ##### FUNCTION g_object_steal_data ##### --> <para> </para> @object: +@key: +@Returns: <!-- ##### FUNCTION g_object_get_qdata ##### --> @@ -353,45 +361,70 @@ The Base Object Type @Returns: -<!-- ##### FUNCTION g_object_get_data ##### --> +<!-- ##### FUNCTION g_object_set_property ##### --> <para> </para> @object: -@key: +@property_name: +@value: + + +<!-- ##### FUNCTION g_object_get_property ##### --> +<para> + +</para> + +@object: +@property_name: +@value: + + +<!-- ##### FUNCTION g_object_new_valist ##### --> +<para> + +</para> + +@object_type: +@first_property_name: +@var_args: @Returns: +<!-- # Unused Parameters # --> +@first_param_name: -<!-- ##### FUNCTION g_object_set_data ##### --> +<!-- ##### FUNCTION g_object_set_valist ##### --> <para> </para> @object: -@key: -@data: +@first_property_name: +@var_args: +<!-- # Unused Parameters # --> +@first_param_name: -<!-- ##### FUNCTION g_object_set_data_full ##### --> +<!-- ##### FUNCTION g_object_get_valist ##### --> <para> </para> @object: -@key: -@data: -@destroy: +@first_property_name: +@var_args: +<!-- # Unused Parameters # --> +@first_param_name: -<!-- ##### FUNCTION g_object_steal_data ##### --> +<!-- ##### FUNCTION g_object_watch_closure ##### --> <para> </para> @object: -@key: -@Returns: +@closure: <!-- ##### FUNCTION g_value_set_object ##### --> @@ -421,15 +454,6 @@ The Base Object Type @Returns: -<!-- ##### FUNCTION g_object_watch_closure ##### --> -<para> - -</para> - -@object: -@closure: - - <!-- ##### MACRO G_OBJECT_WARN_INVALID_PROPERTY_ID ##### --> <para> diff --git a/docs/reference/gobject/tmpl/param_specs.sgml b/docs/reference/gobject/tmpl/param_specs.sgml index 53319627a..d57c0a40c 100644 --- a/docs/reference/gobject/tmpl/param_specs.sgml +++ b/docs/reference/gobject/tmpl/param_specs.sgml @@ -118,6 +118,7 @@ Parameter Specifications @G_PARAM_WRITABLE: @G_PARAM_CONSTRUCT: @G_PARAM_CONSTRUCT_ONLY: +@G_PARAM_LAX_VALIDATION: @G_PARAM_PRIVATE: <!-- ##### FUNCTION g_param_spec_ref ##### --> @@ -293,8 +294,9 @@ Parameter Specifications @param_name: @owner_type: @walk_ancestors: -@trailer_p: @Returns: +<!-- # Unused Parameters # --> +@trailer_p: <!-- ##### FUNCTION g_param_spec_internal ##### --> diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml index 558b97388..4445fa03d 100644 --- a/docs/reference/gobject/tmpl/signals.sgml +++ b/docs/reference/gobject/tmpl/signals.sgml @@ -15,8 +15,8 @@ so basically they are a per-type facility that is inherited. A signal emission mainly involves invocation of a certain set of callbacks in precisely defined manner. There are two main categories of such callbacks, per-object - <footnote><para> Although signals can deal with any kind of type, i'm - referring to those types as "object types" in the following, simply + <footnote><para> Although signals can deal with any kind of instantiatable type, + i'm referring to those types as "object types" in the following, simply because that is the context most users will encounter signals in. </para></footnote> ones and user provided ones. @@ -182,6 +182,27 @@ filled in by the g_signal_query() function. #gpointer data2); </programlisting></msgtext> +<!-- ##### MACRO G_SIGNAL_TYPE_STATIC_SCOPE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO G_SIGNAL_MATCH_MASK ##### --> +<para> + +</para> + + + +<!-- ##### MACRO G_SIGNAL_FLAGS_MASK ##### --> +<para> + +</para> + + + <!-- ##### FUNCTION g_signal_newc ##### --> <para> diff --git a/docs/reference/gobject/tmpl/standard_params.sgml b/docs/reference/gobject/tmpl/standard_params.sgml index ec7df7c2e..08b218caf 100644 --- a/docs/reference/gobject/tmpl/standard_params.sgml +++ b/docs/reference/gobject/tmpl/standard_params.sgml @@ -238,22 +238,6 @@ Standard Parameter Types @pspec: -<!-- ##### MACRO G_IS_PARAM_SPEC_CCALLBACK ##### --> -<para> - -</para> - -@pspec: - - -<!-- ##### MACRO G_PARAM_SPEC_CCALLBACK ##### --> -<para> - -</para> - -@pspec: - - <!-- ##### MACRO G_IS_PARAM_SPEC_PARAM ##### --> <para> @@ -414,13 +398,6 @@ Standard Parameter Types @parent_instance: -<!-- ##### STRUCT GParamSpecCCallback ##### --> -<para> - -</para> - -@parent_instance: - <!-- ##### STRUCT GParamSpecParam ##### --> <para> @@ -642,18 +619,6 @@ Standard Parameter Types @Returns: -<!-- ##### FUNCTION g_param_spec_ccallback ##### --> -<para> - -</para> - -@name: -@nick: -@blurb: -@flags: -@Returns: - - <!-- ##### FUNCTION g_param_spec_param ##### --> <para> diff --git a/docs/reference/gobject/tmpl/types.sgml b/docs/reference/gobject/tmpl/types.sgml index 4289ca474..87f848d1f 100644 --- a/docs/reference/gobject/tmpl/types.sgml +++ b/docs/reference/gobject/tmpl/types.sgml @@ -178,50 +178,48 @@ interfaces and C++ classes containing only pure virtual functions. The predefined identifiers of the reserved fundamental types. </para> -@G_TYPE_INVALID: Usually a return value indicating an error. -@G_TYPE_NONE: A synonym for the "void" type in C. -@G_TYPE_INTERFACE: Root type of all interface types. -@G_TYPE_CHAR: Identifier for the built-in type "gchar". -@G_TYPE_UCHAR: Identifier for the built-in type "guchar". -@G_TYPE_BOOLEAN: Identifier for the built-in type "gboolean". -@G_TYPE_INT: Identifier for the built-in type "gint". -@G_TYPE_UINT: Identifier for the built-in type "guint". -@G_TYPE_LONG: Identifier for the built-in type "glong". -@G_TYPE_ULONG: Identifier for the built-in type "gulong". -@G_TYPE_ENUM: Identifier for the "#GEnum" type. -@G_TYPE_FLAGS: Identifier for the "#GFlags" type. -@G_TYPE_FLOAT: Identifier for the built-in type "gfloat". +@G_TYPE_INVALID: Usually a return value indicating an error. +@G_TYPE_NONE: A synonym for the "void" type in C. +@G_TYPE_INTERFACE: Root type of all interface types. +@G_TYPE_CHAR: Identifier for the built-in type "gchar". +@G_TYPE_UCHAR: Identifier for the built-in type "guchar". +@G_TYPE_BOOLEAN: Identifier for the built-in type "gboolean". +@G_TYPE_INT: Identifier for the built-in type "gint". +@G_TYPE_UINT: Identifier for the built-in type "guint". +@G_TYPE_LONG: Identifier for the built-in type "glong". +@G_TYPE_ULONG: Identifier for the built-in type "gulong". +@G_TYPE_ENUM: Identifier for the "#GEnum" type. +@G_TYPE_FLAGS: Identifier for the "#GFlags" type. +@G_TYPE_FLOAT: Identifier for the built-in type "gfloat". @G_TYPE_DOUBLE: Identifier for the built-in type "gdouble". @G_TYPE_STRING: Identifier for a pointer to a null-terminated string "gchar*". -@G_TYPE_PARAM: Identifier for the "#GParam" type. -@G_TYPE_BOXED: Identifier for the "#GBoxed" type. -@G_TYPE_POINTER: Identifier for anonymous pointers "void*". -@G_TYPE_CCALLBACK: Identifier for a pointer to a C function. +@G_TYPE_POINTER: Identifier for anonymous pointers "void*". +@G_TYPE_BOXED: Identifier for the "#GBoxed" type. +@G_TYPE_PARAM: Identifier for the "#GParam" type. @G_TYPE_OBJECT: Identifier for the "#GObject" type. -@G_TYPE_GTK_SIGNAL: Reserved for use by the Gtk+ software package. -@G_TYPE_BSE_PROCEDURE: Reserved for use by the BSE software package. -@G_TYPE_BSE_TIME: Reserved for use by the BSE software package. -@G_TYPE_BSE_NOTE: Reserved for use by the BSE software package. -@G_TYPE_BSE_DOTS: Reserved for use by the BSE software package. -@G_TYPE_GLE_GOBJECT: Reserved for use by the GLE software package. -@G_TYPE_LAST_RESERVED_FUNDAMENTAL: New third-party fundamental types have to use IDs higher than this. -@G_TYPE_PARAM_CHAR: Identifier for the "#GParamSpecChar" type. -@G_TYPE_PARAM_UCHAR: Identifier for the "#GParamSpecUChar" type. -@G_TYPE_PARAM_BOOLEAN: Identifier for the "#GParamSpecBoolean" type. -@G_TYPE_PARAM_INT: Identifier for the "#GParamSpecInt" type. -@G_TYPE_PARAM_UINT: Identifier for the "#GParamSpecUInt" type. -@G_TYPE_PARAM_LONG: Identifier for the "#GParamSpecLong" type. -@G_TYPE_PARAM_ULONG: Identifier for the "#GParamSpecULong" type. -@G_TYPE_PARAM_ENUM: Identifier for the "#GParamSpecEnum" type. -@G_TYPE_PARAM_FLAGS: Identifier for the "#GParamSpecFlags" type. -@G_TYPE_PARAM_FLOAT: Identifier for the "#GParamSpecFloat" type. -@G_TYPE_PARAM_DOUBLE: Identifier for the "#GParamSpecDouble" type. -@G_TYPE_PARAM_STRING: Identifier for the "#GParamSpecString" type. -@G_TYPE_PARAM_PARAM: Identifier for the "#GParamSpecParam" type. -@G_TYPE_PARAM_POINTER: Identifier for the "#GParamSpecPointer" type. -@G_TYPE_PARAM_CCALLBACK: Identifier for the "#GParamSpecCCallback" type. -@G_TYPE_PARAM_BOXED: Identifier for the "#GParamSpecBoxed" type. -@G_TYPE_PARAM_OBJECT: Identifier for the "#GParamSpecObject" type. +@G_TYPE_RESERVED_BSE_FIRST: First fundamental type ID reserved for BSE. +@G_TYPE_RESERVED_BSE_LAST: Last fundamental type ID reserved for BSE. +@G_TYPE_RESERVED_LAST_FUNDAMENTAL: Last reserved fundamental type ID. +@G_TYPE_CLOSURE: +@G_TYPE_VALUE_ARRAY: +@G_TYPE_PARAM_CHAR: Identifier for the "#GParamSpecChar" type. +@G_TYPE_PARAM_UCHAR: Identifier for the "#GParamSpecUChar" type. +@G_TYPE_PARAM_BOOLEAN: Identifier for the "#GParamSpecBoolean" type. +@G_TYPE_PARAM_INT: Identifier for the "#GParamSpecInt" type. +@G_TYPE_PARAM_UINT: Identifier for the "#GParamSpecUInt" type. +@G_TYPE_PARAM_LONG: Identifier for the "#GParamSpecLong" type. +@G_TYPE_PARAM_ULONG: Identifier for the "#GParamSpecULong" type. +@G_TYPE_PARAM_ENUM: Identifier for the "#GParamSpecEnum" type. +@G_TYPE_PARAM_FLAGS: Identifier for the "#GParamSpecFlags" type. +@G_TYPE_PARAM_FLOAT: Identifier for the "#GParamSpecFloat" type. +@G_TYPE_PARAM_DOUBLE: Identifier for the "#GParamSpecDouble" type. +@G_TYPE_PARAM_STRING: Identifier for the "#GParamSpecString" type. +@G_TYPE_PARAM_PARAM: Identifier for the "#GParamSpecParam" type. +@G_TYPE_PARAM_BOXED: Identifier for the "#GParamSpecBoxed" type. +@G_TYPE_PARAM_POINTER: Identifier for the "#GParamSpecPointer" type. +@G_TYPE_PARAM_VALUE_ARRAY: Identifier for the "#GParamSpecValueArray" type. +@G_TYPE_PARAM_CLOSURE: Identifier for the "#GParamClosure" type. +@G_TYPE_PARAM_OBJECT: Identifier for the "#GParamSpecObject" type. <!-- ##### STRUCT GTypeInterface ##### --> <para> @@ -256,8 +254,8 @@ across invocation of g_type_register_static(). @instance_size: Size of the instance (object) structure (required for instantiatable types only). @n_preallocs: Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). @instance_init: Location of the instance initialization function (optional, for instantiatable types only). -@value_table: Function table for generic handling of GValues of this type (usualy only usefull for - fundamental types). +@value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usualy only + usefull for fundamental types). <!-- ##### STRUCT GTypeFundamentalInfo ##### --> <para> @@ -278,20 +276,6 @@ used specifically for managing interface types. @interface_data: Location of user data passed to the @interface_init and @interface_finalize functions (optional). -<!-- ##### STRUCT GTypeValueTable ##### --> -<para> - -</para> - -@value_init: -@value_free: -@value_copy: -@value_peek_pointer: -@collect_format: -@collect_value: -@lcopy_format: -@lcopy_value: - <!-- ##### MACRO G_TYPE_FROM_INSTANCE ##### --> <para> Returns the type identifier from a given @instance structure. @@ -423,8 +407,8 @@ Return the unique name that is assigned to a type ID (this is the preferred meth to find out whether a specific type has been registered for the passed in ID yet). </para> -@type: Type to return name for. -@Returns: Static type name or NULL. +@type: Type to return name for. +@Returns: Static type name or NULL. <!-- ##### FUNCTION g_type_qname ##### --> @@ -458,17 +442,17 @@ If the passed in type has no parent, i.e. is a fundamental type, 0 is returned. <!-- ##### FUNCTION g_type_next_base ##### --> <para> -Given a @type and a @base_type which is contained in its anchestry, return -the type that @base_type is the direct parent type for. -In other words, for a given type branch, e.g. Root-Derived1-Derived2-Leaf, specified -through @type=Leaf, return the nextmost child of @base_type. In this example, for -@base_type=Derived1, the returned value would be Derived2, for @base_type=Root, the -returned value would be Derived1. +Given a @leaf_type and a @root_type which is contained in its anchestry, return +the type that @root_type is the immediate parent of. +In other words, this function determines the type that is derived directly from +@root_type which is also a base class of @leaf_type. Given a root type and a +leaf type, this function can be used to determine the types and order in which +the leaf type is descended from the root type. </para> -@type: Descendant of @base_type and the type to be returned. -@base_type: Direct parent of the returned type. -@Returns: Immediate child of @base_type and anchestor of @type. +@leaf_type: Descendant of @root_type and the type to be returned. +@root_type: Immediate parent of the returned type. +@Returns: Immediate child of @root_type and anchestor of @leaf_type. <!-- ##### FUNCTION g_type_is_a ##### --> @@ -799,6 +783,7 @@ Bit masks used to check or determine characteristics of a type. @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type. +@G_TYPE_FLAG_VALUE_ABSTRACT: <!-- ##### ENUM GTypeFundamentalFlags ##### --> <para> @@ -1034,16 +1019,6 @@ the anchestry of @instance. @Returns: -<!-- ##### FUNCTION g_type_value_is_a ##### --> -<para> -Determines if @value is a #GValue whose type conforms to @type. -</para> - -@value: A valid #GValue structure. -@type: A #GType value. -@Returns: #TRUE if @value is a #GValue of @type or #FALSE if not. - - <!-- ##### FUNCTION g_type_value_table_peek ##### --> <para> Returns the location of the #GTypeValueTable associated with @type. diff --git a/docs/reference/gobject/tmpl/value_types.sgml b/docs/reference/gobject/tmpl/value_types.sgml index 9e568b26e..fe77eb6ae 100644 --- a/docs/reference/gobject/tmpl/value_types.sgml +++ b/docs/reference/gobject/tmpl/value_types.sgml @@ -9,20 +9,14 @@ Standard value types </para> + <!-- ##### SECTION See_Also ##### --> <para> </para> -<!-- ##### MACRO G_IS_VALUE_CHAR ##### --> -<para> -</para> - -@value: - - -<!-- ##### MACRO G_IS_VALUE_UCHAR ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_CHAR ##### --> <para> </para> @@ -30,7 +24,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_BOOLEAN ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_UCHAR ##### --> <para> </para> @@ -38,7 +32,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_INT ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_BOOLEAN ##### --> <para> </para> @@ -46,7 +40,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_UINT ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_INT ##### --> <para> </para> @@ -54,7 +48,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_LONG ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_UINT ##### --> <para> </para> @@ -62,7 +56,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_ULONG ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_LONG ##### --> <para> </para> @@ -70,7 +64,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_FLOAT ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_ULONG ##### --> <para> </para> @@ -78,7 +72,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_DOUBLE ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_FLOAT ##### --> <para> </para> @@ -86,7 +80,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_STRING ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_DOUBLE ##### --> <para> </para> @@ -94,7 +88,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_POINTER ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_STRING ##### --> <para> </para> @@ -102,7 +96,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_CCALLBACK ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_POINTER ##### --> <para> </para> @@ -110,7 +104,7 @@ Standard value types @value: -<!-- ##### MACRO G_IS_VALUE_PARAM ##### --> +<!-- ##### MACRO G_VALUE_HOLDS_PARAM ##### --> <para> </para> @@ -298,6 +292,15 @@ Standard value types @v_string: +<!-- ##### FUNCTION g_value_set_string_take_ownership ##### --> +<para> +This is an internal function introduced mainly for C marshallers. +</para> + +@value: +@v_string: + + <!-- ##### FUNCTION g_value_get_string ##### --> <para> @@ -343,16 +346,6 @@ Standard value types @Returns: -<!-- ##### FUNCTION g_value_get_ccallback ##### --> -<para> - -</para> - -@value: -@callback_func: -@callback_data: - - <!-- ##### FUNCTION g_value_get_pointer ##### --> <para> @@ -371,25 +364,6 @@ Standard value types @v_pointer: -<!-- ##### FUNCTION g_value_get_as_pointer ##### --> -<para> - -</para> - -@value: -@Returns: - - -<!-- ##### FUNCTION g_value_set_ccallback ##### --> -<para> - -</para> - -@value: -@callback_func: -@callback_data: - - <!-- ##### FUNCTION g_value_set_instance ##### --> <para> |