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
’sinstance_pos
(if you’re usingGtk.Builder
’s signal auto-connection functionality).
Applying attributes#
They are written as:
1[AnnotationName (details-list)]
2declaration
For example:
1[CCode (cname = "var_c_name")]
2static int my_var;
CCode attribute#
This attribute influences the C code which is generated by Vala.
Name |
Applies to |
Type |
---|---|---|
Description (optional) |
Example (optional) |
|
|
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. |
||
|
field |
string |
|
field |
string |
|
constructor, delegate, method, parameter |
double |
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. |
0.9 |
|
|
field, method |
string |
|
constructor method, delegate, field, parameter, property |
bool |
|
class, constant, constructor, delegate, enum, field, interface, method, namespace, struct |
string (comma-separated list of headers) |
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. |
“glib.h” |
|
|
class, constant, constructor, delegate, enum, field, method, struct, propacc |
string |
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. |
“gboolean” |
|
|
class, struct |
string |
|
constructor |
string |
|
class |
string |
|
class, enum, namespace, struct |
string |
|
struct |
string - C value expression |
A C expression representing this type’s default value. |
“FALSE” |
|
|
field |
bool |
|
constructor, delegate, method, parameter |
double |
0.1 |
||
|
delegate, field/parameter |
string |
A C expression representing the name of the target/userdata related to a delegate field/parameter. |
“userdata” |
|
|
struct |
string |
|
parameter`` |
double |
|
class |
string |
|
class |
bool |
|
method |
double |
|
class, struct |
string (C function name) |
A function which will return an object when passed a GValue. |
“g_value_get_boolean” |
|
|
namespace |
string |
|
namespace |
string |
|
method |
bool |
|
struct |
bool |
|
struct |
bool |
|
method |
bool |
|
delegate |
bool |
|
class, struct, enum |
bool |
This is used to specify whether a corresponding GType must exists. |
true |
|
|
constructor, delegate, method |
double |
The argument position of the instance that will be used as |
||
|
namespace |
string |
|
class, enum, errordomain, interface |
string |
|
class, struct |
string |
“BOOLEAN” |
||
|
property |
bool |
|
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. |
||
|
class |
string |
|
parameter |
double |
|
class |
string |
|
class |
bool |
Whether the ref function returns void. Default is |
||
|
class |
string |
|
class |
bool |
Whether the ref_sink function returns void. Default is |
||
|
method |
bool |
Whether the method returns a floating reference to an object. |
||
|
constructor, method |
string |
Sentinel value to use as the last of variadic arguments. |
||
|
delegate, parameter |
string |
Scope of the delegate as in GIR notation. |
“async” |
|
|
class, struct |
string (C function name) |
A function that will set a GValue with an object of this type. |
“g_value_set_boolean” |
|
|
method |
bool |
|
class |
string |
|
class, interface, field, parameter, method |
string |
|
class |
string |
|
interface |
string |
|
class, enum, struct |
string |
The GObject type system type that this object is registered with. If |
“G_TYPE_BOOLEAN” |
|
|
class, interface, struct |
string |
|
class |
string |
|
constructor, method |
string |
Version attribute#
Used to annotate symbols with versioning information.
Available since Vala 0.31.1.
Name |
Type |
Description |
---|---|---|
|
string |
Version number - if used will be checked against locally installed package version. |
|
bool |
Was |
|
string |
Version number |
|
string |
Symbol name |
|
bool |
Was |
|
string |
Version number |
SimpleType attribute#
This attribute is applied to structs. Consider reading: 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 |
---|---|
|
integer |
|
integer |
|
integer |
|
integer |
|
bool |
FloatingType attribute#
This attribute is applied to structs, combined with SimpleType. Marks the struct as being a floating point number type.
Name |
Type |
---|---|
|
bool |
|
integer |
|
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) |
|
|
bool |
Sets the |
|
|
bool |
Sets the |
|
|
string |
Significant values are “first”, “last” or “cleanup”. Default is “last”. |
|
|
bool |
Sets the |
|
|
bool |
Sets the |
Description attribute#
This attribute influences the generation and usage of object properties, mostly for the GObject type system.
Name |
Type |
---|---|
|
string |
|
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 |
---|---|---|
Description (optional) |
||
|
class, interface, method, property, signal |
string |
Usually some reverse domain name notation is used, e.g. “org.my.interface” or “MyMember” |
||
|
string |
|
This makes it possible to use GVariant in D-Bus clients and servers without automatic boxing/unboxing. |
||
|
enum |
bool |
Marshalling enum values as strings |
||
|
enumvalue |
string |
Marshalling enum values as strings |
||
|
enum |
bool |
|
method, property |
integer |
Timeout is specified in milliseconds |
||
|
method |
|
Do not expect a reply from the server |
||
|
method |
string |
|
method, property, signal |
bool |
By setting |
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) |
||
|
string |
“/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) |
||
|
string |
|
Custom name being used in the Gtk builder ui definition. By default the name of the marked field is used. |
||
|
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) |
||
|
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 |
---|---|---|
|
method |
|
|
class |
|
|
abstract property |
Use get/set functions, but do not override them as they are not abstract. |
|
method |
|
|
method |
|
|
class |
Only use by GLib.Error at the moment |
|
enum |
Marks the enum values to be flags |
|
parameter |
specifies that the method takes and returns a printf or scanf format string |
|
signal |
|
|
class, struct |
|
|
method |
Marks the associated type as dynamic, and marks the method as a TypeModule init function. See TypeModule example |
|
property |
|
|
method |
Once the method is called, it will never return |
|
method |
Marks methods that can never throw exceptions. Dova profile only |
|
method |
|
|
||
|
method |
Stringifies and concatenates all arguments you pass to the method |
|
method |
See also ScanfFormat attribute |
|
method |
|
|
method |
See also PrintFormat attribute |
|
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 |
---|---|---|
|
0.31.1 |
|
|
0.31.1 |
|
|
0.7.10 |
|
Examples#
TODO: write examples.