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


@node Type Information
@subsection Type Information

G-Golf GObject Type Information low level API.@*
Type Information — The GLib Runtime type identification and management system


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-type->symbol}
@item @ref{symbol->g-type}
@item @ref{g-type-from-class}
@item @ref{g-type-name}
@item @ref{g-type-from-name}
@item @ref{g-type-parent}
@item @ref{g-type-is-a}
@item @ref{g-type-class-ref}
@item @ref{g-type-class-peek}
@item @ref{g-type-class-unref}
@item @ref{g-type-class-peek-parent}
@item @ref{g-type-interface-peek}
@item @ref{g-type-interfaces}
@item @ref{g-type-query}
@item @ref{g-type-register-static-simple}
@item @ref{g-type-add-interface-static}
@item @ref{g-type-fundamental}
@item @ref{g-type-ensure}
@end table
@end indentedblock


@subheading Types and Values

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


@subheading Object Hierarchy

@indentedblock
gpointer           	       @*
@ @ +--- GType		       @*
@end indentedblock


@subheading Description

The @code{GType API} is the foundation of the GObject system. It
provides the facilities for registering and managing all fundamental
data types, user-defined object and interface types.

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


@subheading Procedures


@anchor{g-type->symbol}
@deffn Procedure g-type->symbol g-type

Returns a symbol.

Get the symbol that correspond to the type ID @var{g-type}. Note that
this function (like all other GType API) cannot cope with invalid type
IDs. It accepts validly registered type ID, but randomized type IDs
should not be passed in and will most likely lead to a crash.
@end deffn


@anchor{symbol->g-type}
@deffn Procedure symbol->g-type symbol

Returns a type ID.

Get the type ID for @var{symbol}. Note that this function (like all
other GType API) cannot cope with invalid type ID symbols. It accepts
validly registered type ID symbol, but randomized type IDs should not be
passed in and will most likely lead to a crash.
@end deffn


@anchor{g-type-from-class}
@deffn Procedure g-type-from-class g-class

Returns a GType.

Obtains and returns the GType for @var{g-class} (a pointer to a valid
GTypeClass structure).
@end deffn


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

Returns a string.

Get the unique name that is assigned to @var{g-type}, a type ID. Note
that this function (like all other GType API) cannot cope with invalid
type IDs. It accepts validly registered type ID, but randomized type IDs
should not be passed in and will most likely lead to a crash.
@end deffn


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

Returns a type ID or @code{#f}.

Obtains and returns the type ID for the given type @var{name}, or
@code{#f} if no type has been registered under this @var{name} (this is
the preferred method to find out by name whether a specific type has
been registered yet).
@end deffn


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

Returns a @code{GType}.

Returns the direct parent type for @var{g-type}. If @var{g-type} has no
parent, i.e. is a fundamental type, 0 is returned.
@end deffn


@anchor{g-type-is-a}
@deffn Procedure g-type-is-a g-type is-a-g-type

Returns #t if @var{g-type} is a  @var{is-a-g-type}.

If @var{is-a-g-type} is a derivable type, check whether @var{g-type} is
a descendant of @var{is-a-g-type}. If @var{is-a-g-type} is an interface,
check whether  @var{g-type} conforms to it.
@end deffn


@anchor{g-type-class-ref}
@deffn Procedure g-type-class-ref g-type

Returns a pointer.

Obtains and returns a pointer to the @code{GTypeClass} structure for
@var{g-type} (a GObject class GType). The reference count of the class
is incremented, and the class is @samp{created} (instanciated) if/when
it doesn't exist already.
@end deffn


@anchor{g-type-class-peek}
@deffn Procedure g-type-class-peek g-type

Returns a pointer.

Obtains and returns a pointer to the @code{GTypeClass} structure for
@var{g-type} (a GObject class GType). The reference count of the class
isn't incremented. As a consequence, this function may return @code{#f}
- if the class of the type passed in does not currently exist (hasn't
been referenced before).
@end deffn


@anchor{g-type-class-unref}
@deffn Procedure g-type-class-unref g-class

Returns nothing.

Decrements the reference count for @var{g-class} (a pointer to a
@code{GTypeClass} structure). Once the last reference count of a class
has been released, it may be finalized by the type system. Attempting to
further dereference a finalized class is invalid.
@end deffn


@anchor{g-type-class-peek-parent}
@deffn Procedure g-type-class-peek-parent g-class

Returns a pointer or @code{#f}.

Obtains and returns a pointer to the class structure of the immediate
parent type for @var{g-class} (a pointer to a @code{GTypeClass}
structure). If no immediate parent type exists, it returns @code{#f}.
@end deffn


@anchor{g-type-interface-peek}
@deffn Procedure g-type-interface-peek g-class iface-type

Returns a pointer of @code{#f}.

Obtains and returns the (a pointer to) @code{GTypeInterface} structure
for @var{iface-type} if implemented by @var{g-class}, Otherwise. it
returs @code{#f}.
@end deffn


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

Returns a (possibily empty) list.

Obtains and returns the (possibily empty) list of the interface IDs
(g-type) that @var{g-type} conforms to.
@end deffn


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

Returns a list.

Obtains and returns the @code{(g-type type-name class-size
instance-size)} list for @var{g-type}.
@end deffn


@anchor{g-type-register-static-simple}
@deffn Procedure g-type-register-static-simple parent-type type-name @
         class-size class-init-func instance-size instance-init-func flags

Returns a new type ID.

Registers @var{type-name} as the name of a new static type derived from
@var{parent-type}. The value of @var{flags} determines the nature
(e.g. abstract or not) of the type. It works by filling a
@code{GTypeInfo} struct and calling @code{g_type_register_static}.
@end deffn


@anchor{g-type-add-interface-static}
@deffn Procedure g-type-add-interface-static g-type iface-type iface-info

Returns nothing.

Adds @var{iface-type} to the static @var{g-type}. The information
contained in the @code{GInterfaceInfo} structure pointed to by
@var{iface-info} is used to manage the relationship.

If @var{iface-info} is @code{#f}, a new @code{GInterfaceInfo} structure
is made, with @code{iface-init-func} and @code{iface-finalize-func} set
to no-op procedures, and @code{iface-data} set to the %null-pointer
(this is only meant to be used for testing and debugging purposes).
@end deffn


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

Returns a type ID.

Extracts the fundamental type ID portion for @var{g-type}.
@end deffn


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

Returns nothing.

Ensures that the indicated @var{g-type} has been registered with the
type system, and that its @code{_class_init} method has been run.
@end deffn


@subheading Types and Values


@anchor{%g-type-fundamental-flags}
@defivar <gi-enum> %g-type-fundamental-flags

Bit masks used to check or determine specific characteristics of a
fundamental type.

An instance of @code{<gi-enum>}, who's members are the scheme
representation of the @code{GTypeFundamentalFlags}:

@indentedblock
@emph{g-name}: GTypeFundamentalFlags  @*
@emph{name}: g-type-fundamental-flags  @*
@emph{enum-set}:
@indentedblock
@table @code

@item classed
Indicates a classed type

@item instantiable
Indicates an instantiable type (implies classed)

@item derivable
Indicates a flat derivable type

@item deep-derivable
Indicates a deep derivable type (implies derivable)
@end table
@end indentedblock
@end indentedblock
@end defivar


@anchor{%g-type-fundamental-types}
@defivar <gi-enum> %g-type-fundamental-types

An instance of @code{<gi-enum>}, who's members are the scheme
representation of the @code{GType} obtained from the fundamentl types
defined using @code{G_TYPE_MAKE_FUNDAMENTAL}, which starts
with @code{G_TYPE_INVALID} and ends with @code{G_TYPE_OBJECT}.

@indentedblock
@emph{g-name}: #f@footnote{There is no corresponding @code{enum} in
GOject.  These fundamental types (in GObject) are defined using a macro,
@code{G_TYPE_MAKE_FUNDAMENTAL}, that applies bitwise arithmetic shift
given by @code{G_TYPE_FUNDAMENTAL_SHIFT} (which we also have to apply,
to get to the type ID for the fundamental number @code{x}).}
@*

@emph{name}: g-type-fundamental-types @*
@emph{enum-set}:
@indentedblock
@table @code

@item invalid
An invalid GType used as error return value in some functions which
return a GType.

@item none
A fundamental type which is used as a replacement for the C void return
type.

@item interface
The fundamental type from which all interfaces are derived.

@item char
The fundamental type corresponding to gchar. It is unconditionally an
8-bit signed integer. This may or may not be the same type a the C type
"gchar".

@item uchar
The fundamental type corresponding to guchar.

@item boolean
The fundamental type corresponding to gboolean.

@item int
The fundamental type corresponding to gint.

@item uint
The fundamental type corresponding to guint.

@item long
The fundamental type corresponding to glong.

@item ulong
The fundamental type corresponding to gulong.

@item int64
The fundamental type corresponding to gint64.

@item uint64
The fundamental type corresponding to guint64.

@item enum
The fundamental type from which all enumeration types are derived.

@item flags
The fundamental type from which all flags types are derived.

@item float
The fundamental type corresponding to gfloat.

@item double
The fundamental type corresponding to gdouble.

@item string
The fundamental type corresponding to nul-terminated C strings.

@item pointer
The fundamental type corresponding to gpointer.

@item boxed
The fundamental type from which all boxed types are derived.

@item param
The fundamental type from which all @ref{GParamSpec} types are derived.

@item object
The fundamental type for @ref{GObject_}.

@end table
@end indentedblock
@end indentedblock
@end defivar
