[vala/0.34] manual: Initial import of manual.xml from wiki.gnome.org
- From: Rico Tzschichholz <ricotz src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [vala/0.34] manual: Initial import of manual.xml from wiki.gnome.org
- Date: Tue, 7 Mar 2017 08:46:17 +0000 (UTC)
commit 12011ea82b3571e356a4ec43f276b03cecdb3894
Author: Alistair Thomas <astavale yahoo co uk>
Date: Tue Feb 21 00:02:58 2017 +0000
manual: Initial import of manual.xml from wiki.gnome.org
https://bugzilla.gnome.org/show_bug.cgi?id=779090
doc/manual/attributes.xml | 6 -
doc/manual/classes.xml | 86 --
doc/manual/delegates.xml | 13 -
doc/manual/enums.xml | 25 -
doc/manual/exceptions.xml | 9 -
doc/manual/expressions.xml | 108 --
doc/manual/index.xml | 23 -
doc/manual/interfaces.xml | 41 -
doc/manual/manual.xml | 3338 ++++++++++++++++++++++++++++++++++++++++++++
doc/manual/methods.xml | 43 -
doc/manual/namespaces.xml | 30 -
doc/manual/overview.xml | 30 -
doc/manual/statements.xml | 102 --
doc/manual/structs.xml | 36 -
doc/manual/types.xml | 166 ---
15 files changed, 3338 insertions(+), 718 deletions(-)
---
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
new file mode 100644
index 0000000..0a54b81
--- /dev/null
+++ b/doc/manual/manual.xml
@@ -0,0 +1,3338 @@
+<?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>
+
+<section>
+<title>Vala Reference Manual [Draft]</title>
+<para>Back to <ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual#";>Vala
Reference Manual</ulink> </para>
+
+<section>
+<title>Overview</title>
+<para>Vala is a 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="highlight" linenumbering="numbered" startinglinenumber="1"><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[main]]></methodname><![CDATA[ (]]><token><![CDATA[string]]></token><![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</emphasis></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</emphasis> 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="highlight"
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
are 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 either 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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Types#Pointer_types";>Types/Pointer
types</ulink>. </para>
+<para>There are more details about memory management elsewhere, see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Types#";>Types</ulink>, see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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="highlight" linenumbering="numbered"
startinglinenumber="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[
(]]><token><![CDATA[string]]></token><![CDATA[[] ]]><methodname><![CDATA[args]]></methodname><![CDATA[) { ...
}]]>
+<token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[
(]]><token><![CDATA[string]]></token><![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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Types#";>Types</ulink>. </para>
+<para>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 <link
linkend="References_and_ownership">Concepts/References and ownership</link> 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><programlisting format="linespecific" language="highlight" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[;]]>
+</programlisting>
+<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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Types#Reference_types";>Types/Reference
types</ulink>. </para>
+<para>If a type is directly instantiated in a variable declaration statement, then the variable will be
created owning that new instance, for example: </para><programlisting format="linespecific"
language="highlight" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[string]]></token><![CDATA[
]]><methodname><![CDATA[s]]></methodname><![CDATA[ =
]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[stringvalue]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[;]]>
+</programlisting>
+<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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Statements#Variable_declaration";>Statements/Variable
declaration</ulink> and <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Namespaces#";>Namespaces</ulink>,
<ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#";>Classes</ulink>
and <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Methods#";>Methods</ulink> and
<ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/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="highlight" 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 named 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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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 described elsewhere in this documentation. See <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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 describe 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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#";>Classes</ulink>. </para>
+<para>Vala provides inheritance functionality to any type of class (see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#Types_of_class";>Classes/Types
of class</ulink>). Given the following definition, every SubType instance is-a SuperType instance:
</para><programlisting format="linespecific" language="highlight" 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="highlight" 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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Types#";>Types</ulink>) 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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Ownership_transfer_expressions";>Expressions/Ownership
transfer expressions</ulink>). </para>
+</section>
+
+<section>
+<title>Reference types</title>
+<para>With reference 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. this 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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Types#Pointer_types";>Types/Pointer
types</ulink>. </para>
+</section>
+</section>
+</section>
+<para>Back to <ulink url="http://wiki.gnome.org/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>Vala 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="none">
+<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> fundamental-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 properties. See <ulink
url="http://wiki.gnome.org/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/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 when 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.gnome.org/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/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/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Enumerated%20types%20%28Enums%29#";>Enumerated
types (Enums)</ulink> for documentation on defining and using enumerated 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><listitem 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-array-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/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Overview#Memory_management";>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 sa
me rules apply. The types of classes available are discussed at <ulink
url="http://wiki.gnome.org/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/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/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Errors#";>Errors</ulink>, <ulink
url="http://wiki.gnome.org/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/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/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/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/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 that 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/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/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 explicit 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/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Concepts#Object_oriented_programming";>Concepts/Object
oriented programming</ulink>, see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#";>Classes</ulink>. </para>
+<para>For explicit casting expressions, see <ulink
url="http://wiki.gnome.org/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/Projects/Vala/Manual/Export/Projects/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 combined 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:</para><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/Projects/Vala/Manual/Export/Projects/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>[ primary-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><listitem 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></listitem></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 floating 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 subtraction 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.) </para>
+</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-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> 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><programlisting format="linespecific" language="highlight"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[var]]></token><![CDATA[
]]><methodname><![CDATA[postfix]]></methodname><![CDATA[ =
]]><methodname><![CDATA[i]]></methodname><![CDATA[++;]]>
+<token><![CDATA[var]]></token><![CDATA[ ]]><methodname><![CDATA[prefix]]></methodname><![CDATA[ =
--]]><methodname><![CDATA[j]]></methodname><![CDATA[;]]>
+</programlisting>
+<para>are equivalent to: </para><programlisting format="linespecific" language="highlight"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[var]]></token><![CDATA[
]]><methodname><![CDATA[postfix]]></methodname><![CDATA[ =
]]><methodname><![CDATA[i]]></methodname><![CDATA[;]]>
+<methodname><![CDATA[i]]></methodname><![CDATA[ += 1;]]>
+
+<methodname><![CDATA[j]]></methodname><![CDATA[ -= 1;]]>
+<token><![CDATA[var]]></token><![CDATA[ ]]><methodname><![CDATA[prefix]]></methodname><![CDATA[ =
]]><methodname><![CDATA[j]]></methodname><![CDATA[;]]>
+</programlisting>
+</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>Documentation </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><programlisting
format="linespecific" language="highlight" linenumbering="numbered"
startinglinenumber="1"><methodname><![CDATA[result]]></methodname><![CDATA[ +=
]]><methodname><![CDATA[value]]></methodname><![CDATA[;]]>
+<methodname><![CDATA[result]]></methodname><![CDATA[ <<=
]]><methodname><![CDATA[value]]></methodname><![CDATA[;]]>
+<![CDATA[...]]>
+</programlisting>
+<para>Are equivalent to simple assignments: </para><programlisting format="linespecific"
language="highlight" linenumbering="numbered"
startinglinenumber="1"><methodname><![CDATA[result]]></methodname><![CDATA[ =
]]><methodname><![CDATA[result]]></methodname><![CDATA[ +
]]><methodname><![CDATA[value]]></methodname><![CDATA[;]]>
+<methodname><![CDATA[result]]></methodname><![CDATA[ =
]]><methodname><![CDATA[result]]></methodname><![CDATA[ <<
]]><methodname><![CDATA[value]]></methodname><![CDATA[;]]>
+<![CDATA[...]]>
+</programlisting>
+</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 will 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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Delegates#";>Delegates</ulink>
</para>
+<para>Firing a signal is basically the same. See <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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><itemizedlist><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">
+<para>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>
+</section>
+
+<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 <emphasis 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 expression 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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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 ] identifier</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 of" 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></itemizedlist></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/Projects/Vala/Manual/Export/Projects/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>
+<para> 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 cannot 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> statement-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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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 equivalent 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> boolean-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</emphasis> 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><listitem 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 <link
linkend="Jump_statements">Statements/Jump statements</link>. </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-embedded-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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink> and <link linkend="Simple_statements">Statements/Simple statements</link>. </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 on 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 of the try statement, See <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual#";>Vala
Reference Manual</ulink> </para>
+
+<section>
+<title>Namespaces</title>
+<para>Namespaces are named scopes (see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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="highlight" 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="highlight" 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.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 <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#";>Classes</ulink>, <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Structs#";>Structs</ulink>, <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Delegates#";>Delegates</ulink>,
<ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Enumerated%20types%20%28Enums%29#";>Enumerated
types (Enums)</ulink>, and <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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 beginning 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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink>). If the identifier cannot be resolved in any scope, each 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><programlisting format="linespecific" language="highlight" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[using]]></token><![CDATA[
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[;]]>
+</programlisting>
+<para>TODO: Include examples. </para>
+</section>
+</section>
+<para>Back to <ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Namespaces#";>Namespaces</ulink>,
<ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#";>Classes</ulink>,
<ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Interfaces#";>Interfaces</ulink>,
<ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Concepts#Scope_and_naming";>Concepts/Scope
and naming</ulink>. </para>
+<para>The <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#";>Classes</ulink> section
of this documentation talks about both methods and abstract methods. It 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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Concepts#Variables,_fields_and_parameters";>Concepts/Variables,
fields and parameters</ulink>). This basic form of parameter is technically an "in" parameter,
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 sections 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 override="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></listitem></itemizedlist></listitem></itemizedlist>
+<para>For more details see <link linkend="Contract_programming">Methods/Contract programming</link>, and
<ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Errors#";>Errors</ulink>.
</para>
+</section>
+
+<section>
+<title>Invocation</title>
+<para>See <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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 returns 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="highlight"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[delegate]]></token><![CDATA[
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[DelegateType]]></methodname><![CDATA[
(]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[a]]></methodname><![CDATA[,
]]><token><![CDATA[string]]></token><![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[, ]]><token><![CDATA[string]]></token><![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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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" keyword 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 <emphasis 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 the respective sections of the method decleration syntax (see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Invocation_expressions";>Expressions/Invocation
expressions</ulink>. </para>
+</section>
+
+<section>
+<title>Examples</title>
+<para>Defining delegates: </para><programlisting format="linespecific" language="highlight"
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="highlight" 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="highlight"
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[}]]>
+
+<token><![CDATA[delegate]]></token><![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[
(]]><token><![CDATA[string]]></token><![CDATA[[] ]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><token><![CDATA[var]]></token><![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><programlisting format="linespecific" language="highlight"
linenumbering="numbered"
startinglinenumber="1"><methodname><![CDATA[f2]]></methodname><![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[); }, 5);]]>
+</programlisting>
+</section>
+</section>
+<para>Back to <ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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 try 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-statement:</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></itemizedlist></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="highlight"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[errordomain]]></token><![CDATA[
]]><methodname><![CDATA[ErrorType1]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[CODE_1A]]></methodname>
+<![CDATA[ }]]>
+
+<![CDATA[ ]]><token><![CDATA[errordomain]]></token><![CDATA[
]]><methodname><![CDATA[ErrorType2]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><methodname><![CDATA[CODE_2A]]></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[ ]]><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[ } ]]><token><![CDATA[finally]]></token><![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[(]]><token><![CDATA[string]]></token><![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/Projects/Vala/Manual/Export/Projects/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="highlight" 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></listitem><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 class 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 class, 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 the 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="highlight" 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. 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></itemizedlist>
+<para>This defines whether the member is visible to code in different locations:
</para><itemizedlist><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="strong">{</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></itemizedlist>
+<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 <link linkend="Types_of_class">Classes/Types of class</link> 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 "class 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-declaration:</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="highlight" linenumbering="numbered"
startinglinenumber="1"><token><![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/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> creation-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
<emphasis 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 particular 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 instance, 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 ] <emphasis 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/Projects/Vala/Manual/Export/Projects/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="strong">;</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/Projects/Vala/Manual/Export/Projects/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-name 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
role="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 methods. 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/Projects/Vala/Manual/Export/Projects/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/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 changed. </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> lambda-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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Delegates#";>Delegates</ulink>.
For details on lambda expressions see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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 immediately 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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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><programlisting format="linespecific" language="highlight"
linenumbering="numbered" startinglinenumber="1"><lineannotation><![CDATA[// ...]]></lineannotation>
+<lineannotation/>
+</programlisting>
+
+<section>
+<title>Using Properties</title>
+<para>For more examples see: <ulink url="https://live.gnome.org/Vala/PropertiesSample";>Samples for Class
Properties</ulink> </para>
+
+<section>
+<title>Virtual Properties</title><programlisting format="linespecific" language="highlight"
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[ ]]><token><![CDATA[get]]></token><![CDATA[ { ]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_number]]></methodname><![CDATA[; ]]>
+<![CDATA[ } ]]>
+<![CDATA[ ]]><token><![CDATA[set]]></token><![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[ ]]><token><![CDATA[string]]></token><![CDATA[
]]><methodname><![CDATA[name]]></methodname><![CDATA[ { ]]><token><![CDATA[get]]></token><![CDATA[;
]]><token><![CDATA[set]]></token><![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[
]]><token><![CDATA[override]]></token><![CDATA[ ]]><token><![CDATA[int]]></token><![CDATA[
]]><methodname><![CDATA[number]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[get]]></token><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_number]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]><token><![CDATA[set]]></token><![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[
(]]><token><![CDATA[string]]></token><![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[ ]]><token><![CDATA[var]]></token><![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[ ]]><token><![CDATA[var]]></token><![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[ ]]><token><![CDATA[var]]></token><![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="highlight"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[namespace]]></token><![CDATA[
]]><methodname><![CDATA[Properties]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[abstract]]></token><![CDATA[ ]]><token><![CDATA[class]]></token><![CDATA[
]]><methodname><![CDATA[Base]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><token><![CDATA[abstract]]></token><![CDATA[ ]]><token><![CDATA[string]]></token><![CDATA[
]]><methodname><![CDATA[name]]></methodname><![CDATA[ { ]]><token><![CDATA[get]]></token><![CDATA[;
]]><token><![CDATA[set]]></token><![CDATA[ ]]><token><![CDATA[construct]]></token><![CDATA[; }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[construct]]></token><![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[
]]><token><![CDATA[string]]></token><![CDATA[ ]]><methodname><![CDATA[_name]]></methodname><![CDATA[;]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><token><![CDATA[override]]></token><![CDATA[ ]]><token><![CDATA[string]]></token><![CDATA[
]]><methodname><![CDATA[name]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[get]]></token><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[
]]><token><![CDATA[this]]></token><![CDATA[.]]><methodname><![CDATA[_name]]></methodname><![CDATA[;]]>
+<![CDATA[ }]]>
+<![CDATA[ ]]>
+<![CDATA[ ]]><token><![CDATA[set]]></token><![CDATA[
]]><token><![CDATA[construct]]></token><![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[
(]]><token><![CDATA[string]]></token><![CDATA[ ]]><methodname><![CDATA[name]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><methodname><![CDATA[Object]]></methodname><![CDATA[
(]]><methodname><![CDATA[name]]></methodname><![CDATA[:]]><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[
(]]><token><![CDATA[string]]></token><![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[ ]]><token><![CDATA[var]]></token><![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[ ]]><token><![CDATA[var]]></token><![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="highlight"
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[ ]]><token><![CDATA[signal]]></token><![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[ ]]><token><![CDATA[delegate]]></token><![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[
(]]><token><![CDATA[string]]></token><![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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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="highlight" linenumbering="numbered"
startinglinenumber="1"><token><![CDATA[interface]]></token><![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 using this
scope. </para>
+<para>For an overview of object oriented programming, see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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> inheritance-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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#Class_fields";>Classes/Class
fields</ulink>. For more explanation of static vs instance members, see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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="none">
+<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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Classes#Class_methods";>Classes/Class
methods</ulink>. For information about methods in general, see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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/Projects/Vala/Manual/Export/Projects/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><programlisting format="linespecific" language="highlight" linenumbering="numbered"
startinglinenumber="1"><lineannotation><![CDATA[/*]]></lineannotation>
+<lineannotation><![CDATA[ This example gives you a simple interface, Speaker, with]]></lineannotation>
+<lineannotation><![CDATA[ - one abstract method, speak]]></lineannotation>
+<lineannotation/>
+<lineannotation><![CDATA[ It shows you three classes to demonstrate how these and overriding them
behaves:]]></lineannotation>
+<lineannotation><![CDATA[ - Fox, implementing Speaker]]></lineannotation>
+<lineannotation><![CDATA[ - ArcticFox, extending Fox AND implementing Speaker]]></lineannotation>
+<lineannotation><![CDATA[ (ArcticFox.speak () replaces superclasses' .speak())]]></lineannotation>
+<lineannotation><![CDATA[ - RedFox, extending Fox BUT NOT implementing speaker]]></lineannotation>
+<lineannotation><![CDATA[ (RedFox.speak () does not replace superclasses' .speak())]]></lineannotation>
+<lineannotation/>
+<lineannotation><![CDATA[ Important notes:]]></lineannotation>
+<lineannotation><![CDATA[ - generally an object uses the most specific class's
implementation]]></lineannotation>
+<lineannotation><![CDATA[ - ArcticFox extends Fox (which implements Speaker) and implements Speaker
itself,]]></lineannotation>
+<lineannotation><![CDATA[ - ArcticFox defines speak () with new, so even casting to Fox or Speaker
still]]></lineannotation>
+<lineannotation><![CDATA[ gives you ArcticFox.speak ()]]></lineannotation>
+<lineannotation><![CDATA[ - RedFox extends from Fox, but DOES NOT implement Speaker]]></lineannotation>
+<lineannotation><![CDATA[ - RedFox speak () gives you RedFox.speak ()]]></lineannotation>
+<lineannotation><![CDATA[ - casting RedFox to Speaker or Fox gives you Fox.speak ()]]></lineannotation>
+<lineannotation><![CDATA[*/]]></lineannotation>
+
+<lineannotation><![CDATA[/* Speaker: extends from GObject */]]></lineannotation>
+<token><![CDATA[interface]]></token><![CDATA[ ]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><lineannotation><![CDATA[/* speak: abstract without a body */]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[abstract]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[speak]]></methodname><![CDATA[ ();]]>
+<![CDATA[}]]>
+
+<lineannotation><![CDATA[/* Fox: implements Speaker, implements speak () */]]></lineannotation>
+<token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[Fox]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[,
]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[speak]]></methodname><![CDATA[ () {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[ Fox says Ow-wow-wow-wow]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<lineannotation><![CDATA[/* ArcticFox: extends Fox; must also implement Speaker to
re-define]]></lineannotation>
+<lineannotation><![CDATA[ * inherited methods and use them as Speaker */]]></lineannotation>
+<token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[ArcticFox]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[,
]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><lineannotation><![CDATA[/* speak: uses 'new' to replace speak () from Fox
*/]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[new]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[speak]]></methodname><![CDATA[ () {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[ ArcticFox says
Hatee-hatee-hatee-ho!]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<lineannotation><![CDATA[/* RedFox: extends Fox, does not implement Speaker */]]></lineannotation>
+<token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[RedFox]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[new]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[speak]]></methodname><![CDATA[ () {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[ RedFox says Wa-pa-pa-pa-pa-pa-pow!]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[ () {]]>
+<![CDATA[ ]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[
]]><methodname><![CDATA[f]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[ ();]]>
+<![CDATA[ ]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[
]]><methodname><![CDATA[a]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[ArcticFox]]></methodname><![CDATA[ ();]]>
+<![CDATA[ ]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[
]]><methodname><![CDATA[r]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[RedFox]]></methodname><![CDATA[ ();]]>
+
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+
+]]><phrase><![CDATA[// Fox implements Speaker, speak ()]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Fox as Speaker:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[f]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Fox.speak () */]]></lineannotation>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+]]><phrase><![CDATA[Fox as Fox:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[f]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Fox.speak () */]]></lineannotation>
+
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+
+]]><phrase><![CDATA[// ArcticFox extends Fox, re-implements Speaker and
]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[ +]]>
+<![CDATA[ ]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[replaces speak
()]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[ArcticFox as Speaker:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[a]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* ArcticFox.speak () */]]></lineannotation>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+]]><phrase><![CDATA[ArcticFox as Fox:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[a]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* ArcticFox.speak () */]]></lineannotation>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+]]><phrase><![CDATA[ArcticFox as ArcticFox:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[a]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[ArcticFox]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* ArcticFox.speak () */]]></lineannotation>
+
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+
+]]><phrase><![CDATA[// RedFox extends Fox, DOES NOT re-implement Speaker
but]]></phrase><phrase><![CDATA["]]></phrase><![CDATA[ +]]>
+<![CDATA[ ]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[ does replace speak () for
itself]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[RedFox as Speaker:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[r]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Speaker]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Fox.speak () */]]></lineannotation>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+]]><phrase><![CDATA[RedFox as Fox:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[r]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Fox.speak () */]]></lineannotation>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+]]><phrase><![CDATA[RedFox as RedFox:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[r]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[RedFox]]></methodname><![CDATA[).]]><methodname><![CDATA[speak]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* RedFox.speak () */]]></lineannotation>
+
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[ 0;]]>
+<![CDATA[}]]>
+</programlisting>
+<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><programlisting format="linespecific"
language="highlight" linenumbering="numbered"
startinglinenumber="1"><lineannotation><![CDATA[/*]]></lineannotation>
+<lineannotation><![CDATA[ This example gives you a simple interface, Yelper, with]]></lineannotation>
+<lineannotation><![CDATA[ - one virtual default method, yelp]]></lineannotation>
+<lineannotation/>
+<lineannotation><![CDATA[ It shows you two classes to demonstrate how these and overriding them
behaves:]]></lineannotation>
+<lineannotation><![CDATA[ - Cat, implementing Yelper (inheriting yelp)]]></lineannotation>
+<lineannotation><![CDATA[ - Fox, implementing Yelper (overriding yelp)]]></lineannotation>
+<lineannotation/>
+<lineannotation><![CDATA[ Important notes:]]></lineannotation>
+<lineannotation><![CDATA[ - generally an object uses the most specific class's
implementation]]></lineannotation>
+<lineannotation><![CDATA[ - Yelper provides a default yelp (), but Fox overrides it]]></lineannotation>
+<lineannotation><![CDATA[ - Fox overriding yelp () means that even casting Fox to Yelper still
gives]]></lineannotation>
+<lineannotation><![CDATA[ you Fox.yelp ()]]></lineannotation>
+<lineannotation><![CDATA[ - as with the Speaker/speak() example, if a subclass wants to override
an]]></lineannotation>
+<lineannotation><![CDATA[ implementation (e.g. Fox.yelp ()) of a virtual interface
method]]></lineannotation>
+<lineannotation><![CDATA[ (e.g. Yelper.yelp ()), it must use 'new']]></lineannotation>
+<lineannotation><![CDATA[ - 'override' is used when overriding regular class virtual
methods,]]></lineannotation>
+<lineannotation><![CDATA[ but not when implementing interface virtual methods.]]></lineannotation>
+<lineannotation><![CDATA[*/]]></lineannotation>
+
+<token><![CDATA[interface]]></token><![CDATA[ ]]><methodname><![CDATA[Yelper]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><lineannotation><![CDATA[/* yelp: virtual, if we want to be able to override it
*/]]></lineannotation>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[virtual]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[ ]]><methodname><![CDATA[yelp]]></methodname><![CDATA[ () {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[ Yelper yelps Yelp!]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<lineannotation><![CDATA[/* Cat: implements Yelper, inherits virtual yelp () */]]></lineannotation>
+<token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[Cat]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[,
]]><methodname><![CDATA[Yelper]]></methodname><![CDATA[ {]]>
+<![CDATA[}]]>
+
+<lineannotation><![CDATA[/* Fox: implements Yelper, overrides virtual yelp () */]]></lineannotation>
+<token><![CDATA[class]]></token><![CDATA[ ]]><methodname><![CDATA[Fox]]></methodname><![CDATA[ :
]]><methodname><![CDATA[Object]]></methodname><![CDATA[,
]]><methodname><![CDATA[Yelper]]></methodname><![CDATA[ {]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[yelp]]></methodname><![CDATA[ () {]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[ Fox yelps
Ring-ding-ding-ding-dingeringeding!]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ }]]>
+<![CDATA[}]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[int]]></token><![CDATA[ ]]><methodname><![CDATA[main]]></methodname><![CDATA[ () {]]>
+<![CDATA[ ]]><methodname><![CDATA[Yelper]]></methodname><![CDATA[
]]><methodname><![CDATA[f]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[ ();]]>
+<![CDATA[ ]]><methodname><![CDATA[Yelper]]></methodname><![CDATA[
]]><methodname><![CDATA[c]]></methodname><![CDATA[ = ]]><token><![CDATA[new]]></token><![CDATA[
]]><methodname><![CDATA[Cat]]></methodname><![CDATA[ ();]]>
+
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[// Cat implements Yelper, inherits
yelp]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Cat as Yelper:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[c]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Yelper]]></methodname><![CDATA[).]]><methodname><![CDATA[yelp]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Yelper.yelp () */]]></lineannotation>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+]]><phrase><![CDATA[Cat as Cat:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[c]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Cat]]></methodname><![CDATA[).]]><methodname><![CDATA[yelp]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Yelper.yelp () */]]></lineannotation>
+
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+
+]]><phrase><![CDATA[// Fox implements Yelper, overrides yelp ()]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><phrase><![CDATA[Fox as Yelper:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[f]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Yelper]]></methodname><![CDATA[).]]><methodname><![CDATA[yelp]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Fox.yelp () */]]></lineannotation>
+<![CDATA[
]]><methodname><![CDATA[stdout]]></methodname><![CDATA[.]]><methodname><![CDATA[printf]]></methodname><![CDATA[
(]]><phrase><![CDATA["]]></phrase><![CDATA[
+]]><phrase><![CDATA[Fox as Fox:]]></phrase><![CDATA[
+]]><phrase><![CDATA["]]></phrase><![CDATA[);]]>
+<![CDATA[ (]]><methodname><![CDATA[f]]></methodname><![CDATA[ ]]><token><![CDATA[as]]></token><![CDATA[
]]><methodname><![CDATA[Fox]]></methodname><![CDATA[).]]><methodname><![CDATA[yelp]]></methodname><![CDATA[
(); ]]><lineannotation><![CDATA[/* Fox.yelp () */]]></lineannotation>
+
+<![CDATA[ ]]><token><![CDATA[return]]></token><![CDATA[ 0;]]>
+<![CDATA[}]]>
+</programlisting>
+</section>
+</section>
+<para>Back to <ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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 < Object > > ( ) ;</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><itemizedlist><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="linespecific" language="highlight"
linenumbering="numbered" startinglinenumber="1"><token><![CDATA[using]]></token><![CDATA[
]]><methodname><![CDATA[GLib]]></methodname><![CDATA[;]]>
+
+<token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[interface]]></token><![CDATA[
]]><methodname><![CDATA[With]]></methodname><![CDATA[ < ]]><methodname><![CDATA[T]]></methodname><![CDATA[ >
{]]>
+<![CDATA[ ]]><token><![CDATA[public]]></token><![CDATA[
]]><token><![CDATA[abstract]]></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[public]]></token><![CDATA[
]]><token><![CDATA[abstract]]></token><![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[ ]]><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[ ]]><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[ ]]><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[ ]]><token><![CDATA[public]]></token><![CDATA[ ]]><token><![CDATA[static]]></token><![CDATA[
]]><token><![CDATA[void]]></token><![CDATA[
]]><methodname><![CDATA[main]]></methodname><![CDATA[(]]><token><![CDATA[string]]></token><![CDATA[[]
]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><token><![CDATA[var]]></token><![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[ ]]><token><![CDATA[var]]></token><![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[
]]><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/Projects/Vala/Manual/Export/Projects/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="highlight" 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-name</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">(</emphasis> 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><itemizedlist><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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Methods#";>Methods</ulink>, See
<ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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">throws</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><programlisting format="linespecific" language="highlight"
linenumbering="numbered" startinglinenumber="1"><lineannotation><![CDATA[// ...]]></lineannotation>
+<lineannotation/>
+</programlisting>
+</section>
+</section>
+<para>Back to <ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/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 not 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 ]</para></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 static 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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Expressions#Flag_operations";>Expressions/Flag
operations</ulink>. For how to use attributes, see <ulink
url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Attributes#";>Attributes</ulink>.
</para>
+<para>Flag example follows: </para><programlisting format="linespecific" language="highlight"
linenumbering="numbered" startinglinenumber="1"><lineannotation><![CDATA[// ...]]></lineannotation>
+<lineannotation/>
+</programlisting>
+</section>
+
+<section>
+<title>Error domains</title>
+<para>Error 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/Projects/Vala/Manual/Export/Projects/Vala/Manual/Errors#";>Errors</ulink>. </para>
+</section>
+
+<section>
+<title>Examples</title>
+<para>Demonstrating... </para><programlisting format="linespecific" language="highlight"
linenumbering="numbered" startinglinenumber="1"><lineannotation><![CDATA[// ...]]></lineannotation>
+<lineannotation/>
+</programlisting>
+</section>
+</section>
+<para>Back to <ulink url="http://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual#";>Vala
Reference Manual</ulink> </para>
+
+<section>
+<title>Attributes</title>
+<para>Attributes are metadata information that is specified 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-connection 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="highlight"
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="highlight"
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></entry><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" namest="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 colsep="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 colsep="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 the position of the vfunc in the vtable. Once one ordering has been specified in a class, it
must be specified for all of the vfuncs.</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" 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 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" rowsep="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_name</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" rowsep="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 rowsep="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://wiki.gnome.org/Projects/Vala/Manual/Export/Projects/Vala/Manual/Types#Value_types";>Vala Manual -
Value Types</ulink> and <ulink url="http://wiki.gnome.org/Projects/Vala/Tutorial#Value_Types";>Vala Tutorial -
Value Types</ulink>. </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"><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>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>class, 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></entry></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">
+<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</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>
+<para><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</para></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><entry 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/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></entry><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 longer 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" rowsep="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/Projects/Vala/Manual/Export/Projects/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></listitem></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-expression:</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">false</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="highlight" 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[#]]><token><![CDATA[if]]></token><![CDATA[
]]><methodname><![CDATA[PREPROCESSOR_DEBUG]]></methodname>
+<![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[#]]><token><![CDATA[else]]></token>
+<![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[#]]><methodname><![CDATA[endif]]></methodname>
+<![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[
(]]><token><![CDATA[string]]></token><![CDATA[[] ]]><methodname><![CDATA[args]]></methodname><![CDATA[) {]]>
+<![CDATA[ ]]><token><![CDATA[var]]></token><![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>
+<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>
+</section>
+</section>
+<para>Back to <ulink url="http://wiki.gnome.org/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/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 the 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"><entry 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 hidden="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, length 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"><entry 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> <code>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" rowsep="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 colsep="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 array </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"><entry 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"><entry 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> <code>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 function 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 (except 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">
+<para> 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">
+<para> 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-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>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/Projects/Vala/Manual/Export/Projects/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="highlight" 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 select 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
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">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 hold 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="highlight" 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[ =
]]><token><![CDATA[false]]></token><![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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
