From 55d1c2ac5fcc9aa6f478f5859ad1f92ee9678c41 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Thu, 19 Nov 2020 14:35:23 +0100 Subject: manual: Update from wiki.gnome.org --- doc/manual/manual.xml | 88 +++++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 44 deletions(-) (limited to 'doc') diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 727dbcdbc..c8a1a7cd8 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -13,7 +13,7 @@
Getting started -The classic "Hello, world" example in Vala: +The classic "Hello, world" example in Vala: @@ -33,7 +33,7 @@ optional-section: literalstring3 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 literalstrings here are not rules, and thus cannot be expanded. -Example code is shown as follows. Example code will always be valid Vala code, but will not necessarily be usable out of context. +Example code is shown as follows. Example code will always be valid Vala code, but will not necessarily be usable out of context. @@ -93,7 +93,7 @@
Application entry point -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: +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: @@ -116,11 +116,11 @@
Variables -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: +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: 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 assignment 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. 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 unowned keyword. See Types/Reference types. -If a type is directly instantiated in a variable declaration statement, then the variable will be created owning that new instance, for example: +If a type is directly instantiated in a variable declaration statement, then the variable will be created owning that new instance, for example: 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. For more details of the concepts in this section, see Statements/Variable declaration and Expressions/Assignment operations. @@ -145,7 +145,7 @@
Scope and naming -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: +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: @@ -175,7 +175,7 @@ Object oriented programming 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. 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 Classes. -Vala provides inheritance functionality to any type of class (see Classes/Types of class). Given the following definition, every SubType instance is-a SuperType instance: +Vala provides inheritance functionality to any type of class (see Classes/Types of class). Given the following definition, every SubType instance is-a SuperType instance: @@ -184,7 +184,7 @@ Whenever a SuperType instance is required, a SubType instance may be used. This is the extent of inheritance 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. -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: +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: @@ -536,10 +536,10 @@ prefix-expression: ++ unary-expression -- unary-expression -Postfix and prefix expressions: +Postfix and prefix expressions: -are equivalent to: +are equivalent to: @@ -600,11 +600,11 @@ conditional-expression ^= expression conditional-expression <<= expression conditional-expression >>= expression -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: +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: -Are equivalent to simple assignments: +Are equivalent to simple assignments: @@ -940,10 +940,10 @@ Namespaces Namespaces are named scopes (see Concepts/Scope and naming). 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. 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. -The simplest namespace declaration looks like this: +The simplest namespace declaration looks like this: -Namespace nesting is achieved either by nesting the declarations, or by providing multiple names in one declaration: +Namespace nesting is achieved either by nesting the declarations, or by providing multiple names in one declaration: @@ -1018,7 +1018,7 @@ namespace-list: qualified-namespace-name [ , namespace-list ] There can be any number of using statements in a Vala source file, but they must all appear outside any other declarations. Note that using 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. -Most code depends on members of the GLib namespace, and so many source files begin with: +Most code depends on members of the GLib namespace, and so many source files begin with: TODO: Include examples.
@@ -1085,7 +1085,7 @@ ( [ lambda-params-list ] ) => { statement-list } lambda-params-list: identifier [ , lambda-params-list ] -An example of lambda use: +An example of lambda use: @@ -1102,7 +1102,7 @@
Contract programming -Vala supports basic contract programming features. A method may have preconditions (requires) and postconditions (ensures) that must be fulfilled at the beginning or the end of a method respectively: +Vala supports basic contract programming features. A method may have preconditions (requires) and postconditions (ensures) that must be fulfilled at the beginning or the end of a method respectively: 0 && ]]> = 0.0 && ]]> = 0.0 && ]]> @@ -1110,14 +1110,14 @@ result is a special variable representing the return value. -For example, if you call method_name with arguments 5 and 3.0, it will output a CRITICAL message and return 0. +For example, if you call method_name with arguments 5 and 3.0, it will output a CRITICAL message and return 0. Output: = 0.0 && d <= 1.0' failed 0]]> -Vala allows you to manage the safety of issued messages at 6 levels: ERROR, CRITICAL, INFO, DEBUG, WARNING, MESSAGE. For example, the following code will cause a runtime error. +Vala allows you to manage the safety of issued messages at 6 levels: ERROR, CRITICAL, INFO, DEBUG, WARNING, MESSAGE. For example, the following code will cause a runtime error. @@ -1162,7 +1162,7 @@
Examples -Defining delegates: +Defining delegates: @@ -1171,7 +1171,7 @@ -Invoking delegates, and passing as parameters. Invoking delegates, and passing as parameters. @@ -1180,7 +1180,7 @@ -Instance delegates: +Instance delegates: -With Lambda: { ]]>With Lambda: { ]]>
@@ -1253,7 +1253,7 @@
Examples -Demonstrating... +Demonstrating... @@ -1292,7 +1292,7 @@
Classes 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. -The simplest class declaration looks like this: +The simplest class declaration looks like this: 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.... @@ -1319,7 +1319,7 @@
Class scope 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. -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 this scope can be used, for example: +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 this scope can be used, for example: @@ -1405,7 +1405,7 @@
Controlling instantiation -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: +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: @@ -1612,7 +1612,7 @@
Examples -Demonstrating... +Demonstrating... @@ -1621,7 +1621,7 @@ For more examples see: Samples for Class Properties
-Virtual Properties +Virtual Properties @@ -1680,7 +1680,7 @@
-Abstract Properties +Abstract Properties @@ -1732,7 +1732,7 @@
-Using signals +Using signals @@ -1762,7 +1762,7 @@
Interfaces 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 Classes/Types of class.) -The simplest interface declaration looks like this: +The simplest interface declaration looks like this: 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 inheritance 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. @@ -1845,7 +1845,7 @@
Examples -Here is an example implementing (and overriding) an abstract interface method, +Here is an example implementing (and overriding) an abstract interface method, @@ -1952,7 +1952,7 @@ -Here is an example of implementing (and inheriting) a virtual interface method. Note that the same rules for subclasses re-implementing methods that apply to the abstract interface method above apply here. +Here is an example of implementing (and inheriting) a virtual interface method. Note that the same rules for subclasses re-implementing methods that apply to the abstract interface method above apply here. @@ -2072,7 +2072,7 @@
Examples -Demonstrating... +Demonstrating... {]]> @@ -2130,7 +2130,7 @@
Structs A struct is a data type that can contain fields, constants, and methods. -The simplest struct declaration looks like this: +The simplest struct declaration looks like this: @@ -2192,7 +2192,7 @@
Examples -Demonstrating... +Demonstrating...
@@ -2239,7 +2239,7 @@
Flag types 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 Expressions/Flag operations. For how to use attributes, see Attributes. -For example, say we want to draw the borders of a table cell: +For example, say we want to draw the borders of a table cell: @@ -2268,7 +2268,7 @@
Examples -Demonstrating... +Demonstrating...
@@ -2288,10 +2288,10 @@
Applying attributes -They are written as: +They are written as: -For example: +For example:
@@ -2831,7 +2831,7 @@ Examples How to conditionally compile code based on a valac option -D. Sample code: -vala-test:examples/advanced.vala +vala-test:examples/advanced.vala @@ -3204,7 +3204,7 @@ $ ./preprocessor-debug]]>
Comments -Comments in the metadata have the same syntax as in Vala code: +Comments in the metadata have the same syntax as in Vala code: @@ -3377,7 +3377,7 @@ $ ./preprocessor-debug]]> Overriding Types When you have the following expression: where GList will hold integers, use type metadata as follows: "]]> -The above metadata will generate the following code: {]]> +The above metadata will generate the following code: {]]> -- cgit v1.2.1