Zwabel’s Weblog

December 10, 2008

Code-Navigation in KDevelop4: Meet the Magic Modifier!

Today I’m going to blog about the various duchain based navigation and browsing features available in KDevelop4. So let’s start right from the beginning. Consider you have just opened your project. Where to start? Graphically browsing project-trees is ok to get an overview, but it’s horribly inefficient if you need to do it to reach a place you know.

Quick Open
The Quick Open feature is the answer to that problem. KDevelop3 already had it, and IMO it was one of it’s most productivity-boosting features. Strangely it was/is not very well known among the users I talked to.

In short, the Quick Open feature is a simple list of all files, classes, and/or functions within your whole project. By typing into a line-edit you can filter that list.

I have re-implemented Quick Open for KDevelop4 in a much more flexible way, with several different data providers, probably similar to plasmas runner design. The data-providers are split up by “Scopes” and “Items”, allowing everything to be shown within the same list, or showing only specific parts. For the feature to work best, full-project parsing should be enabled, so classes/functions from within all open projects can be listed. Here you see it in action:
Quick Open

So now you’ve got a way to jump into arbitrary locations and get going. But what if you don’t want jump to an arbitrary location, but rather one in the same file? For this, there is an additional “Outline Quick Open”, based on the same framework, but only showing interesting items in the current file. The list can be filtered as well, but as additional gimmick the function/class you’re currently in is always pre-selected, which means you can comfortably use it repeatedly jump from one neighbour function to the next.

Local Navigation
When the duchain is working correctly, and the uses are built, nearly every symbol in a source-file is referencing a declaration in another place. That information is not only used for the highlighting, which will be the subject of another blog post, but also for direct navigation. Pushing CTRL+’.’ or CTRL+’,’ allows jumping directly to that declaration respectively definition.

One of the most useful local navigation features though is the following one. As you see in the following screenshot, all uses of the declaration under the cursor are automatically highlighted in yellow.
Since these highlighted uses are real “spots of interest”, it makes quite sense that the user might want to jump directly to one of them. So the shortcuts “Next Use” and “Previous Use” allow you directly cycling through them, jumping from one to the next, even across file boundaries. In my experience, since often your current interest is bound to a specific variable or function, this allows you getting where you want a lot faster.

The switch declaration/definition shortcut which allows jumping directly from within a definition to the related declaration and back, perfectly complements the team.

Navigation History
When it’s easy to jump to a random location, it should also be easy to get back. The code-browser implements an intelligent editor navigation history, that only inserts one history-entry for each function/class you’ve visited. Thanks to this, every really interesting place is in the history once, without too many useless jumps in between.

The Code Browser
In my opinion a really good C++ IDE should make a tool like Doxygen unnecessary. The IDE should know all the relevant information, it can update it dynamically, and it can present it to the user precisely where needed. That’s why I implemented the so called navigation-widget right when I started working on KDevelop4 C++ code completion. It is a html text-view containing some nicely formatted text, similar to the output of doxygen. The widget matured together with the duchain, being able to show more and more useful information with time, and at some point it was far enough to be really useful. In the end it found its permanent home in the Code Browser, visible at bottom in the following screenshot:
Code Browser
Listing all the information this widget shows would not fit into this blog post. It really shows nearly anything interesting about the shown item, and especially it allows jumping to related items from return-types, template-parameters, inheriters, base-classes, overriders, it allows showing the preprocessed text of macro invocations, showing all declarations from include files, jumping to direct source-locations, searching uses, and so on. When full-project parsing is enabled, this mostly surpasses the quality of what doxygen shows, since it can deal with C++ specifics like templates or macros really well.

The Code Browser always shows informations about the item currently under the mouse- or text-cursor in the document, unless the little lock at the top right is activated, which preserves the view.

Since a real developer hates using the mouse when in hacking mode, the navigation widget is completely keyboard accessible.

The Magic Modifier
Now thanks to the navigation widget, we do have a lot of keyboard-accessible information to show. Wouldn’t it be great if exactly that information was available from everywhere, with a consistent accessibility scheme? This is where the Magic Modifier(A marketing-name invented by me 😉 ) comes into play. The Magic Modifier allows you peeking from the sketchy code-realm into the semantic one, seeing the connections behind the code. Currently it is hard-coded to the “ALT” key, so that’s actually all you need to remember. This is how it works:
– By pressing the ALT key, you will in some way get presented a navigation-widget. While you keep it pressed, you can navigate within it using the arrow-keys and the enter-key. Once you release ALT again, it will again disappear, unless you push and release it really fast, which equals a “toggle”.
Completion Expanded
On this screenshot you see how the first item in the completion-list was expanded because ALT is pressed. The same thing is possible within all quickopen lists. This also works directly within the editor. When the code-browser is visible, you can always navigate within it using ALT+Arrows. When the code-browser is not visible and ALT is pressed, the following keyboard-accessible tooltip is popped up, and disappears once ALT is released again.

So thanks to the Magic Modifier, you’re always just a single keypress away from the semantic information behind your code.

Html-Like Browsing
Sometimes when not in hacking-mode, it is comfortable to browse through the code comfortably without any keyboard-interaction. One way to achieve this is by using the new navigation tooltip I have added the last days, or the code-browser, by first pointing at the interesting item. However due to the duchain structure, the complete document could be interpreted as a single hyperlinked document, where each use is a link to its declaration.

While pressing either CTRL or the Magic Modifier, you can click onto uses directly in the document, and it will bring you directly to the used declaration. The mouse-cursor will change to a hyperlink-style pointing hand when this is possible. For even more comfort without any keyboard interaction, it’s possible to go into a permanent “browsing” state, by clicking the little green lamp toolbutton in the code browser.

So now you have a lot of navigation tools at hand, which all together allow really efficient working and browsing. I recomment every KDevelop user to memorize all of them, so you have the right tool at Hand in the right moment.

Development Status
In the last weeks I’ve once again spent quite some time on the duchain backend. Parsing and especially update-checking is a lot more efficient now, somewhat less disk-space is consumed, several consistency and crash problems have been fixed.

Also tons of bugs in code-completion and general C++ support were fixed, the shown items in the completion-list are now intelligently shortened when they are too long by leaving away template-parameters. The completion-list in general looks better now with less colors and lighter icons, I’ve implemented the consistent “Magic Modifier” navigation, and tons of other stuff that I don’t remember.

Just by the way if you’re wondering why my development speed is so fast at the moment: Soon I will begin working on my Diploma Thesis, which will leave a lot less time for KDevelop. I will be working on a C++ project though, and of course I will be using KDevelop4, which 1. means that I will definitely not lose KDevelop out of focus, and which 2. means that I want KDevelop to be in a good state until then.

What makes me a bit sad is that the rest of KDevelop is not really taking off. Debugger, project-management, documentation-integration, etc. all still need quite some work before a 4.0 release. One interesting thing is that Aleix Pol Gonzales has been improving the cmake duchain support, which means that many of the described features will also be available while working on cmake files at some point.


  1. This looks absolutely stunning. David, fantastic work!

    I really wish more developers would become interested in developing for KDevelop. Hopefully things will pick up when KDevelop 4.0 is released and developers realise just how much easier, faster and more convenient it is to develop s/w with a good IDE as opposed to a good text editor (I speak from experience having migrated somewhat grudgingly from Vim to Eclipse for Java development).

    Comment by KDevFan — December 10, 2008 @ 12:58 pm

  2. Wow, this is absolutely amazing. Great work, David! I’m really looking forward to the Kdevelop4 release 🙂

    Comment by Thorben — December 10, 2008 @ 2:44 pm

  3. David,

    I use kdev4 almost daily now and its really hard to now code without it. kdevelop knows more about my code than i do and code completion almost requires no configuration to get it working! Actually, i think that is “zero” configuration.

    Unfortunately, i still use kdevelop3 bu then i limit its use to setting and breakpoints and stepping. I do my editing in kdev4. I think kdevelop 4 is a completely new IDE and its wonderful and can be put into beta release mode if not for the debugger.. 😦

    Other features can follow post the first 4.0 release but a debugger is a must i think.

    Thanks for your amazing work!

    Comment by Kishore — December 10, 2008 @ 3:54 pm

  4. I use it for all my C / C++ school projects now, but it’s been crashing on me and I’m hopelessly out of free hacking time for the next two months or so … I use Kate for bulk editing and KDevelop for browsing and quickly grokking code.
    One gripe I have with KDevelop is that it ‘stutters’ when I type. I haven’t looked at how is KDevelop written, but you might want to use a ternary search tree structure for looking up symbols… that is, if it isn’t there yet 🙂

    Comment by Peterix — December 10, 2008 @ 5:47 pm

  5. @Peterix: I don’t know what you’re meaning with that “ternary” stuff, but symbol lookup for sure isn’t the reason for the stuttering. It’s more probably the editor, or some other component in the duchain that hits some scalability limit. This just needs some more profiling.

    About the crashes, you should a) update, because some crashes were fixed, and b) if you encounter crashes, send backtraces to us.

    Comment by David Nolden — December 10, 2008 @ 6:52 pm

  6. Hi,
    this looks so great, thank you ! However, I would love to have a very simple shortcut to set a temporary bookmark. I explains :
    – I’m typing some code in a file.
    – I hit a keyboard shortcut that set a temporary special bookmark (line, cursor position)
    – I can then scroll in the file or in another file (in order to look at some other code, etc.)
    -When I hit the shortcut again, I get back to my previous bookmark and it is deleted

    Comment by DanaKil — December 10, 2008 @ 8:30 pm

  7. @DanaKil: I think the default bookmark toggle button is CTRL+B, and I have assigned the buttons Meta+Up and Meta+Down to jump to the previous/next bookmark. I think this is enough to achieve what you want! You just push CTRL+B to set the bookmark, edit something else, jump back to the bookmark using the other shortcuts, and remove it again using CTRL+B.

    If you want it all automatic, you can use the navigation history.

    Comment by David Nolden — December 10, 2008 @ 8:59 pm

  8. The Quick-Open dialog somehow reminds me of KDevelop3’s flat class view, where I sometimes missed the ability to filter the classes based upon some pattern. Damn, if I’d had some spare time I’d go right ahead and implement such a class view for KDevelop4. The necessary infrastructure seems to be all there…

    Comment by Bernhard — December 10, 2008 @ 9:10 pm

  9. Can’t code without QuickOpen anymore 😀

    And really useful to have all documentation inside the editor!
    What is missing though are Qt-Docs. It would be great if KDev would parse the qt docs in some way to show them in the NavigationWidget. (Additional to an integrated Assistant)


    Comment by niko — December 11, 2008 @ 7:02 am

  10. @Niko: That’s what we need to documentation integration for. It should be integrated with the navigation widget, so it could also show the classic documentation. Then we don’t need to parse anything. 🙂

    Comment by zwabel — December 11, 2008 @ 11:27 am

  11. Great work!

    A quick comment about the quick open dialog. I think it would make sense to place the “Search”, “Scopes” and “Items” widgets all together, as they are all just ways of filtering the list. I’m not sure if it’d be better to place them all at the top or all at the bottom, but placing the results in the middle seems a bit awkward.

    Comment by Parker Coates — December 11, 2008 @ 4:28 pm

  12. @Parker Coates: It’s a question of priority. At the top you do the typing, and at the top you have the items in the list. That’s the important stuff, and it should stay together(nothing between these two).

    Those “scopes” and “items” usually are usually pre-set depending on the shortcut you use, and remembered from what you used before, and you will only seldomly change them. Thus they’re at the bottom, waiting for the rare occasion of being used.

    Comment by zwabel — December 11, 2008 @ 5:04 pm

  13. Can I turn it off?

    I mean, OK, maybe I’m just a curmudgeon, but having all this random tooltip crap pop up when I mouseover any semantic element in my code, quite frankly, just annoys me 😉 Semantic highlight already highjacked my colors and I had to slap it around, and now semantic popup-on-mouseover and highlight-all-instances are in completely the wrong color and obnoxious.

    can it be disabled?

    Comment by a — April 28, 2010 @ 5:41 am

  14. @a: If you don’t like any of the features, then you’re simply using the wrong IDE.

    Comment by zwabel — May 2, 2010 @ 12:34 pm

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a free website or blog at

%d bloggers like this: