Valencia User Guide
Quick reference
Symbols
F12: Jump to definition
Alt+Left: Jump back
Alt+Right: Jump forward
Ctrl+F12: Jump to outer scope
Ctrl+Alt+S: Search for symbol
Autocomplete
Ctrl+Space: Autocomplete symbol
Building and running
Ctrl+Alt+B: Build project
Ctrl+Alt+R: Run project
Ctrl+Alt+C: Clean
Ctrl+Alt+N: Next compile error
Ctrl+Alt+P: Previous compile error
Jumping to symbols
To jump to the definition of any symbol in your project, place the cursor on the symbol name and choose Search -> Go to Definition or press F12. Valencia will jump to the position where the symbol is defined. Valencia can jump to variables, fields, methods, classes, interfaces and namespaces. Symbol jumping is context sensitive: if you place the cursor on the word bar in the expression foo.bar() and choose Go To Definition, Valencia will find the appropriate implementation of bar() for the object foo. After jumping to a symbol, you can browse backward and forward up to the most recent symbol to which you have jumped via the Search -> Go Back and Search -> Go Forward commands (Alt+Left and Alt+Right).
The first time you jump to a symbol definition in a large Vala project (such as the valac compiler sources), Valencia will display a progress dialog as it indexes Vala source files. All subsequent symbol jumps should be fast.
Valencia parses system vapi files such as glib.vapi and gtk.vapi, allowing you to jump to symbols defined in any vapi file defined in the default system directory.
When Valencia is enabled, the gedit status bar displays the class name containing the current cursor position. This can help you tell you what class you've ended up in after jumping to a symbol definition.
The Search -> Go to Outer Scope command (Ctrl+F12) jumps to the method containing the cursor position. If the cursor is not inside a method, this command jumps to the class containing the cursor position. So you can run this command once to jump to the enclosing method, and then again to jump to its enclosing class.
Valencia includes a symbol browser pane in the gedit sidebar. The symbol browser lists only symbols in your project. It looks within local namespaces to find all top-level symbols, and does not include symbols found within scopes other than namespaces (e.g. methods or fields found in classes). To see the symbol browser pane, choose View -> Side Pane, then click the magnifying class icon tab at the bottom of the sidebar. To search for a symbol, choose Search -> Find Symbol or press Ctrl+Alt+S to go to the search entry box, where you can type the name of the symbol which you want to find.
Tooltips and Autocomplete
Both tooltips and autocomplete use the same menu item (Search -> AutoComplete) and shortcut key (Ctrl+Space). These features are context-sensitive and must be invoked manually to be used. You can cancel a tooltip or autocomplete dialog any time by pressing escape when it is on the screen. When trying to invoke autocomplete, sometimes the cursor may be in the context to get a tooltip. Simply invoke autocomplete again and a list will appear.
To see a tooltip for any method within the project, place the cursor anywhere within a method call after the opening parenthesis, and invoke autocomplete. To get an autocompletion list for an incomplete symbol, invoke autocomplete when the cursor is at the end of the symbol. If the cursor is inside a symbol, it will attempt to get an autocompletion list for the partial symbol before the cursor. Invoking autocomplete at an empty space will bring up a list of all members of the global and using namespaces. You can scroll through the list with the up and down arrows, browse by pages with pageup and pagedown, and skip to the beginning and end of the list with the home and end keys, respectively.
Building your project
To build your project, choose Project -> Build or press Ctrl+Alt+B. The build will occur in your project's root directory (see The project root below). Valencia runs make to perform the build; you must provide a Makefile that invokes valac on your source files. (You can write a Makefile by hand, or can generate one using a tool such as automake). The build output will appear in a pane at the bottom of the gedit window. You can double-click on any build error to jump to the source line where it occurred. You can also use the Search ? Next Error and Search ? Previous Error commands (Ctrl+Alt+N and Ctrl+Alt+P) to move between build errors.
If you do not use make, or want to specify command line options (e.g. make -j2), you can tell Valencia a new command to use. Either choose Project -> Settings or press Ctrl+Alt+T to go to the settings dialog, where you can specify your own custom build command.
You can also clean the project's build output by choosing Project -> Clean or pressing Ctrl+Alt+C. Valencia by default runs make clean, but if you do not use make, or would rather run a different command (e.g. rm *.o *.so), you can also specify a custom clean command to use in the settings dialog, just like with the build command.
Running your program
After you've built your project, you can launch the generated program from within gedit. To do this, you must add a variable definition PROGRAM=name to your Makefile, where name is the name of the program generated by your Makefile. To run your program, choose Project -> Run or type Ctrl+Alt+R. Valencia will launch your program and display its output in a pane in the gedit window.
The Project -> Run command is somewhat limited: it does not work for Autotools-based projects and it's not currently possible to specify arguments to be passed when running your program.
The project root
In Valencia, a project consists of a set of Vala files, plus an optional Makefile used for building.
If all of your Vala source files are in a single directory, you don't need to specify a project root in any way. By default, when you open any source file, Valencia will let you browse to symbols in all other source files in the same directory.
If your project spans multiple directories, your project's root directory must contain either of the following:
a Makefile containing the definition BUILD_ROOT=1
a file named configure.ac or configure.in
When you open any source file below the root directory, Valencia will find the project root and will consider the project to include all Vala (and .vapi) source files below the root.