Class ParamSpec

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.ParamSpec

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

ParamArray, ParamFraction, ParamSpec.ParamSpec$Impl, ParamSpecBoolean, ParamSpecBoxed, ParamSpecChar, ParamSpecDouble, ParamSpecEnum, ParamSpecExpression, ParamSpecFlags, ParamSpecFloat, ParamSpecGType, ParamSpecInt, ParamSpecInt64, ParamSpecLong, ParamSpecObject, ParamSpecOverride, ParamSpecParam, ParamSpecPointer, ParamSpecString, ParamSpecUChar, ParamSpecUInt, ParamSpecUInt64, ParamSpecULong, ParamSpecUnichar, ParamSpecValueArray, ParamSpecVariant

@Generated("org.javagi.JavaGI")
public abstract class ParamSpec
extends TypeInstance

GParamSpec encapsulates the metadata required to specify parameters, such as GObject properties.

Parameter names

A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the - or _ character. The first character of a property name must be a letter. These are the same rules as for signal naming (see GObjects.signalNew(String, Type, Set, int, SignalAccumulator, SignalCMarshaller, Type, int, Object...)).

When creating and looking up a GParamSpec, either separator can be used, but they cannot be mixed. Using - is considerably more efficient, and is the ‘canonical form’. Using _ is discouraged.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ParamSpec.ParamSpec$Impl	The ParamSpec$Impl type represents a native instance of the abstract ParamSpec class.
static class	ParamSpec.ParamSpecClass	The class structure for the GParamSpec type.

Constructor Summary

Constructors

Constructor	Description
ParamSpec(MemorySegment address)	Create a ParamSpec instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected ParamSpec	asParent()	Return this instance as if it were its parent type.
protected void	finalize_()	The instance finalization function (optional), should chain up to the finalize method of the parent class.
@Nullable String	getBlurb()	Get the short description of a GParamSpec.
Value	getDefaultValue()	Gets the default value of this ParamSpec as a pointer to a GValue.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
String	getName()	Get the name of a GParamSpec.
Quark	getNameQuark()	Gets the GQuark for the name.
String	getNick()	Get the nickname of a GParamSpec.
@Nullable MemorySegment	getQdata(Quark quark)	Gets back user data pointers stored via g_param_spec_set_qdata().
@Nullable ParamSpec	getRedirectTarget()	If the paramspec redirects operations to another paramspec, returns that paramspec.
static Type	getType()	Get the GType of the GParamSpec class.
static ParamSpec	internal(Type paramType, String name, @Nullable String nick, @Nullable String blurb, Set<ParamFlags> flags)	Creates a new GParamSpec instance.
static ParamSpec	internal(Type paramType, String name, @Nullable String nick, @Nullable String blurb, ParamFlags... flags)	Creates a new GParamSpec instance.
static boolean	isValidName(String name)	Validate a property name for a GParamSpec.
ParamSpec	ref()	Increments the reference count of pspec.
ParamSpec	refSink()	Convenience function to ref and sink a GParamSpec.
void	setQdata(Quark quark, @Nullable MemorySegment data)	Sets an opaque, named pointer on a GParamSpec.
void	setQdataFull(Quark quark, @Nullable MemorySegment data)	This function works like g_param_spec_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with data as argument when the this ParamSpec is finalized, or the data is being overwritten by a call to g_param_spec_set_qdata() with the same quark.
void	sink()	The initial reference count of a newly created GParamSpec is 1, even though no one has explicitly called g_param_spec_ref() on it yet.
@Nullable MemorySegment	stealQdata(Quark quark)	Gets back user data pointers stored via g_param_spec_set_qdata() and removes the data from this ParamSpec without invoking its destroy() function (if any was set).
void	unref()	Decrements the reference count of a pspec.
protected boolean	valueIsValid(Value value)	Checks if contents of value comply with the specifications set out by this type, without modifying the value.
protected int	valuesCmp(Value value1, Value value2)	Compares value1 with value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp().
protected void	valueSetDefault(Value value)	Resets a value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default().
protected boolean	valueValidate(Value value)	Ensures that the contents of value comply with the specifications set out by this type (optional), see g_param_value_validate().

Methods inherited from class TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ParamSpec

public ParamSpec(MemorySegment address)

Create a ParamSpec instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the GParamSpec class.

Returns:

always Types.PARAM

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected ParamSpec asParent()

Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.

Returns:

the instance as if it were its parent type

internal

public static ParamSpec internal(Type paramType,
 String name,
 @Nullable String nick,
 @Nullable String blurb,
 Set<ParamFlags> flags)

Creates a new GParamSpec instance.

See GObject.ParamSpec#parameter-names for details of the rules for name. Names which violate these rules lead to undefined behaviour.

Beyond the name, GParamSpecs have two more descriptive strings, the nick and blurb, which may be used as a localized label and description. For GTK and related libraries these are considered deprecated and may be omitted, while for other libraries such as GStreamer and its plugins they are essential. When in doubt, follow the conventions used in the surrounding code and supporting libraries.

Parameters:

paramType - the GType for the property; must be derived from G_TYPE_PARAM

name - the canonical name of the property

nick - the nickname of the property

blurb - a short description of the property

flags - a combination of GParamFlags

Returns:

(transfer floating): a newly allocated GParamSpec instance, which is initially floating

internal

public static ParamSpec internal(Type paramType,
 String name,
 @Nullable String nick,
 @Nullable String blurb,
 ParamFlags... flags)

Creates a new GParamSpec instance.

See GObject.ParamSpec#parameter-names for details of the rules for name. Names which violate these rules lead to undefined behaviour.

Beyond the name, GParamSpecs have two more descriptive strings, the nick and blurb, which may be used as a localized label and description. For GTK and related libraries these are considered deprecated and may be omitted, while for other libraries such as GStreamer and its plugins they are essential. When in doubt, follow the conventions used in the surrounding code and supporting libraries.

Parameters:

paramType - the GType for the property; must be derived from G_TYPE_PARAM

name - the canonical name of the property

nick - the nickname of the property

blurb - a short description of the property

flags - a combination of GParamFlags

Returns:

(transfer floating): a newly allocated GParamSpec instance, which is initially floating

isValidName

public static boolean isValidName(String name)

Validate a property name for a GParamSpec. This can be useful for dynamically-generated properties which need to be validated at run-time before actually trying to create them.

See GObject.ParamSpec#parameter-names for details of the rules for valid names.

Parameters:

name - the canonical name of the property

Returns:

true if name is a valid property name, false otherwise.

Since:

2.66

getBlurb

public @Nullable String getBlurb()

Get the short description of a GParamSpec.

Returns:

the short description of pspec.

getDefaultValue

public Value getDefaultValue()

Gets the default value of this ParamSpec as a pointer to a GValue.

The GValue will remain valid for the life of pspec.

Returns:

a pointer to a GValue which must not be modified

Since:

2.38

getName

public String getName()

Get the name of a GParamSpec.

The name is always an "interned" string (as per g_intern_string()). This allows for pointer-value comparisons.

Returns:

the name of pspec.

getNameQuark

public Quark getNameQuark()

Gets the GQuark for the name.

Returns:

the GQuark for pspec>name.

Since:

2.46

getNick

public String getNick()

Get the nickname of a GParamSpec.

Returns:

the nickname of pspec.

getQdata

public @Nullable MemorySegment getQdata(Quark quark)

Gets back user data pointers stored via g_param_spec_set_qdata().

Parameters:

quark - a GQuark, naming the user data pointer

Returns:

the user data pointer set, or null

getRedirectTarget

public @Nullable ParamSpec getRedirectTarget()

If the paramspec redirects operations to another paramspec, returns that paramspec. Redirect is used typically for providing a new implementation of a property in a derived type while preserving all the properties from the parent type. Redirection is established by creating a property of type GParamSpecOverride. See g_object_class_override_property() for an example of the use of this capability.

Returns:

paramspec to which requests on this paramspec should be redirected, or null if none.

Since:

2.4

ref

public ParamSpec ref()

Increments the reference count of pspec.

Returns:

the GParamSpec that was passed into this function

refSink

public ParamSpec refSink()

Convenience function to ref and sink a GParamSpec.

Returns:

the GParamSpec that was passed into this function

Since:

2.10

setQdata

public void setQdata(Quark quark,
 @Nullable MemorySegment data)

Sets an opaque, named pointer on a GParamSpec. The name is specified through a GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the this ParamSpec with g_param_spec_get_qdata(). Setting a previously set user data pointer, overrides (frees) the old pointer set, using null as pointer essentially removes the data stored.

Parameters:

quark - a GQuark, naming the user data pointer

data - an opaque user data pointer

setQdataFull

public void setQdataFull(Quark quark,
 @Nullable MemorySegment data)

This function works like g_param_spec_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with data as argument when the this ParamSpec is finalized, or the data is being overwritten by a call to g_param_spec_set_qdata() with the same quark.

Parameters:

quark - a GQuark, naming the user data pointer

data - an opaque user data pointer

sink

public void sink()

The initial reference count of a newly created GParamSpec is 1, even though no one has explicitly called g_param_spec_ref() on it yet. So the initial reference count is flagged as "floating", until someone calls g_param_spec_ref (pspec); g_param_spec_sink (pspec); in sequence on it, taking over the initial reference count (thus ending up with a this ParamSpec that has a reference count of 1 still, but is not flagged "floating" anymore).

stealQdata

public @Nullable MemorySegment stealQdata(Quark quark)

Gets back user data pointers stored via g_param_spec_set_qdata() and removes the data from this ParamSpec without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier.

Parameters:

quark - a GQuark, naming the user data pointer

Returns:

the user data pointer set, or null

unref

public void unref()

Decrements the reference count of a pspec.

finalize_

protected void finalize_()

The instance finalization function (optional), should chain up to the finalize method of the parent class.

valueIsValid

protected boolean valueIsValid(Value value)

Checks if contents of value comply with the specifications set out by this type, without modifying the value. This vfunc is optional. If it isn't set, GObject will use valueValidate. Since 2.74

valueSetDefault

protected void valueSetDefault(Value value)

Resets a value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default().

valueValidate

protected boolean valueValidate(Value value)

Ensures that the contents of value comply with the specifications set out by this type (optional), see g_param_value_validate().

valuesCmp

protected int valuesCmp(Value value1,
 Value value2)

Compares value1 with value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp().