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 |
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 - c omma-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_valu e_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
|
|||
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/p roperty/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
|
|||
ref_sink_function |
class |
string |
|
ref_sink_function_void |
class |
bool |
|
Whether the
ref_sink
function
returns void.
Default is
|
|||
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_valu e_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_since |
string |
Version number |
replacement |
string |
Symbol name |
experimental |
bool |
Was |
experimental_until |
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 |
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 |
“o rg.my.interface” or “MyMember” |
signature |
string |
||
This makes it possible to use GVariant in D-Bus clients and servers without automatic boxing/unboxing. |
|||
use_st ring_marshalling |
enum |
bool |
|
Marshalling enum values as strings |
|||
value |
enumvalue |
string |
|
Marshalling enum values as strings |
|||
use_st ring_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
|
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/g nome/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 <https://v aladoc.org/gobject-2. 0/GLib.TypeModule>`__ init function. See TypeModule exa mple |
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 |
||
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 |
|
Experimental |
0.31.1 |
|
NoArrayLength |
0.7.10 |
|
Examples#
TODO: write examples.