@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2016 - 2024 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@node GObject_
@subsection GObject

G-Golf GObject low level API.@*
GObject — The base object type


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-object-class-install-property}
@item @ref{g-object-class-find-property}
@item @ref{g-object-class-list-properties}
@item @ref{g-object-new}
@item @ref{g-object-new-with-properties}
@item @ref{g-object-ref}
@item @ref{g-object-unref}
@item @ref{g-object-ref-sink}
@item @ref{g-object-ref-count}
@item @ref{g-object-is-floating}
@item @ref{g-object-add-toggle-ref}
@item @ref{g-object-remove-toggle-ref}
@item @ref{g-object-type}
@item @ref{g-object-type-name}
@item @ref{g-object-get-property}
@item @ref{g-object-set-property}
@end table
@end indentedblock


@c @subheading Types and Values

@c @indentedblock
@c @table @code
@c @item @ref{%g-type-fundamental-flags}
@c @end table
@c @end indentedblock


@subheading Object Hierarchy

@indentedblock
GObject           	       @*
@ @ +--- GBinding	       @*
@ @ +--- GInitiallyUnowned     @*
@ @ +--- GTypeModule	       @*
@end indentedblock


@subheading Description

@code{GObject} is the fundamental type providing the common attributes
and methods for all object types in @code{GTK+}, @code{Pango} and other
libraries based on GObject. The GObject class provides methods for
object construction and destruction, property access methods, and signal
support.

Please read the @uref{@value{UGOBJECT-GObject}, GObject} section from
the GObject reference manual for a complete description.


@subheading Procedures

Note: in this section, unless otherwise specified, the @var{object}
argument is [must be] a pointer to a @code{GObject} (instance).


@anchor{g-object-class-install-property}
@deffn Procedure g-object-class-install-property g-class p-id p-spec

Returns nothing.

Installs a new property.

The arguments are @var{g-class} a (pointer to a) @code{GObjectClass}),
 @var{p-id} the id for the new property, and @var{p-spec} the (a pointer
 to the) @code{GParamSpec} for the new property.

All properties should be installed during the class initializer. It is
possible to install properties after that, but doing so is not
recommend, and specifically, is not guaranteed to be thread-safe vs. use
of properties on the same type on other threads.

Note that it is possible to redefine a property in a derived class, by
installing a property with the same name. This can be useful at times,
e.g. to change the range of allowed values or the default value.
@end deffn


@anchor{g-object-class-find-property}
@deffn Procedure g-object-class-find-property g-class name

Returns a pointer or @code{#f}.

Obtains and returns (a pointer to) the @code{GParamSpec} for @var{name},
or @code{#f} if @var{g-class} (a pointer to a @code{GObjectClass})
doesn't have a property of that @var{name}.
@end deffn


@anchor{g-object-class-list-properties}
@deffn Procedure g-object-class-list-properties g-class

Returns two values.

Obtains and returns (1) the (possibly empty) list of GParamSpec
pointers for @var{g-class} and (2) its length (the number of properties
for @var{g-class}).
@end deffn


@anchor{g-object-new}
@deffn Procedure g-object-new gtype

Returns a pointer.

Creates and returns a (pointer to) a new instance of a GObject subtype
@var{gtype}.  All properties are set to there default values.
@end deffn


@anchor{g-object-new-with-properties}
@deffn Procedure g-object-new-with-properties gtype n-prop names g-values

Returns a pointer.

Creates and returns a (pointer to) a new instance of a GObject subtype
@var{gtype}. The other arguments are @var{n-prop} the number of
properties, @var{names} a pointer to an array of pointers to strings
with the names of each property to be set and @var{values} an array of
@code{GValue} containing the values of each property to be set.

Properties that are not explicitly specified are set to there default
values.
@end deffn


@anchor{g-object-ref}
@deffn Procedure g-object-ref object

Returns a pointer.

Increases the reference count of @var{object}.
@end deffn


@anchor{g-object-unref}
@deffn Procedure g-object-unref object

Returns nothing.

Decreases the reference count of @var{object}. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).

@c If the pointer to the GObject may be reused in future (for example, if
@c it is an instance variable of another object), it is recommended to
@c clear the pointer to NULL rather than retain a dangling pointer to a
@c potentially invalid GObject instance. Use @code{g-clear-object} for this.
@end deffn


@anchor{g-object-ref-sink}
@deffn Procedure g-object-ref-sink object

Returns a pointer.

If @var{object} has a floating reference, then this call @samp{assumes
ownership} of the floating reference, converting it to a normal
reference by clearing the floating flag while leaving the reference
count unchanged.

If @var{object} is not floating, then this call adds a new normal
reference increasing the reference count by one.
@end deffn


@anchor{g-object-ref-count}
@deffn Procedure g-object-ref-count object

Returns an integer.

Obtains and returns the (public GObject struct field) @code{ref_count}
value for @var{object}.
@end deffn


@anchor{g-object-is-floating}
@deffn Procedure g-object-is-floating object

Returns @code{#t} if @var{object} has a floating reference, otherwise it
returns @code{#f}.
@end deffn


@anchor{g-object-add-toggle-ref}
@deffn Procedure g-object-add-toggle-ref object notify data

Returns nothing.

Increases the reference count of @var{object} by one and sets a
callback, @var{notify}, to be called when all other references to
@var{object} are dropped, or when this is already the last reference to
@var{object} and another reference is established.

Please refer to the GObject
@uref{@value{UGOBJECT-Object-add-toggle-ref}, g_object_add_toggle_ref}
documentation for a complete description.

Multiple toggle references may be added to the same gobject, however if
there are multiple toggle references to an object, none of them will
ever be notified until all but one are removed.

@var{object} is (a pointer to) a GObject, @var{notify} is a function to
call when this reference is the last reference to the object, or is no
longer the last reference, and @var{data} is (a pointer to) the data to
pass to @var{notify}. The @var{data} argument can be @code{#f}.
@end deffn


@anchor{g-object-remove-toggle-ref}
@deffn Procedure g-object-remove-toggle-ref object notify data

Returns nothing.

Removes a reference added with @ref{g-object-add-toggle-ref}. The
reference count of @var{object} is decreased by one.

@var{object} is (a pointer to) a GObject, @var{notify} is a function to
call when this reference is the last reference to the object, or is no
longer the last reference, and @var{data} is (a pointer to) the data to
pass to @var{notify}. The @var{data} argument can be @code{#f}.
@end deffn


@anchor{g-object-type}
@deffn Procedure g-object-type object

Returns the @var{GType} (the type id) for @var{object}.
@end deffn


@anchor{g-object-type-name}
@deffn Procedure g-object-type-name object

Returns the @var{GType} name for @var{object}.
@end deffn


@anchor{g-object-get-property}
@deffn Procedure g-object-get-property object property [g-type #f]

Returns the @var{property} value for @var{object}.

The @var{property} argument is (must be) a pointer to a valid
@code{GIPropertyInfo} (@var{property} must point to one of the
properties infos of the class of @var{object}).  The @var{g-type}
argument must be a valid @code{GType} value.  If @code{#f}, which is the
default, @ref{gi-property-g-type} is called.
@end deffn


@anchor{g-object-set-property}
@deffn Procedure g-object-set-property object property value [g-type #f]

Returns @var{value}.

Sets the @var{object} @var{property} to @var{value}.  The
@var{property} argument is (must be) a pointer to a valid
@code{GIPropertyInfo} (@var{property} must point to one of the
properties infos of the class of @var{object}).  The @var{g-type}
argument must be a valid @code{GType} value.  If @code{#f}, which is the
default, @ref{gi-property-g-type} is called.
@end deffn


@c @subheading Types and Values
