Vala Reference Manual

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:

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

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

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

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

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

Examples

TODO: write examples.