@c -*-texinfo-*-

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


@defindex bi


@node Base Info
@subsection Base Info

G-Golf Base Info low level API.@*
GIBaseInfo — Base struct for all GITypelib structs.


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-base-info-ref}
@item @ref{g-base-info-unref}
@item @ref{g-base-info-equal}
@item @ref{g-base-info-get-type}
@item @ref{g-base-info-get-typelib}
@item @ref{g-base-info-get-namespace}
@item @ref{g-base-info-get-name}
@item @ref{g-base-info-get-attribute}
@item @ref{g-base-info-iterate-attributes}
@item @ref{g-base-info-get-container}
@item @ref{g-base-info-is-deprecated}
@end table
@end indentedblock


@subheading Types and Values

@indentedblock
@table @code
@item @ref{%gi-info-type}
@end table
@end indentedblock


@subheading Struct Hierarchy

@indentedblock
GIBaseInfo           	       @*
@ @ +--- GIArgInfo	       @*
@ @ +--- GICallableInfo	       @*
@ @ +--- GIConstantInfo        @*
@ @ +--- GIFieldInfo           @*
@ @ +--- GIPropertyInfo        @*
@ @ +--- GIRegisteredTypeInfo  @*
@ @ +--- GITypeInfo
@end indentedblock


@subheading Description

@code{GIBaseInfo} is the common base struct of all other *Info structs
accessible through the @code{GIRepository API}.

Most @code{GIRepository APIs} returning a @code{GIBaseInfo} is actually
creating a new struct, in other words, @ref{g-base-info-unref} has to be
called when done accessing the data. @code{GIBaseInfos} are normally
accessed by calling either @ref{g-irepository-find-by-name},
@ref{g-irepository-find-by-gtype} or @ref{g-irepository-get-info}.

@example
@strong{Example:} Getting the Button of the Gtk typelib
@end example

@lisp
,use (g-golf gi)
(g-irepository-require "Gtk")
(g-irepository-find-by-name "Gtk" "Button")
@result{} $4 = #<pointer 0x20e0000>
... use button info ...
(g-base-info-unref $4)
@end lisp


@subheading Procedures

Note: in this section, the @var{info}, @var{info1} and @var{info2}
arguments are [must be] pointers to a @code{GIBaseInfo}.

@anchor{g-base-info-ref}
@deffn Procedure g-base-info-ref info

Returns the same @var{info}.

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


@anchor{g-base-info-unref}
@deffn Procedure g-base-info-unref info

Returns nothing.

Decreases the reference count of @var{info}. When its reference count
drops to 0, the @var{info} is freed.
@end deffn


@anchor{g-base-info-equal}
@deffn Procedure g-base-info-equal info1 info2

Returns #t if and only if @var{info1} equals @var{info2}.

Compares two @code{GIBaseInfo}.

Using pointer comparison is not practical since many functions return
different instances of @code{GIBaseInfo} that refers to the same part of
the typelib: use this procedure instead to do @code{GIBaseInfo}
comparisons.
@end deffn

@anchor{g-base-info-get-type}
@deffn Procedure g-base-info-get-type info

Returns the info type of @var{info}.
@end deffn


@anchor{g-base-info-get-typelib}
@deffn Procedure g-base-info-get-typelib info

Returns a pointer to the @code{GITypelib} the @var{info} belongs to.
@end deffn


@anchor{g-base-info-get-namespace}
@deffn Procedure g-base-info-get-namespace info

Returns the namespace of @var{info}
@end deffn


@anchor{g-base-info-get-name}
@deffn Procedure g-base-info-get-name info

Returns the name of @var{info} or @code{#f} if it lacks a name.

What the name represents depends on the @code{GIInfoType} of the
info. For instance for @code{GIFunctionInfo} it is the name of the
function.
@end deffn


@anchor{g-base-info-get-attribute}
@deffn Procedure g-base-info-get-attribute info name

Returns the value of the attribute or @code{#f} if not such attribute
exists.
@end deffn


@anchor{g-base-info-iterate-attributes}
@deffn Procedure g-base-info-iterate-attributes info proc

Returns nothing.

Iterate and calls @var{proc} over all attributes associated with this
node. @var{proc} must be a procedure of two arguments, the @var{name}
and the @var{value} of the attribute.
@end deffn


@anchor{g-base-info-get-container}
@deffn Procedure g-base-info-get-container info

Returns a pointer to a @code{GIBaseInfo}.

The container is the parent @code{GIBaseInfo}. For instance, the parent
of a @code{GIFunctionInfo} is an @code{GIObjectInfo} or
@code{GIInterfaceInfo}.
@end deffn


@anchor{g-base-info-is-deprecated}
@deffn Procedure g-base-info-is-deprecated info

Returns @code{#t} if deprecated.

Obtain whether @var{info} represents a metadata which is deprecated or
not.
@end deffn


@subheading Types and Values

@anchor{%gi-info-type}
@defivar <gi-enum> %gi-info-type

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

@indentedblock
@emph{g-name}: GIInfoType  @*
@emph{name}: gi-info-type @*
@emph{enum-set}:
@indentedblock
invalid		@*
function	@*
callback	@*
struct		@*
boxed		@*
enum		@*
flags		@*
object		@*
interface	@*
constant	@*
error-domain	@*
union		@*
value		@*
signal		@*
vfunc		@*
property	@*
field		@*
arg		@*
type		@*
unresolved
@end indentedblock
@end indentedblock
@end defivar
