@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 Parameters and Values
@subsection Parameters and Values

G-Golf GObject Parameters and Values low level API.@*
Parameters and Values — Standard Parameter and Value Types


@subheading Procedures and Methods

@indentedblock
@table @code
@item @ref{g-value-type}
@item @ref{g-value-type-tag}
@item @ref{g-value-type-name}
@item @ref{g-value-ref}
@item @ref{g-value-set!}
@item @ref{g-param-spec-boolean}
@item @ref{g-value-get-boolean}
@item @ref{g-value-set-boolean}
@item @ref{g-param-spec-int}
@item @ref{g-value-get-int}
@item @ref{g-value-set-int}
@item @ref{g-param-spec-uint}
@item @ref{g-value-get-uint}
@item @ref{g-value-set-uint}
@item @ref{g-param-spec-float}
@item @ref{g-value-get-float}
@item @ref{g-value-set-float}
@item @ref{g-param-spec-double}
@item @ref{g-value-get-double}
@item @ref{g-value-set-double}
@item @ref{g-param-spec-enum}
@item @ref{g-value-get-enum}
@item @ref{g-value-set-enum}
@item @ref{g-param-spec-flags}
@item @ref{g-value-get-flags}
@item @ref{g-value-set-flags}
@item @ref{g-param-spec-string}
@item @ref{g-value-get-string}
@item @ref{g-value-set-string}
@item @ref{g-param-spec-param}
@item @ref{g-value-get-param}
@item @ref{g-value-set-param}
@item @ref{g-param-spec-boxed}
@item @ref{g-value-get-boxed}
@item @ref{g-value-set-boxed}
@item @ref{g-value-get-pointer}
@item @ref{g-value-set-pointer}
@item @ref{g-param-spec-object}
@item @ref{g-value-get-object}
@item @ref{g-value-set-object}
@item @ref{g-value-get-variant}
@end table
@end indentedblock


@subheading Types and Values

@indentedblock
@table @code
@item @ref{g-type-param-boolean}
@item @ref{g-type-param-char}
@item @ref{g-type-param-uchar}
@item @ref{g-type-param-int}
@item @ref{g-type-param-uint}
@item @ref{g-type-param-long}
@item @ref{g-type-param-ulong}
@item @ref{g-type-param-int64}
@item @ref{g-type-param-uint64}
@item @ref{g-type-param-float}
@item @ref{g-type-param-double}
@item @ref{g-type-param-enum}
@item @ref{g-type-param-flags}
@item @ref{g-type-param-string}
@item @ref{g-type-param-param}
@item @ref{g-type-param-boxed}
@item @ref{g-type-param-pointer}
@item @ref{g-type-param-object}
@item @ref{g-type-param-unichar}
@item @ref{g-type-param-override}
@item @ref{g-type-param-gtype}
@item @ref{g-type-param-variant}
@end table
@end indentedblock


@subheading Description

@code{GValue} provides an abstract container structure which can be
copied, transformed and compared while holding a value of any (derived)
type, which is registered as a GType with a GTypeValueTable in its
GTypeInfo structure. Parameter specifications for most value types can
be created as @code{GParamSpec} derived instances, to implement
e.g. @code{GObject properties} which operate on GValue containers.

Parameter names need to start with a letter (a-z or A-Z). Subsequent
characters can be letters, numbers or a '-'. All other characters are
replaced by a '-' during construction.


@subheading Procedures and Methods

Note: in this section, the @var{g-value} argument is [must be] a pointer
to a @code{GValue}.


@anchor{g-value-type}
@anchor{g-value-type-tag}
@anchor{g-value-type-name}
@deffn Procedure g-value-type g-value
@deffnx Procedure g-value-type-tag g-value
@deffnx Procedure g-value-type-name g-value

Returns an integer, a symbol or a string, respectively.

Obtains and returns the @code{GType}, the @code{GType} tag (see
@ref{%g-type-fundamental-types}) or the @code{GType} name (see
@ref{g-type-name} for @var{g-value}, respectively.
@end deffn


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

Returns the content of @var{g-value}.

Obtains and returns the content of @var{g-value}.  Supported
@code{GType} (their scheme representaion) for @var{g-value} are:
@code{boolean}, @code{uint}, @code{int}, @code{float}, @code{double},
@code{enum}, @code{flags}, @code{string}, @code{boxed}, @code{pointer},
@code{object}, @code{interface}.
@end deffn


@anchor{g-value-set!}
@deffn Procedure g-value-set! g-value value

Returns nothing.

Sets the content of @var{g-value} to @var{value}.  Supported
@code{GType} (their scheme representaion) for @var{g-value} are:
@code{boolean}, @code{uint}, @code{int}, @code{float}, @code{double},
@code{enum}, @code{flags}, @code{string}, @code{boxed}, @code{pointer},
@code{object}, @code{interface}.

Note that this procedure cannot cope with invalid values (the type of
@var{value} must correspond to the @code{GType} for @var{g-value},
otherwise it will most likely lead to a crash.
@end deffn


@anchor{g-param-spec-boolean}
@deffn Procedure g-param-spec-boolean name nick blurb @
         default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecBoolean} instance
specifying a @code{G_TYPE_BOOLEAN} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{default} the
default value and @var{flags} the flags - for the property specified.
@end deffn


@anchor{g-value-get-boolean}
@deffn Procedure g-value-get-boolean g-value

Returns @code{#t} or @code{#f}.

Obtains the content of @var{g-value} and returns @code{#f} if it is
@code{0}, otherwise it returns @code{#t}.
@end deffn


@anchor{g-value-set-boolean}
@deffn Procedure g-value-set-boolean g-value val

Returns nothing.

Sets the content of @var{g-value} to @code{0} if @var{val} is
@code{#f}, otherwise sets the content to @code{1}.
@end deffn


@anchor{g-param-spec-int}
@deffn Procedure g-param-spec-int name nick blurb @
         minimum maximum default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecInt} instance
specifying a @code{G_TYPE_INT} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{minimum} the
minimum value, @var{maximum} the maximum value, @var{default} the
default value and @var{flags} the flags - for the property specified.
@end deffn


@anchor{g-value-get-int}
@deffn Procedure g-value-get-int g-value

Returns a integer.

Obtains and returns the content of @var{g-value}.
@end deffn


@anchor{g-value-set-int}
@deffn Procedure g-value-set-int g-value int

Returns nothing.

Sets the content of @var{g-value} to @var{int}.
@end deffn


@anchor{g-param-spec-uint}
@deffn Procedure g-param-spec-uint name nick blurb @
         minimum maximum default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecUInt} instance
specifying a @code{G_TYPE_UINT} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{minimum} the
minimum value, @var{maximum} the maximum value, @var{default} the
default value and @var{flags} the flags - for the property specified.
@end deffn


@anchor{g-value-get-uint}
@deffn Procedure g-value-get-uint g-value

Returns an unsigned integer.

Obtains and returns the content of @var{g-value}.
@end deffn


@anchor{g-value-set-uint}
@deffn Procedure g-value-set-uint g-value uint

Returns nothing.

Sets the content of @var{g-value} to @var{uint}.
@end deffn


@anchor{g-param-spec-float}
@deffn Procedure g-param-spec-float name nick blurb @
         minimum maximum default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecFloat} instance
specifying a @code{G_TYPE_FLOAT} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{minimum} the
minimum value, @var{maximum} the maximum value, @var{default} the
default value and @var{flags} the flags - for the property specified.
@end deffn


@anchor{g-value-get-float}
@deffn Procedure g-value-get-float g-value

Returns a float.

Obtains and returns the content of @var{g-value}.
@end deffn


@anchor{g-value-set-float}
@deffn Procedure g-value-set-float g-value float

Returns nothing.

Sets the content of @var{g-value} to @var{float}.
@end deffn


@anchor{g-param-spec-double}
@deffn Procedure g-param-spec-double name nick blurb @
         minimum maximum default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecDouble} instance
specifying a @code{G_TYPE_DOUBLE} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{minimum} the
minimum value, @var{maximum} the maximum value, @var{default} the
default value and @var{flags} the flags - for the property specified.
@end deffn


@anchor{g-value-get-double}
@deffn Procedure g-value-get-double g-value

Returns a double.

Obtains and returns the content of @var{g-value}.
@end deffn


@anchor{g-value-set-double}
@deffn Procedure g-value-set-double g-value double

Returns nothing.

Sets the content of @var{g-value} to @var{double}.
@end deffn


@anchor{g-param-spec-enum}
@deffn Procedure g-param-spec-enum name nick blurb type @
         default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecEnum} instance
specifying a @code{G_TYPE_ENUM} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{type} a
@code{<gi-enum>} instance, @var{default} the default value and
@var{flags} the flags  - for the property specified.
@end deffn


@anchor{g-value-get-enum}
@deffn Procedure g-value-get-enum g-value

Returns a symbol.

Obtains and returns the (registered) enum type info symbol for
@var{g-value}.
@end deffn


@anchor{g-value-set-enum}
@deffn Method g-value-set-enum g-value (id <integer>)
@deffnx Method g-value-set-enum g-value (sym <symbol>)

Returns nothing.

Sets the content of @var{g-value} to @var{id}, or to the id
corresponding to @var{sym} respectively.  The @var{id} or the @var{sym}
must be valid (as in being a valid member of the (registered) enum type
info for @var{g-value}), otherwise an exception is raised.
@end deffn


@anchor{g-param-spec-flags}
@deffn Procedure g-param-spec-flags name nick blurb type @
         default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecFlags} instance
specifying a @code{G_TYPE_FLAGS} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{type} a
@code{<gi-flags>} instance, @var{default} the default value and
@var{flags} the flags  - for the property specified.
@end deffn


@anchor{g-value-get-flags}
@deffn Procedure g-value-get-flags g-value

Returns a list.

Obtains and returns the (registered) list of flags for @var{g-value}.
@end deffn


@anchor{g-value-set-flags}
@deffn Method g-value-set-flags g-value (val <integer>)
@deffnx Method g-value-set-flags g-value (flags <list>)

Returns nothing.

Sets the content of @var{g-value} to @var{val}, or to the value given by
calling @ref{flags->integer} upon the list of @var{flags},
respectively. The @var{val} or the @var{flags} must be valid (as in
being a valid member of the (registered) gi-flags type for
@var{g-value}), otherwise an exception is raised.
@end deffn


@anchor{g-param-spec-string}
@deffn Procedure g-param-spec-string name nick blurb @
         default flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecString} instance
specifying a @code{G_TYPE_STRING} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{default} the
default value and @var{flags} the flags - for the property specified.
@end deffn


@anchor{g-value-get-string}
@deffn Procedure g-value-get-string g-value

Returns a string or @code{#f}.

Obtains and returns the content of @var{g-value}, a string or @code{#f}
if the @var{g-value} content is the @code{%null-pointer}.
@end deffn


@anchor{g-value-set-string}
@deffn Procedure g-value-set-string g-value str

Returns nothing.

Sets the content of @var{g-value} to @var{str}.
@end deffn


@anchor{g-param-spec-param}
@deffn Procedure g-param-spec-param name nick blurb @
         type flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecParam} instance
specifying a @code{G_TYPE_PARAM} property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{type} a
GType derived from @code{G_TYPE_PARAM} and @var{flags} the flags - for
the property specified.
@end deffn


@anchor{g-value-get-param}
@deffn Procedure g-value-get-param g-value

Returns a (pointer to) @code{GParamSpec} or @code{#f}.

Obtains and returns the content of @var{g-value}, a (pointer to)
@code{GParamSpec} or @code{#f} if the @var{g-value} content is the
@code{%null-pointer}.
@end deffn


@anchor{g-value-set-param}
@deffn Procedure g-value-set-param g-value param

Returns nothing.

Sets the content of @var{g-value} to @var{param}.
@end deffn


@anchor{g-param-spec-boxed}
@deffn Procedure g-param-spec-boxed name nick blurb @
         type flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecBoxed} instance
specifying a @code{G_TYPE_BOXED} derived property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{type} a
GType derived from @code{G_TYPE_BOXED} and @var{flags} the flags - for
the property specified.
@end deffn


@anchor{g-value-get-boxed}
@deffn Procedure g-value-get-boxed g-value

Returns either a list of values, or a pointer.

Obtains and returns the content of @var{g-value}. If the boxed type
@ref{!is-opaque?} or @ref{!is-semi-opaque?}, it @samp{blindingly}
returns the boxed instance @var{g-value} pointer. Otherwise, the boxed
instance is @samp{decoded}, and a list of its field values is returned.
@end deffn


@anchor{g-value-set-boxed}
@deffn Procedure g-value-set-boxed g-value boxed

Returns nothing.

Sets the content of @var{g-value} to @var{boxed}. If the boxed type
@ref{!is-opaque?} or @ref{!is-semi-opaque?}, then @var{boxed} is
(supposed to be) a pointer, used to @samp{blindingly} set
@var{g-value}. Otherwise, the boxed instance is (supposed to be) a list
of values, that are @samp{encoded}, and its (newly created) pointer is
used to set @var{g-value}.
@end deffn


@anchor{g-value-get-pointer}
@deffn Procedure g-value-get-pointer g-value

Returns a pointer.

Obtains and returns the content of @var{g-value}.
@end deffn


@anchor{g-value-set-pointer}
@deffn Procedure g-value-set-pointer g-value pointer

Returns nothing.

Sets the content of @var{g-value} to @var{pointer}.
@end deffn


@anchor{g-param-spec-object}
@deffn Procedure g-param-spec-object name nick blurb type flags

Returns a pointer.

Creates and returns a pointer to a new @code{GParamSpecBoxed} instance
specifying a @code{G_TYPE_OBJECT} derived property.

The @var{name} is the canonical name of the property specified,
@var{nick} its nick name, @var{blurb} its description, @var{type} a
@code{<gobject>} derived type of this property and @var{flags} the flags
- for the property specified.
@end deffn


@anchor{g-value-get-object}
@deffn Procedure g-value-get-object g-value

Returns a pointer.

Obtains and returns the content of @var{g-value}.
@end deffn


@anchor{g-value-set-object}
@deffn Procedure g-value-set-object g-value object

Returns nothing.

Sets the content of @var{g-value} to @var{object} (a pointer to a
@code{GObject} instance) and increases the @var{object} reference count.
@end deffn


@anchor{g-value-get-variant}
@deffn Procedure g-value-get-variant g-value

Returns a pointer or #f.

Obtains and returns content of a variant @var{g-value}, or #f (may be
NULL).
@end deffn


@subheading Types and Values

Note: in GObject, G_TYPE_PARAM_BOOLEAN, G_TYPE_PARAM_CHAR, etc., are
defined as macros. In G-Golf, we define a procedure for each of those
types, which binds a libg-golf function which merely invoques the macro,
the expansion of which returns the corresponding (dynamic - runtime)
GType value.


@anchor{g-type-param-boolean}
@anchor{g-type-param-char}
@anchor{g-type-param-uchar}
@anchor{g-type-param-int}
@anchor{g-type-param-uint}
@anchor{g-type-param-long}
@anchor{g-type-param-ulong}
@anchor{g-type-param-int64}
@anchor{g-type-param-uint64}
@anchor{g-type-param-float}
@anchor{g-type-param-double}
@anchor{g-type-param-enum}
@anchor{g-type-param-flags}
@anchor{g-type-param-string}
@anchor{g-type-param-param}
@anchor{g-type-param-boxed}
@anchor{g-type-param-pointer}
@anchor{g-type-param-object}
@anchor{g-type-param-unichar}
@anchor{g-type-param-override}
@anchor{g-type-param-gtype}
@anchor{g-type-param-variant}
@deffn Procedure g-type-param-boolean
@deffnx Procedure g-type-param-char
@deffnx Procedure g-type-param-uchar
@deffnx Procedure g-type-param-int
@deffnx Procedure g-type-param-uint
@deffnx Procedure g-type-param-long
@deffnx Procedure g-type-param-ulong
@deffnx Procedure g-type-param-int64
@deffnx Procedure g-type-param-uint64
@deffnx Procedure g-type-param-float
@deffnx Procedure g-type-param-double
@deffnx Procedure g-type-param-enum
@deffnx Procedure g-type-param-flags
@deffnx Procedure g-type-param-string
@deffnx Procedure g-type-param-param
@deffnx Procedure g-type-param-boxed
@deffnx Procedure g-type-param-pointer
@deffnx Procedure g-type-param-object
@deffnx Procedure g-type-param-unichar
@deffnx Procedure g-type-param-override
@deffnx Procedure g-type-param-gtype
@deffnx Procedure g-type-param-variant

Returns a GType.

Obtains and returns the GType of @code{GParamSpecBoolean},
@code{GParamSpecChar}, etc.
@end deffn

