Projects/Vala/Manual/Attributes

Back to Vala Reference Manual

Attributes

Contents

Attributes

Attributes are metadata information that is specified with regards to a symbol (a class, field, parameter, etc.).

Attributes provide extra information in order to:

Integrate libraries more directly. These are the ones most often used in new Vala programs/libraries.
Control C code generation, particularly with existing libraries. Mostly used in bindings.
Give extra information to Vala that isn't included in code. Mostly used internally in Vala.

Most of these attributes are only useful within bindings. Some, however, are useful in normal code:

[DBus], [Description], [Version], [Signal], [ModuleInit] (if you're writing a module).
CCode's instance_pos (if you're using Gtk.Builder's signal auto-connection functionality).

Applying attributes

They are written as:

[ AnnotationName ( details-list ) ]
declaration

For example:

[ CCode ( cname = "var_c_name" ) ]
static int my_var;

CCode Attribute

This attribute influences the C code which is generated by Vala.

Name	Applies to	Type	Example
Description (optional)
array_length	delegate, field, property, method, parameter	bool
If the array length is unknown, setting array_length = false in the CCode attribute will cause Vala to set the array's .length property to -1 and not pass the length when used as a parameter.
array_length_cname	field	string
array_length_cexpr	field	string
array_length_pos	constructor, delegate, method, parameter	double	0.9
The position of the argument which should be the length of the return array. Integers (such as 1.0, 2.0) specify arguments, so to place it before or after these arguments, use a value less (i.e. 0.9) or more (i.e. 1.1) than the argument.
array_length_type	field, method	string
array_null_terminated	constructor, method, delegate, field, parameter, property	bool
cheader_filename	class, constant, constructor, delegate, enum, field, interface, method, namespace, struct	string - comma-separated list of headers	"glib.h"
The header file(s) which should be #included in the emitted C code, so that this symbol is usable. If more than one header file is needed, separate them by commas.
cname	class, constant, constructor, delegate, enum, field, method, struct, propacc	string	"gboolean"
The name that this symbol will take when translated into C code. If this attribute is not specified, the symbol will get a name with the normal vala translation rules.
const_cname	class, struct	string
construct_function	constructor	string
copy_function	class	string
cprefix	class, enum, namespace, struct	string
default_value	struct	string - C value expression	"FALSE"
A C expression representing this type's default value.
delegate_target	field	bool
delegate_target_pos	constructor, delegate, method, parameter	double	0.1
delegate_target_cname	delegate field/parameter	string	"userdata"
A C expression representing the name of the target/userdata related to a delegate field/parameter.
destroy_function	struct	string
destroy_notify_pos	parameter	double
free_function	class	string
free_function_address_of	class	bool
generic_type_pos	method	double
get_value_function	class, struct	string - function name	"g_value_get_boolean"
A function which will return an object when passed a GValue.
gir_namespace	namespace	string
gir_version	namespace	string
has_construct_function	method	bool
has_copy_function	struct	bool
has_destroy_function	struct	bool
has_new_function	method	bool
has_target	delegate	bool
has_type_id	class, struct, enum	bool	true
This is used to specify whether a corresponding GType must exists.
instance_pos	constructor, delegate, method	double
The argument position of the instance that will be used as `this` in methods.
lower_case_cprefix	namespace	string
lower_case_csuffix	class, enum, errordomain, interface	string
marshaller_type_name	class, struct	string	"BOOLEAN"
notify	property	bool
ordering	virtual method/property/signal	int
Specify the position of the vfunc in the vtable. Once one ordering has been specified in a class, it must be specified for all of the vfuncs.
param_spec_function	class	string
pos	parameter	double
ref_function	class	string
ref_function_void	class	bool
Whether the ref function returns void. Default is `false`.
ref_sink_function	class	string
ref_sink_function_void	class	bool
Whether the ref_sink function returns void. Default is `false`.
returns_floating_reference	method	bool
Whether the method returns a floating reference to an object.
sentinel	constructor, method	string
Sentinel value to use as the last of variadic arguments.
scope	delegate, parameter	string	"async"
Scope of the delegate as in GIR notation.
set_value_function	class, struct	string - function name	"g_value_set_boolean"
A function that will set a GValue with an object of this type.
simple_generics	method	bool
take_value_function	class	string
type	class, interface, field, parameter, method	string
type_check_function	class	string
type_cname	interface	string
type_id	class, enum, struct	string	"G_TYPE_BOOLEAN"
The GObject type system type that this object is registered with. If type_id is not specified, Vala uses a type ID based on the type's name.
type_signature	class, interface, struct	string
Will be soon moved to DBus.
unref_function	class	string
vfunc_name	constructor, method	string

Version attribute

Used to annotate symbols with versioning information.

Available since Vala 0.31.1.

Name	Type	Description
since	string	Version number - if used will be checked against locally installed package version.
deprecated	bool	Was `[Deprecated]`
deprecated_since	string	Version number
replacement	string	Symbol name
experimental	bool	Was `[Experimental]`
experimental_until	string	Version number

SimpleType attribute

This attribute is applied to structs. Consider reading: Vala Manual - Value Types and Vala Tutorial - Value Types.

BooleanType Attribute

This attribute is applied to structs, combined with SimpleType. Marks the struct as being a boolean type.

IntegerType Attribute

This attribute is applied to structs, combined with SimpleType. Marks the struct as being an integer number type.

Name	Type
min	integer
max	integer
rank	integer
width	integer
signed	bool

FloatingType Attribute

This attribute is applied to structs, combined with SimpleType. Marks the struct as being a floating point number type.

Name	Type
decimal	bool
rank	integer
width	integer

Signal Attribute

This attribute influences the generation and usage of object signals, mostly for the GObject type system. The default is G_SIGNAL_RUN_LAST.

Name	Type
Description (optional)
detailed	bool
Sets the G_SIGNAL_DETAILED flag.
no_recurse	bool
Sets the G_SIGNAL_NO_RECURSE flag.
run	string
Significant values are "first", "last" or "cleanup". Default is "last".
action	bool
Sets the G_SIGNAL_ACTION flag.
no_hooks	bool
Sets the G_SIGNAL_NO_HOOKS flag.

Description Attribute

This attribute influences the generation and usage of object properties, mostly for the GObject type system.

Name	Type
nick	string
blurb	string

DBus Attribute

This attribute influences the generation of DBus interfaces (for servers) or DBus calls (for clients) which are generated by Vala.

Name	Applies to	Type	Example
Description (optional)
name	class, interface, method, property, signal	string	"org.my.interface" or "MyMember"
signature	string
This makes it possible to use GVariant in D-Bus clients and servers without automatic boxing/unboxing.
use_string_marshalling	enum	bool
Marshalling enum values as strings
value	enumvalue	string
Marshalling enum values as strings
use_string_marshalling	enum	bool
timeout (client only)	method, property	integer
Timeout is specified in milliseconds
no_reply	method
Do not expect a reply from the server
result (server only)	method	string
visible (server only)	method, property, signal	bool
By setting `visible = false` you can specify that the member should not be exported via D-Bus

Gtk attributes

GtkTemplate attribute

Can only be applied to classes that inherit from Gtk.Widget. The "ui" argument is mandatory.

Name	Type	Example
Description (optional)
ui	string (mandatory)	"/org/gnome/yourapp/main.ui"
Specifies the .ui gresource to be used for building the Gtk widget

GtkChild attribute

Can only be applied to fields of classes being marked with [GtkTemplate]. It's used to connect a field with a child object in the Gtk builder definition.

Name	Type	Example
Description (optional)
name	string
Custom name being used in the Gtk builder ui definition. By default the name of the marked field is used.
internal	bool
Whether this child is internal or not in the Gtk builder ui definition.

GtkCallback attribute

Can only be applied to methods of classes being marked with [GtkTemplate]. It's used to connect to a signal defined in the Gtk builder ui with the marked method.

Name	Type	Example
Description (optional)
name	string	"on_button_clicked"
Custom name being used in the Gtk builder ui definition. By default the name of the marked method is used.

Other attributes

Name	Applies to	Description
Assert	method
Compact	class
ConcreteAccessor	abstract property	Use get/set functions, but do not override them as they are not abstract.
DestroysInstance	method
Diagnostics	method
ErrorBase	class	Only use by GLib.Error at the moment
Flags	enum	Marks the enum values to be flags
FormatArg	parameter	specifies that the method takes and returns a printf or scanf format string
HasEmitter	signal
Immutable	class, struct
ModuleInit	method	Marks the associated type as dynamic, and marks the method as a TypeModule init function. See TypeModule example
NoAccessorMethod	property
NoReturn	method	Once the method is called, it will never return
NoThrow	method	Marks methods that can never throw exceptions. Dova profile only
NoWrapper	method
PointerType
Print	method	Stringifies and concatenates all arguments you pass to the method
PrintfFormat	method	See also ScanfFormat attribute
ReturnsModifiedPointer	method
ScanfFormat	method	See also PrintFormat attribute
SingleInstance	class	Makes the class a thread-safe singleton

Deprecated Attributes

Attributes that have been deprecated and should no longer be used in new code.

Name	Since	Use instead
Deprecated	0.31.1	[Version (deprecated = true, deprecated_since = "", replacement = "")]
Experimental	0.31.1	[Version (experimental = true, experimental_until = "")]
NoArrayLength	0.7.10	[CCode (array_length = false)]

Examples

TODO: write examples.