Attributes - Vala Reference Manual

## 15. 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).

- `[ThreadLocal]` (if you're using the Dova profile).

### 15.1 Applying attributes

They are written as:

    [ AnnotationName ( details-list ) ]
    declaration

For example:

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

### 15.2 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 |
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 |

### 15.3 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

### 15.4 SimpleType attribute

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

### 15.5 BooleanType Attribute

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

### 15.6 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

### 15.7 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

### 15.8 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.

### 15.9 Description Attribute

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

Name | Type
nick | string
blurb | string

### 15.10 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

### 15.11 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.

### 15.12 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
Experimental |
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 |
NoArrayLength | method | Deprecated, use `[CCode (array_length = false)]` instead
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
ThreadLocal | field | Thread local fields. Dova profile only

### 15.13 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 = "")]

### 15.14 Examples

TODO: write examples.