Bookmarks have been in GPS for a very long time (first added in 2005). They help you mark places in your source code that you want to easily go back to, even when the code changes.

The description in this blog only apply to very recent development versions of GPS. For our customers, you can immediately request a wavefront (nightly build of GPS) if you want to try them out. For users of the public versions, they will be part of the next GPL 2017 release , so you will have to wait a bit :-)

Basic usage

The basic usage of bookmarks is as follows: you open a source editor and navigate to the line of interest. You can then create a new bookmark by either using the menu /Edit/Create Bookmark or by opening the Bookmarks view (/Tools/Views/Bookmarks) and then clicking on the [+] button in the local toolbar. In both cases, the Bookmarks view is opened, a new bookmark is created and selected so that you can immediately change its name.

The default name of bookmark is the name of the enclosing subprogram and the initial location of the bookmark (file:line). But you can start typing a new name, and press Enter to finally create the bookmark.

In practice, this is really just a few clicks (one of the menu and press Enter to use the new name), or even just two key strokes if you have set a keyboard shortcut for the menu, via the Preferences dialog.

At any point in time, you can rename an existing bookmark by either clicking on the button in the local toolbar, or simply with a long press on the bookmark itself.

Note the goto icon on the left of the editor line 1646, which indicates there is a bookmark there, as well as the colored mark in the editor scrollbar that helps navigate in the file.

Even though the default name of the bookmark includes a file location, the major benefit of the bookmarks is that they will remain at the same location as the text is edited. In our example, if we add a new subprogram before Display_Splash_Screen, the bookmark will still point at the line containing the call to Gtk_New, even though that line might now be 1700 for instance.

Of course, GPS is not able to monitor changes that you might do through other editors, so in this case the marks might be altered and stop pointing to the expected location.

Adding more bookmarks

We can create any number of bookmarks, and these have limited impact on performance. So let's do that and create a few more bookmarks, in various files. As you can see in the scrollbar of the editor, we have two bookmarks set in the file bookmark_views.adb, and we can easily jump to them by clicking on the color mark.

But of course, it is much simpler to double-click inside the Bookmarks view itself, on the bookmark of interest to us.

At this point, we have a rather long unorganized list of bookmarks, and it is becoming harder to find them. This is basically what has been available in GPS since 2005, and that doesn't help keeping things organized. So we have recently done a number of improvements that get us far beyond this basic usage.

Organizing bookmarks into groups

When we create new bookmarks, GPS adds them at the top of the list. We might want to organize them differently, which we can do simply with a drag and drop operation: select the bookmark, keep the mouse pressed, and move it to a better place in the list.

Things become more interesting when you drop a bookmark on top of another one. In this case, GPS creates a group that contains the two bookmarks (and that basically behaves like a folder for files). The group is immediately selected so that you can rename it as you see fit.

In our example, we created two groups, corresponding to two features we are working on.

Groups can be nested to any depth, providing great flexibility. So let's create two nested groups, which we'll name TODO, beneath the two we have created. This is a great way to create a short todo list: one top-level group for the name of the feature, then below one group for the todo list, and a few additional bookmarks to relevant places in the code.

To create these additional groups, we will select the Source editor group, then click on the Create New Group button in the local toolbar, and type "TODO<enter>". This will automatically add the new group beneath Source editor. Let's do the same for the Bookmarks groups. These two groups are empty for now.

Let's add new entries to them. if we already know where code should be added to implement the new todo item, we can do as before: open the editor, select the line, then click on the [+] button. Most often, though, we don't yet know where the implementation will go.

So we want to create an unattached bookmark. Using the name bookmark here is really an abuse of language, since these have no associated source location. But since they are visible in the Bookmarks view, it is convenient to name them bookmarks.

To create them, let's select one of the TODO groups, then select the Create Unattached Bookmark in the local toolbar, and immediately start typing a brief description of the todo. As you can see in the screenshot, these bookmarks do not have a goto icon, since you cannot double click on them to jump to a source location.

When you delete a group, all bookmarks within are also deleted. So once you are done implementing a feature, simply delete the corresponding group to clean up the bookmarks view.

Adding notes

The short name we gave the bookmark is not enough to list all the great ideas we might have for it. Fortunately, we can now add notes to bookmarks, as a way to store more information.

Let's select the "write a blog post" item, then click on the Edit Note button in the local toolbar. This opens a small dialog with a large text area where we can type anything we want. Press Apply to save the text.

Note how a new tag icon was added next to the bookmark, to indicate it has more information. You can view this information in one of three ways:

• select the bookmark, and click again on the Edit Note button as before
• double-click on the tag icon.
• leave the mouse hover the bookmark line. This will display a tooltip with extra information on the bookmark: its name, its current location and any note it might have. This is useful if you only want to quickly glance at the notes for one or more bookmarks

Add note with drag and drop

Sometimes, though, you want to associate code with the note (i.e. the bookmark should not only point to a location, but you also want to remember the code that was in that location). The simplest to do this is to select the text in the editor, and then drag and drop the selected text directly onto the bookmark. This will create a note (if needed) or add to the existing note the full selected text.

In the tooltips, we use a non-proportional font, so that the code is properly rendered and alignment preserved.

Filtering bookmarks

If you start creating a lot of bookmarks, and even if you have properly organized them into groups, it might become difficult to find them later on. So we added a standard filter in the local toolbar, like was done already for a lot of other views. As soon as you start typing text in that filter, only the bookmarks that match (name, location or note) are left visible, and all the others are hidden.

Favorite files

GPS provides a large number of ways to navigate your code, and in particular to open source files. The most efficient one is likely the omni-search (the search field at the top-right corner).

But some users like to have a short list of favorite files that they go to frequently. The Bookmarks view can be used to implement this.

Simply create a new group (here named Favorite files), and create one new bookmark in this group for each file you are interested in. I like to create the bookmark on line 1, but I always remove the line number indication in the name of the bookmark since the exact line is irrelevant here.

Conclusion

The flexibility of the Bookmarks view has been greatly enhanced recently, providing much needed features such as groups of bookmarks, notes, todo items, enhanced tooltips, drag-and-drop operations, ...

We have described two use cases in this post (bookmarks as todo lists and bookmarks for favorite files), but I am sure there are other ways that bookmarks can be used. I would be curious to hear your own ideas in the comments...