@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.


@node GParamSpec
@subsection GParamSpec

G-Golf GObject GParamSpec low level API.@*
GParamSpec — Metadata for parameter specifications.


@subheading Procedures

@indentedblock
@table @code
@item @ref{gi-g-param-spec-show}
@item @ref{g-param-spec-type}
@item @ref{g-param-spec-type-name}
@item @ref{g-param-spec-get-default-value}
@item @ref{g-param-spec-get-name}
@item @ref{g-param-spec-get-nick}
@item @ref{g-param-spec-get-blurb}
@item @ref{g-param-spec-get-flags}
@end table
@end indentedblock


@subheading Types and Values

@indentedblock
@table @code
@item @ref{%g-param-flags}
@end table
@end indentedblock


@subheading Description

@code{GParamSpec} is an object structure that encapsulates the metadata
required to specify parameters, such as e.g. GObject properties.


@subheading Procedures

Note: in this section, the @var{p-spec} argument is [must be] a pointer
to a @code{GParamSpec}.


@anchor{gi-g-param-spec-show}
@deffn Procedure gi-g-param-spec-show p-spec

Returns nothing.

Obtains and displays the following informations about the interface
pointed to by @var{p-spec}:

@lisp
,use (g-golf)
(g-irepository-require "Gtk" #:version "4.0")
@result{} $2 = #<pointer 0x55ae43d74a60>

(gi-import-by-name "Gtk" "Label")
@result{} $3 = #<<gobject-class> <gtk-label> 7f1a75436a50>

(!g-class <gtk-label>)
@result{} $4 = #<pointer 0x55ae43deb0c0>

(g-object-class-find-property $4 "css-classes")
@result{} $5 = #<pointer 0x55ae43d9d510>

(gi-g-param-spec-show $5)
@print{}
@print{} #<pointer 0x55ae43d9d510> is a (pointer to a) GParamSpec:
@print{}
@print{}                name: "css-classes"
@print{}                nick: "CSS Style Classes"
@print{}               blurb: "List of CSS classes"
@print{}              g-type: 94206951022032
@print{}         g-type-name: "GStrv"
@print{}           type-name: g-strv
@print{}
@end lisp

Note that the last item, @code{type-name: g-strv} is not part of the
@code{GParamSpec} structure. It is obtained (and used by G-Golf
internally by calling @code{(@ref{g-name->name} g-type-name)}.
@end deffn


@anchor{g-param-spec-type}
@anchor{g-param-spec-type-name}
@deffn Procedure g-param-spec-type p-spec
@deffnx Procedure g-param-spec-type-name p-spec

Returns an integer or a (symbol) name, respectively.

Obtains and returns the @code{GType} or the @code{GType} (symbol) name
for @var{p-spec}, respectively.
@end deffn


@anchor{g-param-spec-get-default-value}
@deffn Procedure g-param-spec-get-default-value p-spec

Returns a pointer.

Obtains and returns the @var{p-spec} default value as pointer to a
@code{GValue}, which will remain valid for the life of @var{p-spec} and
must not be modified.
@end deffn


@anchor{g-param-spec-get-name}
@anchor{g-param-spec-get-nick}
@anchor{g-param-spec-get-blurb}
@deffn Procedure g-param-spec-get-name p-spec
@deffnx Procedure g-param-spec-get-nick p-spec
@deffnx Procedure g-param-spec-get-blurb p-spec

Returns a string.

Obtains and returns the name, nickname or short description for
@var{p-spec}, respectively.
@end deffn


@anchor{g-param-spec-get-flags}
@deffn Procedure g-param-spec-get-flags p-spec

Returns a (possibly empty) list.

Obtains and returns a list of the combination of @ref{%g-param-flags}
that applies to @var{p-spec}.
@end deffn


@subheading Types and Values

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

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

@indentedblock
@emph{type-name}: GParamFlags  @*
@emph{name}: g-param-flags @*
@emph{enum-set}:
@indentedblock
@table @code
@item readable
the parameter is readable

@item writable
the parameter is writable

@item readwrite
alas for readable writable

@item construct
the parameter will be set upon object construction

@item construct-only
the parameter can only be set upon object construction

@item lax-validation
upon parameter conversion, strict validation is not required

@item static-name
the string used as name when constructing the parameter is guaranteed to
remain valid and unmodified for the lifetime of the parameter. Since 2.8

@item private
internal

@item static-nick
the string used as nick when constructing the parameter is guaranteed to
remain valid and unmmodified for the lifetime of the parameter. Since 2.8

@item static-blurb
the string used as blurb when constructing the parameter is guaranteed
to remain valid and unmodified for the lifetime of the parameter. Since 2.8

@item explicit-notify
calls to @code{g_object_set_property} for this property will not
automatically result in a @samp{notify} signal being emitted: the
implementation must call @code{g_object_notify} themselves in case the
property actually changes. Since: 2.42

@item deprecated
the parameter is deprecated and will be removed in a future version. A
warning will be generated if it is used while running with
@code{G_ENABLE_DIAGNOSTIC=1}. Since 2.26

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