Navigating in source code

In the previous section, we have discussed exploring source code, i.e. getting information about symbols, files and projects. The next step is then to jump around your source base, i.e. to navigate in it. There are again various levels at which this is possible: local, within a file, and within a project.

Note

Many of the ways to navigate through code are accessible from the Navigate menu in the KDevelop main window.

Local navigation

KDevelop is much more than an editor, but it is also a source editor. As such, you can of course move the cursor up, down, left or right in a source file. You can also use the PageUp and PageDown keys, and all the other commands you are used from any useful editor.

File scope navigation and outline mode

At the file scope, KDevelop offers many possible ways to navigate through source code. For example:

  • Outline: You can get an outline of what's in the current file in at least three different ways:

    • Clicking into the Outline textbox at the top right of the main window, or hitting Alt+Ctrl+N opens a drop-down menu that lists all function and class declarations:

      You can then just select which one to jump to, or — if there are a lot — start typing any text that may appear in the names shown; in that case, as you keep typing, the list becomes smaller and smaller as names are removed that don't match the text already typed until you are ready to select one of the choices.

    • Positioning the cursor at file scope (i.e. outside any function or class declarations or definitions) and having the Code Browser tool open:

      This also provides you an outline of what is happening in the current file, and allows you to select where you want to jump to.

    • Hovering the mouse over the tab for one of the open files also yields an outline of the file in that tab.

  • Source files are organized as a list of function declarations or definitions. Hitting Alt+Ctrl+PgUp and Alt+Ctrl+PgDown jumps to the previous or next function definition in this file.

Project and session scope navigation: Semantic navigation

As mentioned in other places, KDevelop does not usually consider individual source files but rather looks at projects as a whole (or, rather, at all projects that are part of the current session). As a consequence, it offers many possibilities for navigating through entire projects. Some of these are derived from what we have already discussed in the section on Exploring source code while others are genuinely different. The common theme is that these navigation features are based on a semantic understanding of the code, i.e. they offer you something that requires parsing entire projects and connecting data. The following list shows some ways how to navigate through source code that is scattered throughout a potentially very large number of files:

  • As seen in the section on Exploring source code, you can get a tooltip explaining individual namespace, class, function or variable names by hovering your mouse over it or keeping the Alt key pressed for a while. Here is an example:

    Clicking on the links for the declaration of a symbol or expanding the list of uses allows you to jump to these locations, if necessary opening the respective file and placing the cursor at the corresponding location. A similar effect can be achieved by using the Code Browser tool view also discussed previously.

  • A quicker way to jump to the declaration of a symbol without having to click on the links in the tooltip is to temporary enabling Source Browse Mode by holding down the Alt or Ctrl key. In this mode, it is possible to directly click on any symbol in the editor to jump to its declaration.

  • Quick open: A very powerful way of jumping to other files or locations is to use the various quick open methods in KDevelop. There are four versions of these:

    • Quick open class (NavigateQuick open class or Alt+Ctrl+C): You will get a list of all classes in this session. Start typing (a part of) the name of a class and the list will continue to whittle down to only those that actually match what you've typed so far. If the list is short enough, select an element using the up and down keys and KDevelop will get you to the place where the class is declared.

    • Quick open function (NavigateQuick open function or Alt+Ctrl+M): You will get a list of all (member) functions that are part of the projects in the current session, and you can select from it in the same way as above. Note that this list may include both function declarations and definitions.

    • Quick open file (NavigateQuick open file or Alt+Ctrl+O): You will get a list of all files that are part of the projects in the current session, and you can select from it in the same way as above.

    • Universal quick open (NavigateQuick open or Alt+Ctrl+Q): If you forget which key combination is bound to which of the above commands, this is the universal swiss army knife — it simply presents you with a combined list of all files, functions, classes, and other things from which you can select.

  • Jump to declaration/definition: When implementing a (member) function, one often needs to switch back to the point where a function is declared, for example to keep the list of function arguments synchronised between declaration and definition, or to update the documentation. To do so, place the cursor onto the function name and select NavigationJump to declaration (or hit Ctrl+.) to get to the place where the function is declared. There are multiple ways to get back to the original place:

    • Selecting NavigationJump to definition (or hitting Ctrl+,).

    • Selecting NavigationPrevious visited context (or hit Meta+Left), as described below.

Note

Jumping to the declaration of a symbol is something that does not only work when placing the cursor on the name of the function you are currently implementing. Rather, it also works for other symbols: Putting the cursor on a (local, global, or member) variable and jumping to its declaration also transports you to its location of declaration. Similarly, you can place the cursor on the name of a class, for example in a variable of function declaration, and jump to the location of its declaration.

  • Switch between declaration/definition: In the example above, to jump to the site of the declaration of the current function, you need to first place the cursor on the function name. To avoid this step, you can select NavigationSwitch definition/declaration (or hit Shift+Ctrl+C) to jump to the declaration of the function within which the cursor currently is. Selecting the same menu entry a second time transports you back to the place where the function is defined.

  • Previous/Next use: Placing the cursor on the name of a local variable and selecting NavigationNext use (or hitting Meta+Shift+Right) transports you to the next use of this variable in the code. (Note that this doesn't just search for the next occurrence of the variable name but in fact takes into account that variables with the same name but in different scopes are different.) The same works for the use of function names. Selecting NavigationPrevious use (or hitting Meta+Shift+Left) transports you to the previous use of a symbol.

Note

To see the list of all uses of a name through which these commands cycle, place the cursor onto it and open the Code Browser tool view or press and hold the Alt button. This is explained in more detail in the section on Exploring code.

  • The context list: Web browsers have this feature where you can go backward and forward in the list of most recently visited web pages. KDevelop has the same kind of features, except that instead of web pages you visit contexts. A context is the current location of the cursor, and you change it by navigating away from it using anything but cursor commands — for example, by clicking on a location provided by a tooltip, in the Code Browser tool view, one of the options given in the Navigation menu, or any other navigation command. Using the NavigationPrevious Visited Context (Meta+Left) and NavigationNext Visited Context (Meta+Right) transports you along this list of visited contexts just like the back and forward buttons of a browser transports you to the previous or next webpage in the list of visited pages.

  • Finally, there are tool views that allow you to navigate to different places in your code base. For example, the Classes tool provides you with a list of all namespaces and classes in all projects of the current session, and allows you to expand it to see member functions and variables of each of these classes:

    Double-clicking on an item (or going through the context menu using the right mouse button) allows you to jump to the location of the declaration of the item. Other tools allow similar things; for example, the Projects tool view provides a list of files that are part of a session:

    Again, double-clicking on a file opens it.