[vala/wip/manual] doc: Update from https://wiki.gnome.org/Projects/Vala/Manual
- From: Rico Tzschichholz <ricotz src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [vala/wip/manual] doc: Update from https://wiki.gnome.org/Projects/Vala/Manual
- Date: Tue, 10 Jan 2017 16:40:28 +0000 (UTC)
commit b2d860faca022c1b59ac43eb7913dee96ef23a56
Author: Rico Tzschichholz <ricotz ubuntu com>
Date: Mon Jan 9 20:19:35 2017 +0100
doc: Update from https://wiki.gnome.org/Projects/Vala/Manual
doc/vala/Makefile.am | 52 +++---
doc/vala/attributes.xml | 6 -
doc/vala/classes.xml | 86 --------
doc/vala/default.css | 38 ++++-
doc/vala/delegates.xml | 13 --
doc/vala/enums.xml | 25 ---
doc/vala/exceptions.xml | 9 -
doc/vala/expressions.xml | 108 ----------
doc/vala/index.xml | 23 ---
doc/vala/interfaces.xml | 41 ----
doc/vala/manual.xml | 494 ++++++++++++++++++++++++++++++++++++++++++++++
doc/vala/methods.xml | 43 ----
doc/vala/namespaces.xml | 30 ---
doc/vala/overview.xml | 30 ---
doc/vala/statements.xml | 102 ----------
doc/vala/structs.xml | 36 ----
doc/vala/toc.xsl | 16 ++
doc/vala/types.xml | 166 ----------------
doc/vala/xhtml.xsl | 373 +++++++++++++++++++++++++----------
19 files changed, 838 insertions(+), 853 deletions(-)
---
diff --git a/doc/vala/Makefile.am b/doc/vala/Makefile.am
index c980cf6..4206f28 100644
--- a/doc/vala/Makefile.am
+++ b/doc/vala/Makefile.am
@@ -5,19 +5,26 @@ book_name=vala@PACKAGE_SUFFIX@
bookdir=$(datadir)/devhelp/books/$(book_name)
chapter_data = \
- overview.html \
- types.html \
- expressions.html \
- statements.html \
- namespaces.html \
- methods.html \
- classes.html \
- structs.html \
- interfaces.html \
- enums.html \
- delegates.html \
- exceptions.html \
- attributes.html \
+ Attributes.html \
+ Classes.html \
+ Compile_and_Run.html \
+ Concepts.html \
+ Delegates.html \
+ Enumerated_types_(Enums).html \
+ Errors.html \
+ Expressions.html \
+ Generics.html \
+ GIDL_metadata_format.html \
+ GIR_metadata_format.html \
+ Interfaces.html \
+ Methods.html \
+ Namespaces.html \
+ Overview.html \
+ Preprocessor.html \
+ Signals.html \
+ Statements.html \
+ Structs.html \
+ Types.html \
$(NULL)
built_data = \
@@ -34,28 +41,15 @@ book_DATA = \
endif
index.html: $(book_sources) xhtml.xsl
- $(AM_V_GEN)$(XSLTPROC) --xinclude $(srcdir)/xhtml.xsl $(srcdir)/index.xml > index.html
+ $(AM_V_GEN)$(XSLTPROC) --xinclude $(srcdir)/xhtml.xsl $(srcdir)/manual.xml > index.html
$(chapter_data): index.html
$(book_name).devhelp2: $(book_sources) devhelp.xsl
- $(AM_V_GEN)$(XSLTPROC) --xinclude $(srcdir)/devhelp.xsl $(srcdir)/index.xml > $(book_name).devhelp2
+ $(AM_V_GEN)$(XSLTPROC) --xinclude $(srcdir)/devhelp.xsl $(srcdir)/manual.xml > $(book_name).devhelp2
book_sources = \
- index.xml \
- overview.xml \
- types.xml \
- expressions.xml \
- statements.xml \
- namespaces.xml \
- methods.xml \
- classes.xml \
- structs.xml \
- interfaces.xml \
- enums.xml \
- delegates.xml \
- exceptions.xml \
- attributes.xml \
+ manual.xml \
$(NULL)
MOSTLYCLEANFILES = $(built_data)
diff --git a/doc/vala/default.css b/doc/vala/default.css
index 9294f26..e1f230e 100644
--- a/doc/vala/default.css
+++ b/doc/vala/default.css
@@ -26,6 +26,9 @@ a:link, a:visited, a:hover, a:active {
font-size: smaller;
}
+.page_toc li {
+}
+
h3 a {
/* ensure anchors don't vanish below the fixed header */
position: relative;
@@ -53,10 +56,14 @@ div.note {
margin: 0 2em 1em 2em;
}
-div.note p, div.note h4 {
+div.note h4 {
margin: 0;
}
+div.note p {
+ margin-bottom: 0;
+}
+
pre {
background-color: #eee;
border: 1px solid black;
@@ -67,6 +74,12 @@ pre {
blockquote {
font-style: italic;
white-space: pre;
+ overflow-x: auto;
+}
+
+code {
+ font-family: monospace;
+ font-style: normal;
}
blockquote span.literal {
@@ -74,3 +87,26 @@ blockquote span.literal {
font-style: normal;
font-weight: bold;
}
+
+blockcode {
+ overflow-x: auto;
+}
+
+pre span.token {color: #A00000;}
+pre span.type {color: #0080ff; font-weight: bold;}
+pre span.mehodname {color: #000000;}
+pre span.phrase {color: #004080;}
+
+table {
+ border-collapse: collapse;
+}
+
+table td {
+ border: 1px solid #005a9c;
+}
+
+table td p {
+ margin: .2em .2em .2em .2em;
+ padding: 0 0 0 0;
+ font-size: smaller;
+}
diff --git a/doc/vala/manual.xml b/doc/vala/manual.xml
new file mode 100644
index 0000000..c46d73e
--- /dev/null
+++ b/doc/vala/manual.xml
@@ -0,0 +1,494 @@
+<?xml version="1.0" encoding="utf-8"?><!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.4//EN'
'http://www.docbook.org/xml/4.4/docbookx.dtd'><article><articleinfo><title>Projects/Vala/Manual/Export</title><revhistory><revision><revnumber>5</revnumber><date>2013-11-22
16:48:27</date><authorinitials>WilliamJonMcCann</authorinitials><revremark>Renamed from
'Vala/Manual/Export'.</revremark></revision><revision><revnumber>4</revnumber><date>2011-02-24
11:03:45</date><authorinitials>LucaBrunoLethalman</authorinitials></revision><revision><revnumber>3</revnumber><date>2010-07-15
08:27:55</date><authorinitials>LucaBrunoLethalman</authorinitials></revision><revision><revnumber>2</revnumber><date>2010-07-14
12:16:54</date><authorinitials>LucaBrunoLethalman</authorinitials></revision><revision><revnumber>1</revnumber><date>2010-07-14
09:48:50</date><authorinitials>LucaBrunoLethalman</authorinitials></revision></revhistory></articleinfo><section><title>Vala
Reference Manual [Draf
t]</title><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Overview</title><para>Vala is a new programming language that aims to
bring modern language features to GNOME developers without imposing any additional runtime requirements and
without using a different ABI than applications and libraries written in C. It provides a concise way of
using GLib and GObject features, but does not attempt to expose all possibilities. In particular, Vala is
primarily a statically typed language - this is a design decision, not an oversight. </para><para>The only
support that Vala applications require at runtime are the standard GLib and GObject libraries. It is
possible to use any system library from Vala, provided that a VAPI file is written to describe the interface
- Vala is distributed with VAPI descriptions of most libraries commonly used by GNOME applications, and many
others
as well. </para><para>Vala provides easy integration with DBus, by automatically writing boiler plate code
where required, for exposing objects, dispatching methods, etc. </para><section><title>Getting
started</title><para>The classic "Hello, world" example in Vala: </para><programlisting
format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[hello, world]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[ 0;]]>
+<![CDATA[}]]>
+</programlisting><para>Store the code in a file whose name ends in ".vala", such as
<code>hello.vala</code>, and compile it with the command: </para><para><code>valac -o hello hello.vala</code>
</para><para>This will produce an executable file called <code>hello</code>. "valac" is the Vala
compiler; it will also allow you to take more control of the compile and link processes when required, but
that is outside the scope of this introductory section. </para></section><section><title>Documentation
conventions</title><para>A large amount of this documentation describes the language features precisely using
a simple rule notation. The same notation is used to describe language syntax and semantics, with the
accompanying text always explaining what is described. The following example shows the form:
</para><itemizedlist><listitem override="none"><para>rule-name:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">literalstring1</emph
asis></para><para> <emphasis role="strong">literalstring2</emphasis> [ optional-section
]</para></listitem></itemizedlist><para> optional-section:</para><itemizedlist><listitem
override="none"><para><emphasis
role="strong">literalstring3</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>Here,
"rule-name" and "optional-section" describe rules, each of which can be expanded in a
particular way. Expanding a rule means substituting one of the options of the rule into the place the rule
is used. In the example, "optional-section" can be expanded into "literalstring3" or, in
"rule-name", "optional-section" can also be substituted for nothing, as it is declared
optional by the square brackets. Wherever "rule-name" is required, it can be substituted for
either of the options declared in "rule-name". Anything highlighted, such as all <emphasis
role="strong">literalstrings</emp
hasis> here are not rules, and thus cannot be expanded. </para><para>Example code is shown as follows.
Example code will always be valid Vala code, but will not necessarily be usable out of context.
</para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[MyClass]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[field]]></methodname><![CDATA[ = 1;]]>
+<![CDATA[}]]>
+</programlisting><para>Some phrases are used in a specific ways in this documentation and it is often useful
to recognise their precise meanings: that is, to create a method, you write a declaration for it. When the
program is running and the method exists, it is then defined as per your declaration and can be invoked.
</para></section><section><title>Vala source files</title><para>There are two types of Vala input files.
Vala source files (with a ".vala" extension) contain compileable Vala code. VAPI files (with a
".vapi" extension) describe an interface to a library, which can be written in either Vala or C.
VAPI files are not compileable, and cannot contain any executable code - they are used when compiling Vala
source files. </para><para>There are no requirements for how Vala source files are named, although there are
conventions that can be followed. VAPI files are usually named to matched the pkg-config name of the library
they relate to; they ar
e described more fully in the documention about bindings. </para><para>All Vala input files should be
encoded in UTF-8. </para></section><section><title>Vala conventions</title><para>The logical structure of a
Vala project is entirely based on the program text, not the file layout or naming. Vala therefore does not
force particular naming schemes or file layouts. There are established conventions derived from how GNOME
related applications are normally written, which are strongly encouraged. The choice of directory structure
for a project is outside the scope of this documentation. </para><para>Vala source files usually contain one
main public class, after which the source file is named. A common choice is to convert this main class' name
to lowercase, and prefix with its namespace, also in lower case, to form the file name. In a small project
the namespace may be redundant and so excluded. None of this is a requirement, it is just a convention.
</para><para>It is not
encouraged to include declarations in more than one namespace in a single Vala source file, simply for
reasons of clarity. A namespace may be divided over any number of source files, but will normally not be
used outside of one project. Each library or application will normally have one main namespace, with
potentially others nested within. </para><para>In source code, the following naming conventions are normally
followed: </para><itemizedlist><listitem><para>Namespaces are named in camel case: NameSpaceName
</para></listitem><listitem><para>Classes are named in camel case: ClassName
</para></listitem><listitem><para>Method names are all lowercase and use underscores to separate words:
method_name </para></listitem><listitem><para>Constants (and values of enumerated types) are all uppercase,
with underscores between words: CONSTANT_NAME </para></listitem></itemizedlist><para>Vala supports the notion
of a package to conveniently divide program sections. A package is eithe
r a combination of an installed system library and its Vala binding, or else is a local directory that can
be treated in a similar way. In the latter case it will contain all functionality related to some topic, the
scope of which is up to the developer. All source files in package are placed within a directory named for
package name. For details on using packages, see the Vala compiler documentation
</para></section><section><title>Vala syntax</title><para>Vala's syntax is modelled on C#'s, and is therefore
similar to all C-like languages. Curly braces are the basic delimeter, marking the start and end of a
declaration or block of code. </para><para>There is no whitespace requirement, though this is a standard
format that is used in Vala itself, and in many Vala projects. This format is a version of the coding style
used for glib and gnome projects, but is not fully described in this document, other than being used for all
examples. </para><para>There is flexibility in
the order of declarations in Vala. It is not required to pre-declare anything in order to use it before
its declaration. </para><para>Identifiers all follow the same rules, whether for local variables or class
names. Legal identifiers must begin with one alphabetic character or underscore, followed by any number
(zero or more) of alphanumerics or underscores (/[:alpha:_]([:alphanum:_])*/). It is also possible to use
language keywords as identifiers, provided they are prefixed with a "@" when used in this way - the
"@" is not considered a part of the identifier, it simply informs the compiler that the token
should be considered as an identifier. </para></section><section><title>GType and GObject</title><para>Vala
uses the runtime type system called GType. This system allows every type in Vala, including the fundamental
types, to be identified at runtime. A Vala developer doesn't need to be aware of GType in most
circumstances, as all interaction with
the system is automatic. </para><para>GType provides Vala with a powerful object model called GObject. To
all types descended from GLib.Object class, this model provides for features such as properties and signals.
</para><para>GType and GObject are entirely runtime type systems, intended to be usable to dynamically typed
languages. Vala is primarily a statically typed language, and so is designed not to provide access to all of
GType and GObject's features. Instead Vala uses a coherent subset to support particular programming styles.
</para><para>Vala is designed to use GType and GObject seamlessly. There are occasions, mostly when working
with existing libraries, when you might need to circumvent parts of the system. These are all indicated in
this documentation. </para></section><section><title>Memory management</title><para>Vala automatically uses
the memory management system in GLib, which is a reference counting system. In order for this to work, the
types used
must support reference counting, as is the case with all GObject derived types and some others.
</para><para>Memory is allocated and initialised by Vala when needed. The memory management scheme means it
is also freed when possible. There is though no garbage collector, and currently reference cycles are not
automatically broken. This can lead to memory being leaked. The main way to avoid this problem is to use
weak references - these are not counted references and so cannot prevent memory being released, at the cost
that they can be left refering to non existent data. </para><para>Vala also allows use of pointers in much
the same way as C. An instance of a pointer type refers directly to an address in memory. Pointers are not
references, and therefore the automatic memory management rules do not apply in the same way. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Types#Pointer_types";>Types/Pointer
types</ulink>. </para><par
a>There are more details about memory management elsewhere, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Types#";>Types</ulink>, see
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#";>Concepts</ulink>.
</para></section><section><title>Vala compilation</title><para>Vala programs and libraries are translated
into C before being compiled into machine code. This stage is intended to be entirely transparent unless you
request otherwise, as such it is not often required to know the details. </para><para>When performing a more
complicated compile or link process than valac's default, valac can be instructed to simply output its
intermediate C form of the program and exit. Each Vala source file is transformed into a C header and a C
source file, each having the same name as the Vala source file except for the extension. These C files can
be compiled without any help from any Vala utility or
library. </para><para>The only times it is definitely required to be aware of the translation process is
when a Vala feature cannot be represented in C, and so the generated C API will not be the same as the Vala
one. For example, private struct members are meaningless in C. These issues are indicated in this
documentation. </para></section><section><title>Application entry point</title><para>All Vala applications
are executed beginning with a method called "main". This must be a non-instance method, but may
exist inside a namespace or class. If the method takes a string array parameter, it will be passed the
arguments given to the program on execution. If it returns an int type, this value will be passed to the
user on the program's normal termination. The entry point method may not accept any other parameters, or
return any other types, making the acceptable definitions: </para><programlisting format="linespecific"
language="cpp" linenumbering="numbered" st
artinglinenumber="1"><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[main]]></methodname><![CDATA[ () { ... }]]>
+<token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[ () { ... }]]>
+<token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) { ... }]]>
+<token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) { ... }]]>
+</programlisting><para>The entry point can be implicit, in the sense that you can write the main code block
directly in the file outside the <code>main</code> function. </para></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Concepts</title><para>This pages describes concepts that are widely
applicable in Vala. Specific syntax is not described here, see the linked pages for more details.
</para><section><title>Variables, fields and parameters</title><para>Any piece of data in a Vala application
is considered an instance of a data type. There are various different categories of data types, some being
built into Vala, and others being user defined. Details about types are described elsewhere in this
documentation, in particular see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Types#";>Types</ulink>.
</para><par
a>Instances of these types are created in various different ways, depending on the type. For example,
fundamental types are instantiated with literal expressions, and classed types with the new operator.
</para><para>In order to access data, the instance must be identifiable in some way, such as by a name. In
Vala, there are broadly three ways that this is done, with similar but not identical semantics.
</para><para>(All these subsections refer to ownership, so it may be useful to read the section on <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#References_and_ownership";>Concepts/References
and ownership</ulink> in conjunction with this section) </para><section><title>Variables</title><para>Within
executable code in a method, an instance may be assigned to a variable. A variable has a name and is
declared to refer to an instance of a particular data type. A typical variable declaration would be:
</para><screen><![CDATA[int
a;]]></screen><para>This declaration defines that "a" should become an expression that evaluates
to an instance of the int type. The actual value of this expression will depend on which int instance is
assigned to the variable. "a" can be assigned to more than once, with the most recent assigment
being the only one considered when "a" is evaluated. Assignment to the variable is achieved via an
assignment expression. Generally, the semantics of an assignment expression depends on the type of the
variable. </para><para>A variable can take ownership of an instance, the precise meaning of which depends on
the data type. In the context of reference types, it is possible to declare that a variable should not ever
take ownership of an instance, this is done with the <code>unowned</code> keyword. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Types#Reference_types";>Types/Reference
types</ulink>. </para><p
ara>If a type is directly instantiated in a variable declaration statement, then the variable will be
created owning that new instance, for example: </para><screen><![CDATA[string s =
"stringvalue";]]></screen><para>A variable ceases to exist when its scope is destroyed, that is when the code
block it is defined in finishes. After this, the name can no longer be used to access the instance, and no
new assignment to the variable is allowed. What happens to the instance itself is dependent on the type.
</para><para>For more details of the concepts in this section, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Statements#Variable_declaration";>Statements/Variable
declaration</ulink> and <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Assignment_operations";>Expressions/Assignment
operations</ulink>. </para></section><section><title>Fields</title><para>A field is similar to a variable,
except for the scope that it is defined in. Fields can be defined in namespaces, classes and structs. In
the case of classes and structs, they may be either in the scope of the the class or struct, or in the scope
of each instance of the class or struct. </para><para>A field is valid as long as its scope still exists -
for non-instance fields, this is the entire life of the application; for instance fields, this is the
lifetime of the instance. </para><para>Like variables, fields can take ownership of instances, and it is
again possible to avoid this with the <code>unowned</code> keyword. </para><para>If a type is directly
instantiated in the declaration of the field, then that field will be created owning that new instance.
</para><para>For more details about fields, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Namespaces#";>Namespaces</ulink>,
<ulink url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual
/Classes#">Classes</ulink> and <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Structs#";>Structs</ulink>.
</para></section><section><title>Parameters</title><para>Instances passed to methods are accessible within
that method with names given in the method's parameter list. </para><para>They act like variables, except
that they cannot, by default, take ownership of the first instance that is assigned to them, i.e. the
instance passed to the method. This behaviour can be changed using explicit ownership transfer. When
reassigning to a parameter, the result depends on the parameter direction. Assuming the parameter has no
direction modifier, it will subsequently act exactly as a variable. </para><para>For more details of methods
and parameters, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#";>Methods</ulink> and
<ulink url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Va
la/Manual/Expressions#Ownership_transfer_expressions">Expressions/Ownership transfer expressions</ulink>.
</para></section></section><section><title>Scope and naming</title><para>A "scope" in Vala refers
to any context in which identifiers can be valid. Identifiers in this case refers to anything named,
including class definitions, fields, variables, etc. Within a particular scope, identifiers defined in this
scope can be used directly: </para><programlisting format="linespecific" language="cpp"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[main]]></methodname><![CDATA[ () {]]>
+<![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[ = 5;]]>
+<![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[b]]></methodname><![CDATA[ = ]]><methodname><![CDATA[a]]></methodname><![CDATA[ +
1;]]>
+<![CDATA[}]]>
+</programlisting><para>Scopes in Vala are introduced in various different ways.
</para><itemizedlist><listitem><para>Named scopes can be created directly with declarations like namespaces.
These are always in existence when the program is running, and can be referred to by their name.
</para></listitem><listitem><para>Transient scopes are created automatically as the program executes. Every
time a new code block is entered, a new scope is created. For example, a new scope is created when a method
is invoked. There is no way to refer to this type of scope from outside.
</para></listitem><listitem><para>Instance scopes are created when a data type is instantiated, for example
when a new instance of a classed type is created. These scopes can be accessed via identifiers defined in
other scopes, e.g. a variable to which the new instance is assigned.
</para></listitem></itemizedlist><para>To refer to an identifier in another scope, you must generally qualify
the name. For n
amed scopes, the scope name is used; for instance scopes, any identifier to which the instance is assigned
can be used. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Member_access_expressions";>Expressions/Member
access expressions</ulink> for the syntax of accessing other scopes. </para><para>Scopes have parent scopes.
If an identifier is not recognised in the current scope, the parent scope is searched. This continues up to
the the global scope. The parent scope of any scope is inferred from its position in the program - the
parent scope can easily be identified as it is the scope the current declaration is in. </para><para>For
example, a namespace method creates a transient scope when it is invoked - the parent of this scope if the
namespace which contains the definition of the method. There are slightly different rules applied when
instances are involved, as are described at <ulink url="http://wiki.gnome.org/act
ion/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Class_scope">Classes/Class scope</ulink>.
</para><para>The ultimate parent of all other scopes is the global scope. The scope contains the fundamental
data types, e.g. int, float, string. If a program has a declaration outside of any other, it is placed in
this scope. </para><section><title>Qualifying names</title><para>The following rules describe when to qualify
names: </para><itemizedlist><listitem><para>For names in the same scope as the current definition, just the
name should be used. </para></listitem><listitem><para>For names in scopes of which the current is parent,
qualify with just the names of scopes that the current definition is not nested within.
</para></listitem><listitem><para>For names in other scopes entirely, or that are less deeply nested than the
current, use the fully qualified name (starting from the global scope.)
</para></listitem></itemizedlist><para>There are some intricacies of scopes de
scribed elsewhere in this documentation. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#";>Classes</ulink> for
how scopes are managed for inherited classes. </para><para>Vala will lookup names assuming first that they
are not fully qualified. If a fully qualified name can be partially matched locally, or in a parent scope
that is not the global scope, the compilation will fail. To avoid problems with this, do not reuse names
from the global scope in other scopes. </para><para>There is one special scope qualifier that can be used to
avoid the problem described in the previous paragraph. Prefixing an identifier with <code>global::</code>
will instruct the compiler to only attempt to find the identifier in the global scope, skipping all earlier
searching. </para></section></section><section><title>Object oriented programming</title><para>Vala is
primarily an object oriented language. This documentation isn't going to describ
e object oriented programming in detail, but in order for other sections to make sense, some things need to
be explained. </para><para>A class in Vala is a definition of a potentially polymorphic type. A polymorphic
type is one which can be viewed as more than one type. The basic method for this is inheritance, whereby one
type can be defined as a specialized version of another. An instance of a subtype, descended from a
particular supertype, has all the properties of the supertype, and can be used wherever an instance of the
supertype is expected. This sort of relationship is described as a "subtype instance is-a supertype
instance." See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#";>Classes</ulink>.
</para><para>Vala provides inheritance functionality to any type of class (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Types_of_class";>Classes/Types
of class</ul
ink>). Given the following definition, every SubType instance is-a SuperType instance:
</para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[SuperType]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[act]]></methodname><![CDATA[() {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[ 1;]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+<token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[SubType]]></methodname><![CDATA[ :
]]><methodname><![CDATA[SuperType]]></methodname><![CDATA[ {]]>
+<![CDATA[}]]>
+</programlisting><para>Whenever a SuperType instance is required, a SubType instance may be used. This is
the extent of inheritence allowed to compact classes, but full classes are more featured. All classes that
are not of compact type, can have virtual methods, and can implement interfaces. </para><para>To explain
virtual functions, it makes sense to look at the alternative first. In the above example, it is legal for
SubType to also define a method called "act" - this is called overriding. In this case, when a
method called "act" is called on a SubType instance, which method is invoked depends on what type
the invoker believed it was dealing with. The following example demonstrates this: </para><programlisting
format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><methodname><![CDATA[SubType]]></methodname><![CDATA[
]]><methodname><![CDATA[sub]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[ ]]>
<methodname><![CDATA[SubType]]></methodname><![CDATA[();]]>
+<methodname><![CDATA[SuperType]]></methodname><![CDATA[
]]><methodname><![CDATA[super]]></methodname><![CDATA[ =
]]><methodname><![CDATA[sub]]></methodname><![CDATA[;]]>
+
+<methodname><![CDATA[sub]]></methodname><![CDATA[.]]><methodname><![CDATA[act]]></methodname><![CDATA[();]]>
+<methodname><![CDATA[super]]></methodname><![CDATA[.]]><methodname><![CDATA[act]]></methodname><![CDATA[();]]>
+</programlisting><para>Here, when sub.act() is called, the method invoked will be SubType's "act"
method. The call super.act() will call SuperType's "act". If the act method were virtual, the
SubType.act method would have been called on both occasions. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Class_methods";>Classes/Class
methods</ulink> for how to declare virtual methods. </para><para>Interfaces are a variety of
non-instantiatable type. This means that it is not possible to create an instance of the type. Instead,
interfaces are implemented by other types. Instances of these other types may then be used as though they
were instances of the interface in question. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Interfaces#";>Interfaces</ulink>.
</para></section><section><title>References and ownership</title><para>Type instances in Vala are
automatically
managed to a large degree. This means that memory is allocated to store the data, and then deallocated when
the data is no longer required. However, Vala does not have a runtime garbage collector, instead it applies
rules at compile time that will predictably deallocate memory at runtime. </para><para>A central concept of
Vala's memory management system is ownership. An instance is considered still in use as long as there is at
least one way of accessing it, i.e. there is some field, variable or parameter that refers to the instance -
one such identifier will be considered the instance's owner, and therefore the instance's memory will not be
deallocated. When there is no longer any way to access the data instance, it is considered unowned, and its
memory will be deallocated. </para><section><title>Value types</title><para>When dealing with instances of
value types (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Types#";>Types</ul
ink>) knowledge of ownership is rarely important. This is because the instance is copied whenever it is
assigned to a new identifier. This will cause each identifier to become owner of a unique instance - that
instance will then be deallocated when the identifier ceases to be valid. </para><para>There is one exception
to this rule: when a struct type instance is passed to a method, Vala will, by default, create the method
parameter as a reference to the instance instead of copying the instance. This reference is a weak
reference, as described in the following section. If the struct should instead be copied, and the parameter
created as a standard value type identifier, the ownership transfer operator should be used (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Ownership_transfer_expressions";>Expressions/Ownership
transfer expressions</ulink>). </para></section><section><title>Reference types</title><para>With refer
ence types, it is possible for several identifiers to reference the same data instance. Not all identifiers
that refer to reference type instance are capable of owning the instance, for reasons that will be explained.
It is therefore often required to think about instance ownership when writing Vala code. </para><para>Most
reference types support reference counting. This means that the instance internally maintains a count of how
many references to it currently exist. This count is used to decide whether the instance is still in use, or
if its memory can be deallocated. Each reference that is counted in this way is therefore a potential owner
of the instance, as it ensures the instance continues to exist. There are situations when this is not
desired, and so it is possible to define a field or variable as "weak". In this case the reference
is not counted, and so the fact that the reference exists will not stop the instance being possibly
deallocated, i.e. th
is sort of reference cannot take ownership of the instance. </para><para>When using reference counted types,
the main use for weak references is to prevent reference cycles. These exist when a data instance contains
internally a reference to another instance, which in turn contains a reference to the first. In this case it
would not be possible to deallocate the instances, as each would be potentially owning the other. By
ensuring that one of the references is weak, one of the instances can become unowned and be deallocated, and
in the process the other will be dereferenced, and potentially become unowned and be deallocated also.
</para><para>It is also possible to have reference types which are not reference counted; an example of this
is the fundamental string type, others are compact classed types. If Vala were to allow several references
to own such instances, it would not be able to keep track of when they all ceased to exist, and therefore
would not be able to know
when to deallocate the instance. Instead, exactly one or zero identifiers will own the instance - when it
is zero, the instance is deallocated. This means that all references to an already owned instance must
either be weak references, or ownership must be specifically passed to the new reference, using the ownership
transfer operator (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Ownership_transfer_expressions";>Expressions/Ownership
transfer expressions</ulink>). </para></section><section><title>Pointer types</title><para>Pointer types are
of great importance. Pointer types are value types, whose instances are references to some other data
instance. They are therefore not actual references, and will never own the instance that they indirectly
refer to. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Types#Pointer_types";>Types/Pointer
types</ulink>. </para></section></secti
on></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Types</title><para>A "type", loosely described, is just an
abstract set of 0 or more data fields. A type may be instantiated by creating an entity that contains values
that map to the fields of the type. In Vala, a type generally consists of:
</para><itemizedlist><listitem><para>A type name, which is used in various contexts in Vala code to signify
an instance of the type. </para></listitem><listitem><para>A data structure that defines how to represent an
instance of the type in memory. </para></listitem><listitem><para>A set of methods that can be called on an
instance of the type. </para></listitem></itemizedlist><para>These elements are combined as the definition of
the type. The definition is given to Vala in the form of a declaration, for example a class declaration.
</para><para>Val
a supports three kinds of data types: value types, reference types, and meta types. Value types include
simple types (e.g. char, int, and float), enum types, and struct types. Reference types include object types,
array types, delegate types, and error types. Type parameters are parameters used in generic types.
</para><para>Value types differ from reference types in that there is only ever one variable or field that
refers to each instance, whereas variables or fields of the reference types store references to data which
can also be referred to by other variable or fields. When two variables or fields of a reference type
reference the same data, changes made using one identifier are visible when using the other. This is not
possible with value types. </para><para>Meta types are created automatically from other types, and so may
have either reference or value type semantics. </para><itemizedlist><listitem
override="none"><para>type:</para><itemizedlist><listitem override="n
one"><para>value-type</para><para> reference-type</para><para>
meta-type</para></listitem></itemizedlist><para> meta-type:</para><itemizedlist><listitem
override="none"><para>parameterised-type</para><para> nullable-type</para><para>
pointer-type</para></listitem></itemizedlist></listitem></itemizedlist><section><title>Value
types</title><para>Instances of value types are stored directly in variables or fields that represent them.
Whenever a value type instance is assigned to another variable or field, the default action is to duplicate
the value, such that each identifier refers to a unique copy of the data, over which it has ownership. When
a value type is instantiated in a method, the instance is created on the stack.
</para><itemizedlist><listitem override="none"><para>value-type:</para><itemizedlist><listitem
override="none"><para>fundamental-struct-type</para><para> user-defined-struct-type</para><para>
enumerated-type</para></listitem></itemizedlist><para> fundament
al-struct-type:</para><itemizedlist><listitem override="none"><para>integral-type</para><para>
floating-point-type</para><para> <emphasis
role="strong">bool</emphasis></para></listitem></itemizedlist><para>
integral-type:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">char</emphasis></para><para> <emphasis role="strong">uchar</emphasis></para><para> <emphasis
role="strong">short</emphasis></para><para> <emphasis role="strong">ushort</emphasis></para><para> <emphasis
role="strong">int</emphasis></para><para> <emphasis role="strong">uint</emphasis></para><para> <emphasis
role="strong">long</emphasis></para><para> <emphasis role="strong">ulong</emphasis></para><para> <emphasis
role="strong">size_t</emphasis></para><para> <emphasis role="strong">ssize_t</emphasis></para><para>
<emphasis role="strong">int8</emphasis></para><para> <emphasis role="strong">uint8</emphasis></para><para>
<emphasis role="strong">int16</emphasis></para><para> <emphasis role=
"strong">uint16</emphasis></para><para> <emphasis role="strong">int32</emphasis></para><para> <emphasis
role="strong">uint32</emphasis></para><para> <emphasis role="strong">int64</emphasis></para><para> <emphasis
role="strong">uint64</emphasis></para><para> <emphasis
role="strong">unichar</emphasis></para></listitem></itemizedlist><para>
floating-point-type:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">float</emphasis></para><para> <emphasis
role="strong">double</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>Where a
literal is indicated, this means the actual type name of a built in struct type is given. The definition of
these types is included in Vala, so these types are always available. </para><section><title>Struct
types</title><para>A struct type is one that provides just a data structure and some methods that act upon
it. Structs are not polymorphic, and cannot have advanced features such as signals or prope
rties. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Structs#";>Structs</ulink>
for documentation on how to define structs and more details about them. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Struct_instantiation";>Expressions/Struct
instantiation</ulink> for how to instantiate structs. </para><para>Each variable or field to which a struct
stype instance is assigned gains a copy of the data, over which it has ownership. However, when a struct type
instance is passed to a method, a copy is not made. Instead a reference to the instance is passed. This
behaviour can be changed by declaring the struct to be a simple type.
</para></section><section><title>Fundamental types</title><para>In Vala, the fundamental types are defined as
struct types whose data structure is known internally to Vala. They have one anonymous field, which is
automatically accessed w
hen required. All fundamental value types are defined as simple types, and so whenever the instance is
assigned to a variable or field or passed as a function parameter, a copy of the data is made.
</para><para>The fundamental value types fall into one of three categories: the boolean type, integral types,
and floating point types. </para></section><section><title>Integral types</title><para>Integral types can
contain only integers. They are either signed or unsigned, each of which is considered a different type,
though it is possible to cast between them when needed. </para><para>Some types define exactly how many bits
of storage are used to represent the integer, others depend of the environment. long, int short map to C
data types and therefore depend on the machine architecture. char is 1 byte. unichar is 4 bytes, i.e. large
enough to store any UTF-8 character. </para><para>All these types can be instantiated using a literal
expression, see <ulink url="http://wiki.g
nome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Literal_expressions">Expressions/Literal
expressions</ulink>. </para></section><section><title>Floating point types</title><para>Floating point types
contain real floating point numbers in a fixed number of bits (see IEEE 754). </para><para>All these types
can be instantiated using a literal expression, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Literal_expressions";>Expressions/Literal
expressions</ulink>. </para></section><section><title>The bool type</title><para>Can have values of true of
false. Although there are only two values that a bool instance can take, this is not an enumerated type.
Each instance is unique and will be copied when required, the same as for the other fundamental value types.
</para><para>This type can be instantiated using literal expressions, see <ulink
url="http://wiki.gnome.org/action/show/Project
s/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Literal_expressions">Expressions/Literal
expressions</ulink>. </para></section><section><title>Enumerated types</title><para>An enumerated type is one
in which all possible values that instances of the type can hold are declared with the type. In Vala
enumerated types are real types, and will not be implicitly converted. It is possible to explicitly cast
between enumerated types, but this is not generally advisable. When writing new code in Vala, don't rely on
being able to cast in this way. </para><para>A variation on an enumerated type is a flag type. This
represents a set of flags, any number of which can be combined in one instance of the flag type, in the same
fashion as a bitfield in C. </para><para>See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Enumerated%20types%20%28Enums%29#";>Enumerated
types (Enums)</ulink> for documentation on defining and using enumerate
d types. </para></section></section><section><title>Reference types</title><para>Instances of reference
types are always stored on the heap. Variables of reference types contain references to the instances,
rather than the instances themselves. Assinging an instance of a reference type to a variable or field will
not make a copy of the data, instead only the reference to the data is copied. This means that both
variables will refer to the same data, and so changes made to that data using one of the references will be
visible when using the other. </para><para>Instances of any reference type can be assigned a variable that is
declared "weak". This implies that the variable must not be known to the type instance. A
reference counted type does not increase its reference count after being assigned to a weak variable: a weak
variable cannot take ownership of an instance. </para><itemizedlist><listitem
override="none"><para>reference-type:</para><itemizedlist><listit
em override="none"><para>classed-type</para><para> array-type</para><para> delegate-type</para><para>
error-type</para><para> <emphasis role="strong">string</emphasis></para></listitem></itemizedlist><para>
classed-type:</para><itemizedlist><listitem override="none"><para>simple-classed-type</para><para>
type-instance-classed-type</para><para> object-classed-type</para></listitem></itemizedlist><para>
simple-classed-type:</para><itemizedlist><listitem
override="none"><para>user-defined-simple-classed-type</para></listitem></itemizedlist><para>
type-instance-classed-type:</para><itemizedlist><listitem
override="none"><para>user-defined-type-instance-classed-type</para></listitem></itemizedlist><para>
object-classed-type:</para><itemizedlist><listitem
override="none"><para>user-defined-object-classed-type</para></listitem></itemizedlist><para>
array-type:</para><itemizedlist><listitem override="none"><para>non-array-type <emphasis
role="strong">[]</emphasis></para><para> non-a
rray-type <emphasis role="strong">[</emphasis> dimension-separators <emphasis
role="strong">]</emphasis></para></listitem></itemizedlist><para>
non-array-type:</para><itemizedlist><listitem override="none"><para>value-type</para><para>
classed-type</para><para> delegate-type</para><para> error-type</para></listitem></itemizedlist><para>
dimension-separators:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">,</emphasis></para><para> dimension-separators <emphasis
role="strong">,</emphasis></para></listitem></itemizedlist><para>
delegate-type:</para><itemizedlist><listitem
override="none"><para>user-defined-delegate-type</para></listitem></itemizedlist><para>
error-type:</para><itemizedlist><listitem
override="none"><para>user-defined-error-type</para></listitem></itemizedlist></listitem></itemizedlist><section><title>Classed
types</title><para>A class definition introduces a new reference type - this is the most common way of
creating a new type in
Vala. Classes are a very powerful mechanism, as they have features such as polymorphism and inheritance.
Full discussion of classes is found at <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#";>Classes</ulink>.
</para><para>Most classed types in Vala are reference counted. This means that every time a classed type
instance is assigned to a variable or field, not only is the reference copied, but the instance also records
that another reference to it has been created. When a field or variable goes out of scope, the fact that a
reference to the instance has been removed is also recorded. This means that a classed type instance can be
automatically removed from memory when it is no longer needed. The only classed types that are not reference
counted are compact classes.. Memory management is discussed at <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Overview#Memory_man
agement">Overview/Memory management</ulink>. If the instance is not of a reference counted type, then the
ownership must be explicitly transferred using the # operator - this will cause the original variable to
become invalid. When a classed-type instance is passed to a method, the same rules apply. The types of
classes available are discussed at <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#Types_of_class";>Classes/Types
of class</ulink>. </para></section><section><title>Array types</title><para>TODO: Check correctness.
</para><para>An array is a data structure that can contains zero or more elements of the same type, up to a
limit defined by the type. An array may have multiple dimensions; for each possible set of dimensions a new
type is implied, but there is a meta type available that describes an array of any size with the same number
of dimensions, i.e. int[1] is not the same type as int[2], while int[] is the
same type as either. </para><para>See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Array_instantiation";>Expressions/Array
instantiation</ulink> for how to instantiate an array type. </para></section><section><title>Delegate
types</title><para>A delegate is a data structure that refers to a method. A method executes in a given
scope which is also stored, meaning that for instance methods a delegate will contain also a reference to the
instance. </para><para>Delegates are technically a referenced type, but since methods are immutable, this
distinction is less important than for other types. Assigning a delegate to a variable or field cannot copy
the method indicated, and no delegate is able to change the method in any way. </para><para>See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Delegates#";>Delegates</ulink>
for full documentation. </para></section><section><
title>Error Types</title><para>Instances of error types represent recoverable runtime errors. All errors
are described using error domains, a type of enumerated value, but errors themselves are not enumerated
types. Errors are discussed in detail in several sections of this documentation, see: <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Errors#";>Errors</ulink>,
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Enumerated%20types%20%28Enums%29#Error_domains";>Enumerated
types (Enums)/Error domains</ulink> and <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Methods#";>Methods</ulink>.
</para></section><section><title>Strings</title><para>Vala has built in support for Unicode strings, via the
fundamental string type. This is the only fundamental type that is a reference type. Like other fundamental
types, it can be instantiated with a
literal expression (<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Literal_expressions";>Expressions/Literal
expressions</ulink>.) Strings are UTF-8 encoded, the same as Vala source files, which means that they
cannot be accessed like character arrays in C - each Unicode character is not guaranteed to be stored in just
one byte. Instead the string fundamental struct type (which all strings are instances of) provides access
methods along with other tools. </para><para>While strings are technically a reference type, they have the
same default copy semantics as structs - the data is copied whenever a string value is assigned to a variable
or field, but only a reference is passed as a parameter to a method. This is required because strings are
not reference counted, and so the only way for a variable or field to be able to take ownership of a string
is by being assigned a copy of the string. To avoid this behaviour,
string values can be assigned to weak references (in such a case no copy is made). </para><para>The concept
of ownership is very important in understanding string semantics. For more details see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Concepts#References_and_ownership";>Concepts/References
and ownership</ulink>. </para></section></section><section><title>Parameterised types</title><para>TODO:
Casting. </para><para>Vala allows definitions of types that can be customised at runtime with type
parameters. For example, a list can be defined so that it can be instantiated as a list of ints, a list of
Objects, etc. This is achieved using generic declarations. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Generics#";>Generics</ulink>.
</para></section><section><title>Nullable types</title><para>The name of a type can be used to implicitly
create a nullable type related to tha
t type. An instance of a nullable type <code>T?</code> can either be a value of type <code>T</code> or
<code>null</code>. </para><para>A nullable type will have either value or reference type semantics, depending
on the type it is based on. </para></section><section><title>Pointer types</title><para>The name of a type
can be used to implicitly create a pointer type related to that type. The value of a variable declared as
being of type T* represents the memory address of an instance of type T. The instance is never made aware
that its address has been recorded, and so cannot record the fact that it is referred to in this way.
</para><para>Instances of any type can be assigned to a variable that is declared to be a pointer to an
instance of that type. For referenced types, direct assignment is allowed in either direction. For value
types the pointer-to operator "&" is required to assign to a pointer, and the
pointer-indirection operator "*" is used
to access the instance pointed to. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Pointer_expressions";>Expressions/Pointer
expressions</ulink>. </para><para>The <code>void*</code> type represents a pointer to an unknown type. As
the referent type is unknown, the indirection operator cannot be applied to a pointer of type
<code>void*</code>, nor can any arithmetic be performed on such a pointer. However, a pointer of type
<code>void*</code> can be cast to any other pointer type (and vice-versa) and compared to values of other
pointer types. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Type_operations";>Expressions/Type
operations</ulink>. </para><para>A pointer type itself has value type semantics.
</para></section><section><title>Type conversions</title><para>There are two types if type conversions
possible in Vala, implicit conversions and expli
cit casts. In expressions, Vala will often convert fundamental types in order to make calculations
possible. When the default conversion is not what you require, you can cast explicitly so that all operands
are of compatible types. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#";>Expressions</ulink>
for details of automatic conversions. </para><para>Vala will also automatically perform conversions related
to polymorphism where the required cast is unambiguous and can be inferred from the context. This allows you
to use a classed-type instance when an instance of any of its superclasses or implemented interfaces is
required. Vala will never automatically cast to a subtype, as this must be done explicitly. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Concepts#Object_oriented_programming";>Concepts/Object
oriented programming</ulink>, see <ulink url="http://wi
ki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#">Classes</ulink>.
</para><para>For explicit casting expressions, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Type_operations";>Expressions/Type
operations</ulink>. </para></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Expressions</title><para>Expressions are short pieces of code that
define an action that should be taken when they are reached during a program's execution. Such an operation
can be arithmetical, calling a method, instantiating a type, and so on. All expressions evaluate to a single
value of a particular type - this value can then be used in another expression, either by combing the
expressions together, or by assigning the value to an identifier. </para><para>When expressions are combin
ed together (e.g. add two numbers, then multiply the result by another: 5 + 4 * 3), then the order in which
the sub-expressions are evaluated becomes significant. Parentheses are used to mark out which expressions
should be nested within others, e.g. (5 + 4) * 3 implies the addition expression is nested inside the
multiplication expression, and so must be evaluated first. </para><para>When identifiers are used in
expressions they evaluate to their value, except when used in assignment. The left handed side of an
assignment are a special case of expressions where an identifier is not considered an expression in itself
and is therefore not evaluated. Some operations combine assignment with another operation (e.g. increment
operations,) in which cases an identifier can be thought of as an expression initially, and then just an
identifier for assignment after the overall expression has been evaluated. </para><itemizedlist><listitem
override="none"><para>primary-expression:</p
ara><itemizedlist><listitem override="none"><para>literal</para><para> template</para><para>
member-access-expression</para><para> pointer-member-access-expression</para><para>
element-access-expression</para><para> postfix-expression</para><para>
class-instantiation-expression</para><para> array-instantiation-expression</para><para>
struct-instantiation-expression</para><para> invocation-expression</para><para>
sizeof-expression</para><para> typeof-expression</para></listitem></itemizedlist><para>
unary-expression:</para><itemizedlist><listitem override="none"><para>primary-expression</para><para>
sign-expression</para><para> logical-not-expression</para><para> bitwise-not-expression</para><para>
prefix-expression</para><para> ownership-transfer-expression</para><para> cast-expression</para><para>
pointer-expression</para></listitem></itemizedlist><para> expression:</para><itemizedlist><listitem
override="none"><para>conditional-expression</para><para> assignment-expression
</para><para>
lambda-expression</para></listitem></itemizedlist></listitem></itemizedlist><section><title>Literal
expressions</title><para>Each literal expression instantiates its respective type with the value given.
</para><para>Integer types... -?[:digit:]+ </para><para>Floating point types... -?[:digit:]+(.[:digit:]+)?
</para><para>Strings... "[^"\n]*". """.*"""
</para><para>Booleans... true|false </para><para>A final literal expression is <code>null</code>. This
expression evaluates to a non-typed data instance, which is a legal value for any nullable type (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Types#Nullable_types";>Types/Nullable
types</ulink>.) </para></section><section><title>Member access</title><para>To access members of another
scope. </para><itemizedlist><listitem
override="none"><para>member-access-expression:</para><itemizedlist><listitem override="none"><para>[ pr
imary-expression <emphasis role="strong">.</emphasis> ]
identifier</para></listitem></itemizedlist></listitem></itemizedlist><para>If no inner expression is
supplied, then the identifier will be looked up starting from the current scope (for example a local variable
in a method). Otherwise, the scope of the inner expression will be used. The special identifier <emphasis
role="strong">this</emphasis> (without inner expression) inside an instance method will refer to the instance
of the type symbol (class, struct, enum, etc.). </para></section><section><title>Element
access</title><itemizedlist><listitem
override="none"><para>element-access-expression:</para><itemizedlist><listitem
override="none"><para>container <emphasis role="strong">[</emphasis> indexes <emphasis
role="strong">]</emphasis></para></listitem></itemizedlist><para> container:</para><itemizedlist><listitem
override="none"><para>expression</para></listitem></itemizedlist><para> indexes:</para><itemizedlist><list
item override="none"><para>expression [ <emphasis role="strong">,</emphasis> indexes
]</para></listitem></itemizedlist></listitem></itemizedlist><para>Element access can be used for:
</para><itemizedlist><listitem><para>Accessing an element of a container at the given indexes
</para></listitem><listitem><para>Assigning an element to a container at the given indexes. In this case the
element access expression is the left handed side of an assignment.
</para></listitem></itemizedlist><para>Element access can be used on strings, arrays and types that have
<emphasis role="strong">get</emphasis> and/or <emphasis role="strong">set</emphasis> methods.
</para><itemizedlist><listitem><para>On strings you can only access characters, it's not possible to assign
any value to an element. </para></listitem><listitem><para>On arrays, it's possible to both access an element
or assign to an element. The type of the element access expression is the same as the array element type.
</para></lis
titem></itemizedlist><para>Element access can also be used with complex types (such as class, struct, etc.)
as containers: </para><itemizedlist><listitem><para>If a <emphasis role="strong">get</emphasis> method exists
accepting at least one argument and returning a value, then indexes will be used as arguments and the return
value as element. </para></listitem><listitem><para>If a <emphasis role="strong">set</emphasis> method exists
accepting at least two arguments and returns <emphasis role="strong">void</emphasis>, then indexes will be
used as arguments and the assigned value as last argument..
</para></listitem></itemizedlist></section><section><title>Arithmetic operations</title><para>Binary
operators, taking one argument on each side. Each argument is an expression returning an appropriate type.
</para><para>Applicable, unless said otherwise, where both operands evaluate to numeric types (integer or
floating point). </para><para>Where at least one operand is a of float
ing point type, the result will be the same type as the largest floating point type involved. Where both
operands are of integer types, the result will have the same type as the largest of the integer types
involved. </para><para>Addition/Subtraction: </para><itemizedlist><listitem
override="none"><para>additive-expression:</para><itemizedlist><listitem
override="none"><para>multiplicative-expression</para><para> multiplicative-expression <emphasis
role="strong">+</emphasis> multiplicative-expression</para><para> multiplicative-expression <emphasis
role="strong">-</emphasis> multiplicative-expression</para></listitem></itemizedlist><para>
sign-expression:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">+</emphasis>
unary-expression</para><para> <emphasis role="strong">-</emphasis>
unary-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Adds/Subtracts the second
argument to/from the first. Negations is equivalent to subtr
action the operand from 0. </para><para>Overflow? </para><para>Multiplication/Division:
</para><itemizedlist><listitem override="none"><para>multiplicative-expression:</para><itemizedlist><listitem
override="none"><para>unary-expression</para><para> unary-expression <emphasis role="strong">*</emphasis>
unary-expression</para><para> unary-expression <emphasis role="strong">/</emphasis>
unary-expression</para><para> unary-expression <emphasis role="strong">%</emphasis>
unary-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Multiplies/divides the first
argument by the second. </para><para>If both operands are of integer types, then the result will be the
quotient only of the calculation (equivalent to the precise answer rounded down to an integer value.) If
either operand is of a floating point type, then the result will be as precise as possible within the
boundaries of the result type (which is worked out from the basic arithmetic type rules.) </par
a></section><section><title>Relational operations</title><para>Result in a value of bool type.
</para><para>Applicable for comparing two instances of any numeric type, or two instances of string type.
Where numeric with at least one floating point type instance, operands are both converted to the largest
floating point type involved. Where both operands are of integer type, both are converted to the largest
integer type involved. When both are strings, they are lexically compared somehow.
</para><itemizedlist><listitem override="none"><para>equality-expression:</para><itemizedlist><listitem
override="none"><para>relational-expression </para><para>relational-expression <emphasis
role="strong">==</emphasis> relational-expression</para><para> relational-expression <emphasis
role="strong">!=</emphasis>
relational-expression</para></listitem></itemizedlist><para>relational-expression:</para><itemizedlist><listitem
override="none"><para>shift-expression </para><para>shift-expre
ssion <emphasis role="strong"><</emphasis> relational-expression</para><para> shift-expression <emphasis
role="strong"><=</emphasis> relational-expression</para><para> shift-expression <emphasis
role="strong">></emphasis> relational-expression</para><para> shift-expression <emphasis
role="strong">>=</emphasis> relational-expression</para><para> is-expression</para><para>
as-expression</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Increment/decrement
operations</title><itemizedlist><listitem
override="none"><para>postfix-expression:</para><itemizedlist><listitem
override="none"><para>primary-expression <emphasis role="strong">++</emphasis></para><para>
primary-expression <emphasis role="strong">--</emphasis></para></listitem></itemizedlist><para>
prefix-expression:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">++</emphasis>
unary-expression</para><para> <emphasis role="strong">--</emphasis> unary-
expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Postfix and prefix expressions:
</para><screen><![CDATA[var postfix = i++;
+var prefix = --j;]]></screen><para>are equivalent to: </para><screen><![CDATA[var postfix = i;
+i += 1;
+]]><![CDATA[
+j -= 1;
+var prefix = j;]]></screen></section><section><title>Logical operations</title><para>Applicable to boolean
type operands, return value is of boolean type. No non boolean type instances are automatically converted.
</para><itemizedlist><listitem override="none"><para>logical-or-expression:</para><itemizedlist><listitem
override="none"><para>logical-and-expression <emphasis role="strong">||</emphasis>
logical-and-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Documentation
</para><itemizedlist><listitem override="none"><para>logical-and-expression:</para><itemizedlist><listitem
override="none"><para>contained-in-expression <emphasis role="strong">&&</emphasis>
contained-in-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Documentation
</para><itemizedlist><listitem override="none"><para>logical-not-expression:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">!</emphasis> expression</para>
</listitem></itemizedlist></listitem></itemizedlist></section><section><title>Bitwise
operations</title><para>All only applicable to integer types. </para><itemizedlist><listitem
override="none"><para>bitwise-or-expression:</para><itemizedlist><listitem
override="none"><para>bitwise-xor-expression <emphasis role="strong">|</emphasis>
bitwise-xor-expression</para></listitem></itemizedlist><para>
bitwise-xor-expression:</para><itemizedlist><listitem override="none"><para>bitwise-and-expression <emphasis
role="strong">&</emphasis> bitwise-and-expression</para></listitem></itemizedlist><para>
bitwise-and-expression:</para><itemizedlist><listitem override="none"><para>equality-expression <emphasis
role="strong">&</emphasis> equality-expression</para></listitem></itemizedlist><para>
bitwise-not-expression:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">~</emphasis> expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Docum
entation </para><itemizedlist><listitem
override="none"><para>shift-expression:</para><itemizedlist><listitem
override="none"><para>additive-expression <emphasis role="strong"><<</emphasis>
additive-expression</para><para> additive-expression <emphasis role="strong">>></emphasis>
additive-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Shifts the bits of the
left argument left/right by the number represented by the second argument. </para><para>Undefined for
shifting further than data size, e.g. with a 32 bit integer... </para><para>Documentation
</para></section><section><title>Assignment operations</title><para>Value assigned to identifier on left.
Type must match. </para><para>When assignment includes another operation natural result type must match the
declared type of variable which is the left hand side of the expression. e.g. Let a be an int instance with
the value 1, a += 0.5 is not allowed, as the natural result type of 1 +
0.5 is a float, not an int. </para><itemizedlist><listitem
override="none"><para>assignment-expression:</para><itemizedlist><listitem
override="none"><para>simple-assignment-expression</para><para>
number-assignment-expression</para></listitem></itemizedlist><para>
simple-assignment-expression:</para><itemizedlist><listitem override="none"><para>conditional-expression
<emphasis role="strong">=</emphasis> expression</para></listitem></itemizedlist><para>
number-assignment-expression:</para><itemizedlist><listitem override="none"><para>conditional-expression
<emphasis role="strong">+=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong">-=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong">*=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong">/=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong">%=</emphasis> expression</para><para> conditional-expression <
emphasis role="strong">|=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong">&=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong">^=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong"><<=</emphasis> expression</para><para> conditional-expression <emphasis
role="strong">>>=</emphasis>
expression</para></listitem></itemizedlist></listitem></itemizedlist><para>A simple assignment expression
assigns the right handed side value to the left handed side. It is necessary that the left handed side
expression is a valid lvalue. Other assignments: </para><screen><![CDATA[result += value;
+result <<= value;
+...]]></screen><para>Are equivalent to simple assignments: </para><screen><![CDATA[result = result + value;
+result = result << value;
+...]]></screen></section><section><title>Invocation expressions</title><itemizedlist><listitem
override="none"><para>invocation-expression:</para><itemizedlist><listitem override="none"><para>[ <emphasis
role="strong">yield</emphasis> ] primary-expression <emphasis role="strong">(</emphasis> [ arguments ]
<emphasis role="strong">)</emphasis></para></listitem></itemizedlist><para>
arguments:</para><itemizedlist><listitem override="none"><para>expression [ <emphasis
role="strong">,</emphasis> arguments]</para></listitem></itemizedlist></listitem></itemizedlist><para>The
expression can refer to any callable: a method, a delegate or a signal. The type of the expression depends
upon the return type of the callable symbol. Each argument expression type must be compatible against the
respective callable parameter type. If an argument is not provided for a parameter then: </para><orderedlist
numeration="arabic"><listitem><para>If the parameter has a default value, then that value wi
ll be used as argument. </para></listitem><listitem><para>Otherwise an error occurs.
</para></listitem></orderedlist><para>If the callable has an ellipsis parameter, then any number of arguments
of any type can be provided past the ellipsis. </para><para>Delegates... See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Delegates#";>Delegates</ulink>
</para><para>Firing a signal is basically the same. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Signals";>Classes/Signals</ulink>
</para></section><section><title>Class instantiation</title><para>To instantiate a class (create an instance
of it) use the <code>new</code> operator. This operator takes a the name of the class, and a list of zero or
more arguments to be passed to the creation method. </para><itemizedlist><listitem
override="none"><para>class-instantiation-expression:</para><itemizedlist><listitem
override="none"><para><emphasis
role="strong">new</emphasis> type-name <emphasis role="strong">(</emphasis> arguments <emphasis
role="strong">)</emphasis></para></listitem></itemizedlist><para> arguments:</para><itemizedlist><listitem
override="none"><para>expression [ <emphasis role="strong">,</emphasis> arguments
]</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Struct
instantiation</title><itemizedlist><listitem
override="none"><para>struct-instantiation-expression:</para><itemizedlist><listitem
override="none"><para>type-name <emphasis role="strong">(</emphasis> arguments <emphasis
role="strong">)</emphasis> [ <emphasis role="strong">{</emphasis> initializer <emphasis
role="strong">}</emphasis> ]</para></listitem></itemizedlist><para>
initializer:</para><itemizedlist><listitem override="none"><para>field-name <emphasis
role="strong">=</emphasis> expression [ <emphasis role="strong">,</emphasis> initializer
]</para></listitem></itemizedlist><para> arguments:</para><it
emizedlist><listitem override="none"><para>expression [ <emphasis role="strong">,</emphasis> arguments
]</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Array
instantiation</title><para>This expression will create an array of the given size. The second approach shown
below is a shorthand to the first one. </para><itemizedlist><listitem
override="none"><para>array-instantiation-expression:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">new</emphasis> type-name <emphasis role="strong">[</emphasis>
sizes <emphasis role="strong">]</emphasis> [ <emphasis role="strong">{</emphasis> [ initializer ] <emphasis
role="strong">}</emphasis> ]</para><para> <emphasis role="strong">{</emphasis> initializer <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para> sizes:</para><itemizedlist><listitem
override="none"><para>expression [ <emphasis role="strong">,</emphasis> sizes
]</para></listitem></itemizedlist
<para> initializer:</para><itemizedlist><listitem override="none"><para>expression [ <emphasis
role="strong">,</emphasis> initializer
]</para></listitem></itemizedlist></listitem></itemizedlist><para>Sizes expressions must evaluate either to
an integer type or an enum value. Initializer expressions type must be compatible with the array element
type. </para></section><section><title>Conditional expressions</title><para>Allow a conditional in a single
expression. </para><itemizedlist><listitem
override="none"><para>conditional-expression:</para><itemizedlist><listitem
override="none"><para>boolean-expression [ <emphasis role="strong">?</emphasis> conditional-true-clause
<emphasis role="strong">:</emphasis> conditional-false-clause ]</para></listitem></itemizedlist><para>
boolean-expression:</para><itemizedlist><listitem
override="none"><para>coalescing-expression</para></listitem></itemizedlist><para>
conditional-true-clause:</para><itemizedlist><listitem override="none"><pa
ra>expression</para></listitem></itemizedlist><para> conditional-false-clause</para><itemizedlist><listitem
override="none"><para>expression</para></listitem></itemizedlist></listitem></itemizedlist><para>First
boolean-expression is evaluated. If true, then the conditional-true-clause is evaluated, and its result is
the result of the conditional expression. If the boolean expression evaluates to false, then the
conditional-false-clause is evaluated, and its result becomes the result of the conditional expression.
</para></section><section><title>Coalescing expressions</title><itemizedlist><listitem
override="none"><para>coalescing-expression:</para><itemizedlist><listitem
override="none"><para>nullable-expression [ <emphasis role="strong">??</emphasis> coalescing-expression
]</para></listitem></itemizedlist><para> nullable-expression:</para><itemizedlist><listitem
override="none"><para>logical-or-expression</para></listitem></itemizedlist></listitem></itemizedlist></sectio
n><section><title>Flag operations</title><para>Flag types are a variation on enumerated types, in which any
number of flag values can be combined in a single instance of the flag type. There are therefore operations
available to combine several values in an instance, and to find out which values are represented in an
instance. </para><itemizedlist><listitem
override="none"><para>flag-combination-expression:</para><itemizedlist><listitem
override="none"><para>expression <emphasis role="strong">|</emphasis>
expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Where both expressions evaluate to
instances of the same flag type, the result of this expression is a new instance of the flag type in which
all values represented by either operand are represented. </para><itemizedlist><listitem
override="none"><para>flag-recombination-expression:</para><itemizedlist><listitem
override="none"><para>expression <emphasis role="strong">^</emphasis> expression</para><
/listitem></itemizedlist></listitem></itemizedlist><para>Where both expressions evaluate to instances of the
same flag type, the result of this expression is a new instance of the flag type in which all values
represented by exactly one of the operands are represented. </para><itemizedlist><listitem
override="none"><para>flag-separation-expression:</para><itemizedlist><listitem
override="none"><para>expression <emphasis role="strong">&</emphasis>
expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Where both expressions evaluate to
instances of the same flag type, the result of this expression is a new instance of the flag type in which
all values represented by both operands are represented. </para><itemizedlist><listitem
override="none"><para>flag-in-expression:</para><itemizedlist><listitem override="none"><para>expression
<emphasis role="strong">in</emphasis>
expression</para></listitem></itemizedlist></listitem></itemizedlist><para>Where both
expressions evaluate to instances of the same flag type, the result of this expression is a boolean. The
result will be true if the left-handed flag is set into the right-handed flags.
</para></section><section><title>Type operations</title><itemizedlist><listitem
override="none"><para>is-expression:</para><itemizedlist><listitem override="none"><para>shift-expression
<emphasis role="strong">is</emphasis>
type-name</para></listitem></itemizedlist></listitem></itemizedlist><para>Performs a runtime type check on
the instance resulting from evaluating the the nested expression. If the instance is an instance of the type
described (with, for example, a class or interface name,) the overall expression evaluates to true.
</para><para>Casting: </para><itemizedlist><listitem
override="none"><para>cast-expression:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">(!)</emphasis> unary-expression</para><para> <emphasis role="strong">(</emphasis> type-name <em
phasis role="strong">)</emphasis>
unary-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>A cast expression returns
the instance created in the nested expression as an instance of the type described. If the nested expression
evaluates to an instance of a type that is not also an instance of the given type, the expression is not
valid. If you are not sure whether the cast is valid, instead use an "as" expression.
</para><itemizedlist><listitem override="none"><para>as-expression:</para><itemizedlist><listitem
override="none"><para>shift-expression <emphasis role="strong">as</emphasis>
type-name</para></listitem></itemizedlist></listitem></itemizedlist><para>An "as" expression
combines an "is" expression and a cast operation, with the latter depending on the former. If the
nested expression evaluates to an instance of the given type, then a cast is performed and the expression
evaluates to the result of the nested expre
ssion cast as the given type. Otherwise, the result is null. </para><itemizedlist><listitem
override="none"><para>sizeof-expression:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">sizeof (</emphasis> type-name <emphasis
role="strong">)</emphasis></para></listitem></itemizedlist><para>
typeof-expression:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">typeof
(</emphasis> type-name <emphasis
role="strong">)</emphasis></para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Ownership
transfer expressions</title><itemizedlist><listitem
override="none"><para>ownership-transfer-expression:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">(owned)</emphasis>
unary-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>When an instance of a
reference type is assigned to a variable or field, it is possible to request that the ownership of the
instance is
passed to the new field or variable. The precise meaning of this depends on the reference type, for an
explanation of ownership, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#References_and_ownership";>Concepts/References
and ownership</ulink>. The identifier in this expression must refer to an instance of a reference type.
</para><para>Note that similar syntax is used to define that a method parameter should take ownership of a
value assigned to it. For this, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#";>Methods</ulink>.
</para></section><section><title>Lambda expressions</title><itemizedlist><listitem
override="none"><para>lambda-expression:</para><itemizedlist><listitem override="none"><para>params <emphasis
role="strong">=></emphasis> body</para></listitem></itemizedlist><para>
params:</para><itemizedlist><listitem override="none"><para>[ direction ] identifie
r</para><para> <emphasis role="strong">(</emphasis> [ param-names ] <emphasis
role="strong">)</emphasis></para></listitem></itemizedlist><para> param-names:</para><itemizedlist><listitem
override="none"><para>[ direction ] identifier [ <emphasis role="strong">,</emphasis> param-names
]</para></listitem></itemizedlist><para> direction:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">out</emphasis></para><para> <emphasis
role="strong">ref</emphasis></para></listitem></itemizedlist><para> body:</para><itemizedlist><listitem
override="none"><para>statement-block</para><para>
expression</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Pointer
expressions</title><itemizedlist><listitem
override="none"><para>addressof-expression:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">&</emphasis>
unary-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>The "address o
f" expression evaluates to a pointer to the inner expression. Valid inner expressions are:
</para><itemizedlist><listitem><para>Variables (local variables, fields and parameters)
</para></listitem><listitem><para>Element access whose container is an array or a pointer </para><para>
pointer-indirection-expression:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">*</emphasis>
unary-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>The pointer indirection
evaluates to the value pointed to by the inner expression. The inner expression must be a valid pointer type
and it must not be a pointer to a reference type (for example pointer indirection to a type
<code>SomeClass*</code> is not possible). </para><itemizedlist><listitem
override="none"><para>pointer-member-access-expression:</para><itemizedlist><listitem
override="none"><para>primary-expression <emphasis role="strong">-></emphasis>
identifier</para></listitem></ite
mizedlist></listitem></itemizedlist><para>This expression evaluates to the value of the member identified by
the identifier. The inner expression must be a valid pointer type and the member must be in the scope of the
base type of the pointer type. </para></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Statements</title><para>Statements define the path of execution within
methods and similar constructions. They combine expressions together with structures for choosing between
different code paths, repeating code sections, etc. </para><itemizedlist><listitem
override="none"><para>statement:</para><itemizedlist><listitem
override="none"><para>empty-statement</para><para> simple-statement</para><para> statement-block</para><para>
variable-declaration-statement</para><para> if-statement</para><para> switch-statement</para><para>
while-statement</para><p
ara> do-statement</para><para> for-statement</para><para> foreach-statement</para><para>
return-statement</para><para> throw-statement</para><para> try-statement</para><para>
lock-statement</para></listitem></itemizedlist><para> embedded-statement:</para><itemizedlist><listitem
override="none"><para>statement</para></listitem></itemizedlist></listitem></itemizedlist><section><title>Simple
statements</title><para>The Empty Statement does nothing, but is a valid statement nonetheless, and so can
be used wherever a statement is required. </para><itemizedlist><listitem
override="none"><para>empty-statement:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>A Simple Statement
consists of one a subset of expressions that are considered free-standing. Not all expressions are allowed,
only those that potentially have a useful side effect - for example, arithmetic expressions canno
t form simple statements on their own, but are allowed as part of an assignement expressions, which has a
useful side effect. </para><itemizedlist><listitem
override="none"><para>simple-statement:</para><itemizedlist><listitem
override="none"><para>statement-expression <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>
statement-expression:</para><itemizedlist><listitem override="none"><para>assigment-expression</para><para>
class-instantiation-expression</para><para> struct instantiation-expression</para><para>
invocation-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>A Statement Block
allows several statements to be used in a context that would otherwise only allow one.
</para><itemizedlist><listitem override="none"><para>statement-block:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">{</emphasis> [ statement-list ] <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para> s
tatement-list:</para><itemizedlist><listitem override="none"><para>statement [ statement-list
]</para></listitem></itemizedlist></listitem></itemizedlist><para>Blocks create anonymous, transient scopes.
For more details about scopes, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink>. </para></section><section><title>Variable declaration</title><para>Variable Declaration
Statements define a local variable in current scope. The declaration includes a type, which signifies the
variable will represent an instance of that type. Where the type can be inferred by the compiler, the
type-name can be replaced with the literal "var" </para><itemizedlist><listitem
override="none"><para>variable-declaration-statement:</para><itemizedlist><listitem
override="none"><para>variable-declaration-with-explicit-type</para><para>
variable-declaration-with-explicit-type-and-initialiser
</para><para> variable-declaration-with-type-inference</para></listitem></itemizedlist><para>
variable-declaration-with-explicit-type:</para><itemizedlist><listitem override="none"><para>type-name
identifier <emphasis role="strong">;</emphasis></para></listitem></itemizedlist><para>
variable-declaration-with-explicit-type-and-initialiser:</para><itemizedlist><listitem
override="none"><para>type-name identifier <emphasis role="strong">=</emphasis> expression <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>
variable-declaration-with-type-inference:</para><itemizedlist><listitem override="none"><para>var identifier
<emphasis role="strong">=</emphasis> expression <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>Type inference is
possible in any case where the variable is immediately assigned to. The type chosen will always be the type
of the assigned expression, as decided by the rules described at <
ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#";>Expressions</ulink>.
It is important to realise that the type of the variable will be fixed after the first assignment, and will
not change on assigning another value to the variable. If the variable should be created with a type other
than that of the assigned expression, the expression should be wrapped with a cast expression, provided that
the cast is valid. </para></section><section><title>Selection statements</title><para>The If Statement
decides whether to execute a given statement based on the value of a boolean expression. There are two
possible extensions to this model: </para><para>An else clause declares that a given statement should be run
if-and-only-if the condition in the the if statement fails. </para><para>Any number of "else if"
clauses may appear between the "if" statement and its "else" clause (if there is one.)
These are equ
ivalent to: </para><para>FIXME: This doesn't work. </para><para>In simple terms, the program will test the
conditions of the if statement and its "else if" clauses in turn, executing the statement belonging
to the first that succeeds, or running the else clause if every condition fails.
</para><itemizedlist><listitem override="none"><para>if-statement:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">if</emphasis> <emphasis role="strong">(</emphasis>
boolean-expression <emphasis role="strong">)</emphasis> embedded-statement [ elseif-clauses ] [ <emphasis
role="strong">else</emphasis> embedded-statement ]</para></listitem></itemizedlist><para>
elseif-clauses:</para><itemizedlist><listitem override="none"><para>elseif-clause</para><para> [
elseif-clauses ]</para></listitem></itemizedlist><para> elseif-clause:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">else if</emphasis> <emphasis role="strong">(</emphasis> b
oolean-expression <emphasis role="strong">)</emphasis>
embedded-statement</para></listitem></itemizedlist></listitem></itemizedlist><para>The switch statement
decides which of a set of statements to execute based on the value of an expression. A switch statement will
lead to the execution of one or zero statements. The choice is made by: </para><itemizedlist><listitem
override="none"><para>switch-statement:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">switch</emphasis> <emphasis role="strong">(</emphasis> expression <emphasis
role="strong">)</emphasis> <emphasis role="strong">{</emphasis> [ case-clauses ] [ default-clause ] <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para> case-clauses:</para><itemizedlist><listitem
override="none"><para>case-clause</para><para> [ case-clauses ]</para></listitem></itemizedlist><para>
case-clause:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">case</emphas
is> literal-expression <emphasis role="strong">:</emphasis>
embedded-statement</para></listitem></itemizedlist><para> default-clause:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">default</emphasis> <emphasis role="strong">:</emphasis>
embedded-statement</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Iteration
statements</title><para>Iteration statements are used to execute statements multiple times based on certain
conditions. Iteration Statements contain loop embedded statements - a superset of embedded statements which
adds statements for manipulating the iteration. </para><itemizedlist><listitem
override="none"><para>loop-embedded-statement:</para><itemizedlist><listitem
override="none"><para>loop-embedded-statement-block</para><para> embedded-statement</para><para>
break-statement</para><para> continue-statement</para></listitem></itemizedlist><para>
loop-embedded-statement-block:</para><itemizedlist><l
istitem override="none"><para><emphasis role="strong">{</emphasis> [ loop-embedded-statement-list ]
<emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
loop-embedded-statement-list:</para><itemizedlist><listitem override="none"><para>loop-embedded-statement [
loop-embedded-statement-list ]</para></listitem></itemizedlist></listitem></itemizedlist><para>Both break and
continue statement are types of jump statement, described in <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Statements#Jump_statements";>Statements/Jump
statements</ulink>. </para><para>The while statement conditionally executes an embedded statement zero or
more times. When the while statement is reached, the boolean expression is executed. If the boolean value
is true, the embedded statement is executed and execution returns to the while statement. If the boolean
value is false, execution continues after the while statement. </para><itemizedlist>
<listitem override="none"><para>while-statement:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">while</emphasis> <emphasis role="strong">(</emphasis>
boolean-expression <emphasis role="strong">)</emphasis>
loop-embedded-statement</para></listitem></itemizedlist></listitem></itemizedlist><para>The do statement
conditionally executes an embedded statement one or more times. First the embedded statement is executed,
and then the boolean expression is evaluated. If the boolean value is true, execution returns to the do
statement. If the boolean value is false, execution continues after the do statement.
</para><itemizedlist><listitem override="none"><para>do-statement:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">do</emphasis> loop-embedded-statement <emphasis
role="strong">while</emphasis> <emphasis role="strong">(</emphasis> boolean-expression <emphasis
role="strong">)</emphasis> <emphasis role="strong">;</emphasis
</para></listitem></itemizedlist></listitem></itemizedlist><para>The for statement first evaluates a
sequence of initialization expressions, then repeatedly executes an embedded statement. At the start of
each iteration a boolean expression is evaluated, with a true value leading the execution of the embedded
statement, a false value leading to execution passing to the first statement following the do statement.
After each iteration a sequence of iteration expressions are evaluated. Executing this type of statement
creates a new transient scope, in which any variables declared in the initializer are created.
</para><itemizedlist><listitem override="none"><para>for-statement:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">for</emphasis> <emphasis role="strong">(</emphasis> [
for-initializer ] <emphasis role="strong">;</emphasis> [ for-condition ] <emphasis
role="strong">;</emphasis> [ for-iterator ] <emphasis role="strong">)</emphasis> loop-em
bedded-statement</para></listitem></itemizedlist><para> for-initializer:</para><itemizedlist><listitem
override="none"><para>variable-declaration [ <emphasis role="strong">,</emphasis> expression-list
]</para></listitem></itemizedlist><para> for-condition:</para><itemizedlist><listitem
override="none"><para>boolean-expression</para></listitem></itemizedlist><para>
for-iterator:</para><itemizedlist><listitem
override="none"><para>expression-list</para></listitem></itemizedlist></listitem></itemizedlist><para>The
foreach statement enumerates the elements of a collection, executing an embedded statement for each element
of the collection. Each element in turn is assigned to a variable with the given identifier and the embedded
statement is executed. Executing this type of statement creates a new transient scope in which the variable
representing the collection element exists. </para><itemizedlist><listitem
override="none"><para>foreach-statement:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">foreach</emphasis> <emphasis role="strong">(</emphasis> type
identifier <emphasis role="strong">in</emphasis> expression <emphasis role="strong">)</emphasis>
loop-embedded-statement</para></listitem></itemizedlist></listitem></itemizedlist><para>Foreach Statements
are able to iterate over arrays and any class that implements the Gee.Iterable interface. This may change in
future if an Iterable interface is incorporated into GLib. </para></section><section><title>Jump
statements</title><para>Jump statements move execution to an arbitary point, dependent on the type of
statement and its location. In any of these cases any transient scopes are ended appropriately: <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink> and <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Statements#Simple_statements";>Stat
ements/Simple statements</ulink>. </para><para>A break statement moves execution to the first statement
after the nearest enclosing while, do, for, or foreach statement. </para><itemizedlist><listitem
override="none"><para>break-statement:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">break</emphasis> <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>A continue
statement immediately moves execution the nearest enclosing while, do, for, or foreach statement.
</para><itemizedlist><listitem override="none"><para>continue-statement:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">continue</emphasis> <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>The return
statement ends the execution of a method, and therefore completes the invocation of the method. The
invocation expression has then been fully evaluated, and takes o
n the value of the expression in the return statement if there is one. </para><itemizedlist><listitem
override="none"><para>return-statement:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">return</emphasis> [ expression ] <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>The throw
statement throws an exception. </para><itemizedlist><listitem
override="none"><para>throw-statement:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">throw</emphasis> expression <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Try
statement</title><para>The try statement provides a mechanism for catching exceptions that occur during
execution of a block. Furthermore, the try statement provides the ability to specify a block of code that is
always executed when control leaves the try statement. </para><para>For the syntax o
f the try statement, See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Errors#Error_catching";>Errors/Error
catching</ulink>. </para></section><section><title>Lock statement</title><para>Locks Statements are the main
part of Vala's resource control mechanism. </para><para>FIXME: Haven't actually written anything here about
resource control. </para><itemizedlist><listitem
override="none"><para>lock-statement:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">lock</emphasis> <emphasis role="strong">(</emphasis> identifier <emphasis
role="strong">)</emphasis>
embedded-statement</para></listitem></itemizedlist></listitem></itemizedlist></section></section><para>Back
to <ulink url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Namespaces</title><para>Namespaces are named scopes (see <ulink
url="http://wiki.gnome.org/action/show/Projec
ts/Vala/Manual/Export/Vala/Manual/Concepts#Scope_and_naming">Concepts/Scope and naming</ulink>).
Definitions in different namespaces can use the same names without causing conflicts. A namespace can be
declared across any number of Vala source files, and there can be multiple namespaces defined in a single
Vala source file. Namespaces can be nested to any depth. </para><para>When code needs to access definitions
from other namespaces, it must either refer to them using a fully qualified name, or be written in a file
with an appropriate using statement. </para><para>The simplest namespace declaration looks like this:
</para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[namespace]]></token><![CDATA[
]]><methodname><![CDATA[NameSpaceName]]></methodname><![CDATA[ {]]>
+<![CDATA[}]]>
+</programlisting><para>Namespace nesting is achieved either by nesting the declarations, or by providing
multiple names in one declaration: </para><programlisting format="linespecific" language="cpp"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[namespace]]></token><![CDATA[
]]><methodname><![CDATA[NameSpaceName1]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[namespace]]></token><![CDATA[
]]><methodname><![CDATA[NameSpaceName2]]></methodname><![CDATA[ {]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<token><![CDATA[namespace]]></token><![CDATA[
]]><methodname><![CDATA[NameSpaceName1]]></methodname><![CDATA[.]]><methodname><![CDATA[NameSpaceName2]]></methodname><![CDATA[
{]]>
+<![CDATA[}]]>
+</programlisting><section><title>The global namespace</title><para>Everything not declared within a
particular namespace declaration is automatically in the global namespace. All defined namespaces are nested
inside the global namespace at some depth. This is also where the fundamental types are defined.
</para><para>If there is ever a need to explictly refer to an identifier in the global namespace, the
identifier can be prefixed with <code>global::</code>. This will allow you, for example, to refer to a
namespace which has the same name as a local variable. </para></section><section><title>Namespace
declaration</title><itemizedlist><listitem
override="none"><para>namespace-declaration:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">namespace</emphasis> qualified-namespace-name <emphasis role="strong">{</emphasis> [
namespace-members ] <emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
qualified-namespace-name:</para>
<itemizedlist><listitem override="none"><para>[ qualified-namespace-name <emphasis
role="strong">.</emphasis> ]
namespace-name</para></listitem></itemizedlist><para>namespace-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
namespace-members:</para><itemizedlist><listitem override="none"><para>namespace-member [ namespace-members
]</para></listitem></itemizedlist><para> namespace-member:</para><itemizedlist><listitem
override="none"><para>class-declaration</para><para> abstract-class-declaration</para><para>
constant-declaration</para><para> delegate-declaration</para><para> enum-declaration</para><para>
errordomain-declaration</para><para> field-declaration</para><para> interface-declaration</para><para>
method-declaration</para><para> namespace-declaration</para><para>
struct-declaration</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Members</title><para>Namespaces
members exist
in the namespace's scope. They fall into two broad categories: data and definitions. Data members are
fields which contain type instances. Definitions are things that can be invoked or instantiated. Namespace
members can be declared either private or public. Public data can be accessed from anywhere, whilst private
data can only be accessed from inside the namespace. Public definitions are visible to code defined in a
different namespace, and thus can be invoked or instantiated from anywhere, private definitions are only
visible to code inside the namespace, and so can only be invoked or instantiated from there.
</para><itemizedlist><listitem override="none"><para>access-modifier:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">public</emphasis></para><para> <emphasis
role="strong">private</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>For the
types of namespace members that are not described on this page: see <ul
ink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#";>Classes</ulink>,
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Structs#";>Structs</ulink>,
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Delegates#";>Delegates</ulink>,
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Enumerated%20types%20%28Enums%29#";>Enumerated
types (Enums)</ulink>, and <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Enumerated%20types%20%28Enums%29#Error_domains";>Enumerated
types (Enums)/Error domains</ulink>. </para></section><section><title>Fields</title><para>Variables that
exist directly in a namespace are known as namespace fields. These exist only once, and within the scope of
the namespace which exists for the application's entire run time. They are therefore similar to global
variables in C but without
the risk of naming clashes. </para><itemizedlist><listitem
override="none"><para>field-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] qualified-type-name field-name [ <emphasis role="strong">=</emphasis> expression ]
;</para></listitem></itemizedlist><para> field-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist></listitem></itemizedlist><para>Fields in
general are described at <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Variables,_fields_and_parameters";>Concepts/Variables,
fields and parameters</ulink>. </para></section><section><title>Constants</title><para>Constants are similar
to variables but can only be assigned to once. It is therefore required that the expression that initialises
the constant be executable at the time the constant comes into scope. For namespaces this means that the
expressions must be evaluable at the beginnin
g of the application's execution. </para><itemizedlist><listitem
override="none"><para>constant-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] <emphasis role="strong">const</emphasis> qualified-type-name constant-name <emphasis
role="strong">=</emphasis> expression ;</para></listitem></itemizedlist><para>
constant-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>The
"using" statement</title><para><code>using</code> statements can be used to avoid having to
qualify names fully on a file-by-file basis. For all identifiers in the same file as the using statement,
Vala will first try to resolve them following the usual rules (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink>). If the identifier cannot be resolved in any scope, e
ach namespace that is referenced in a <code>using</code> will be searched in turn.
</para><itemizedlist><listitem override="none"><para>using-statement:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">using</emphasis> namespace-list <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>
namespace-list:</para><itemizedlist><listitem override="none"><para>qualified-namespace-name [ <emphasis
role="strong">,</emphasis> namespace-list
]</para></listitem></itemizedlist></listitem></itemizedlist><para>There can be any number of using statements
in a Vala source file, but they must all appear outside any other declarations. Note that <code>using</code>
is not like import statements in other languages - it does not load anything, it just allows for automatic
searching of namespace scopes, in order to allow frugal code to be written. </para><para>Most code depends on
members of the GLib namespace, and so many source files begin with:
</para><screen><![CDATA[using GLib;]]></screen><para>TODO: Include examples.
</para></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Methods</title><para>TODO: Do we really need this discussion? Are we
introducing Vala, or general programming? </para><para>A method is an executable statement block that can be
identified in one or more ways (i.e. by a name, or any number of delegate instances). A method can be invoked
with an optional number of parameters, and may return a value. When invoked, the method's body will be
executed with the parameters set to the values given by the invoker. The body is run in sequence until the
end is reached, or a return statement is encountered, resulting in a return of control (and possibly some
value, in the case of a return) to the invoker. </para><para>There are various contexts that may contain
method declarations
(see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Namespaces#";>Namespaces</ulink>,
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#";>Classes</ulink>,
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Interfaces#";>Interfaces</ulink>,
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Structs#";>Structs</ulink>). A
method is always declared inside one of these other declarations, and that declaration will mark the parent
scope that the method will be executed within. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink>. </para><para>The <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#";>Classes</ulink>
section of this documentation talks about both methods and abstract methods. I
t should be noted that the latter are not truly methods, as they cannot be invoked. Instead, they provide a
mechanism for declaring how other methods should be defined. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#";>Classes</ulink> for
a description of abstract methods and how they are used. </para><para>The syntax for invoking a method is
described on the expressions page (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Invocation_expressions";>Expressions/Invocation
expressions</ulink>). </para><section><title>Parameter directions</title><para>The basics of method
parameter semantics are described on the concepts page (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Variables,_fields_and_parameters";>Concepts/Variables,
fields and parameters</ulink>). This basic form of parameter is technically an "in" para
meter, which is used to pass data needed for the method to operate. If the parameter is of a reference
type, the method may change the fields of the type instance it receives, but assignments to the parameter
itself will not be visible to the invoking code. If the parameter is of a value type, which is not a
fundamental type, the same rules apply as for a reference type. If the parameter is of a fundamental type,
then the parameter will contain a copy of the value, and no changes made to it will be visible to the
invoking code. </para><para>If the method wishes to return more than one value to the invoker, it should use
"out" parameters. Out parameters do not pass any data to the method - instead the method may
assign a value to the parameter that will be visible to the invoking code after the method has executed,
stored in the variable passed to the method. If a method is invoked passing a variable which has already
been assigned to as an out parameter, then
the value of that variable will be dereferenced or freed as appropriate. If the method does not assign a
value to the parameter, then the invoker's variable will end with a value of "null".
</para><para>The third parameter type is a "ref" argument (equivalent to "inout" in some
other languages.) This allows the method to receive data from the invoker, and also to assign another value
to the parameter in a way that will be visible to the invoker. This functions similarly to "out"
parameters, except that if the method does not assign to the parameter, the same value is left in the
invoker's variable. </para></section><section><title>Method declaration</title><para>The syntax for declaring
a method changes slightly based on what sort of method is being declared. This section shows the form for a
namespace method, Vala's closest equivalent to a global method in C. Many of the parts of the declaration
are common to all types, so sectio
ns from here are referenced from class methods, interface methods, etc. </para><itemizedlist><listitem
override="none"><para>method-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] return-type qualified-method-name ( [ params-list ] ) [ <emphasis
role="strong">throws</emphasis> error-list ] method-contracts <emphasis role="strong">{</emphasis>
statement-list <emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
return-type:</para><itemizedlist><listitem override="none"><para>type</para><para> <emphasis
role="strong">void</emphasis></para></listitem></itemizedlist><para>
qualified-method-name:</para><itemizedlist><listitem override="none"><para>[ qualified-namespace-name
<emphasis role="strong">.</emphasis> ] method-name</para></listitem></itemizedlist><para>
method-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
params-list:</para><itemizedlist><listitem ove
rride="none"><para>parameter [ <emphasis role="strong">,</emphasis> params-list
]</para></listitem></itemizedlist><para> parameter:</para><itemizedlist><listitem override="none"><para>[
parameter-direction ] type identifier</para></listitem></itemizedlist><para>
parameter-direction:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">ref</emphasis></para><para> <emphasis
role="strong">out</emphasis></para></listitem></itemizedlist><para> error-list:</para><itemizedlist><listitem
override="none"><para>qualified-error-domain [ <emphasis role="strong">,</emphasis> error-list
]</para></listitem></itemizedlist><para> method-contracts:</para><itemizedlist><listitem
override="none"><para>[ <emphasis role="strong">requires</emphasis> <emphasis role="strong">(</emphasis>
expression <emphasis role="strong">)</emphasis> ] [ <emphasis role="strong">ensures</emphasis> <emphasis
role="strong">(</emphasis> expression <emphasis role="strong">)</emphasis> ]</para></li
stitem></itemizedlist></listitem></itemizedlist><para>For more details see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#Contract_programming";>Methods/Contract
programming</ulink>, and <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Errors#";>Errors</ulink>.
</para></section><section><title>Invocation</title><para>See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Invocation_expressions";>Expressions/Invocation
expressions</ulink>. </para></section><section><title>Scope</title><para>The execution of a method happens
in a scope created for each invocation, which ceases to exist after execution is complete. The parent scope
of this transient scope is always the scope the method was declared in, regardless of where it is invoked
from. </para><para>Parameters and local variables exist in the invocation's transient scope. For more on
scoping see
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink>. </para></section><section><title>Lambdas</title><para>As Vala supports delegates, it is
possible to have a method that is identified by a variable (or field, or parameter.) This section discusses
a Vala syntax for defining inline methods and directly assigning them to an identifier. This syntax does not
add any new features to Vala, but it is a lot more succinct than the alternative (defining all methods
normally, in order to assign them to variables at runtime). See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Delegates#";>Delegates</ulink>.
</para><para>Declaring an inline method must be done with relation to a delegate or signal, so that the
method signature is already defined. Parameter and return types are then learned from the signature. A
lambda definition is an expression that r
eturns an instance of a particular delegate type, and so can be assigned to a variable declared for the same
type. Each time that the lambda expression is evaluated it will return a reference to exactly the same
method, even though this is never an issue as methods are immutable in Vala. </para><itemizedlist><listitem
override="none"><para>lambda-declaration:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">(</emphasis> [ lambda-params-list ] <emphasis role="strong">)</emphasis> <emphasis
role="strong">=></emphasis> <emphasis role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>
lambda-params-list:</para><itemizedlist><listitem override="none"><para>identifier [ <emphasis
role="strong">,</emphasis> lambda-params-list
]</para></listitem></itemizedlist></listitem></itemizedlist><para>An example of lambda use:
</para><programlisting format="linespecific" language="cpp" linenumbering="
numbered" startinglinenumber="1"><methodname><![CDATA[delegate]]></methodname><![CDATA[
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[DelegateType]]></methodname><![CDATA[
(]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[a]]></methodname><![CDATA[,
]]><methodname><![CDATA[string]]></methodname><![CDATA[
]]><methodname><![CDATA[b]]></methodname><![CDATA[);]]>
+
+<token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[use_delegate]]></methodname><![CDATA[
(]]><methodname><![CDATA[DelegateType]]></methodname><![CDATA[
]]><methodname><![CDATA[d]]></methodname><![CDATA[, ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[, ]]><methodname><![CDATA[string]]></methodname><![CDATA[
]]><methodname><![CDATA[b]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><methodname><![CDATA[d]]></methodname><![CDATA[ (]]><methodname><![CDATA[a]]></methodname><![CDATA[,
]]><methodname><![CDATA[b]]></methodname><![CDATA[);]]>
+<![CDATA[}]]>
+
+<token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[make_delegate]]></methodname><![CDATA[ ()
{]]>
+<![CDATA[ ]]><methodname><![CDATA[DelegateType]]></methodname><![CDATA[
]]><methodname><![CDATA[d]]></methodname><![CDATA[ = (]]><methodname><![CDATA[a]]></methodname><![CDATA[,
]]><methodname><![CDATA[b]]></methodname><![CDATA[) => {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[;]]>
+<![CDATA[ };]]>
+<![CDATA[
]]><methodname><![CDATA[use_delegate]]></methodname><![CDATA[(]]><methodname><![CDATA[d]]></methodname><![CDATA[,
5,
]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[test]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[}]]>
+</programlisting></section><section><title>Contract programming</title><para>TODO: requires, ensures.
</para><para>requires ( ... ) Denotes things that must be true to start execution. </para><para>ensures ( ...
) Denotes things that must be true to end execution.
</para></section><section><title>Examples</title><para>TODO: write examples.
</para></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Delegates</title><para>A delegate declaration defines a method type: a
type that can be invoked, accepting a set of values of certain types, and returning a value of a set type. In
Vala, methods are not first-class objects, and as such cannot be created dynamically; however, any method can
be considered to be an instance of a delegate's type, provided that the method signature matches that of the
delegate. </para><para>Methods are considered to be an immutable
reference type. Any method can be referred to by name as an expression returning a reference to that method
- this can be assigned to a field (or variable, or parameter), or else invoked directly as a standard method
invocation (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Invocation_expressions";>Expressions/Invocation
expressions</ulink>). </para><section><title>Types of delegate</title><para>All delegate types in Vala are
defined to be either static or instance delegates. This refers to whether the methods that may be considered
instances of the delegate type are instance members of classes or structs, or not. </para><para>To assign an
instance of an instance delegate, you must give the method name qualified with an identifier that refers to a
class or struct instance. When an instance of an instance delegate is invoked, the method will act as though
the method had been invoked directly: the "this" keywo
rd will be usuable, instance data will be accessible, etc. </para><para>Instance and static delegate
instances are not interchangeable. </para></section><section><title>Delegate declaration</title><para>The
syntax for declaring a delegate changes slightly based on what sort of delegate is being declared. This
section shows the form for a namespace delegate. Many of the parts of the declaration are common to all
types, so sections from here are referenced from class delegates, interface delegates, etc.
</para><itemizedlist><listitem override="none"><para>delegate-declaration:</para><itemizedlist><listitem
override="none"><para>instance-delegate-declaration</para><para>
static-delegate-declaration</para></listitem></itemizedlist><para>
instance-delegate-declaration:</para><itemizedlist><listitem override="none"><para>[ access-modifier ]
<emphasis role="strong">delegate</emphasis> return-type qualified-delegate-name <emphasis
role="strong">(</emphasis> method-params-list <emp
hasis role="strong">)</emphasis> [ <emphasis role="strong">throws</emphasis> error-list ] <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>
static-delegate-declaration:</para><itemizedlist><listitem override="none"><para>[ access-modifier ]
<emphasis role="strong">static</emphasis> <emphasis role="strong">delegate</emphasis> return-type
qualified-delegate-name <emphasis role="strong">(</emphasis> method-params-list <emphasis
role="strong">)</emphasis> [ <emphasis role="strong">throws</emphasis> error-list ] <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>
qualified-delegate-name:</para><itemizedlist><listitem override="none"><para>[ qualified-namespace-name
<emphasis role="strong">.</emphasis> ] delegate-name</para></listitem></itemizedlist><para>
delegate-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist></listitem></itemizedlist><para>Parts of
this syntax are based on th
e respective sections of the method decleration syntax (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#";>Methods</ulink> for
details). </para></section><section><title>Using delegates</title><para>A delegate declaration defines a
type. Instances of this type can then be assigned to variables (or fields, or paramaters) of this type.
Vala does not allow creating methods at runtime, and so the values of delegate-type instances will be
references to methods known at compile time. To simplify the process, inlined methods may be written (see
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#Lambdas";>Methods/Lambdas</ulink>).
</para><para>To call the method referenced by a delegate-type instance, use the same notation as for calling
a method; instead of giving the method's name, give the identifier of the variable, as described in <ulink
url="http://wiki.gnome.org/action/show/Projects/
Vala/Manual/Export/Vala/Manual/Expressions#Invocation_expressions">Expressions/Invocation
expressions</ulink>. </para></section><section><title>Examples</title><para>Defining delegates:
</para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><lineannotation><![CDATA[// Static delegate taking two ints, returning
void:]]></lineannotation>
+<lineannotation/><token><![CDATA[static]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[DelegateName]]></methodname><![CDATA[ (]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[, ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[b]]></methodname><![CDATA[);]]>
+
+<lineannotation><![CDATA[// Instance delegate with the same signature:]]></lineannotation>
+<lineannotation/><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[DelegateName]]></methodname><![CDATA[ (]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[, ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[b]]></methodname><![CDATA[);]]>
+
+<lineannotation><![CDATA[// Static delegate which may throw an error:]]></lineannotation>
+<lineannotation/><token><![CDATA[static]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[DelegateName]]></methodname><![CDATA[ ()
]]><token><![CDATA[throws]]></token><![CDATA[
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[.]]><methodname><![CDATA[Error]]></methodname><![CDATA[;]]>
+</programlisting><para>Invoking delegates, and passing as parameters. </para><programlisting
format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[f1]]></methodname><![CDATA[(]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[) {
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[%d]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[, ]]><methodname><![CDATA[a]]></methodname><![CDATA[); }]]>
+<![CDATA[...]]>
+<token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[f2]]></methodname><![CDATA[(]]><methodname><![CDATA[DelegateType]]></methodname><![CDATA[
]]><methodname><![CDATA[d]]></methodname><![CDATA[, ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><methodname><![CDATA[d]]></methodname><![CDATA[(]]><methodname><![CDATA[a]]></methodname><![CDATA[);]]>
+<![CDATA[}]]>
+<![CDATA[...]]>
+<methodname><![CDATA[f2]]></methodname><![CDATA[(]]><methodname><![CDATA[f1]]></methodname><![CDATA[, 5);]]>
+</programlisting><para>Instance delegates: </para><programlisting format="linespecific" language="cpp"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Test]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[private]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[data]]></methodname><![CDATA[ = 5;]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[method]]></methodname><![CDATA[ (]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[%d
%d]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[, ]]><methodname><![CDATA[a]]></methodname><![CDATA[,
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[data]]></methodname><![CDATA[);]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<methodname><![CDATA[delegate]]></methodname><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[DelegateType]]></methodname><![CDATA[ (]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[);]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Test]]></methodname><![CDATA[();]]>
+<![CDATA[ ]]><methodname><![CDATA[DelegateType]]></methodname><![CDATA[
]]><methodname><![CDATA[d]]></methodname><![CDATA[ =
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[method]]></methodname><![CDATA[;]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><methodname><![CDATA[d]]></methodname><![CDATA[(1);]]>
+<![CDATA[}]]>
+</programlisting><para>With Lambda: </para><screen><![CDATA[f2(a => { stdout.printf("%d\n", a); },
5);]]></screen></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Errors</title><para>Vala Error handling is just for recoverable runtime
errors, anything that can be reasonably foreseen should not be handled with errors, e.g. passing the wrong
args to a method. In that example, a better action is to state that the method's result is undefined on
illegal input, and use method contracts or assertions to catch potential problems during development: See
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#Contract_programming";>Methods/Contract
programming</ulink>. A more suitable use for errors would be reporting missing files, which of course
cannot be detected until the program is running. </para><para>A method may
declare that it throws methods from any number of error domains. Error domains are groups of related
errors, each of which is denoted by a unique symbol in much the same way an enumerated type, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Enumerated%20types%20%28Enums%29#Error_domains";>Enumerated
types (Enums)/Error domains</ulink> for declaration syntax. In Vala it is not allowed to throw arbitrary
data as in C++, and there is no class for errors, as in Java. </para><para>No error can be thrown must either
be caught or declared as being thrown. </para><para>When a method declares it may thrown an error, the
invoker may choose to either catch the error (should one be thrown), or ignore it, meaning it will be thrown
on to that methods caller. In the latter case, the method failing to catch the error must also be declared
to throw that type of error. Errors can only be caught when the method throwing it is invoked within the tr
y block of a try statement. A try statement, with its associated catch blocks, can potentially catch all
errors thrown in its scope, either with catch blocks for all error domains from which a thrown error might
come, or with a generic catch block to catch any error. </para><para>When an error is first thrown, the
"throw" statement is considered the same as a method which from which an error has been thrown.
This means that it is possible to catch errors locally, but this is not good practise. The only proper use
of this functionality is to use a finally block to free resources before the error is thrown from the method.
</para><para>When an error is thrown, the following sequence of events happens: </para><para>NB: finally
clauses are always run, regardless of if error is thrown and/or handled. </para><section><title>Error
throwing</title><para>Throwing an error is done with the following syntax: </para><itemizedlist><listitem
override="none"><para>throw-statem
ent:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">throw</emphasis>
error-description <emphasis role="strong">;</emphasis></para></listitem></itemizedlist><para>
error-description:</para><itemizedlist><listitem override="none"><para>identifier</para><para>
error-creation-expression</para></listitem></itemizedlist><para>
error-creation-expression:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">new</emphasis> qualified-error-type <emphasis role="strong">(</emphasis> message-expression
<emphasis role="strong">)</emphasis></para></listitem></itemizedlist><para>
qualified-error-type:</para><itemizedlist><listitem override="none"><para>qualified-error-domain <emphasis
role="strong">.</emphasis> error-type</para></listitem></itemizedlist><para>
qualified-error-domain:</para><itemizedlist><listitem override="none"><para>[ qualified-namespace-name
<emphasis role="strong">.</emphasis> ] error-domain-name</para></listitem></ite
mizedlist></listitem></itemizedlist><para>That is, throw an error that has already been created and can be
identified by a name, or a new error created with a textual description. The message-expression is any
expression that evaluates to a instace of the string type. </para></section><section><title>Error
catching</title><para>The syntax of the try statement: </para><itemizedlist><listitem
override="none"><para>try-statement:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">try</emphasis> statement-block catch-clauses</para><para> <emphasis
role="strong">try</emphasis> statement-block [catch-clauses]
finally-clause</para></listitem></itemizedlist><para> catch-clauses:</para><itemizedlist><listitem
override="none"><para>[ specific-catch-clauses ] general-catch-clause</para></listitem></itemizedlist><para>
specific-catch-clauses:</para><itemizedlist><listitem
override="none"><para>specific-catch-clause</para><para> [ specific-catch-clauses ]</para>
</listitem></itemizedlist><para> specific-catch-clause:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">catch</emphasis> <emphasis role="strong">(</emphasis>
qualified-error-type identifier <emphasis role="strong">)</emphasis>
statement-block</para></listitem></itemizedlist><para> general-catch-clause:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">catch</emphasis>
statement-block</para></listitem></itemizedlist><para> finally-clause:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">finally</emphasis>
statement-block</para></listitem></itemizedlist></listitem></itemizedlist><para>In the statement block scope
of each catch clause, the error is assigned to a variable with the identifier given.
</para></section><section><title>Examples</title><para>Demonstrating... </para><programlisting
format="linespecific" language="cpp" linenumbering="numbered" startinglinenumber="1"><methodname><![CDATA[err
ordomain]]></methodname><![CDATA[ ]]><methodname><![CDATA[ErrorType1]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[CODE_1A]]></methodname>
+<![CDATA[}]]>
+
+<methodname><![CDATA[errordomain]]></methodname><![CDATA[
]]><methodname><![CDATA[ErrorType2]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[CODE_2A]]></methodname>
+<![CDATA[}]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Test]]></methodname><![CDATA[ :
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[.]]><methodname><![CDATA[Object]]></methodname><![CDATA[
{]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[thrower]]></methodname><![CDATA[()
]]><token><![CDATA[throws]]></token><![CDATA[ ]]><methodname><![CDATA[ErrorType1]]></methodname><![CDATA[,
]]><methodname><![CDATA[ErrorType2]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[throw]]></token><![CDATA[
]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[ErrorType2]]></methodname><![CDATA[.]]><methodname><![CDATA[CODE_1A]]></methodname><![CDATA[(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Error]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ }]]>
+
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[catcher]]></methodname><![CDATA[()
]]><token><![CDATA[throws]]></token><![CDATA[ ]]><methodname><![CDATA[ErrorType2]]></methodname><![CDATA[ {]]>
+
+<![CDATA[ ]]><token><![CDATA[try]]></token><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[thrower]]></methodname><![CDATA[();]]>
+<![CDATA[ } ]]><token><![CDATA[catch]]></token><![CDATA[
(]]><methodname><![CDATA[ErrorType1]]></methodname><![CDATA[
]]><methodname><![CDATA[ex]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><lineannotation><![CDATA[// Deal with ErrorType1]]></lineannotation>
+<lineannotation/><![CDATA[ } ]]><methodname><![CDATA[finally]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><lineannotation><![CDATA[// Tidy up]]></lineannotation>
+<lineannotation/><![CDATA[ }]]>
+<![CDATA[ }]]>
+
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[main]]></methodname><![CDATA[(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+
+<![CDATA[ ]]><token><![CDATA[try]]></token><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[catcher]]></methodname><![CDATA[();]]>
+<![CDATA[ } ]]><token><![CDATA[catch]]></token><![CDATA[
(]]><methodname><![CDATA[ErrorType2]]></methodname><![CDATA[
]]><methodname><![CDATA[ex]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><lineannotation><![CDATA[// Deal with ErrorType2]]></lineannotation>
+<lineannotation/><![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+</programlisting></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Classes</title><para>A class is definition of a data type. A class can
contain fields, constants, methods, properties, and signals. Class types support inheritance, a mechanism
whereby a derived class can extend and specialize a base class. </para><para>The simplest class declaration
looks like this: </para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[ClassName]]></methodname><![CDATA[ {]]>
+<![CDATA[}]]>
+</programlisting><para>As class types support inheritance, you can specify a base class you want to derive
from. A derived class is-a superclass. It gets access to some of its methods etc. It can always be used in
place of a and so on.... </para><para>No classes can have multiple base classes, however GObject subclasses
may implement multiple interfaces. By implementing an interface, a classed type has an is-a relationship
with an interface. Whenever an instance of that interface is expected, an instance of this class will do.
</para><section><title>Types of class</title><para>Vala supports three different types of class:
</para><itemizedlist><listitem><para>GObject subclasses are any classes derived directly or indirectly from
GLib.Object. This is the most powerful type of class, supporting all features described in this page. This
means signals, managed properties, interfaces and complex construction methods, plus all features of the
simpler class types. </para></li
stitem><listitem><para>Fundamental GType classes are those either without any superclass or that don't
inherit at any level from GLib.Object. These classes support inheritence, interfaces, virtual methods,
reference counting, unmanaged properties, and private fields. They are instantiated faster than GObject
subclasses but are less powerful - it isn't recommended in general to use this form of class unless there is
a specific reason to. </para></listitem><listitem><para>Compact classes, so called because they use less
memory per instance, are the least featured of all class types. They are not registered with the GType
system and do not support reference counting, virtual methods, or private fields. They do support unmanaged
properties. Such classes are very fast to instantiate but not massively useful except when dealing with
existing libraries. They are declared using the Compact attribute on the class, See
</para></listitem></itemizedlist><para>Any non-compact clas
s can also be defined as abstract. An abstract class cannot be instantiated and is used as a base class for
derived classes. </para></section><section><title>Types of class members</title><para>There are three
fundamentally different types of class members, instance, class and static.
</para><itemizedlist><listitem><para>Instance members are held per instance of the class. That is, each
instance has its own copies of the members in its own instance scope. Changes to instance fields will only
apply to that instance, calling instance methods will cause them to be executed in the scope of that
instance. </para></listitem><listitem><para>Class members are shared between all instances of a class. They
can be accessed without an instance of the class, and class methods will execute in the scope of the class.
</para></listitem><listitem><para>Static members are shared between all instances of a class and any
sub-classes of it. They can be accessed without an instance of the cl
ass, and static methods will execute in the scope of the class. </para></listitem></itemizedlist><para>The
distinction between class and static members is not common to other object models. The essential difference
is that a sub-class will recieve a copy of all its base classes' class members. This is opposed to static
members, of which there is only one copy - sub classes access can their base classes' static members because
they are automatically imported into the class' scope. </para></section><section><title>Class
scope</title><para>Class scope is more complicated than other scopes, but conceptually the same. A class has
a scope, which consists of its static and class members, as describe above. When an instance of the class is
created, it is given its own scope, consisting of the defined instance members, with the class' scope as its
parent scope. </para><para>Within the code of a class, the instance and class scopes are automatically
searched as appropriate after t
he local scope, so no qualification is normally required. When there is a conflict with a name in the local
scope, the <code>this</code> scope can be used, for example: </para><programlisting format="linespecific"
language="cpp" linenumbering="numbered" startinglinenumber="1"><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[ClassName]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[field_name]]></methodname><![CDATA[;]]>
+<![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[function_name]]></methodname><![CDATA[(]]><methodname><![CDATA[field_name]]></methodname><![CDATA[)
{]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[field_name]]></methodname><![CDATA[ =
]]><methodname><![CDATA[field_name]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+</programlisting><para>When a name is defined in a class which conflicts with one in a subclass, the
<code>base</code> scope can be used, to refer to the scope of the subclass.
</para></section><section><title>Class member visibility</title><para>All class members have a visibility.
This defines whether the member is visible to code in different locations. Visibility is declared using the
following mutually exclusive modifiers: </para><itemizedlist><listitem
override="none"><para>class-member-visibility-modifier:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">private</emphasis></para><para> <emphasis
role="strong">protected</emphasis></para><para> <emphasis role="strong">internal</emphasis></para><para>
<emphasis
role="strong">public</emphasis></para></listitem></itemizedlist></listitem><listitem><para>"private"
asserts that the member will only be visible to code that is within this class declaration
</para></listitem><listitem><para
"protected" asserts that the member will be visible to any code within this class, and also to
any code that is in a subclass of this class </para></listitem><listitem><para>"internal" asserts
that the member should be visible to any code in the project, but excludes the member from the public API
of a shared object </para></listitem><listitem><para>"public" asserts that the member should be
visible to any code, including the public API of a shared object
</para></listitem></itemizedlist><note><para><emphasis role="strong">C Note</emphasis> </para><para>A field
or method's protected status cannot be enforced in the C translation of a Vala library.
</para></note></section><section><title>Class declaration</title><itemizedlist><listitem
override="none"><para>class-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] <emphasis role="strong">class</emphasis> qualified-class-name [ inheritance-list ]
<emphasis role="s
trong">{</emphasis> [ class-members ] <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>
qualified-class-name:</para><itemizedlist><listitem override="none"><para>[ qualified-namespace-name
<emphasis role="strong">.</emphasis> ] class-name</para></listitem></itemizedlist><para>
class-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
inheritance-list:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">:</emphasis>
superclasses-and-interfaces</para></listitem></itemizedlist><para>
superclasses-and-interfaces:</para><itemizedlist><listitem override="none"><para>( qualified-class-name |
qualified-interface-name ) [ <emphasis role="strong">,</emphasis> superclasses-and-interfaces
]</para></listitem></itemizedlist><para> class-members:</para><itemizedlist><listitem
override="none"><para>class-member [ class-members ]</para></listitem></itemizedlist><para>
class-member:</para
<itemizedlist><listitem override="none"><para>class-creation-method-declaration</para><para>
class-constructor-declaration</para><para> class-destructor-declaration</para><para>
class-constant-declaration</para><para> class-delegate-declaration</para><para>
class-enum-declaration</para><para> class-instance-member</para><para> class-class-member</para><para>
class-static-member</para><para> inner-class-declaration</para></listitem></itemizedlist><para>
class-constructor-declaration:</para><itemizedlist><listitem
override="none"><para>class-instance-constructor-declaration</para><para>
class-class-constructor-declaration</para><para>
class-static-constructor-declaration</para></listitem></itemizedlist><para>
class-instance-member:</para><itemizedlist><listitem
override="none"><para>class-instance-field-declaration</para><para>
class-instance-method-declaration</para><para> class-instance-property-declaration</para><para>
class-instance-signal-declaration</para></listitem></i
temizedlist><para> class-class-member:</para><itemizedlist><listitem
override="none"><para>class-class-field-declaration</para><para> class-class-method-declaration</para><para>
class-class-property-declaration</para></listitem></itemizedlist><para>
class-static-member:</para><itemizedlist><listitem
override="none"><para>class-static-field-declaration</para><para>
class-static-method-declaration</para><para>
class-static-property-declaration</para></listitem></itemizedlist><para>
inner-class-declaration:</para><itemizedlist><listitem override="none"><para>[ access-modifier ] <emphasis
role="strong">class</emphasis> class-name [ inheritance-list ] <emphasis role="strong">{</emphasis> [
class-members ] <emphasis role="strong">}</emphasis>
</para></listitem></itemizedlist></listitem></itemizedlist><para>In Vala, a class must have either one or
zero superclasses, where have zero superclasses has the result described in <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/
Manual/Export/Vala/Manual/Classes#Types_of_class">Classes/Types of class</ulink> section. A class must meet
all the prerequisites defined by the interfaces it wishes to implement, by implementing prerequisite
interfaces or inheriting from a particular class. This latter requirement means it is potentially possible
to have two interfaces that cannot be implemented by a single class. </para><note><itemizedlist><listitem
override="none"><para><emphasis role="strong">Note:</emphasis> Interfaces are only supported for GType
classes. Compact classes have access only to a limited form of inheritence, whereby they may inherit from
exactly one or zero other compact classes. </para></listitem></itemizedlist></note><para>When declaring which
class, if any, a new class subclasses, and which interfaces it implements, the names of those other classes
or interfaces can be qualified relative to the class being declared. This means that, for example, if the
class is declared as "cla
ss foo.Bar" (class "Bar" in namespace "foo") then it may subclass class
"Base" in namespace "foo" simply with "class foo.Bar : Base". </para><para>If
an access modifier for the class is not given, the default "internal" is used. </para><para>It is
possible to declare a class definition to be "abstract." An abstract class is one they may not be
instantiated, instead it first be subclassed by a non-abstract ("concrete") class. An abstract
class declaration may include abstract class instance members. These act as templates for methods or
properties that must be implemented in all concrete subclasses of the abstract class. It is thus guaranteed
that any instance of the abstract class (which must be in fact an instance of a concrete subclass) will have
a method or property as described in the abstract class definition. </para><itemizedlist><listitem
override="none"><para>abstract-class-decla
ration:</para><itemizedlist><listitem override="none"><para>[ access-modifier ] <emphasis
role="strong">abstract</emphasis> <emphasis role="strong">class</emphasis> qualified-class-name [
inheritance-list ] <emphasis role="strong">{</emphasis> [ abstract-class-members ] <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>abstract-class-members:</para><itemizedlist><listitem
override="none"><para>class-members</para><para> class-instance-abstract-method-declaration</para><para>
class-instance-abstract-property-declaration</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Controlling
instantiation</title><para>When a class is instantiated, data might be required from the user to set initial
properties. To define which properties should be or can be set at this stage, the class declaration should
be written as: </para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><to
ken><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[ClassName]]></methodname><![CDATA[ :
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[.]]><methodname><![CDATA[Object]]></methodname><![CDATA[
{]]>
+
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[ClassName]]></methodname><![CDATA[() {]]>
+<![CDATA[ }]]>
+
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[ClassName]]></methodname><![CDATA[.]]><methodname><![CDATA[with_some_quality]]></methodname><![CDATA[
(]]><methodname><![CDATA[Property1Type]]></methodname><![CDATA[
]]><methodname><![CDATA[property1value]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[property1]]></methodname><![CDATA[ =
]]><methodname><![CDATA[property1value]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+</programlisting><para>This example allows the <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/ClassName#";>ClassName</ulink> class to be
instantiated either setting no properties, or setting the property. The convention is to name constructors
as "with_" and then a description of what the extra properties will be used for, though following
this is optional. </para><itemizedlist><listitem
override="none"><para>class-creation-method-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] class-name [ <emphasis role="strong">.</emphasis>
creation-method-name ] <emphasis role="strong">(</emphasis> param-list <emphasis role="strong">)</emphasis>
<emphasis role="strong">{</emphasis> construction-assignments <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para> class-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para> crea
tion-method-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
construction-assignments:</para><itemizedlist><listitem override="none"><para>this <emphasis
role="strong">.</emphasis> property-name <emphasis role="strong">=</emphasis> param-name <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>class-name must be
the same as the name of the class. If a creation method is given an extra name, this name is also used with
instantiating the class, using the same syntax as for declaring the method, e.g. <code>var a = new
Button.with_label ("text")</code>. </para><para>If the property being set is construct type then
assignment is made before construction, else afterwards. </para><para>Any number of these are allowed, but
only one with each name (including null name.) </para><note><itemizedlist><listitem
override="none"><para><emphasis role="strong">Note:</emphasis
</para><para><emphasis>For a GObject derived class, only properties may be set at this stage in
construction, no other processing can be done at this time.</emphasis>
</para></listitem></itemizedlist></note></section><section><title>Construction</title><note><itemizedlist><listitem
override="none"><para><emphasis role="strong">Note:</emphasis> </para><para><emphasis>Construction only
follows this process in GObject derived classes.</emphasis>
</para></listitem></itemizedlist></note><para>During instantiaion, after construction properties have been
set, a series of blocks of code are executed. This is the process that prepares the instance for use.
There are three types of <code>construct</code> blocks that a class may define:
</para><itemizedlist><listitem
override="none"><para>class-instance-constructor-declaration:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">construct</emphasis> <emphasis role="strong">{</emphasis>
statement-list <emphas
is role="strong">}</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>Code in this
block is executed on every instance of the class that is instantiated. It is run after construction
properties have been set. </para><itemizedlist><listitem
override="none"><para>class-class-constructor-declaration:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">class</emphasis> <emphasis role="strong">construct</emphasis>
<emphasis role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>This block will be
executed once at the first use of its class, and once at the first use of each subclass of this class.
</para><itemizedlist><listitem
override="none"><para>class-static-constructor-declaration:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">static</emphasis> <emphasis role="strong">construct</emphasis>
<emphasis role="strong
">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>The first time
that a class, or any subclass of it, is instantiated, this code is run. It is guaranteed that this code will
run exactly once in a program where such a class is used. </para><para>The order of execution for
constructors: </para><itemizedlist><listitem
override="none"><para>class-instance-destructor-declaration:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">~</emphasis> class-name <emphasis role="strong">(</emphasis>
<emphasis role="strong">)</emphasis> <emphasis role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>Destruction here.
When does it happen? And when for each type of class? </para></section><section><title>Class
fields</title><para>Fields act as variable with a scope of either the class or a particul
ar instance, and therefore have names and types in the same way. Basic declarations are as:
</para><itemizedlist><listitem
override="none"><para>class-instance-field-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] qualified-type-name field-name [ <emphasis role="strong">=</emphasis>
expression ] ;</para></listitem></itemizedlist><para>
class-class-field-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">class</emphasis> qualified-type-name field-name [
<emphasis role="strong">=</emphasis> expression ] ;</para></listitem></itemizedlist><para>
class-static-field-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">static</emphasis> qualified-type-name field-name [
<emphasis role="strong">=</emphasis> expression ]
;</para></listitem></itemizedlist></listitem></itemizedlist><para
Initial values are optional. FIXME: how much calculation can be done here? what are the defaults?
</para><note><itemizedlist><listitem override="none"><para><emphasis role="strong">Note</emphasis> Initial
values are only allowed in GObject derived classes.
</para></listitem></itemizedlist></note></section><section><title>Class constants</title><para>Constants
defined in a class are basically the same as those defined in a namespace. The only difference is the
scope and the choice of visibilities available. </para><itemizedlist><listitem
override="none"><para>class-constant-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">const</emphasis> qualified-type-name
constant-name <emphasis role="strong">=</emphasis> expression
;</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Class
methods</title><para>Class methods are methods bound to a particularly class or class i
nstance, i.e. they are executed within the scope of that class or class instance. They are declared the
same way as other methods, but within the declaration of a class. </para><para>The same visibility modifiers
can be used as for fields, although in this case they refer to what code can call the methods, rather than
who can see or change values. </para><para>The <code>static</code> modifier is applicable to methods also. A
static method is independent of any instance of the class. It is therefore only in the class scope, and may
only access other <code>static</code> members. </para><itemizedlist><listitem
override="none"><para>class-instance-method-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] [ class-method-type-modifier ] return-type
method-name <emphasis role="strong">(</emphasis> [ params-list ] <emphasis role="strong">)</emphasis>
method-contracts [ <emphasis role="strong">throws</emphasis> exception-list ] <e
mphasis role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>
class-class-method-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">class</emphasis> return-type method-name <emphasis
role="strong">(</emphasis> [ params-list ] <emphasis role="strong">)</emphasis> method-contracts [ <emphasis
role="strong">throws</emphasis> exception-list ] <emphasis role="strong">{</emphasis> statement-list
<emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
class-static-method-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">static</emphasis> return-type method-name
<emphasis role="strong">(</emphasis> [ params-list ] <emphasis role="strong">)</emphasis> method-contracts [
<emphasis role="strong">throws</emphasis> exception-list ] <emphasis role="strong">{
</emphasis> statement-list <emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
class-method-type-modifier:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">virtual</emphasis></para><para> <emphasis
role="strong">override</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>Methods can
be virtual, as described in <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Object_oriented_programming";>Concepts/Object
oriented programming</ulink>. Methods in Vala classes are not virtual automatically, instead the
"virtual" modifier must be used when it is needed. Virtual methods will only chain up if
overridden using the override keyword. </para><para>Vala classes may also define abstract methods, by writing
the declaration with the "abstract" modifier and replacing the method body with an empty statement
";". Abstract methods are not true
methods, as they do not have an associated statement block, and so cannot be invoked. Abstract methods can
only exist in abstract classes, and must be overridden in derived classes. For this reason an abstract
method is always virtual. The purpose of an abstract method is to define methods that all non-abstract
subclasses of the current definition must implement, it is therefore always allowable to invoke the method on
an instance of the abstract class, because it is required that that instance must in fact be of a
non-abstract subclass. </para><itemizedlist><listitem
override="none"><para>class-instance-abstract-method-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] <emphasis role="strong">abstract</emphasis>
return-type method-name <emphasis role="strong">(</emphasis> [ params-list ] <emphasis
role="strong">)</emphasis> method-contracts [ <emphasis role="strong">throws</emphasis> exception-list ]
<emphasis role="str
ong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><note><itemizedlist><listitem
override="none"><para><emphasis role="strong">Note</emphasis> </para><para><emphasis>Virtual methods are not
available to compact classes.</emphasis>
</para></listitem></itemizedlist></note></section><section><title>Properties</title><note><itemizedlist><listitem
override="none"><para><emphasis role="strong">Development Note:</emphasis> </para><para><emphasis>Class and
static properties are not yet supported in current Vala releases.</emphasis>
</para></listitem></itemizedlist></note><note><itemizedlist><listitem override="none"><para><emphasis
role="strong">Note</emphasis> </para><para><emphasis>Fully managed properties are only available to GObject
derived classes - these are properties that can be set dynamically (by providing the property name at
runtime) and can have attached metadata, as is often used in the GTK+ and GNOME libraries. The other class
types can have
unmanaged properties, which appear similar when using Vala, but are actually implemented using simple
methods.</emphasis> </para></listitem></itemizedlist></note><para>Properties are an enhanced version of
fields. They allow custom code to be called whenever the property is retrieved or assigned to, but may be
treated as fields by external Vala code. Properties also function like methods to some extent, and so can be
defined as virtual and overridden in subclasses. Since they are also allowed in interfaces, they allow
interfaces to declare data members that implementing classes must expose (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Interfaces#";>Interfaces</ulink>.)
</para><section><title>Declaration</title><itemizedlist><listitem
override="none"><para>class-instance-property-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] [ class-method-type-modifier ] qualified-type-nam
e property-name <emphasis role="strong">{</emphasis> accessors [ default-value ] <emphasis
role="strong">}</emphasis> <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>class-instance-abstract-property-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] <emphasis role="strong">abstract</emphasis>
qualified-type-name property-name <emphasis role="strong">{</emphasis> automatic-accessors <emphasis
role="strong">}</emphasis> <emphasis role="strong">;</emphasis></para></listitem></itemizedlist><para>
class-class-property-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">class</emphasis> qualified-type-name property-name
<emphasis role="strong">{</emphasis> accessors [ default-value ] <emphasis role="strong">}</emphasis>
<emphasis role="strong">;</emphasis></para></listitem></itemizedlist><para>
class-static-property-declaration:</
para><itemizedlist><listitem override="none"><para>[ class-member-visibility-modifier ] <emphasis
role="strong">static</emphasis> qualified-type-name property-name <emphasis role="strong">{</emphasis>
accessors [ default-value ] <emphasis role="strong">}</emphasis> <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>
property-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
accessors:</para><itemizedlist><listitem override="none"><para>automatic-accessors</para><para> [ getter ] [
setter ] [ property-constructor ]</para></listitem></itemizedlist><para>
automatic-accessors:</para><itemizedlist><listitem override="none"><para>[ automatic-getter ] [
automatic-setter ] [ automatic-property-constructor ]</para></listitem></itemizedlist><para>
automatic-getter:</para><itemizedlist><listitem override="none"><para>[ class-member-visibility-modifier ]
<emphasis role="strong">get</emphasis> <emphasis ro
le="strong">;</emphasis></para></listitem></itemizedlist><para>
automatic-setter:</para><itemizedlist><listitem override="none"><para>[ class-member-visibility-modifier ]
<emphasis role="strong">set</emphasis> [ <emphasis role="strong">construct</emphasis> ] <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para>
automatic-property-constructor:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">construct</emphasis> <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para> get-accessor:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] <emphasis role="strong">get</emphasis> <emphasis
role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para> set-accessor:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] <emphasis role="strong">set</emphasis>
[ <emphasis role="strong">construct</emphasis> ] <emphasis role="strong">{</emphasis> statement-list
<emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
property-constructor:</para><itemizedlist><listitem override="none"><para>[ class-member-visibility-modifier
] <emphasis role="strong">construct</emphasis> <emphasis role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>
default-value:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">default</emphasis>
<emphasis role="strong">=</emphasis> expression <emphasis role="strong">;</emphasis>
</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Execute Code on
Setting/Getting Values</title><para>Properties can either be declared with code that will perform particular
actions on get and set, or can simply declare which actions are allowed and allow Vala to implement simple
get and set met
hods. This second pattern (automatic property) will result in fields being added to the class to store
values that the property will get and set. If either get or set has custom code, then the other must either
be also written in full, or omitted altogether. </para><para>When a value is assigned to a property, the
<emphasis role="strong">set</emphasis> block is invoked, with a parameter called <emphasis
role="strong">value</emphasis> of the same type as the property. When a value is requested from a property,
the <emphasis role="strong">get</emphasis> block is invoked, and must return an instance of the same type of
the property. </para></section><section><title>Construct / Set Construct Block</title><para>A property may
have zero or one <emphasis role="strong">construct</emphasis> blocks. This means either a <emphasis
role="strong">set construct</emphasis> block or a separate <emphasis role="strong">construct</emphasis>
block. If this is the case that then the property
becomes a construct property, meaning that if it is set in creation method, it will be set (using the
construct block, as opposed to any simple <emphasis role="strong">set</emphasis> block, where there is a
distinction) before class construct blocks are called. </para></section><section><title>Notify Changes
Signals</title><para>Managed properties may be annotated with Notify, See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Attributes#";>Attributes</ulink>.
This will cause the class instance to emit a notify signal when the property has been assigned to.
</para></section><section><title>Virtual Properties</title><para>Instance properties can be defined virtual
with the same semantics as for virtual methods. If in an abstract class, an instance property can be defined
as abstract. This is done using the "abstract" keyword on a declaration that is otherwise the same
as an automatic property. It is then the responsibility
of derived classes to implement the property by providing get or set blocks as appropriate. An abstract
property is automatically virtual. </para></section><section><title>Abstract Properties</title><para>As with
methods, it is possible to declare abstract properties. These have much the same semantics as abstract
methods, i.e. all non-abstract subclasses will have to implement properties with at least the accessors
defined in the abstract property. Any <emphasis role="strong">set construct</emphasis> or construct accessor
must be defined too in non-abstract classes and use <emphasis role="strong">override</emphasis>.
</para><itemizedlist><listitem
override="none"><para>class-instance-abstract-property-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] <emphasis role="strong">abstract</emphasis>
qualified-type-name property-name <emphasis role="strong">{</emphasis> automatic-accessors <emphasis
role="strong">}</emphasis> <
emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist></section></section><section><title>Signals</title><note><itemizedlist><listitem
override="none"><para><emphasis role="strong">Note</emphasis> </para><para><emphasis>Signals are only
available to GObject derived classes.</emphasis> </para></listitem></itemizedlist></note><para>Signals are a
system allowing a classed-type instance to emit events which can be recieved by arbitrary listeners.
Receiving these events is achieved by connecting the signal to a handler, for which Vala has a specific
syntax. Signals are integrated with the GLib <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/MainLoop#";>MainLoop</ulink> system, which
provides a system for queueing events (i.e. signal emissions,) when needed - though this capability is not
needed non-threaded applications. </para><itemizedlist><listitem
override="none"><para>class-instance-signal-declaration:</para>
<itemizedlist><listitem override="none"><para>[ class-member-visibility-modifier ] [
class-method-type-modifier ] <emphasis role="strong">signal</emphasis> return-type signal-name <emphasis
role="strong">(</emphasis> [ params-list ] <emphasis role="strong">)</emphasis> <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist><para> signal-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist></listitem></itemizedlist><para>Signals may
also provide an extra piece of information called a signal detail. This is a single string, which can be
used as an initial hint as to the purpose of the signal emission. In Vala you can register that a signal
handler should only be invoked when the signal detail matches a given string. A typical use of signal
details is in GObject's own "notify" signal, which says that a property of an object has changed -
GObject uses the detail string to say which property has been chang
ed. </para><para>To assign a handler to a signal, (or register to receive this type of event from the
instance), use the following form of expression: </para><itemizedlist><listitem
override="none"><para>signal-connection-expression:</para><itemizedlist><listitem
override="none"><para>qualified-signal-name [ signal-detail ] <emphasis role="strong">+=</emphasis>
signal-handler</para></listitem></itemizedlist><para> qualified-signal-name:</para><itemizedlist><listitem
override="none"><para>[ qualified-namespace-name <emphasis role="strong">.</emphasis> ] variable-identifier
<emphasis role="strong">.</emphasis> signal-name</para></listitem></itemizedlist><para>
signal-detail:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">[</emphasis>
expression <emphasis role="strong">]</emphasis></para></listitem></itemizedlist><para>
signal-handler:</para><itemizedlist><listitem override="none"><para>expression</para><para>
qualified-method-name</para><para> lamb
da-expression</para></listitem></itemizedlist></listitem></itemizedlist><para>This expression will request
that the signal handler given be invoked whenever the signal is emitted. In order for such a connection
expression to be legal, the handler must have the correct signature. The handler should be defined to accept
as parameters the same types as the signal, but with an extra parameter before. This parameter should have
the type of the class in which the signal is declared. When a signal is emitted all handlers are called with
this parameter being the object by which the signal was emitted. </para><para>The time that an arbtirary
expression is acceptable in this expression is when that expression evaluates to an instance of a delegate
type, i.e. to a method that is a legal handler for the signal. For details on delegates, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Delegates#";>Delegates</ulink>.
For details on lambda exp
ressions see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#Lambdas";>Methods/Lambdas</ulink>.
</para><para>Note that optional signal detail should be directly appended to the signal name, with no white
space, e.g. <code>o.notify["name"] += ...</code> </para><para>It is also possible to disconnect a
signal handler using the following expression form: </para><itemizedlist><listitem
override="none"><para>signal-disconnection-expression:</para><itemizedlist><listitem
override="none"><para>qualified-signal-name [ signal-detail ] <emphasis role="strong">-=</emphasis>
connected-signal-handler</para></listitem></itemizedlist><para>
connected-signal-handler:</para><itemizedlist><listitem override="none"><para>expression</para><para>
qualified-method-name</para></listitem></itemizedlist></listitem></itemizedlist><para>Note that you cannot
disconnect a signal handler which was defined inline as a lambda expression and then immed
iately connected to the signal. If this is the effect you really need to achieve, you must assign the
lambda expression to an identifier first, so that the lambda can be referred to again at a later time.
</para></section><section><title>Class enums</title><para>Enums defined in a class are basically the same as
those defined in a namespace. The only difference is the scope and the choice of visibilities available.
See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Enumerated%20types%20%28Enums%29#";>Enumerated
types (Enums)</ulink>. </para><itemizedlist><listitem
override="none"><para>class-enum-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">enum</emphasis> enum-name <emphasis
role="strong">{</emphasis> [ enum-members ] <emphasis role="strong">}</emphasis>
</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Class delegates<
/title><para>Delegates defined in a class are basically the same as those defined in a namespace. The only
difference is the scope and the choice of visibilities available. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Delegates#";>Delegates</ulink>.
</para><itemizedlist><listitem
override="none"><para>class-delegate-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] return-type <emphasis role="strong">delegate</emphasis> delegate-name
<emphasis role="strong">(</emphasis> method-params-list <emphasis role="strong">)</emphasis> <emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Examples</title><para>Demonstrating...
</para><screen><![CDATA[// ...]]></screen><section><title>Using Properties</title><para>For more examples
see: <ulink url="https://live.gnome.org/Vala/PropertiesSample";>Samples for Class Properties</u
link> </para><section><title>Virtual Properties</title><programlisting format="linespecific" language="cpp"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[namespace]]></token><![CDATA[
]]><methodname><![CDATA[Properties]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Base]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[protected]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[_number]]></methodname><![CDATA[;]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><token><![CDATA[virtual]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[number]]></methodname><![CDATA[ { ]]>
+<![CDATA[ ]]><methodname><![CDATA[get]]></methodname><![CDATA[ { ]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_number]]></methodname><![CDATA[; ]]>
+<![CDATA[ } ]]>
+<![CDATA[ ]]><methodname><![CDATA[set]]></methodname><![CDATA[ { ]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_number]]></methodname><![CDATA[ =
]]><methodname><![CDATA[value]]></methodname><![CDATA[; ]]>
+<![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><lineannotation><![CDATA[/* ]]></lineannotation>
+<lineannotation><![CDATA[ * This class just use Base class default handle ]]></lineannotation>
+<lineannotation><![CDATA[ * of number property.]]></lineannotation>
+<lineannotation><![CDATA[ */]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Subclass]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Base]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[string]]></methodname><![CDATA[ ]]><methodname><![CDATA[name]]></methodname><![CDATA[
{ ]]><methodname><![CDATA[get]]></methodname><![CDATA[; ]]><methodname><![CDATA[set]]></methodname><![CDATA[;
}]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><lineannotation><![CDATA[/**]]></lineannotation>
+<lineannotation><![CDATA[ * This class override how number is handle internally.]]></lineannotation>
+<lineannotation><![CDATA[ * ]]></lineannotation>
+<lineannotation><![CDATA[ */]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[ClassOverride]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Base]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[override]]></methodname><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[number]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[get]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_number]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]><methodname><![CDATA[set]]></methodname><![CDATA[ {]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_number]]></methodname><![CDATA[ =
]]><methodname><![CDATA[value]]></methodname><![CDATA[ * 3;]]>
+<![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Implementing Virtual Properties...]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[bc]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Base]]></methodname><![CDATA[ ();]]>
+<![CDATA[
]]><methodname><![CDATA[bc]]></methodname><![CDATA[.]]><methodname><![CDATA[number]]></methodname><![CDATA[ =
3;]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Class number =
']]></phrase><phrase><![CDATA["]]></phrase><![CDATA[ +
]]><methodname><![CDATA[bc]]></methodname><![CDATA[.]]><methodname><![CDATA[number]]></methodname><![CDATA[.]]><methodname><![CDATA[to_string]]></methodname><![CDATA[
() + ]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[']]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[sc]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Subclass]]></methodname><![CDATA[ ();]]>
+<![CDATA[
]]><methodname><![CDATA[sc]]></methodname><![CDATA[.]]><methodname><![CDATA[number]]></methodname><![CDATA[ =
3;]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Class number =
']]></phrase><phrase><![CDATA["]]></phrase><![CDATA[ +
]]><methodname><![CDATA[sc]]></methodname><![CDATA[.]]><methodname><![CDATA[number]]></methodname><![CDATA[.]]><methodname><![CDATA[to_string]]></methodname><![CDATA[
() + ]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[']]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[co]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[ClassOverride]]></methodname><![CDATA[ ();]]>
+<![CDATA[
]]><methodname><![CDATA[co]]></methodname><![CDATA[.]]><methodname><![CDATA[number]]></methodname><![CDATA[ =
3;]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Class number =
']]></phrase><phrase><![CDATA["]]></phrase><![CDATA[ +
]]><methodname><![CDATA[co]]></methodname><![CDATA[.]]><methodname><![CDATA[number]]></methodname><![CDATA[.]]><methodname><![CDATA[to_string]]></methodname><![CDATA[
() + ]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[']]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[ 0;]]>
+<![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+</programlisting></section><section><title>Abstract Properties</title><programlisting format="linespecific"
language="cpp" linenumbering="numbered" startinglinenumber="1"><token><![CDATA[namespace]]></token><![CDATA[
]]><methodname><![CDATA[Properties]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[abstract]]></methodname><![CDATA[
]]><token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[Base]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[abstract]]></methodname><![CDATA[
]]><methodname><![CDATA[string]]></methodname><![CDATA[ ]]><methodname><![CDATA[name]]></methodname><![CDATA[
{ ]]><methodname><![CDATA[get]]></methodname><![CDATA[; ]]><methodname><![CDATA[set]]></methodname><![CDATA[
]]><methodname><![CDATA[construct]]></methodname><![CDATA[; }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><methodname><![CDATA[construct]]></methodname><![CDATA[ {]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[name]]></methodname><![CDATA[ =
]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[NO_NAME]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Subclass]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Base]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[private]]></token><![CDATA[
]]><methodname><![CDATA[string]]></methodname><![CDATA[
]]><methodname><![CDATA[_name]]></methodname><![CDATA[;]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[override]]></methodname><![CDATA[
]]><methodname><![CDATA[string]]></methodname><![CDATA[ ]]><methodname><![CDATA[name]]></methodname><![CDATA[
{]]>
+<![CDATA[ ]]><methodname><![CDATA[get]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_name]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><methodname><![CDATA[set]]></methodname><![CDATA[
]]><methodname><![CDATA[construct]]></methodname><![CDATA[ {]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_name]]></methodname><![CDATA[ =
]]><methodname><![CDATA[value]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><lineannotation><![CDATA[/* This class have a default constructor that
initializes]]></lineannotation>
+<lineannotation><![CDATA[ * name as the construct block on Base, and a
.with_name()]]></lineannotation>
+<lineannotation><![CDATA[ * constructor where the user can set class derived name
]]></lineannotation>
+<lineannotation><![CDATA[ * roperty.]]></lineannotation>
+<lineannotation><![CDATA[ */]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[Subclass]]></methodname><![CDATA[.]]><methodname><![CDATA[with_name]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[
]]><methodname><![CDATA[name]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><methodname><![CDATA[Object]]></methodname><![CDATA[
(]]><methodname><![CDATA[name:]]></methodname><methodname><![CDATA[name]]></methodname><![CDATA[);]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_name]]></methodname><![CDATA[ =
]]><methodname><![CDATA[name]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Implementing Abstract Properties...]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[sc]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Subclass]]></methodname><![CDATA[.]]><methodname><![CDATA[with_name]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[TEST_CLASS]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Class name =
']]></phrase><phrase><![CDATA["]]></phrase><![CDATA[ +
]]><methodname><![CDATA[sc]]></methodname><![CDATA[.]]><methodname><![CDATA[name]]></methodname><![CDATA[ +
]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[']]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[sc2]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Subclass]]></methodname><![CDATA[ ();]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Class name =
']]></phrase><phrase><![CDATA["]]></phrase><![CDATA[ +
]]><methodname><![CDATA[sc2]]></methodname><![CDATA[.]]><methodname><![CDATA[name]]></methodname><![CDATA[ +
]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[']]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[ 0;]]>
+<![CDATA[ }]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+</programlisting><para>Compile and run using: </para><screen><![CDATA[# valac source.vala
+# ./source]]></screen></section></section><section><title>Using signals</title><programlisting
format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[public]]></token><![CDATA[
]]><token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[Test]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[signal]]></methodname><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[test]]></methodname><![CDATA[ (]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[data]]></methodname><![CDATA[);]]>
+<![CDATA[}]]>
+
+<token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[delegate]]></methodname><![CDATA[
]]><methodname><![CDATA[TestHandler]]></methodname><![CDATA[
(]]><methodname><![CDATA[Test]]></methodname><![CDATA[ ]]><methodname><![CDATA[t]]></methodname><![CDATA[,
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[data]]></methodname><![CDATA[);]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+
+<![CDATA[ ]]><methodname><![CDATA[Test]]></methodname><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Test]]></methodname><![CDATA[();]]>
+
+<![CDATA[ ]]><methodname><![CDATA[TestHandler]]></methodname><![CDATA[
]]><methodname><![CDATA[h]]></methodname><![CDATA[ = (]]><methodname><![CDATA[t]]></methodname><![CDATA[,
]]><methodname><![CDATA[data]]></methodname><![CDATA[) => {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Data:
%d]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[, ]]><methodname><![CDATA[d]]></methodname><![CDATA[);]]>
+<![CDATA[ }]]>
+
+<![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[test]]></methodname><![CDATA[
();]]>
+<![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[test]]></methodname><![CDATA[ +=
]]><methodname><![CDATA[h]]></methodname><![CDATA[;]]>
+<![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[test]]></methodname><![CDATA[
();]]>
+<![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[test]]></methodname><![CDATA[ -=
]]><methodname><![CDATA[h]]></methodname><![CDATA[;]]>
+<![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[test]]></methodname><![CDATA[
();]]>
+<![CDATA[}]]>
+</programlisting></section></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Signals</title><para>... </para></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Interfaces</title><para>An interface in Vala is a non-instantiable
type. A class may implement any number of interfaces, thereby declaring that an instance of that class
should also be considered an instance of those interfaces. Interfaces are part of the GType system, and so
compact classes may not implement interfaces (see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Types_of_class";>Classes/Types
of class</ulink>.) </para><para>The simplest interface declaration looks like this: </para><programlisting
format="linespecific" language
="cpp" linenumbering="numbered"
startinglinenumber="1"><methodname><![CDATA[interface]]></methodname><![CDATA[
]]><methodname><![CDATA[InterfaceName]]></methodname><![CDATA[ {]]>
+<![CDATA[}]]>
+</programlisting><para>Unlike C# or Java, Vala's interfaces may include implemented methods, and so provide
premade functionality to an implementing class, similar to mixins in other languages. All methods defined in
a Vala interface are automatically considered to be virtual. Interfaces in Vala may also have prerequisites
- classes or other interfaces that implementing classes must inherit from or implement. This is a more
general form of the interface inheritence found in other languages. It should be noted that if you want to
guarantee that all implementors of an interface are GObject type classes, you should give that class as a
prerequisite for the interface. </para><para>Interfaces in Vala have a static scope, identified by the name
of the interface. This is the only scope associated with them (i.e. there is no class or instance scope
created for them at any time.) Non-instance members of the interface (static members and other
declarations,) can be identified us
ing this scope. </para><para>For an overview of object oriented programming, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Concepts#Object_oriented_programming";>Concepts/Object
oriented programming</ulink>. </para><section><title>Interface declaration</title><itemizedlist><listitem
override="none"><para>interface-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] <emphasis role="strong">interface</emphasis> qualified-interface-name [ inheritance-list ]
<emphasis role="strong">{</emphasis> [ interface-members ] <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>
qualified-interface-name:</para><itemizedlist><listitem override="none"><para>[ qualified-namespace-name
<emphasis role="strong">.</emphasis> ] interface-name</para></listitem></itemizedlist><para>
interface-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para> inh
eritance-list:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">:</emphasis>
prerequisite-classes-and-interfaces</para></listitem></itemizedlist><para>
prerequisite-classes-and-interfaces:</para><itemizedlist><listitem override="none"><para>qualified-class-name
[ <emphasis role="strong">,</emphasis> prerequisite-classes-and-interfaces ]</para><para>
qualified-interface-name [ <emphasis role="strong">,</emphasis> prerequisite-classes-and-interfaces
]</para></listitem></itemizedlist><para> interface-members:</para><itemizedlist><listitem
override="none"><para>interface-member [ interface-members ]</para></listitem></itemizedlist><para>
interface-member:</para><itemizedlist><listitem
override="none"><para>interface-constant-declaration</para><para> interface-delegate-declaration</para><para>
interface-enum-declaration</para><para> interface-instance-member</para><para>
interface-static-member</para><para> interface-inner-class-declaration</para><para>
abstract-method-declaration</para></listitem></itemizedlist><para>
interface-instance-member:</para><itemizedlist><listitem
override="none"><para>interface-instance-method-declaration</para><para>
interface-instance-abstract-method-declaration</para><para>
interface-instance-property-declaration</para><para>
interface-instance-signal-declaration</para></listitem></itemizedlist><para>
interface-static-member:</para><itemizedlist><listitem
override="none"><para>interface-static-field-declaration</para><para>
interface-static-method-declaration</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Interface
fields</title><para>As an interface is not instantiable, it may not contain data on a per instance basis.
It is though allowable to define static fields in an interface. These are equivalent to static fields in a
class: they exist exactly once regardless of how many instances there are of classes that implement the
interface. </para><para>The
syntax for static interface fields is the same as the static class fields: See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Class_fields";>Classes/Class
fields</ulink>. For more explanation of static vs instance members, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Types_of_class_members";>Classes/Types
of class members</ulink>. </para></section><section><title>Interface methods</title><para>Interfaces can
contain abstract and non abstract methods. A non-abstract class that implements the interface must provide
implementations of all abstract methods in the interface. All methods defined in an interface are
automatically virtual. </para><para>Vala interfaces may also define static methods. These are equivalent to
static methods in classes. </para><itemizedlist><listitem
override="none"><para>interface-instance-method-declaration:</para><itemizedlist><listitem override="no
ne"><para>[ class-member-visibility-modifier ] return-type method-name <emphasis role="strong">(</emphasis>
[ params-list ] <emphasis role="strong">)</emphasis> method-contracts [ <emphasis
role="strong">throws</emphasis> exception-list ] <emphasis role="strong">{</emphasis> statement-list
<emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>interface-instance-abstract-method-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] <emphasis role="strong">abstract</emphasis>
return-type method-name <emphasis role="strong">(</emphasis> [ params-list ] <emphasis
role="strong">)</emphasis> method-contracts [ <emphasis role="strong">throws</emphasis> exception-list ]
<emphasis role="strong">;</emphasis></para></listitem></itemizedlist><para>
interface-static-method-declaration:</para><itemizedlist><listitem override="none"><para>[
class-member-visibility-modifier ] <emphasis role="strong">static</emphasis> return
-type method-name <emphasis role="strong">(</emphasis> [ params-list ] <emphasis role="strong">)</emphasis>
method-contracts [ <emphasis role="strong">throws</emphasis> exception-list ] <emphasis
role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist></listitem></itemizedlist><para>For discussion of
methods in classes, see: <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Class_methods";>Classes/Class
methods</ulink>. For information about methods in general, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#";>Methods</ulink>. Of
particular note is that an abstract method of an interface defines a method that can always be called in an
instance of an interface, because that instance is guaranteed to be of a non-abstract class that implements
the interface's abstract methods. </para></section><section><title>Interface properties
</title><para>Interfaces can contain properties in a similar way to classes. As interfaces can not contain
per instance data, interface properties cannot be created automatically. This means that all properties must
either be declared abstract (and implemented by implementing classes,) or have explicit get and set clauses
as appropriate. Vala does not allow an abstract property to be partially implemented, instead it should just
define which actions (get, set or both) should be implemented. </para><para>Interfaces are not constructed,
and so there is not concept of a construction property in an interface. For more on properties in classes,
see: <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Properties";>Classes/Properties</ulink>.
</para><itemizedlist><listitem
override="none"><para>interface-instance-property-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-member-visibility-modifier ] [ class-method-
type-modifier ] qualified-type-name property-name <emphasis role="strong">{</emphasis> accessors [
default-value ] <emphasis role="strong">}</emphasis> <emphasis role="strong">;</emphasis></para><para> [
class-member-visibility-modifier ] <emphasis role="strong">abstract</emphasis> qualified-type-name
property-name <emphasis role="strong">{</emphasis> automatic-accessors <emphasis role="strong">}</emphasis>
<emphasis
role="strong">;</emphasis></para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Interface
signals</title><para>Signals can be defined in interfaces. They have exactly the same semantics as when
directly defined in the implementing class. </para><itemizedlist><listitem
override="none"><para>interface-instance-signal-declaration:</para><itemizedlist><listitem
override="none"><para>class-instance-signal-declaration</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Other
interface members</title><para
Constants, Enums, Delegates and Inner Classes all function the same as when they are declared in a class.
See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#";>Classes</ulink>.
When declared in an interface, all these members can be accessed either using the name of the interface
(that is, of the static interface scope), or through and instance of an implementing class.
</para></section><section><title>Examples</title><para>Here is an example implementing (and overriding) an
<emphasis>abstract</emphasis> interface method, </para><screen><![CDATA[/*
+ This example gives you a simple interface, Speaker, with
+ - one abstract method, speak
+]]><![CDATA[
+ It shows you three classes to demonstrate how these and overriding them behaves:
+ - Fox, implementing Speaker
+ - ArcticFox, extending Fox AND implementing Speaker
+ (ArcticFox.speak () replaces superclasses' .speak())
+ - RedFox, extending Fox BUT NOT implementing speaker
+ (RedFox.speak () does not replace superclasses' .speak())
+]]><![CDATA[
+ Important notes:
+ - generally an object uses the most specific class's implementation
+ - ArcticFox extends Fox (which implements Speaker) and implements Speaker itself,
+ - ArcticFox defines speak () with new, so even casting to Fox or Speaker still
+ gives you ArcticFox.speak ()
+ - RedFox extends from Fox, but DOES NOT implement Speaker
+ - RedFox speak () gives you RedFox.speak ()
+ - casting RedFox to Speaker or Fox gives you Fox.speak ()
+*/
+]]><![CDATA[
+/* Speaker: extends from GObject */
+interface Speaker : Object {
+ /* speak: abstract without a body */
+ public abstract void speak ();
+}
+]]><![CDATA[
+/* Fox: implements Speaker, implements speak () */
+class Fox : Object, Speaker {
+ public void speak () {
+ stdout.printf (" Fox says Ow-wow-wow-wow\n");
+ }
+}
+]]><![CDATA[
+/* ArcticFox: extends Fox; must also implement Speaker to re-define
+ * inherited methods and use them as Speaker */
+class ArcticFox : Fox, Speaker {
+ /* speak: uses 'new' to replace speak () from Fox */
+ public new void speak () {
+ stdout.printf (" ArcticFox says Hatee-hatee-hatee-ho!\n");
+ }
+}
+]]><![CDATA[
+/* RedFox: extends Fox, does not implement Speaker */
+class RedFox : Fox {
+ public new void speak () {
+ stdout.printf (" RedFox says Wa-pa-pa-pa-pa-pa-pow!\n");
+ }
+}
+]]><![CDATA[
+public static int main () {
+ Speaker f = new Fox ();
+ Speaker a = new ArcticFox ();
+ Speaker r = new RedFox ();
+]]><![CDATA[
+ stdout.printf ("\n\n// Fox implements Speaker, speak ()\n");
+ stdout.printf ("Fox as Speaker:\n");
+ (f as Speaker).speak (); /* Fox.speak () */
+ stdout.printf ("\nFox as Fox:\n");
+ (f as Fox).speak (); /* Fox.speak () */
+]]><![CDATA[
+ stdout.printf ("\n\n// ArcticFox extends Fox, re-implements Speaker and " +
+ "replaces speak ()\n");
+ stdout.printf ("ArcticFox as Speaker:\n");
+ (a as Speaker).speak (); /* ArcticFox.speak () */
+ stdout.printf ("\nArcticFox as Fox:\n");
+ (a as Fox).speak (); /* ArcticFox.speak () */
+ stdout.printf ("\nArcticFox as ArcticFox:\n");
+ (a as ArcticFox).speak (); /* ArcticFox.speak () */
+]]><![CDATA[
+ stdout.printf ("\n\n// RedFox extends Fox, DOES NOT re-implement Speaker but" +
+ " does replace speak () for itself\n");
+ stdout.printf ("RedFox as Speaker:\n");
+ (r as Speaker).speak (); /* Fox.speak () */
+ stdout.printf ("\nRedFox as Fox:\n");
+ (r as Fox).speak (); /* Fox.speak () */
+ stdout.printf ("\nRedFox as RedFox:\n");
+ (r as RedFox).speak (); /* RedFox.speak () */
+]]><![CDATA[
+ return 0;
+}]]></screen><para>Here is an example of implementing (and inheriting) a <emphasis>virtual</emphasis>
interface method. Note that the same rules for subclasses re-implementing methods that apply to the
<emphasis>abstract</emphasis> interface method above apply here. </para><screen><![CDATA[/*
+ This example gives you a simple interface, Yelper, with
+ - one virtual default method, yelp
+]]><![CDATA[
+ It shows you two classes to demonstrate how these and overriding them behaves:
+ - Cat, implementing Yelper (inheriting yelp)
+ - Fox, implementing Yelper (overriding yelp)
+]]><![CDATA[
+ Important notes:
+ - generally an object uses the most specific class's implementation
+ - Yelper provides a default yelp (), but Fox overrides it
+ - Fox overriding yelp () means that even casting Fox to Yelper still gives
+ you Fox.yelp ()
+ - as with the Speaker/speak() example, if a subclass wants to override an
+ implementation (e.g. Fox.yelp ()) of a virtual interface method
+ (e.g. Yelper.yelp ()), it must use 'new'
+ - 'override' is used when overriding regular class virtual methods,
+ but not when implementing interface virtual methods.
+*/
+]]><![CDATA[
+interface Yelper : Object {
+ /* yelp: virtual, if we want to be able to override it */
+ public virtual void yelp () {
+ stdout.printf (" Yelper yelps Yelp!\n");
+ }
+}
+]]><![CDATA[
+/* Cat: implements Yelper, inherits virtual yelp () */
+class Cat : Object, Yelper {
+}
+]]><![CDATA[
+/* Fox: implements Yelper, overrides virtual yelp () */
+class Fox : Object, Yelper {
+ public void yelp () {
+ stdout.printf (" Fox yelps Ring-ding-ding-ding-dingeringeding!\n");
+ }
+}
+]]><![CDATA[
+public static int main () {
+ Yelper f = new Fox ();
+ Yelper c = new Cat ();
+]]><![CDATA[
+ stdout.printf ("// Cat implements Yelper, inherits yelp\n");
+ stdout.printf ("Cat as Yelper:\n");
+ (c as Yelper).yelp (); /* Yelper.yelp () */
+ stdout.printf ("\nCat as Cat:\n");
+ (c as Cat).yelp (); /* Yelper.yelp () */
+]]><![CDATA[
+ stdout.printf ("\n\n// Fox implements Yelper, overrides yelp ()\n");
+ stdout.printf ("Fox as Yelper:\n");
+ (f as Yelper).yelp (); /* Fox.yelp () */
+ stdout.printf ("\nFox as Fox:\n");
+ (f as Fox).yelp (); /* Fox.yelp () */
+]]><![CDATA[
+ return 0;
+}]]></screen></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Generics</title><para>Generic programming is a way of defining that
something is applicable to a variety of potential types, without having to know these types before hand. The
classic example would be a collection such as a list, which can be trivially customised to contain any type
of data elements. Generics allow a Vala programmer to have these customisations done automatically.
</para><para>Some of these are possible, which? </para><itemizedlist><listitem override="none"><para>class
Wrapper < T > : Object { ... }</para><para> new Wrapper < Object > ( ) ;</para><para> BUG: class
StringWrapper : Wrapper < string > ( ) { ... }</para><para> FAIL: class WrapperWrapper < Wrapper
< T > > : Object { ... }</para><para> FAIL: new WrapperWrapper < Wrapper < Ob
ject > > ( ) ;</para><para> interface IWrapper < T > { ... }</para><para> class ImpWrapper1 <
T > : Object, IWrapper < T > { ... }</para><para> BUG: class ImpWrapper2 : Object, IWrapper <
string > { ... }</para></listitem></itemizedlist><section><title>Generics declaration</title><para>Some of
the syntax could be best placed in the class/interface/struct pages, but that might overcomplicate them...
</para><para>In class declaration - In struct declaration - In interface declaration - In base class
declaration - In implemented interfaces declaration - In prerequesite class/interface declaration.
</para><para>Declaration with type parameters introduces new types into that scope, identified by names given
in declaration, e.g. T. </para><itemizedlist><listitem
override="none"><para>qualified-type-name-with-generic:</para><itemizedlist><listitem
override="none"><para>qualified-class-name-with-generic</para><para> qualified-interface-name-with-generic
</para><para> qualified-struct-name-with-generic</para></listitem></itemizedlist><para>
qualified-class-name-with-generic:</para><itemizedlist><listitem override="none"><para>[
qualified-namespace-name <emphasis role="strong">.</emphasis> ] class-name
type-parameters</para></listitem></itemizedlist><para>
qualified-interface-name-with-generic:</para><itemizedlist><listitem override="none"><para>[
qualified-namespace-name <emphasis role="strong">.</emphasis> ] interface-name
type-parameters</para></listitem></itemizedlist><para>
qualified-struct-name-with-generic:</para><itemizedlist><listitem override="none"><para>[
qualified-namespace-name <emphasis role="strong">.</emphasis> ] struct-name
type-parameters</para></listitem></itemizedlist><para> type-parameters:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong"><</emphasis> generic-clause <emphasis
role="strong">></emphasis></para></listitem></itemizedlist><para> generic-clause:</para><itemized
list><listitem override="none"><para>type-identifier [ <emphasis role="strong">,</emphasis> generic-clause
]</para><para> qualified-type-name [ <emphasis role="strong">,</emphasis> generic-clause
]</para></listitem></itemizedlist><para> type-identifier:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist></listitem></itemizedlist><para>type-identifier
will be the type-name for the parameterised type. </para><para>Deal is: in the class/interface/struct
sections, replace qualified-*-name with qualified-*-name-with-generic.
</para></section><section><title>Instantiation</title><para>Only explanation here? Syntax should go with
variable declaration statement? </para><para>When using generic for a type-name, only type-names can be used
as type-parameters, not identifiers. NB. in scope of generic class, T etc. is a real type-name.
</para></section><section><title>Examples</title><para>Demonstrating... </para><programlisting format="line
specific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[using]]></token><![CDATA[
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[;]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><methodname><![CDATA[interface]]></methodname><![CDATA[
]]><methodname><![CDATA[With]]></methodname><![CDATA[ < ]]><methodname><![CDATA[T]]></methodname><![CDATA[ >
{]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[abstract]]></methodname><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[sett]]></methodname><![CDATA[(]]><methodname><![CDATA[T]]></methodname><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[);]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[abstract]]></methodname><![CDATA[ ]]><methodname><![CDATA[T]]></methodname><![CDATA[
]]><methodname><![CDATA[gett]]></methodname><![CDATA[();]]>
+<![CDATA[}]]>
+
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[One]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[,
]]><methodname><![CDATA[With]]></methodname><![CDATA[ < ]]><token><![CDATA[int]]></token><![CDATA[ > {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[;]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[sett]]></methodname><![CDATA[(]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[t]]></methodname><![CDATA[ =
]]><methodname><![CDATA[t]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[gett]]></methodname><![CDATA[() {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Two]]></methodname><![CDATA[ < ]]><methodname><![CDATA[T]]></methodname><![CDATA[,
]]><methodname><![CDATA[U]]></methodname><![CDATA[ > :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[,
]]><methodname><![CDATA[With]]></methodname><![CDATA[ < ]]><methodname><![CDATA[T]]></methodname><![CDATA[ >
{]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[T]]></methodname><![CDATA[ ]]><methodname><![CDATA[t]]></methodname><![CDATA[;]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[sett]]></methodname><![CDATA[(]]><methodname><![CDATA[T]]></methodname><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[) {]]>
+<![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[t]]></methodname><![CDATA[ =
]]><methodname><![CDATA[t]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[T]]></methodname><![CDATA[ ]]><methodname><![CDATA[gett]]></methodname><![CDATA[()
{]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[U]]></methodname><![CDATA[ ]]><methodname><![CDATA[u]]></methodname><![CDATA[;]]>
+<![CDATA[}]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Test]]></methodname><![CDATA[ :
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[.]]><methodname><![CDATA[Object]]></methodname><![CDATA[
{]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[main]]></methodname><![CDATA[(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[o]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[One]]></methodname><![CDATA[ ();]]>
+<![CDATA[
]]><methodname><![CDATA[o]]></methodname><![CDATA[.]]><methodname><![CDATA[sett]]></methodname><![CDATA[(5);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[%d]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[,
]]><methodname><![CDATA[o]]></methodname><![CDATA[.]]><methodname><![CDATA[t]]></methodname><![CDATA[);]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Two]]></methodname><![CDATA[ < ]]><token><![CDATA[int]]></token><![CDATA[,
]]><token><![CDATA[double]]></token><![CDATA[ > ();]]>
+<![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[sett]]></methodname><![CDATA[(5);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[%d]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[,
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[t]]></methodname><![CDATA[);]]>
+<![CDATA[ ]]>
+<![CDATA[
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[u]]></methodname><![CDATA[ =
5.0f;]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[%f]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[,
]]><methodname><![CDATA[t]]></methodname><![CDATA[.]]><methodname><![CDATA[u]]></methodname><![CDATA[);]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+</programlisting></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Structs</title><para>A struct is a data type that can contain fields,
constants, and methods. </para><para>The simplest struct declaration looks like this: </para><programlisting
format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[struct]]></token><![CDATA[
]]><methodname><![CDATA[StructName]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[some_field]]></methodname><![CDATA[;]]>
+<![CDATA[}]]>
+</programlisting><para>A struct must have at least one field, except in either one of the following cases:
</para><itemizedlist><listitem><para>It's external </para></listitem><listitem><para>It has either one of
<code>[BooleanType]</code>, <code>[IntegerType]</code> or <code>[FloatingType]</code> attributes
</para></listitem><listitem><para>It inherits from another struct
</para></listitem></itemizedlist><section><title>Struct declaration</title><itemizedlist><listitem
override="none"><para>struct-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] <emphasis role="strong">struct</emphasis> qualified-struct-name [ <emphasis
role="strong">:</emphasis> super-struct ] <emphasis role="strong">{</emphasis> [ struct-members ] <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>
qualified-struct-name:</para><itemizedlist><listitem override="none"><para>[ qualified-namespace-name
<emphasis role="strong">.</emphasis> ] struct-na
me</para></listitem></itemizedlist><para> struct-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
struct-members:</para><itemizedlist><listitem override="none"><para>struct-member [ struct-members
]</para></listitem></itemizedlist><para> struct-member:</para><itemizedlist><listitem
override="none"><para>struct-creation-method-declaration:</para><para> struct-field-declaration</para><para>
struct-constant-declaration</para><para>
struct-method-declaration</para></listitem></itemizedlist></listitem></itemizedlist><para>If a super-struct
is given, the struct-name becomes an alias for that struct. </para></section><section><title>Controlling
instantiation</title><itemizedlist><listitem
override="none"><para>struct-creation-method-declaration:</para><itemizedlist><listitem
override="none"><para>[ struct-access-modifier ] struct-name [ <emphasis role="strong">.</emphasis>
creation-method-name ] <emphasis role="strong">(</e
mphasis> param-list <emphasis role="strong">)</emphasis> <emphasis role="strong">{</emphasis> statement-list
<emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
struct-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist></listitem></itemizedlist><para>Unlike in a
class, any code can go in this method. </para></section><section><title>Struct
fields</title><para>Documentation </para><itemizedlist><listitem
override="none"><para>struct-field-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] [struct-field-type-modifier] qualified-type-name field-name [ <emphasis
role="strong">=</emphasis> expression ] ;</para></listitem></itemizedlist><para>
struct-field-type-modifier:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">static</emphasis></para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Struct
constants</title><item
izedlist><listitem override="none"><para>class-constant-declaration:</para><itemizedlist><listitem
override="none"><para>[ class-access-modifier ] <emphasis role="strong">const</emphasis> qualified-type-name
constant-name <emphasis role="strong">=</emphasis> expression
;</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Struct
methods</title><para>See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Methods#";>Methods</ulink>, See
<ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Classes#Class_methods";>Classes/Class
methods</ulink> </para><itemizedlist><listitem
override="none"><para>struct-method-declaration:</para><itemizedlist><listitem override="none"><para>[
access-modifier ] [ struct-method-type-modifier ] return-type method-name <emphasis
role="strong">(</emphasis> [ params-list ] <emphasis role="strong">)</emphasis> method-contracts [ <emphasis
role="strong">thro
ws</emphasis> exception-list ] <emphasis role="strong">{</emphasis> statement-list <emphasis
role="strong">}</emphasis></para></listitem></itemizedlist><para>
struct-method-type-modifier:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">static</emphasis></para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Examples</title><para>Demonstrating...
</para><screen><![CDATA[// ...]]></screen></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Enumerated types (Enums)</title><para>Enumerated types declare all
possible values that instances of the type may take. They may also define methods of the type, but an
enumerated type has no data other than its value. Enumerated types are value types, and so each
instantiation of the type is unique, even when they represent the same value. This distinction is n
ot significant in practice because when instances are compared, it is always by value not identity.
</para><para>Enumerated types are usually known as simply "enums". </para><section><title>Enum
declaration</title><itemizedlist><listitem
override="none"><para>enum-declaration:</para><itemizedlist><listitem override="none"><para>[ access-modifier
] <emphasis role="strong">enum</emphasis> qualified-enum-name <emphasis role="strong">{</emphasis> [
enum-members ] <emphasis role="strong">}</emphasis></para></listitem></itemizedlist><para>
qualified-enum-name:</para><itemizedlist><listitem override="none"><para>[ qualified-namespace-name <emphasis
role="strong">.</emphasis> ] enum-name</para></listitem></itemizedlist><para>
enum-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
enum-members:</para><itemizedlist><listitem override="none"><para>[ enum-values ] [ <emphasis
role="strong">;</emphasis> enum-methods ]</p
ara></listitem></itemizedlist><para> enum-values:</para><itemizedlist><listitem
override="none"><para>enum-value [ <emphasis role="strong">,</emphasis> enum-values
]</para></listitem></itemizedlist><para> enum-value:</para><itemizedlist><listitem
override="none"><para>enum-value-name [ <emphasis role="strong">=</emphasis> expression
]</para></listitem></itemizedlist><para> enum-value-name:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist><para>
enum-methods:</para><itemizedlist><listitem override="none"><para>enum-method [ enum-methods
]</para></listitem></itemizedlist><para> enum-method:</para><itemizedlist><listitem
override="none"><para>method-declaration</para></listitem></itemizedlist></listitem></itemizedlist></section><section><title>Enum
members</title><para>Equivalent to constants, all have an integer value, either explicit or automatically
assigned. </para></section><section><title>Methods</title><para>Are similar to st
atic methods of classes, i.e. are not related to any particular instance, but can be invoked on either an
instance or the enum itself. </para></section><section><title>Flag types</title><para>An enumerated type
declaration can be converted into a flag type declaration by annotating the declaration with
"Flags". A flag type represents a set of flags, any number of which can be combined in one
instance of the flag type, in the same fashion as a bitfield in C. For an explanation of the operations that
can be performed on flag types, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Expressions#Flag_operations";>Expressions/Flag
operations</ulink>. For how to use attributes, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Attributes#";>Attributes</ulink>.
</para><para>Flag example follows: </para><screen><![CDATA[// ...]]></screen></section><section><title>Error
domains</title><para>Erro
r domains are Vala's method for describing errors. An error domain is declared using a similar syntax to
enumerated types, but this does not define a type - instead it defines a class of errors, which is used to
implicitly create a new error type for the error domain. The error domain declaration syntax is effectively
the same as for enumerated types, but the keyword <code>errordomain</code> is used instead of
<code>enum</code>. </para><para>For more information about handling errors in Vala, see <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual/Errors#";>Errors</ulink>.
</para></section><section><title>Examples</title><para>Demonstrating... </para><screen><![CDATA[//
...]]></screen></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Attributes</title><para>Attributes are metadata information that is
specifie
d with regards to a symbol (a class, field, parameter, etc.). </para><para>Attributes provide extra
information in order to: </para><itemizedlist><listitem><para>Integrate libraries more directly. These are
the ones most often used in new Vala programs/libraries. </para></listitem><listitem><para>Control C code
generation, particularly with existing libraries. Mostly used in bindings.
</para></listitem><listitem><para>Give extra information to Vala that isn't included in code. Mostly used
internally in Vala. </para></listitem></itemizedlist><para>Most of these attributes are only useful within
bindings. Some, however, are useful in normal code: </para><itemizedlist><listitem><para><code>[DBus]</code>,
<code>[Description]</code>, <code>[Version]</code>, <code>[Signal]</code>, <code>[ModuleInit]</code> (if
you're writing a module). </para></listitem><listitem><para><code>CCode</code>'s <code>instance_pos</code>
(if you're using <code>Gtk.Builder</code>'s signal auto-connectio
n functionality). </para></listitem><listitem><para><code>[ThreadLocal]</code> (if you're using the Dova
profile). </para></listitem></itemizedlist><section><title>Applying attributes</title><para>They are written
as: </para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><![CDATA[[ ]]><methodname><![CDATA[AnnotationName]]></methodname><![CDATA[ (
]]><methodname><![CDATA[details]]></methodname><![CDATA[-]]><methodname><![CDATA[list]]></methodname><![CDATA[
) ]]]>
+<methodname><![CDATA[declaration]]></methodname>
+</programlisting><para>For example: </para><programlisting format="linespecific" language="cpp"
linenumbering="numbered" startinglinenumber="1"><![CDATA[[
]]><methodname><![CDATA[CCode]]></methodname><![CDATA[ (
]]><methodname><![CDATA[cname]]></methodname><![CDATA[ =
]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[var_c_name]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[
) ]]]>
+<token><![CDATA[static]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[my_var]]></methodname><![CDATA[;]]>
+</programlisting></section><section><title>CCode Attribute</title><para>This attribute influences the C code
which is generated by Vala. </para><informaltable><tgroup cols="4"><colspec colname="col_0"/><colspec
colname="col_1"/><colspec colname="col_2"/><colspec colname="col_3"/><tbody><row rowsep="1"><entry
align="center" colsep="1" rowsep="1"><para> <emphasis role="strong">Name</emphasis></para></entry><entry
align="center" colsep="1" rowsep="1"><para> <emphasis role="strong">Applies
to</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Type</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Example</emphasis></para></entry></row><row rowsep="1"><entry align="center" colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> <emphasis role="strong">Description
(optional)</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>array_length</para></ent
ry><entry colsep="1" rowsep="1"><para>delegate, field, property, method, parameter</para></entry><entry
colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>array_length_cname</para></entry><entry colsep="1"
rowsep="1"><para>field</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>array_length_cexpr</para></entry><entry colsep="1"
rowsep="1"><para>field</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>array_length_pos</para></entry><entry colsep="1" rowsep="1"><para>constructor, delegate,
method, parameter</para></entry><entry colsep="1" rowsep="1"><para>double</para></entry><entry colsep="1"
rowsep="1"><para>0.9</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3" nam
est="col_0" rowsep="1"><para> 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.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>array_length_type</para></entry><entry colsep="1" rowsep="1"><para>field,
method</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>array_null_terminated</para></entry><entry colsep="1" rowsep="1"><para>constructor, method,
delegate, field, parameter, property</para></entry><entry colsep="1"
rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>cheader_filename</para></entry><entry colsep="1" rowsep="1"><para>class, constant,
constructor, delegate, enum, field, interface
, method, namespace, struct</para></entry><entry colsep="1" rowsep="1"><para>string - comma-separated list
of headers</para></entry><entry colsep="1" rowsep="1"><para>"glib.h"</para></entry></row><row
rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> 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.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>cname</para></entry><entry colsep="1" rowsep="1"><para>class, constant, constructor,
delegate, enum, field, method, struct, propacc</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"><para>"gboolean"</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3"
namest="col_0" rowsep="1"><para> 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.</para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>const_cname</para></entry><entry colsep="1" rowsep="1"><para>class,
struct</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>construct_function</para></entry><entry
colsep="1" rowsep="1"><para>constructor</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>copy_function</para></entry><entry colsep="1" rowsep="1"><para>class</para></entry><entry
colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>cprefix</para></entry><entry colsep="1" rowsep="1"><para>class, enum, namespace,
struct</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><
entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>default_value</para></entry><entry colsep="1" rowsep="1"><para>struct</para></entry><entry
colsep="1" rowsep="1"><para>string - C value expression</para></entry><entry colsep="1"
rowsep="1"><para>"FALSE"</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3"
namest="col_0" rowsep="1"><para> A C expression representing this type's default
value.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>delegate_target</para></entry><entry colsep="1" rowsep="1"><para>field</para></entry><entry
colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>delegate_target_pos</para></entry><entry colsep="1" rowsep="1"><para>constructor,
delegate, method, parameter</para></entry><entry colsep="1" rowsep="1"><para>double</para></entry><entry
colsep="1" rowsep="1"><para>0.1</para></entry><
/row><row rowsep="1"><entry colsep="1" rowsep="1"><para>delegate_target_cname</para></entry><entry
colsep="1" rowsep="1"><para>delegate field/parameter</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"><para>"userdata"</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3"
namest="col_0" rowsep="1"><para> A C expression representing the name of the target/userdata related to a
delegate field/parameter.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>destroy_function</para></entry><entry colsep="1"
rowsep="1"><para>struct</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>destroy_notify_pos</para></entry><entry colsep="1"
rowsep="1"><para>parameter</para></entry><entry colsep="1" rowsep="1"><para>double</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry c
olsep="1" rowsep="1"><para>free_function</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>free_function_address_of</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>generic_type_pos</para></entry><entry
colsep="1" rowsep="1"><para>method</para></entry><entry colsep="1"
rowsep="1"><para>double</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>get_value_function</para></entry><entry colsep="1" rowsep="1"><para>class,
struct</para></entry><entry colsep="1" rowsep="1"><para>string - function name</para></entry><entry
colsep="1" rowsep="1"><para>"g_value_get_boolean"</para></entry></row><row rowsep="1">
<entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> A function which will return an object
when passed a GValue.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>gir_namespace</para></entry><entry colsep="1"
rowsep="1"><para>namespace</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>gir_version</para></entry><entry colsep="1" rowsep="1"><para>namespace</para></entry><entry
colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>has_construct_function</para></entry><entry colsep="1"
rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>has_copy_function</para></entry><entry
colsep="1" rowsep="1"><para>struct</para></entry><entry col
sep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>has_destroy_function</para></entry><entry colsep="1"
rowsep="1"><para>struct</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>has_new_function</para></entry><entry
colsep="1" rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>has_target</para></entry><entry colsep="1" rowsep="1"><para>delegate</para></entry><entry
colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>has_type_id</para></entry><entry colsep="1" rowsep="1"><para>class, struct,
enum</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep=
"1"><para>true</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0"
rowsep="1"><para> This is used to specify whether a corresponding GType must exists.</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>instance_pos</para></entry><entry colsep="1"
rowsep="1"><para>constructor, delegate, method</para></entry><entry colsep="1"
rowsep="1"><para>double</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> The argument position of the instance that will be used as
<code>this</code> in methods.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>lower_case_cprefix</para></entry><entry colsep="1"
rowsep="1"><para>namespace</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>lower_case_csuffix</para></entry><entry colsep="1" rowsep
="1"><para>class, enum, errordomain, interface</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>marshaller_type_name</para></entry><entry colsep="1" rowsep="1"><para>class,
struct</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"><para>"BOOLEAN"</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>notify</para></entry><entry colsep="1" rowsep="1"><para>property</para></entry><entry
colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>ordering</para></entry><entry colsep="1" rowsep="1"><para>virtual
method/property/signal</para></entry><entry colsep="1" rowsep="1"><para>int</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> Specify
th
e 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.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>param_spec_function</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>pos</para></entry><entry
colsep="1" rowsep="1"><para>parameter</para></entry><entry colsep="1"
rowsep="1"><para>double</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ref_function</para></entry><entry colsep="1" rowsep="1"><para>class</para></entry><entry
colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>ref_function_void</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rows
ep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> Whether the ref function returns void. Default is
<code>false</code>.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ref_sink_function</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ref_sink_function_void</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> Whether
the ref_sink function returns void. Default is <code>false</code>.</para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>returns_floating_reference</para></entry><entry colsep="
1" rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0"
rowsep="1"><para> Whether the method returns a floating reference to an object.</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>sentinel</para></entry><entry colsep="1"
rowsep="1"><para>constructor, method</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> Sentinel value to use as the last of variadic
arguments.</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>scope</para></entry><entry
colsep="1" rowsep="1"><para>delegate, parameter</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"><para>"async"</para></entry></row><row rowsep="1"><entry colsep
="1" nameend="col_3" namest="col_0" rowsep="1"><para> Scope of the delegate as in GIR
notation.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>set_value_function</para></entry><entry colsep="1" rowsep="1"><para>class,
struct</para></entry><entry colsep="1" rowsep="1"><para>string - function name</para></entry><entry
colsep="1" rowsep="1"><para>"g_value_set_boolean"</para></entry></row><row rowsep="1"><entry
colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> A function that will set a GValue with an object
of this type.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>simple_generics</para></entry><entry colsep="1" rowsep="1"><para>method</para></entry><entry
colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>take_value_function</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rowsep="1"><para
string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>type</para></entry><entry colsep="1" rowsep="1"><para>class, interface, field, parameter,
method</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>type_check_function</para></entry><entry colsep="1"
rowsep="1"><para>class</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>type_cname</para></entry><entry colsep="1" rowsep="1"><para>interface</para></entry><entry
colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>type_id</para></entry><entry colsep="1" rowsep="1"><para>class, enum,
struct</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1" ro
wsep="1"><para>"G_TYPE_BOOLEAN"</para></entry></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> 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.</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>type_signature</para></entry><entry colsep="1"
rowsep="1"><para>class, interface, struct</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> <emphasis>Will be soon moved to
DBus.</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>unref_function</para></entry><entry colsep="1" rowsep="1"><para>class</para></entry><entry
colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>vfunc_n
ame</para></entry><entry colsep="1" rowsep="1"><para>constructor, method</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"/></row></tbody></tgroup></informaltable></section><section><title>Version
attribute</title><para>Used to annotate symbols with versioning information. </para><para>Available since
Vala 0.31.1. </para><informaltable><tgroup cols="3"><colspec colname="col_0"/><colspec
colname="col_1"/><colspec colname="col_2"/><tbody><row rowsep="1"><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Name</emphasis></para></entry><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Type</emphasis></para></entry><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Description</emphasis> </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> since </para></entry><entry colsep="1" rowsep="1"><para> string
</para></entry><entry colsep="1" rowse
p="1"><para> Version number - if used will be checked against locally installed package version.
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> deprecated </para></entry><entry
colsep="1" rowsep="1"><para> bool </para></entry><entry colsep="1" rowsep="1"><para> Was
<code>[Deprecated]</code> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
deprecated_since </para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1"
rowsep="1"><para> Version number </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
replacement </para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1"
rowsep="1"><para> Symbol name</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
experimental </para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry colsep="1"
rowsep="1"><para> Was <code>[Experimental]</code> </para></entry></row><row r
owsep="1"><entry colsep="1" rowsep="1"><para> experimental_until </para></entry><entry colsep="1"
rowsep="1"><para> string </para></entry><entry colsep="1" rowsep="1"><para> Version number
</para></entry></row></tbody></tgroup></informaltable></section><section><title>SimpleType
attribute</title><para>This attribute is applied to structs. Consider reading: <ulink
url="http://www.vala-project.org/doc/vala-draft/types.html#valuetypes"/> and <ulink
url="http://live.gnome.org/Projects/Vala/Tutorial#Value_Types"/>.
</para></section><section><title>BooleanType Attribute</title><para>This attribute is applied to structs,
combined with SimpleType. Marks the struct as being a boolean type.
</para></section><section><title>IntegerType Attribute</title><para>This attribute is applied to structs,
combined with SimpleType. Marks the struct as being an integer number type. </para><informaltable><tgroup
cols="2"><colspec colname="col_0"/><colspec colname="col_1"/><tbody><row rowsep="1"><en
try align="center" colsep="1" rowsep="1"><para> <emphasis role="strong">Name</emphasis></para></entry><entry
align="center" colsep="1" rowsep="1"><para> <emphasis role="strong">Type</emphasis></para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>min</para></entry><entry colsep="1"
rowsep="1"><para>integer</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>max</para></entry><entry colsep="1" rowsep="1"><para>integer</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>rank</para></entry><entry colsep="1"
rowsep="1"><para>integer</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>width</para></entry><entry colsep="1" rowsep="1"><para>integer</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>signed</para></entry><entry colsep="1"
rowsep="1"><para>bool</para></entry></row></tbody></tgroup></informaltable></section><section><title>FloatingType
Attribute</title><para>This attribute is
applied to structs, combined with SimpleType. Marks the struct as being a floating point number type.
</para><informaltable><tgroup cols="2"><colspec colname="col_0"/><colspec colname="col_1"/><tbody><row
rowsep="1"><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Name</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Type</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>decimal</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>rank</para></entry><entry colsep="1"
rowsep="1"><para>integer</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>width</para></entry><entry colsep="1"
rowsep="1"><para>integer</para></entry></row></tbody></tgroup></informaltable></section><section><title>Signal
Attribute</title><para>This attribute influences the generation and usage of object signals
, mostly for the GObject type system. The default is G_SIGNAL_RUN_LAST. </para><informaltable><tgroup
cols="4"><colspec colname="col_0"/><colspec colname="col_1"/><colspec colname="col_2"/><colspec
colname="col_3"/><tbody><row rowsep="1"><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Name</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Type</emphasis></para></entry></row><row rowsep="1"><entry align="center" colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> <emphasis role="strong">Description
(optional)</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>detailed</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry></row><row
rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> Sets the G_SIGNAL_DETAILED
flag.</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>no_recurse</para></entry><entry
colsep
="1" rowsep="1"><para>bool</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3"
namest="col_0" rowsep="1"><para> Sets the G_SIGNAL_NO_RECURSE flag.</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>run</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0"
rowsep="1"><para> Significant values are "first", "last" or "cleanup". Default
is "last".</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>action</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry></row><row
rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> Sets the G_SIGNAL_ACTION
flag.</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>no_hooks</para></entry><entry
colsep="1" rowsep="1"><para>bool</para></entry></row><row rowsep="1"><entry colsep="1" nameend="col_3"
namest="
col_0" rowsep="1"><para> Sets the G_SIGNAL_NO_HOOKS
flag.</para></entry></row></tbody></tgroup></informaltable></section><section><title>Description
Attribute</title><para>This attribute influences the generation and usage of object properties, mostly for
the GObject type system. </para><informaltable><tgroup cols="2"><colspec colname="col_0"/><colspec
colname="col_1"/><tbody><row rowsep="1"><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Name</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Type</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>nick</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>blurb</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry></row></tbody></tgroup></informaltable></section><section><title>DBus
Attribute</title><para>This attribute influences
the generation of DBus interfaces (for servers) or DBus calls (for clients) which are generated by Vala.
</para><informaltable><tgroup cols="4"><colspec colname="col_0"/><colspec colname="col_1"/><colspec
colname="col_2"/><colspec colname="col_3"/><tbody><row rowsep="1"><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Name</emphasis></para></entry><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Applies to</emphasis></para></entry><entry align="center"
colsep="1" rowsep="1"><para> <emphasis role="strong">Type</emphasis></para></entry><entry align="center"
colsep="1" rowsep="1"><para> <emphasis role="strong">Example</emphasis></para></entry></row><row
rowsep="1"><entry align="center" colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> <emphasis
role="strong">Description (optional)</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>name</para></entry><entry colsep="1" rowsep="1"><para>c
lass, interface, method, property, signal</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"><para>"org.my.interface" or
"MyMember"</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>signature</para></entry><entry align="center" colsep="1" nameend="col_2" namest="col_1"
rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> This makes it possible to use GVariant in D-Bus clients and
servers without automatic boxing/unboxing.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>use_string_marshalling</para></entry><entry colsep="1"
rowsep="1"><para>enum</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para>
Marshalling enum values as strings<
/para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>value</para></entry><entry colsep="1"
rowsep="1"><para>enumvalue</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0"
rowsep="1"><para> Marshalling enum values as strings</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>use_string_marshalling</para></entry><entry colsep="1"
rowsep="1"><para>enum</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>timeout (client
only)</para></entry><entry colsep="1" rowsep="1"><para>method, property</para></entry><entry colsep="1"
rowsep="1"><para>integer</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> Timeout is specified in milliseconds</para></ent
ry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>no_reply</para></entry><entry colsep="1"
rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
nameend="col_3" namest="col_0" rowsep="1"><para> Do not expect a reply from the
server</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>result (server
only)</para></entry><entry colsep="1" rowsep="1"><para>method</para></entry><entry colsep="1"
rowsep="1"><para>string</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>visible (server only)</para></entry><entry colsep="1" rowsep="1"><para>method, property,
signal</para></entry><entry colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" nameend="col_3" namest="col_0" rowsep="1"><para> By
setting <code>visible = false</code> you can specify that the member should not be exported via D-Bus<
/para></entry></row></tbody></tgroup></informaltable></section><section><title>Gtk
attributes</title><para><emphasis role="strong">GtkTemplate attribute</emphasis> </para><para>Can only be
applied to classes that inherit from Gtk.Widget. The "ui" argument is mandatory.
</para><informaltable><tgroup cols="3"><colspec colname="col_0"/><colspec colname="col_1"/><colspec
colname="col_2"/><tbody><row rowsep="1"><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Name</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Type</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Example</emphasis></para></entry></row><row rowsep="1"><entry align="center" colsep="1"
nameend="col_2" namest="col_0" rowsep="1"><para> <emphasis role="strong">Description
(optional)</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ui</para></entry><
entry colsep="1" rowsep="1"><para>string (mandatory)</para></entry><entry colsep="1"
rowsep="1"><para>"/org/gnome/yourapp/main.ui"</para></entry></row><row rowsep="1"><entry colsep="1"
nameend="col_2" namest="col_0" rowsep="1"><para> Specifies the .ui gresource to be used for building the Gtk
widget</para></entry></row></tbody></tgroup></informaltable><para><emphasis role="strong">GtkChild
attribute</emphasis> </para><para>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. </para><informaltable><tgroup
cols="3"><colspec colname="col_0"/><colspec colname="col_1"/><colspec colname="col_2"/><tbody><row
rowsep="1"><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Name</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><para> <emphasis
role="strong">Type</emphasis></para></entry><entry align="center" colsep="1" rowsep="1"><par
a> <emphasis role="strong">Example</emphasis></para></entry></row><row rowsep="1"><entry align="center"
colsep="1" nameend="col_2" namest="col_0" rowsep="1"><para> <emphasis role="strong">Description
(optional)</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>name</para></entry><entry colsep="1" rowsep="1"><para>string</para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" nameend="col_2" namest="col_0" rowsep="1"><para> Custom
name being used in the Gtk builder ui definition. By default the name of the marked field is
used.</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>internal</para></entry><entry
colsep="1" rowsep="1"><para>bool</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" nameend="col_2" namest="col_0" rowsep="1"><para> Whether this child is internal or not in the Gtk
builder ui definition.</para></entry></row></tbody></tgroup></informaltable><par
a><emphasis role="strong">GtkCallback attribute</emphasis> </para><para>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. </para><informaltable><tgroup cols="3"><colspec colname="col_0"/><colspec
colname="col_1"/><colspec colname="col_2"/><tbody><row rowsep="1"><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Name</emphasis></para></entry><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Type</emphasis></para></entry><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Example</emphasis></para></entry></row><row rowsep="1"><entry
align="center" colsep="1" nameend="col_2" namest="col_0" rowsep="1"><para> <emphasis
role="strong">Description (optional)</emphasis></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>name</para></entry><entry colsep="1" rowsep="1"><para>string</pa
ra></entry><entry colsep="1" rowsep="1"><para>"on_button_clicked"</para></entry></row><row
rowsep="1"><entry colsep="1" nameend="col_2" namest="col_0" rowsep="1"><para> Custom name being used in the
Gtk builder ui definition. By default the name of the marked method is
used.</para></entry></row></tbody></tgroup></informaltable></section><section><title>Other
attributes</title><informaltable><tgroup cols="3"><colspec colname="col_0"/><colspec
colname="col_1"/><colspec colname="col_2"/><tbody><row rowsep="1"><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Name</emphasis></para></entry><entry align="center" colsep="1"
rowsep="1"><para> <emphasis role="strong">Applies to</emphasis></para></entry><entry align="center"
colsep="1" rowsep="1"><para> <emphasis role="strong">Description</emphasis></para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>Assert</para></entry><entry colsep="1"
rowsep="1"><para>method</para></entry><entr
y colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>Compact</para></entry><entry colsep="1" rowsep="1"><para>class</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ConcreteAccessor</para></entry><entry colsep="1" rowsep="1"><para>abstract
property</para></entry><entry colsep="1" rowsep="1"><para>Use get/set functions, but do not override them as
they are not abstract.</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>DestroysInstance</para></entry><entry colsep="1"
rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>Diagnostics</para></entry><entry colsep="1" rowsep="1"><para>method</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ErrorBase</para></entry><entry colsep="1" rowsep="1"><para>class</para></entry><entry
colsep="1" rowsep="1"><para>Only use
by GLib.Error at the moment</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>Experimental</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>Flags</para></entry><entry colsep="1" rowsep="1"><para>enum</para></entry><entry
colsep="1" rowsep="1"><para>Marks the enum values to be flags</para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>FormatArg</para></entry><entry colsep="1"
rowsep="1"><para>parameter</para></entry><entry colsep="1" rowsep="1"><para>specifies that the method takes
and returns a printf or scanf format string</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>HasEmitter</para></entry><entry colsep="1" rowsep="1"><para>signal</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>Immutable</para></entry><entry colsep="1" rowsep="1"><para>class,
struct</para></entry><entry colsep="1" rowsep="1"/></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>ModuleInit</para></entry><entry colsep="1"
rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"><para>Marks the associated type as
dynamic, and marks the method as a <ulink
url="http://valadoc.org/#!api=gobject-2.0/GLib.TypeModule";>TypeModule</ulink> init function. See <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/TypeModuleSample#";>TypeModule
example</ulink></para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>NoAccessorMethod</para></entry><entry colsep="1"
rowsep="1"><para>property</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>NoArrayLength</para></entry><entry colsep="1" rowsep="1"><para>method</para></entry><entry
colsep="1" rowsep="1"><para>Deprecated, use <code>[CCode (array_length = false)]</code>
instead</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>NoReturn</para></ent
ry><entry colsep="1" rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"><para>Once the
method is called, it will never return</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>NoThrow</para></entry><entry colsep="1" rowsep="1"><para>method</para></entry><entry
colsep="1" rowsep="1"><para>Marks methods that can never throw exceptions. Dova profile
only</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>NoWrapper</para></entry><entry
colsep="1" rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>PointerType</para></entry><entry align="center" colsep="1" nameend="col_2"
namest="col_1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>Print</para></entry><entry colsep="1" rowsep="1"><para>method</para></entry><entry
colsep="1" rowsep="1"><para>Stringifies and concatenates all arguments you pass to the
method</para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para>PrintfFormat</para></entry><entry colsep="1"
rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"><para>See also ScanfFormat
attribute</para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ReturnsModifiedPointer</para></entry><entry colsep="1"
rowsep="1"><para>method</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para>ScanfFormat</para></entry><entry colsep="1" rowsep="1"><para>method</para></entry><entry
colsep="1" rowsep="1"><para>See also PrintFormat attribute</para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para>ThreadLocal</para></entry><entry colsep="1"
rowsep="1"><para>field</para></entry><entry colsep="1" rowsep="1"><para>Thread local fields. Dova profile
only</para></entry></row></tbody></tgroup></informaltable></section><section><title>Deprecated
Attributes</title><para>Attributes that have been deprecated and should no lon
ger be used in new code. </para><informaltable><tgroup cols="4"><colspec colname="col_0"/><colspec
colname="col_1"/><colspec colname="col_2"/><colspec colname="col_3"/><tbody><row rowsep="1"><entry
align="center" colsep="1" rowsep="1"><para> <emphasis role="strong">Name</emphasis></para></entry><entry
align="center" colsep="1" rowsep="1"><para> <emphasis role="strong">Since</emphasis></para></entry><entry
align="center" colsep="1" nameend="col_3" namest="col_2" rowsep="1"><para> <emphasis role="strong">Use
instead</emphasis></para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>Deprecated
</para></entry><entry colsep="1" rowsep="1"><para>0.31.1 </para></entry><entry colsep="1" rowsep="1"><para>
[Version (deprecated = true, deprecated_since = "", replacement =
"")]</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>Experimental
</para></entry><entry colsep="1" rowsep="1"><para>0.31.1 </para></entry><entry colsep="1" row
sep="1"><para>[Version (experimental = true, experimental_until =
"")]</para></entry></row></tbody></tgroup></informaltable></section><section><title>Examples</title><para>TODO:
write examples. </para></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>Preprocessor</title><para>The Vala preprocessor is a particular part of
Vala that acts at syntax level only, allowing you to conditionally write pieces of your software depending
upon certain compile-time conditions. Preprocessor directives will never be generated in the resulting code.
</para><section><title>Directives syntax</title><para>All preprocessor directives start with a hash
(<emphasis role="strong">#</emphasis>), except for the first line of a file starting with <emphasis
role="strong">#!</emphasis> (used for Vala scripts). </para><itemizedlist><listitem
override="none"><para>vala-code
:</para><itemizedlist><listitem override="none"><para>[ any vala code ] [ pp-condition ] [ any vala code
]</para></listitem></itemizedlist><para> pp-condition:</para><itemizedlist><listitem
override="none"><para><emphasis role="strong">#if</emphasis> pp-expression vala-code [ pp-elif ] [ pp-else ]
<emphasis role="strong">#endif</emphasis></para></listitem></itemizedlist><para>
pp-elif:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">#elif</emphasis>
pp-expression vala-code [ pp-elif ]</para></listitem></itemizedlist><para>
pp-else:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">#else</emphasis>
vala-code</para></listitem></itemizedlist><para> pp-expression:</para><itemizedlist><listitem
override="none"><para>pp-or-expression</para></listitem></itemizedlist><para>
pp-or-expression:</para><itemizedlist><listitem override="none"><para>pp-and-expression [ <emphasis
role="strong">||</emphasis> pp-and-expression ]</para></li
stitem></itemizedlist><para> pp-and-expression:</para><itemizedlist><listitem
override="none"><para>pp-binary-expression [ <emphasis role="strong">&&</emphasis>
pp-binary-expression ]</para></listitem></itemizedlist><para>
pp-binary-expression:</para><itemizedlist><listitem override="none"><para>pp-equality-expression</para><para>
pp-inequality-expression</para></listitem></itemizedlist><para>
pp-equality-expression:</para><itemizedlist><listitem override="none"><para>pp-unary-expression [ <emphasis
role="strong">==</emphasis> pp-unary-expression
]</para></listitem></itemizedlist><para>pp-inequality-expression:</para><itemizedlist><listitem
override="none"><para>pp-unary-expression [ <emphasis role="strong">!=</emphasis> pp-unary-expression
]</para></listitem></itemizedlist><para> pp-unary-expression:</para><itemizedlist><listitem
override="none"><para>pp-negation-expression</para><para>
pp-primary-expression</para></listitem></itemizedlist><para> pp-negation-express
ion:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">!</emphasis>
pp-unary-expression</para></listitem></itemizedlist><para>
pp-primary-expression:</para><itemizedlist><listitem override="none"><para>pp-symbol</para><para> <emphasis
role="strong">(</emphasis> pp-expression <emphasis role="strong">)</emphasis></para><para> <emphasis
role="strong">true</emphasis></para><para> <emphasis
role="strong">false</emphasis></para></listitem></itemizedlist><para>
pp-symbol:</para><itemizedlist><listitem
override="none"><para>identifier</para></listitem></itemizedlist></listitem></itemizedlist><para>The
semantics of the preprocessor are very simple: if the condition is true then the Vala code surrounded by the
preprocessor will be parsed, otherwise it will be ignored. A symbol evaluates to <emphasis
role="strong">true</emphasis> if it is defined at compile-time. If a symbol in a preprocessor directive is
not defined, it evaluates to <emphasis role="strong">fa
lse</emphasis>. </para></section><section><title>Defining symbols</title><para>It's not possible to define a
preprocessor symbol inside the Vala code (like with C). The only way to define a symbol is to feed it through
the <code>valac</code> option <code>-D</code>. </para></section><section><title>Built-in
defines</title><informaltable><tgroup cols="2"><colspec colname="col_0"/><colspec
colname="col_1"/><tbody><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Name</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Description</emphasis> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
POSIX </para></entry><entry colsep="1" rowsep="1"><para> Set if the profile is posix
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> GOBJECT </para></entry><entry
colsep="1" rowsep="1"><para> Set if the profile is gobject </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"
<para> DOVA </para></entry><entry colsep="1" rowsep="1"><para> Set if the profile is dova
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> VALA_X_Y </para></entry><entry
colsep="1" rowsep="1"><para> Set if Vala API version is equal or higher to version X.Y
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> DBUS_GLIB </para></entry><entry
colsep="1" rowsep="1"><para> Set if using dbus-glib-1 package
</para></entry></row></tbody></tgroup></informaltable></section><section><title>Examples</title><para>How
to conditionally compile code based on a <code>valac</code> option <code>-D</code>. </para><para>Sample
code: </para><para><remark>vala-test:examples/advanced.vala</remark> </para><programlisting
format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><lineannotation><![CDATA[// Vala preprocessor example]]></lineannotation>
+<lineannotation/><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Preprocessor]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><methodname><![CDATA[Preprocessor]]></methodname><![CDATA[ () {]]>
+<![CDATA[ }]]>
+
+<![CDATA[ ]]><lineannotation><![CDATA[/* public instance method */]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[run]]></methodname><![CDATA[ () {]]>
+<![CDATA[#if PREPROCESSOR_DEBUG]]>
+<![CDATA[ ]]><lineannotation><![CDATA[// Use "-D PREPROCESSOR_DEBUG" to run this code
path]]></lineannotation>
+<lineannotation/><![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[debug version ]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[#else]]>
+<![CDATA[ ]]><lineannotation><![CDATA[// Normally, we run this code path]]></lineannotation>
+<lineannotation/><![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[production version ]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[#endif]]>
+<![CDATA[ }]]>
+
+<![CDATA[ ]]><lineannotation><![CDATA[/* application entry point */]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><methodname><![CDATA[string]]></methodname><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><methodname><![CDATA[var]]></methodname><![CDATA[
]]><methodname><![CDATA[sample]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Preprocessor]]></methodname><![CDATA[ ();]]>
+<![CDATA[
]]><methodname><![CDATA[sample]]></methodname><![CDATA[.]]><methodname><![CDATA[run]]></methodname><![CDATA[
();]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[ 0;]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+</programlisting></section></section><section><title>Compile and Run</title><para>Normal build/run:
</para><screen><![CDATA[$ valac -o preprocessor Preprocessor.vala
+$ ./preprocessor]]></screen><para>Debug build/run: </para><screen><![CDATA[$ valac -D PREPROCESSOR_DEBUG -o
preprocessor-debug Preprocessor.vala
+$ ./preprocessor-debug]]></screen></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>GIDL metadata format</title><para>This section describes the format of
.metadata files as used by <emphasis>vapigen</emphasis> as additional information for .vapi file generation.
Some of the information specified in the metadata can be used to set <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Projects/Vala/Manual/Attributes#";>symbol
attributes</ulink> as well. </para><section><title>Comments</title><para>Comments start with a <code>#</code>
and end at the end of a line. For example: </para><screen><![CDATA[# this is a
comment]]></screen></section><section><title>Other Lines</title><para>Every non-comment line in the file is
made of up two sections: the specifier, and the parameters. </para><para>The specifier is the first text to
appear on t
he line, and it specifies what the rest of the line will be modifying. </para><para>The parameters are a
space separated list of a parameter name, followed by an equals sign and the value enclosed in quotes.
</para><para>For example, this line sets <emphasis>parameter1</emphasis> and <emphasis>parameter2</emphasis>
on <emphasis>foo.bar</emphasis>: </para><screen><![CDATA[foo.bar parameter1="value"
parameter2="value"]]></screen></section><section><title>Specifiers</title><para>Specifiers always use the C
name for whatever it is you are modifying. For example if your namespace is <emphasis>Foo</emphasis>, and
the Vala name for the type is <emphasis>Bar</emphasis>, then you would use <code>FooBar</code>.
</para><para>Specifiers may also use wildcards, and all items that partially match the specifier will be
selected. For example: </para><screen><![CDATA[*.klass hidden="1"]]></screen><para>will hide the
<emphasis>klass</emphasis> field in all types. </para></section><section><
title>Specifying Different Things</title><para>To specify a: </para><informaltable><tgroup cols="2"><colspec
colname="col_0"/><colspec colname="col_1"/><tbody><row rowsep="1"><entry colsep="1" rowsep="1"><para>
Function </para></entry><entry colsep="1" rowsep="1"><para> <code>name_of_function</code>
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> Type </para></entry><entry
colsep="1" rowsep="1"><para> <code>Type</code> </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> Property </para></entry><entry colsep="1" rowsep="1"><para>
<code>Type:property_name</code> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
Signal </para></entry><entry colsep="1" rowsep="1"><para> <code>Type::signal_name</code>
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> Field </para></entry><entry
colsep="1" rowsep="1"><para> <code>Type.field_name</code> </para></entry></row><row rowsep="1"><ent
ry colsep="1" rowsep="1"><para> Parameter (Function) </para></entry><entry colsep="1" rowsep="1"><para>
<code>name_of_function.param</code> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
Parameter (Delegate) </para></entry><entry colsep="1" rowsep="1"><para> <code>DelegateName.param</code>
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> Parameter (Signal)
</para></entry><entry colsep="1" rowsep="1"><para> <code>Type::signal_name.param</code>
</para></entry></row></tbody></tgroup></informaltable><para>For example, hiding a symbol:
</para><informaltable><tgroup cols="2"><colspec colname="col_0"/><colspec colname="col_1"/><tbody><row
rowsep="1"><entry colsep="1" rowsep="1"><para> Type </para></entry><entry colsep="1" rowsep="1"><para>
<code>Foo hidden="1"</code> </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> Function </para></entry><entry colsep="1" rowsep="1"><para> <code>some_function h
idden="1"</code> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> Field
</para></entry><entry colsep="1" rowsep="1"><para> <code>Foo.bar hidden="1"</code>
</para></entry></row></tbody></tgroup></informaltable></section><section><title>Properties
Reference</title><para>The format for the entries will be like so </para><informaltable><tgroup
cols="4"><colspec colname="col_0"/><colspec colname="col_1"/><colspec colname="col_2"/><colspec
colname="col_3"/><tbody><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Name</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Applies To</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Values</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Description</emphasis> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>foobar</code> </para>
</entry><entry colsep="1" rowsep="1"><para> Signal, Function, Class, Struct, etc </para></entry><entry
colsep="1" rowsep="1"><para> The acceptable values </para></entry><entry colsep="1" rowsep="1"><para> The
description goes here. </para></entry></row></tbody></tgroup></informaltable><para>And in alphabetical order:
</para><informaltable><tgroup cols="4"><colspec colname="col_0"/><colspec colname="col_1"/><colspec
colname="col_2"/><colspec colname="col_3"/><tbody><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<emphasis role="strong">Name</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Applies To</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Values</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Description</emphasis> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>abstract</code> </para></entry><entry colsep="1" rowsep="1"><
para> Class, Function </para></entry><entry colsep="1" rowsep="1"><para> 0, 1</para></entry><entry
colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>accessor_method</code>
</para></entry><entry colsep="1" rowsep="1"><para> Property </para></entry><entry colsep="1"
rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>array_length_cname</code> </para></entry><entry colsep="1" rowsep="1"><para> Field
</para></entry><entry colsep="1" rowsep="1"><para> C identifier </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>array_length_pos</code>
</para></entry><entry colsep="1" rowsep="1"><para> Parameter (Function) </para></entry><entry colsep="1"
rowsep="1"><para> Double (position between two Vala parameters) </para></entry><entry colsep="1"
rowsep="1"><para> Sets the position of the length for the parameter, leng
th needs to be hidden separately. </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>array_length_type</code> </para></entry><entry colsep="1" rowsep="1"><para> Parameter (Function),
Function (returning an array), Field </para></entry><entry colsep="1" rowsep="1"><para> C type
</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>array_null_terminated</code> </para></entry><entry colsep="1" rowsep="1"><para> Function (returning an
array), Parameter (Function), Field </para></entry><entry colsep="1" rowsep="1"><para> 0, 1
</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>async</code> </para></entry><entry colsep="1" rowsep="1"><para> Function </para></entry><entry
colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Force async function,
even if it doesn't end in _async </para></entry></row><row rowsep="1
"><entry colsep="1" rowsep="1"><para> <code>base_class</code> </para></entry><entry colsep="1"
rowsep="1"><para> Class </para></entry><entry colsep="1" rowsep="1"><para> C type </para></entry><entry
colsep="1" rowsep="1"><para> Marks the base class for the type </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> <code>base_type</code> </para></entry><entry colsep="1" rowsep="1"><para> Struct
</para></entry><entry colsep="1" rowsep="1"><para> Vala type </para></entry><entry colsep="1"
rowsep="1"><para> Marks the struct as inheriting </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>cheader_filename</code> </para></entry><entry colsep="1" rowsep="1"><para> Anything
(except parameters) </para></entry><entry colsep="1" rowsep="1"><para> Header include path
</para></entry><entry colsep="1" rowsep="1"><para> Compiler will adds the specified header when thing is
used. </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"
<para> <code>common_prefix</code> </para></entry><entry colsep="1" rowsep="1"><para> Enum
</para></entry><entry colsep="1" rowsep="1"><para> String </para></entry><entry colsep="1"
rowsep="1"><para> Removes a common prefix from enumeration values </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> <code>const_cname</code> </para></entry><entry colsep="1"
rowsep="1"><para> Class (non-GObject) </para></entry><entry colsep="1" rowsep="1"><para> C type
</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>copy_function</code> </para></entry><entry colsep="1" rowsep="1"><para> Class (non-GObject)
</para></entry><entry colsep="1" rowsep="1"><para> C function name </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>cprefix</code>
</para></entry><entry colsep="1" rowsep="1"><para> Module </para></entry><entry colsep="1"
rowsep="1"><para> String </para
</entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>ctype</code> </para></entry><entry colsep="1" rowsep="1"><para> Parameter (Function), Field
</para></entry><entry colsep="1" rowsep="1"><para> C type </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>default_value</code>
</para></entry><entry colsep="1" rowsep="1"><para> Parameter (Function) </para></entry><entry colsep="1"
rowsep="1"><para> Any Vala value that would be valid for the type </para></entry><entry colsep="1"
rowsep="1"><para> Sets the default value for a parameter. </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> <code>delegate_target_pos</code> </para></entry><entry colsep="1"
rowsep="1"><para> Parameter (Function) </para></entry><entry colsep="1" rowsep="1"><para> Double (position
between two Vala parameters) </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><e
ntry colsep="1" rowsep="1"><para> <code>deprecated</code> </para></entry><entry colsep="1" rowsep="1"><para>
Anything (except parameters) </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry
colsep="1" rowsep="1"><para> Marks the thing as deprecated </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> <code>deprecated_since</code> </para></entry><entry colsep="1" rowsep="1"><para>
Anything (except parameters) </para></entry><entry colsep="1" rowsep="1"><para> Version </para></entry><entry
colsep="1" rowsep="1"><para> Marks the thing as deprecated </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> <code>ellipsis</code> </para></entry><entry colsep="1" rowsep="1"><para>
Function </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"><para> Marks that the function has a variable argument list </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> <co
de>errordomain</code> </para></entry><entry colsep="1" rowsep="1"><para> Enum </para></entry><entry
colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Marks the enumeration as
a GError domain </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>finish_name</code> </para></entry><entry colsep="1" rowsep="1"><para> Function </para></entry><entry
colsep="1" rowsep="1"><para> C function name </para></entry><entry colsep="1" rowsep="1"><para> Sets custom
asynchronous finish function </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>free_function</code> </para></entry><entry colsep="1" rowsep="1"><para> Class (non-GObject)
</para></entry><entry colsep="1" rowsep="1"><para> C function name </para></entry><entry colsep="1"
rowsep="1"><para> Sets a free function for the struct </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>gir_namespace</code> </para></entry><entry
colsep="1" rowsep="1"><para> Module </para></entry><entry colsep="1" rowsep="1"><para> String
</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>gir_version</code> </para></entry><entry colsep="1" rowsep="1"><para> Module </para></entry><entry
colsep="1" rowsep="1"><para> Version </para></entry><entry colsep="1" rowsep="1"/></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> <code>has_copy_function</code> </para></entry><entry
colsep="1" rowsep="1"><para> Struct </para></entry><entry colsep="1" rowsep="1"><para> 0, 1
</para></entry><entry colsep="1" rowsep="1"><para> marks the struct as having a copy function
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>has_destroy_function</code>
</para></entry><entry colsep="1" rowsep="1"><para> Struct </para></entry><entry colsep="1" rowsep="1"><para>
0, 1 </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" r
owsep="1"><para> <code>has_emitter</code> </para></entry><entry colsep="1" rowsep="1"><para> Signal
</para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>has_target</code>
</para></entry><entry colsep="1" rowsep="1"><para> Delegate </para></entry><entry colsep="1"
rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>has_type_id</code> </para></entry><entry colsep="1" rowsep="1"><para> Class, Enum,
Struct </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"><para> Marks whether a GType is registered for this thing </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> <code>hidden</code> </para></entry><entry colsep="1"
rowsep="1"><para> Anything </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry co
lsep="1" rowsep="1"><para> Causes the selected thing to not be output in the vapi file.
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>immutable</code>
</para></entry><entry colsep="1" rowsep="1"><para> Struct </para></entry><entry colsep="1" rowsep="1"><para>
0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Marks the struct as immutable
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>instance_pos</code>
</para></entry><entry colsep="1" rowsep="1"><para> Delegate </para></entry><entry colsep="1"
rowsep="1"><para> Double (Position between two Vala parameters) </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>is_array</code>
</para></entry><entry colsep="1" rowsep="1"><para> Function (returning an array), Parameter, Field
</para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para>
Marks the thing as an a
rray </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>is_fundamental</code>
</para></entry><entry colsep="1" rowsep="1"><para> Class (non-GObject) </para></entry><entry colsep="1"
rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>is_immutable</code> </para></entry><entry colsep="1" rowsep="1"><para> Class
(non-GObject) </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>is_out</code>
</para></entry><entry colsep="1" rowsep="1"><para> Parameter </para></entry><entry colsep="1"
rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Marks the parameter as
"out" </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>is_ref</code>
</para></entry><entry colsep="1" rowsep="1"><para> Parameter </para></entry>
<entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Marks the
parameter as "ref" </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>is_value_type</code> </para></entry><entry colsep="1" rowsep="1"><para> Struct, Union
</para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para>
Marks type as a value type (aka struct) </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>lower_case_cprefix</code> </para></entry><entry colsep="1" rowsep="1"><para> Module
</para></entry><entry colsep="1" rowsep="1"><para> String </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>lower_case_csuffix</code>
</para></entry><entry colsep="1" rowsep="1"><para> Interface </para></entry><entry colsep="1"
rowsep="1"><para> String </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><ent
ry colsep="1" rowsep="1"><para> <code>name</code> </para></entry><entry colsep="1" rowsep="1"><para> Any
Type, Function, Signal </para></entry><entry colsep="1" rowsep="1"><para> Vala identifier
</para></entry><entry colsep="1" rowsep="1"><para> Changes the name of the thing, does not change namespace
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>namespace</code>
</para></entry><entry colsep="1" rowsep="1"><para> Any Type </para></entry><entry colsep="1"
rowsep="1"><para> String </para></entry><entry colsep="1" rowsep="1"><para> Changes the namespace of the
thing </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>namespace_name</code>
</para></entry><entry colsep="1" rowsep="1"><para> Signal Parameter </para></entry><entry colsep="1"
rowsep="1"><para> String </para></entry><entry colsep="1" rowsep="1"><para> Specify the namespace of the
parameter type indicated with type_name </para></entry></row><row rowsep="1"><e
ntry colsep="1" rowsep="1"><para> <code>no_array_length</code> </para></entry><entry colsep="1"
rowsep="1"><para> Function (returning an array), Parameter (Function, Delegate) </para></entry><entry
colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Does not implicitly
pass/return array length to/from function </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>nullable</code> </para></entry><entry colsep="1" rowsep="1"><para> Function (having a
return value), Parameter </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry
colsep="1" rowsep="1"><para> Marks the value as nullable </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> <code>owned_get</code> </para></entry><entry colsep="1" rowsep="1"><para>
Property </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <cod
e>parent</code> </para></entry><entry colsep="1" rowsep="1"><para> Any module member </para></entry><entry
colsep="1" rowsep="1"><para> String (Namespace) </para></entry><entry colsep="1" rowsep="1"><para> Strip
namespace prefix from symbol and put it into given sub-namespace </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> <code>printf_format</code> </para></entry><entry colsep="1" rowsep="1"><para>
Function </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>rank</code> </para></entry><entry
colsep="1" rowsep="1"><para> Struct </para></entry><entry colsep="1" rowsep="1"><para> Integer
</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>ref_function</code> </para></entry><entry colsep="1" rowsep="1"><para> Class (non-GObject)
</para></entry><entry colsep="1" rowsep="1"><para> C funct
ion name </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>ref_function_void</code> </para></entry><entry colsep="1" rowsep="1"><para> Class
(non-GObject) </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>rename_to</code>
</para></entry><entry colsep="1" rowsep="1"><para> Any Type </para></entry><entry colsep="1"
rowsep="1"><para> Vala identifier </para></entry><entry colsep="1" rowsep="1"><para> Renames the type to
something else, ie fooFloat to float (not exactly the same as <code>name</code>, AFAIK name changes both the
vala name and the cname. rename_to adds the required code so that when the rename_to'ed type is used, the c
type is used) </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>replacement</code> </para></entry><entry colsep="1" rowsep="1"><para> Anything (excep
t parameters) </para></entry><entry colsep="1" rowsep="1"><para> The thing that replaces this
</para></entry><entry colsep="1" rowsep="1"><para> Specifies a replacement for a deprecated symbol
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>sentinel</code>
</para></entry><entry colsep="1" rowsep="1"><para> Function (with ellipsis) </para></entry><entry colsep="1"
rowsep="1"><para> C value </para></entry><entry colsep="1" rowsep="1"><para> The sentinel value marking the
end of the vararg list </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>simple_type</code> </para></entry><entry colsep="1" rowsep="1"><para> Struct </para></entry><entry
colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Marks the struct as
being a simple type, like int </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>takes_ownership</code> </para></entry><entry colsep="1" rowsep="1"><p
ara> Parameter (Function, Delegate) </para></entry><entry colsep="1" rowsep="1"><para> 0, 1
</para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
<code>throws</code> </para></entry><entry colsep="1" rowsep="1"><para> Function </para></entry><entry
colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Marks that the function
should use an out parameter instead of throwing an error </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> <code>to_string</code> </para></entry><entry colsep="1" rowsep="1"><para> Enum
</para></entry><entry colsep="1" rowsep="1"><para> C function name </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>transfer_ownership</code>
</para></entry><entry colsep="1" rowsep="1"><para> Function/Delegate/Signal (having a return value),
Parameter (Function, Signal) </para></entry><entry colsep="1" rowsep="1
"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"><para> Transfers ownership of the value
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>type_arguments</code>
</para></entry><entry colsep="1" rowsep="1"><para> Function/Delegate/Signal (having a return value),
Property, Field, Parameter </para></entry><entry colsep="1" rowsep="1"><para> Vala types, comma separated
</para></entry><entry colsep="1" rowsep="1"><para> Restricts the generic type of the thing
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>type_check_function</code>
</para></entry><entry colsep="1" rowsep="1"><para> Class (GObject) </para></entry><entry colsep="1"
rowsep="1"><para> C function/macro name </para></entry><entry colsep="1" rowsep="1"/></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> <code>type_id</code> </para></entry><entry colsep="1"
rowsep="1"><para> Struct, Class (GObject) </para></entry><entry colsep="1" rowsep="1"><pa
ra> C macro </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>type_name</code> </para></entry><entry colsep="1" rowsep="1"><para> Function (having
a return value), Property, Parameter, Field </para></entry><entry colsep="1" rowsep="1"><para> Vala type name
</para></entry><entry colsep="1" rowsep="1"><para> Changes the type of the selected thing. Overwrites old
type, so "type_name" must be before any other type modifying metadata </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> <code>type_parameters</code> </para></entry><entry colsep="1"
rowsep="1"><para> Delegate, Class (non-GObject) </para></entry><entry colsep="1" rowsep="1"><para> Vala
generic type parameters, e.g. T, comma separated </para></entry><entry colsep="1" rowsep="1"/></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> <code>unref_function</code> </para></entry><entry colsep="1"
rowsep="1"><para> Class (non-GObjec
t) </para></entry><entry colsep="1" rowsep="1"><para> C function name </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>value_owned</code>
</para></entry><entry colsep="1" rowsep="1"><para> Parameter (Function) </para></entry><entry colsep="1"
rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>vfunc_name</code> </para></entry><entry colsep="1" rowsep="1"><para> Function
</para></entry><entry colsep="1" rowsep="1"><para> C function pointer name </para></entry><entry colsep="1"
rowsep="1"/></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <code>virtual</code>
</para></entry><entry colsep="1" rowsep="1"><para> Function </para></entry><entry colsep="1"
rowsep="1"><para> 0, 1 </para></entry><entry colsep="1" rowsep="1"/></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <code>weak</code> </para></entry><entry colsep="1" rowsep=
"1"><para> Field </para></entry><entry colsep="1" rowsep="1"><para> 0, 1 </para></entry><entry colsep="1"
rowsep="1"><para> Marks the field as weak
</para></entry></row></tbody></tgroup></informaltable></section><section><title>Examples</title><para>Demonstrating...
</para><screen><![CDATA[// ...]]></screen></section></section><para>Back to <ulink
url="http://wiki.gnome.org/action/show/Projects/Vala/Manual/Export/Vala/Manual#";>Vala Reference
Manual</ulink> </para><section><title>GIR metadata format</title><para>The <code>GIR</code> format actually
has a lot of information for generating bindings, but it's a different language than Vala. Therefore, it's
almost impossible to directly map a whole .gir file into a Vala tree, hence the need of metadata. On the
other side we might want to use directly .gir + .metadata instead of generating a .vapi, but .vapi is more
humanly readable and faster to parse than the GIR, hence the need of vapigen for generating a .vapi.
</para><section
<title>Locating metadata</title><para>The filename of a metadata for a <code>SomeLib.gir</code> must be
<code>SomeLib.metadata</code>. By default Vala looks for .metadata into the same directory of the .gir
file, however it's possible to specify other directories using the <code>--metadatadir</code> option.
</para></section><section><title>Comments</title><para>Comments in the metadata have the same syntax as in
Vala code: </para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><lineannotation><![CDATA[// this is a comment]]></lineannotation>
+<lineannotation/><lineannotation><![CDATA[/*]]></lineannotation>
+<lineannotation><![CDATA[ * multi-line comment]]></lineannotation>
+<lineannotation><![CDATA[ */]]></lineannotation>
+</programlisting></section><section><title>Syntax</title><para>Metadata information for each symbol must
provided on different lines: </para><itemizedlist><listitem
override="none"><para>rule:</para><itemizedlist><listitem override="none"><para>pattern [ arguments ] [
<code>newline</code> relative-rules ] <code>newline</code></para></listitem></itemizedlist><para>
relative-rules:</para><itemizedlist><listitem override="none"><para><emphasis role="strong">.</emphasis>
pattern [ arguments ] [ <code>newline</code> relative-rules ]</para></listitem></itemizedlist><para>
pattern:</para><itemizedlist><listitem override="none"><para><code>glob-style-pattern</code> [ <emphasis
role="strong">#</emphasis> selector ] [ <emphasis role="strong">.</emphasis> pattern
]</para></listitem></itemizedlist><para> arguments:</para><itemizedlist><listitem
override="none"><para><code>identifier</code> [ <emphasis role="strong">=</emphasis> expression ] [ arguments
]</para></listitem></itemizedlist>
<para> expression:</para><itemizedlist><listitem override="none"><para><emphasis
role="strong">null</emphasis></para><para> <emphasis role="strong">true</emphasis></para><para> <emphasis
role="strong">false</emphasis></para><para> <emphasis role="strong">-</emphasis> expression</para><para>
integer-literal</para><para> real-literal</para><para> string-literal</para><para>
symbol</para></listitem></itemizedlist><para> symbol:</para><itemizedlist><listitem
override="none"><para>identifier [ <emphasis role="strong">.</emphasis> identifier
]</para></listitem></itemizedlist></listitem></itemizedlist><itemizedlist><listitem><para>Patterns are tied
to the GIR tree: if a class <code>FooBar</code> contains a method <code>baz_method</code> then it can be
referenced in the metadata as <code>FooBar.baz_method</code>. </para></listitem><listitem><para>Selectors are
used to specify a particular element name of the GIR tree, for example <code>FooBar.baz_method#method</code>
will only selec
t method elements whose name is baz_method. Useful to solve name collisions.
</para></listitem><listitem><para>Given a namespace named <code>Foo</code> a special pattern <code>Foo</code>
is available for setting general arguments. </para></listitem><listitem><para>If a GIR symbol matches
multiple rules then all of them will be applied: if there are clashes among arguments, last written rules in
the file take precedence. </para></listitem><listitem><para>If the expression for an argument is not
provided, it's treated as <emphasis role="strong">true</emphasis> by default.
</para></listitem><listitem><para>A <emphasis>relative rule</emphasis> is relative to the nearest preceding
<emphasis>absolute rule</emphasis>. Metadata must contain at least one absolute rule. It's not possible to
make a rule relative to another relative rule.
</para></listitem></itemizedlist></section><section><title>Valid arguments</title><informaltable><tgroup
cols="4"><colspec colname="col_0"/><colspec c
olname="col_1"/><colspec colname="col_2"/><colspec colname="col_3"/><tbody><row rowsep="1"><entry colsep="1"
rowsep="1"><para> <emphasis role="strong">Name</emphasis> </para></entry><entry colsep="1" rowsep="1"><para>
<emphasis role="strong">Applies to</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Type</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> <emphasis
role="strong">Description</emphasis> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
skip </para></entry><entry colsep="1" rowsep="1"><para> all </para></entry><entry colsep="1"
rowsep="1"><para> bool </para></entry><entry colsep="1" rowsep="1"><para> Skip processing the symbol
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> hidden </para></entry><entry
colsep="1" rowsep="1"><para> all </para></entry><entry colsep="1" rowsep="1"><para> bool
</para></entry><entry colsep="1" rowsep="1"><para> Process the symbol but hide
from output </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> type
</para></entry><entry colsep="1" rowsep="1"><para> method, parameter, property, field, constant, alias
</para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1" rowsep="1"><para>
Complete Vala type </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> type_arguments
</para></entry><entry colsep="1" rowsep="1"><para> method, parameter, property, field, constant, alias
</para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1" rowsep="1"><para>
Vala type parameters for generics, separated by commas </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> cheader_filename </para></entry><entry colsep="1" rowsep="1"><para> all including namespace
</para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1" rowsep="1"><para>
C headers separated by commas </para><
/entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> name </para></entry><entry colsep="1"
rowsep="1"><para> all including namespace </para></entry><entry colsep="1" rowsep="1"><para> string
</para></entry><entry colsep="1" rowsep="1"><para> Vala symbol name </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> owned </para></entry><entry colsep="1" rowsep="1"><para>
parameter </para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry colsep="1"
rowsep="1"><para> Whether the parameter value should be owned </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> unowned </para></entry><entry colsep="1" rowsep="1"><para> method, property,
field, constant </para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry colsep="1"
rowsep="1"><para> Whether the symbol is unowned </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> parent </para></entry><entry colsep="1" rowsep="1">
<para> all </para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1"
rowsep="1"><para> Move the symbol to the specified container symbol. If no container exists, a new namespace
will be created. </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> nullable
</para></entry><entry colsep="1" rowsep="1"><para> method, parameter, property, field, constant, alias
</para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry colsep="1" rowsep="1"><para>
Whether the type is nullable or not </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para>
deprecated </para></entry><entry colsep="1" rowsep="1"><para> all </para></entry><entry colsep="1"
rowsep="1"><para> bool </para></entry><entry colsep="1" rowsep="1"><para> Whether the symbol is deprecated or
not </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> replacement
</para></entry><entry colsep="1" rowsep="1"><para> all </para>
</entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1" rowsep="1"><para>
Deprecation replacement, implies <code>deprecated=true</code> </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> deprecated_since </para></entry><entry colsep="1" rowsep="1"><para> all
</para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1" rowsep="1"><para>
Deprecated since version, implies <code>deprecated=true</code> </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> array </para></entry><entry colsep="1" rowsep="1"><para> method, parameter,
property, field, constant, alias </para></entry><entry colsep="1" rowsep="1"><para> bool
</para></entry><entry colsep="1" rowsep="1"><para> Whether the type is an array or not
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> array_length_idx
</para></entry><entry colsep="1" rowsep="1"><para> parameter </para></entry><entry colsep="1"
rowsep="1"><para> int </para></entry><entry colsep="1" rowsep="1"><para> The index of the C array length
parameter </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> default
</para></entry><entry colsep="1" rowsep="1"><para> parameter </para></entry><entry colsep="1"
rowsep="1"><para> any </para></entry><entry colsep="1" rowsep="1"><para> Default expression for the parameter
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> out </para></entry><entry colsep="1"
rowsep="1"><para> parameter </para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry
colsep="1" rowsep="1"><para> Whether the parameter direction is out or not </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> ref </para></entry><entry colsep="1" rowsep="1"><para>
parameter </para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry colsep="1"
rowsep="1"><para> Whether the parameter direction is ref or not </para
</entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> vfunc_name </para></entry><entry
colsep="1" rowsep="1"><para> method </para></entry><entry colsep="1" rowsep="1"><para> string
</para></entry><entry colsep="1" rowsep="1"><para> Name of the C virtual function </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> virtual </para></entry><entry colsep="1" rowsep="1"><para>
method, signal, property </para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry
colsep="1" rowsep="1"><para> Whether the symbol is virtual or not </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> abstract </para></entry><entry colsep="1" rowsep="1"><para>
method, signal, property </para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry
colsep="1" rowsep="1"><para> Whether the symbol is abstract or not </para></entry></row><row
rowsep="1"><entry colsep="1" rowsep="1"><para> scope </para></entry><entry colsep="
1" rowsep="1"><para> parameter (async method) </para></entry><entry colsep="1" rowsep="1"><para> string
</para></entry><entry colsep="1" rowsep="1"><para> Scope of the delegate, in GIR terms
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> struct </para></entry><entry
colsep="1" rowsep="1"><para> record (detected as boxed compact class) </para></entry><entry colsep="1"
rowsep="1"><para> bool </para></entry><entry colsep="1" rowsep="1"><para> Whether the boxed type must be
threaten as struct instead of compact class </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> printf_format </para></entry><entry colsep="1" rowsep="1"><para> method
</para></entry><entry colsep="1" rowsep="1"><para> bool </para></entry><entry colsep="1" rowsep="1"><para>
Add the [PrintfFormat] attribute to the method if true </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> array_length_field </para></entry><entry colsep="1" rowsep="1"><
para> field (array) </para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry
colsep="1" rowsep="1"><para> The name of the length field </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> sentinel </para></entry><entry colsep="1" rowsep="1"><para> method
</para></entry><entry colsep="1" rowsep="1"><para> string </para></entry><entry colsep="1" rowsep="1"><para>
C expression of the last argument for varargs </para></entry></row><row rowsep="1"><entry colsep="1"
rowsep="1"><para> closure </para></entry><entry colsep="1" rowsep="1"><para> parameter </para></entry><entry
colsep="1" rowsep="1"><para> int </para></entry><entry colsep="1" rowsep="1"><para> Specifies the index of
the parameter representing the user data for this callback </para></entry></row><row rowsep="1"><entry
colsep="1" rowsep="1"><para> errordomain </para></entry><entry colsep="1" rowsep="1"><para> enumeration
</para></entry><entry colsep="1" rowsep="1"><para> bool </
para></entry><entry colsep="1" rowsep="1"><para> Whether the enumeration is an errordomain or not
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> destroys_instance
</para></entry><entry colsep="1" rowsep="1"><para> method </para></entry><entry colsep="1" rowsep="1"><para>
bool </para></entry><entry colsep="1" rowsep="1"><para> Whether the instance is owned by the method
</para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> throws </para></entry><entry
colsep="1" rowsep="1"><para> method </para></entry><entry colsep="1" rowsep="1"><para> string
</para></entry><entry colsep="1" rowsep="1"><para> Type of exception the method throws
</para></entry></row></tbody></tgroup></informaltable></section><section><title>Examples</title><para>Demonstrating...
</para><section><title>Overriding Types</title><para>When you have the following expression:
</para><screen><![CDATA[typedef GList MyList;]]></screen><para>where <code>GList</code> will hol
d integers, use <code>type</code> metadata as follows: </para><screen><![CDATA[MyList
type="GLib.List<int>"]]></screen><para>The above metadata will generate the following code:
</para><programlisting format="linespecific" language="cpp" linenumbering="numbered"
startinglinenumber="1"><![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[MyList]]></methodname><![CDATA[ :
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[.]]><methodname><![CDATA[List]]></methodname><![CDATA[<]]><token><![CDATA[int]]></token><![CDATA[>
{]]>
+<![CDATA[ []]><methodname><![CDATA[CCode]]></methodname><![CDATA[
(]]><methodname><![CDATA[has_construct_function]]></methodname><![CDATA[ =
]]><symbol><![CDATA[false]]></symbol><![CDATA[)]]]>
+<![CDATA[ ]]><token><![CDATA[protected]]></token><![CDATA[
]]><methodname><![CDATA[MyList]]></methodname><![CDATA[ ();]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[.]]><methodname><![CDATA[Type]]></methodname><![CDATA[
]]><methodname><![CDATA[get_type]]></methodname><![CDATA[ ();]]>
+<![CDATA[ }]]>
+</programlisting><para>Then you can use <code>GLib.List</code> or <code>NameSpace.MyList</code> as if equal.
</para></section><section><title>Skipping Simbols</title><screen><![CDATA[MySimbol
skip]]></screen></section><section><title>More Examples</title><screen><![CDATA[//
...]]></screen></section></section></section></section></article>
\ No newline at end of file
diff --git a/doc/vala/toc.xsl b/doc/vala/toc.xsl
new file mode 100644
index 0000000..854d7b3
--- /dev/null
+++ b/doc/vala/toc.xsl
@@ -0,0 +1,16 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns="http://www.w3.org/1999/xhtml"; xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.1">
+ <xsl:output method="xml" indent="yes" omit-xml-declaration="yes"
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"; doctype-public="-//W3C//DTD XHTML 1.0
Strict//EN"/>
+
+ <xsl:template match="/">
+ <xsl:apply-templates select="/article/section/section"/>
+ </xsl:template>
+
+ <xsl:template match="/article/section/section"> * [[/<xsl:value-of select="title"/>|<xsl:value-of
select="title"/>]] 
+<xsl:apply-templates select="section"/>
+</xsl:template>
+
+ <xsl:template match="/article/section/section/section"> * [[/<xsl:value-of
select="../title"/>#<xsl:value-of select="title"/>|<xsl:value-of select="title"/>]] 
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/doc/vala/xhtml.xsl b/doc/vala/xhtml.xsl
index 607fbac..5988e99 100644
--- a/doc/vala/xhtml.xsl
+++ b/doc/vala/xhtml.xsl
@@ -1,107 +1,270 @@
<?xml version="1.0"?>
-<xsl:stylesheet xmlns="http://www.w3.org/1999/xhtml"; xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.1">
- <xsl:output method="xml" indent="yes"
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"; doctype-public="-//W3C//DTD XHTML 1.0
Strict//EN"/>
- <xsl:strip-space elements="blockquote/l"/>
- <xsl:template match="/">
- <xsl:apply-templates select="html"/>
- </xsl:template>
- <xsl:template match="html">
- <html><xsl:apply-templates select="head|body"/></html>
- </xsl:template>
- <xsl:template match="head">
- <head>
- <xsl:apply-templates select="title"/>
- <link rel="stylesheet" type="text/css" href="default.css"/>
- </head>
- </xsl:template>
- <xsl:template match="title">
- <title><xsl:value-of select="."/></title>
- </xsl:template>
- <xsl:template match="body">
- <body>
- <div class="header">
- <a href="index.html"><xsl:value-of select="//title/text()"/></a>
- </div>
- <xsl:apply-templates select="h|p|section"/>
- <ul class="toc">
- <xsl:for-each select="section">
- <li>
- <a href="{@id}.html"><xsl:value-of select="h/text()"/></a>
- <xsl:if test="count(section) > 0">
- <ul>
- <xsl:for-each select="section">
- <li><a
href="{../@id}.html#{@id}"><xsl:value-of select="h/text()"/></a></li>
- </xsl:for-each>
- </ul>
- </xsl:if>
- </li>
- </xsl:for-each>
- </ul>
- </body>
- </xsl:template>
- <xsl:template match="body/h">
- <h1><xsl:value-of select="text()"/></h1>
- </xsl:template>
- <xsl:template match="body/section">
- <xsl:document href="{@id}.html" method="xml" indent="yes">
- <html>
- <head>
- <title><xsl:value-of select="h/text()"/> - <xsl:value-of
select="//title/text()"/></title>
- <link rel="stylesheet" type="text/css" href="default.css"/>
- </head>
- <body>
- <div class="header">
- <a href="index.html"><xsl:value-of
select="//title/text()"/></a>
- </div>
- <xsl:apply-templates
select="h|p|section|div|blockcode|blockquote|ol|ul"/>
- </body>
- </html>
- </xsl:document>
- </xsl:template>
- <xsl:template match="body/section/h">
- <h2><xsl:value-of select="text()"/></h2>
- </xsl:template>
- <xsl:template match="body/section/section">
- <xsl:apply-templates select="h|p|div|blockcode|blockquote|section|ol|ul"/>
- </xsl:template>
- <xsl:template match="body/section/section/h">
- <h3><xsl:value-of select="text()"/><a id="{../@id}"><xsl:text> </xsl:text></a></h3>
- </xsl:template>
- <xsl:template match="body/section/section/section">
- <xsl:apply-templates select="h|p|div|blockcode|blockquote|section|ol|ul"/>
- </xsl:template>
- <xsl:template match="body/section/section/section/h">
- <h4><xsl:value-of select="text()"/><a id="{../@id}"><xsl:text> </xsl:text></a></h4>
- </xsl:template>
- <xsl:template match="div[@role='note']">
- <div class="note"><xsl:apply-templates select="h|p|blockcode|blockquote"/></div>
- </xsl:template>
- <xsl:template match="div/h">
- <h4><xsl:value-of select="text()"/></h4>
- </xsl:template>
- <xsl:template match="p">
- <p><xsl:apply-templates select="text()|code"/></p>
- </xsl:template>
- <xsl:template match="code">
- <code><xsl:value-of select="text()"/></code>
- </xsl:template>
- <xsl:template match="blockcode">
- <pre><xsl:value-of select="text()"/></pre>
- </xsl:template>
- <xsl:template match="blockquote">
- <blockquote><xsl:apply-templates select="text()|l"/></blockquote>
- </xsl:template>
- <xsl:template match="blockquote/l">
- <span class="literal"><xsl:value-of select="text()"/></span>
- </xsl:template>
- <xsl:template match="ol">
- <ol><xsl:apply-templates select="item"/></ol>
- </xsl:template>
- <xsl:template match="ul">
- <ul><xsl:apply-templates select="item"/></ul>
- </xsl:template>
- <xsl:template match="ol/item|ul/item">
- <li><xsl:value-of select="text()"/></li>
- </xsl:template>
-</xsl:stylesheet>
+<xsl:stylesheet xmlns="http://www.w3.org/1999/xhtml"; xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
+ xmlns:str="http://exslt.org/strings"; version="1.1">
+ <xsl:output method="xml" indent="yes" omit-xml-declaration="yes"
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"; doctype-public="-//W3C//DTD XHTML 1.0
Strict//EN"/>
+
+ <xsl:template name="sectionid">
+ <xsl:param name="title"/>
+ <xsl:value-of select="str:replace($title, ' ', '_')"/>
+ </xsl:template>
+
+ <xsl:template name="linkto">
+ <xsl:param name="page"/>
+ <xsl:param name="subpage"/>
+ <xsl:param name="title"/>
+
+ <xsl:variable name="pageid">
+ <xsl:call-template name="sectionid">
+ <xsl:with-param name="title" select="$page"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <xsl:variable name="subpageid">
+ <xsl:call-template name="sectionid">
+ <xsl:with-param name="title" select="$subpage"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <a href="{$pageid}.html#{$subpageid}"><xsl:value-of select="$title"/></a>
+ </xsl:template>
+
+ <xsl:template match="/">
+ <xsl:apply-templates select="article"/>
+ </xsl:template>
+
+ <xsl:template match="article">
+ <html><xsl:apply-templates select="articleinfo|section"/></html>
+ </xsl:template>
+
+ <xsl:template match="articleinfo">
+ <head>
+ <xsl:apply-templates select="title"/>
+ <link rel="stylesheet" type="text/css" href="default.css"/>
+ </head>
+ </xsl:template>
+
+ <xsl:template match="article/section/title">
+ <div class="header">
+ <a href="index.html"><xsl:value-of select="."/></a>
+ </div>
+ <h1><xsl:value-of select="."/></h1>
+ </xsl:template>
+
+ <xsl:template match="articleinfo/title">
+ <title><xsl:value-of select="/article/section/title"/></title>
+ </xsl:template>
+
+ <xsl:template match="article/section">
+ <body>
+ <xsl:apply-templates select="title"/>
+ <ul class="toc">
+ <xsl:for-each select="section">
+ <li>
+ <xsl:call-template name="linkto">
+ <xsl:with-param name="page" select="title"/>
+ <xsl:with-param name="title" select="title"/>
+ </xsl:call-template>
+ <xsl:if test="count(section) > 0">
+ <ul>
+ <xsl:for-each select="section">
+ <li>
+ <xsl:call-template name="linkto">
+ <xsl:with-param name="page" select="../title"/>
+ <xsl:with-param name="subpage" select="title"/>
+ <xsl:with-param name="title" select="title"/>
+ </xsl:call-template>
+ </li>
+ </xsl:for-each>
+ </ul>
+ </xsl:if>
+ </li>
+ </xsl:for-each>
+ </ul>
+ <xsl:apply-templates select="section"/>
+ </body>
+ </xsl:template>
+
+ <xsl:template match="article/section/section">
+ <xsl:variable name="id">
+ <xsl:call-template name="sectionid">
+ <xsl:with-param name="title" select="title"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <xsl:document href="{$id}.html" method="xml" indent="yes" omit-xml-declaration="yes"
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"; doctype-public="-//W3C//DTD XHTML 1.0
Strict//EN">
+ <html>
+ <head>
+ <title><xsl:value-of select="title/text()"/> - <xsl:value-of
select="/article/section/title"/></title>
+ <link rel="stylesheet" type="text/css" href="default.css"/>
+ </head>
+ <body>
+ <div class="header">
+ <a href="index.html"><xsl:value-of select="/article/section/title"/></a>
+ </div>
+ <xsl:apply-templates select="title"/>
+ <xsl:if test="count(section) > 0">
+ <ul class="page_toc">
+ <xsl:for-each select="section">
+ <li>
+ <xsl:call-template name="linkto">
+ <xsl:with-param name="page" select="../title"/>
+ <xsl:with-param name="subpage" select="title"/>
+ <xsl:with-param name="title" select="title"/>
+ </xsl:call-template>
+ </li>
+ </xsl:for-each>
+ </ul>
+ </xsl:if>
+ <xsl:apply-templates select="para|section|programlisting|screen|itemizedlist"/>
+ </body>
+ </html>
+ </xsl:document>
+ </xsl:template>
+
+ <xsl:template match="article/section/section/title">
+ <h2><xsl:value-of select="."/></h2>
+ </xsl:template>
+
+ <xsl:template match="article/section/section/section">
+ <xsl:apply-templates select="para|section|programlisting|screen|itemizedlist|title|informaltable"/>
+ </xsl:template>
+
+ <xsl:template match="article/section/section/section/title">
+ <xsl:variable name="id">
+ <xsl:call-template name="sectionid">
+ <xsl:with-param name="title" select="."/>
+ </xsl:call-template>
+ </xsl:variable>
+ <h3><xsl:value-of select="."/><a name="{$id}"> </a></h3>
+ </xsl:template>
+
+ <xsl:template match="article/section/section/section/section">
+ <xsl:apply-templates select="para|section|programlisting|screen|itemizedlist|title|informaltable"/>
+ </xsl:template>
+
+ <xsl:template match="article/section/section/section/section/title">
+ <xsl:variable name="id">
+ <xsl:call-template name="sectionid">
+ <xsl:with-param name="title" select="."/>
+ </xsl:call-template>
+ </xsl:variable>
+ <h4><xsl:value-of select="."/><a name="{$id}"> </a></h4>
+ </xsl:template>
+
+ <xsl:template match="para">
+ <p><xsl:apply-templates select="text()|code|ulink|emphasis"/></p>
+ </xsl:template>
+
+ <xsl:template match="emphasis">
+ <strong><xsl:apply-templates select="text()"/></strong>
+ </xsl:template>
+
+ <xsl:template match="ulink">
+ <xsl:if test="starts-with(@url,'http://live.gnome.org/Vala/Manual/')">
+ <xsl:variable name="pageid">
+ <xsl:call-template name="sectionid">
+ <xsl:with-param name="title" select="str:decode-uri(str:tokenize(substring-after(@url,
'http://live.gnome.org/Vala/Manual/'),'#')[1])"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <a href="{$pageid}.html#{str:tokenize(substring-after(@url,
'http://live.gnome.org/Vala/Manual/'),'#')[2]}"><xsl:value-of select="."/></a>
+ </xsl:if>
+ <xsl:if test="not(starts-with(@url,'http://live.gnome.org/Vala/Manual/'))">
+ <a href="{@url}"><xsl:value-of select="."/></a>
+ </xsl:if>
+ </xsl:template>
+
+
+ <xsl:template match="para/code">
+ <xsl:if test="contains (text(), '
')">
+ <pre><xsl:value-of select="text()"/></pre>
+ </xsl:if>
+ <xsl:if test="not (contains (text(), '
'))">
+ <code><xsl:value-of select="text()"/></code>
+ </xsl:if>
+ </xsl:template>
+ <xsl:template match="screen">
+ <pre><xsl:value-of select="text()"/></pre>
+ </xsl:template>
+
+ <xsl:template match="programlisting">
+ <pre><xsl:apply-templates select="text()|type|methodname|token|phrase"/></pre>
+ </xsl:template>
+
+ <xsl:template match="type">
+ <span class="type"><xsl:value-of select="."/></span>
+ </xsl:template>
+
+ <xsl:template match="token">
+ <span class="token"><xsl:value-of select="."/></span>
+ </xsl:template>
+
+ <xsl:template match="methodname">
+ <span class="methodname"><xsl:value-of select="."/></span>
+ </xsl:template>
+
+ <xsl:template match="phrase">
+ <span class="phrase"><xsl:value-of select="."/></span>
+ </xsl:template>
+
+ <!-- lists -->
+
+ <xsl:template match="itemizedlist[listitem[not(@override)]]">
+ <ul><xsl:apply-templates select="listitem"/></ul>
+ </xsl:template>
+
+ <xsl:template match="listitem[not(@override)]">
+ <li><xsl:apply-templates select="para"/></li>
+ </xsl:template>
+
+ <xsl:template match="itemizedlist[listitem[@override='none']]">
+ <blockquote><xsl:apply-templates select="listitem"/></blockquote>
+ </xsl:template>
+
+ <xsl:template match="listitem[@override='none']/itemizedlist"><xsl:apply-templates
select="listitem"/><xsl:text>
+</xsl:text></xsl:template>
+
+ <xsl:template match="listitem[@override='none']">
+ <xsl:apply-templates select="para|itemizedlist"/>
+ </xsl:template>
+
+ <xsl:template match="listitem[@override='none']/para"><xsl:apply-templates
select="text()|emphasis"/><xsl:text>
+</xsl:text></xsl:template>
+
+ <xsl:template match="listitem[@override='none']/para/text()">
+ <xsl:if test="position()=1 and starts-with(.,' ')">
+ <xsl:if test="normalize-space(.)!=''"><xsl:value-of select="substring-after(.,' ')"/></xsl:if>
+ </xsl:if>
+ <xsl:if test="position()!=1 or not(starts-with(.,' '))">
+ <xsl:if test="normalize-space(.)!=''"><xsl:value-of select="."/></xsl:if>
+ </xsl:if>
+ </xsl:template>
+
+ <xsl:template match="listitem[@override='none']/para/emphasis[@role='strong']"><span
class="literal"><xsl:value-of select="."/></span></xsl:template>
+<xsl:template
match="listitem[@override='none']/itemizedlist/listitem[@override='none']/para"><xsl:text>	</xsl:text><xsl:apply-templates
select="text()|emphasis"/><xsl:text>
+</xsl:text></xsl:template>
+
+ <!-- tables -->
+ <xsl:template match="informaltable">
+ <table>
+ <xsl:apply-templates select="tgroup/tbody/row"/>
+ </table>
+ </xsl:template>
+
+ <xsl:template match="row">
+ <tr>
+ <xsl:apply-templates select="entry"/>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="entry">
+ <td xsl:use-attribute-sets="entry-attrs">
+ <xsl:apply-templates select="para"/>
+ </td>
+ </xsl:template>
+
+ <xsl:attribute-set name="entry-attrs">
+ <xsl:attribute name="align"><xsl:value-of select="@align"/></xsl:attribute>
+ <xsl:attribute name="colspan">
+ <xsl:if test="@nameend"><xsl:value-of select="number(substring-after(@nameend, 'col_'))+1"/></xsl:if>
+ </xsl:attribute>
+ </xsl:attribute-set>
+
+</xsl:stylesheet>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
