Date: 2 MAR 2012 Author: Miloslav Metelka, Petr Somol


Editor Bookmarks Support in NetBeans

Introduction - Current State

Current state: Bookmark symbol is displayed to the left of the bookmarked line. Hovering mouse over displays a tooltip with always the same text 'Bookmark'
Current state: With more than one annotation per line only one is displayed. Clicking the black arrow cycles the annotation symbols (and shows possibly hidden bookmark symbol).
Current state: Right-click on bookmark symbol opens the shared annotation menu. The bookmark submenu puts on show the three currently defined bookmark actions/shortcuts.

Existing bookmarks support in NetBeans consists of three shortcuts:

  • Ctrl+Shift+M for Toggle Bookmark on current line in the currently focused document
  • Ctrl+Shift+Comma and Ctrl+Shift+Period for cycling through bookmarks back/forward in a currently focused document. The choice of these particular shortcuts is good from UEX point of view because the respective keys carry the symbols < and >, what visually underpins the respective cycling directions.

At the moment bookmark navigation is limited to a single file only. Bookmarks are unnamed. Any number of bookmarks can be set in each file, but no shortcuts to access particular bookmarks are provided, nor it is possible to cycle across file borders. There is no view/window available to get an overview over all existing bookmarks.

Bookmarks Storage

Bookmarks are physically stored in private.properties file inside a project in which the particular source file with the bookmark resides. This is generally a desirable approach however it means that the IDE always works with bookmarks from currently opened projects only.

Use-Cases and Scenarios To Be Addressed

Navigation Across Files

Users need to navigate through bookmarks across files. Since a global list of bookmarks can become large it is desirable to have more navigation options than just cycle through previous/next bookmark.

Named Bookmarks

Some users demand to create named bookmarks which many editors support. But they also want to retain unnamed bookmarks which are faster to create and work with.

Bookmark Management

Users need to see a list of all bookmarks in a window (similarly like e.g. a list of all breakpoints). Bookmark window will enable quick navigation. Possibly it would provide also other bookmark management actions: various modes of view sorting/grouping (by name, by file, by project), renaming, search by name, enabling/disabling, adding/removing.

Bookmark Management Improvements Proposed for NetBeans 7.2

Updated Bookmark Definition

In addition to the current properties of a bookmark (source-file and line-number) the bookmark would newly have a name (auto-generated names "bookmark1", "bookmark2" etc. for unnamed bookmarks, may be renamed by user) and an optional key to enable quick navigation. The key is a single character [a-z]. It is assigned automatically to next free value on bookmark creation, if a free value exists. The key can be redefined by user at any time. Editing a key or name is possible in Bookmark Manager window, or through a right-click menu on existing bookmark icon in text editor. In both cases it should be possible to request next free key value, to prevent the necessity for users to remember exactly all key assignments. Note that assigning a conflicting name or key (used already in, e.g., another project) should be permitted but a conflict should be emphasized. The proposed option is to set conflicting name/key in red instead of default black.

Updated Navigation Keyboard Shortcuts

  • Ctrl+Shift+M toggles (add/delete) an unnamed bookmark on the current line. If applied to an existing named bookmark, the named bookmark is not immediately deleted but a confirmation messagebox is displayed first.
  • Ctrl+Shift+Comma and Ctrl+Shift+Period semantics would be changed to navigate in Bookmarks History in form of a switcher which would be similar to Jump List navigation (or a browser navigation history). A bookmark would be added to bookmark history when it gets created (by toggling) or when it is navigated to explicitly either using direct shortcut (using "Ctrl+G") or from Navigator Window.
  • Ctrl+Shift+J opens Bookmark Manager dockable window. Provides hierarchical overview over all bookmarks including location context preview. Enables editing bookmark name/key.
  • Ctrg+G opens Go To dialog used so far for line number navigation only. The improved dialog should enable entering either a line number or a bookmark key or name.
  • Ctrl+TAB opens the quick switcher between opened files. This should be extended to enable bookmark navigation as well. (Remark: Due to farther reaching consequences throughout IDE this feature is not planned for 7.2.)

Remark: The shortcut Ctrl+Shift+J is so far unused and is suitable for bookmark navigation because the location of key J is just above M which has long been used to toggle bookmarks and the letter J suggests 'Jump to..'.

Bookmark Manager

A Bookmark Manager window would behave similarly to windows docked usually under the main editor window, like Output, Breakpoints, etc. The Bookmark Manager would show all the currently navigable bookmarks (from all currently opened projects). On the left there would be a table showing each bookmark's properties: name, shortcut, source-file:line-number (tooltip would show full source path). On the right there would be a preview of the code where the bookmark is located. If a new bookmark was created by Ctrl+Shift+M the window would preselect it when invoked so that the user can easily turn the recently created unnamed bookmark to a named one.

Bookmark Manager in list view mode, should enable in-place editing of bookmark name and shortcut. Conflicting bookmark shortcut illustrated in red.

In Bookmark Manager list view mode, clicking a bookmark line moves focus to the bookmark and shows bookmark context in the right code snippet window, double-clicking the line in place of name or shortcut field enables in-place editor, double-clicking the bookmark line elsewhere navigates to the bookmark in main editor. When shortcut in-place editor is active, the definition is possible by pressing the single key, or the whole Ctrl-J + key sequence.

Bookmark Manager in tree view mode.

Improved Go To dialog

Currently the shortcut Ctrl+G opens the simple Go To dialog allowing to enter a line number to go to. The functionality should be extended to accept also bookmark keys or names:

  • if a number is entered, it is interpreted as line number as before
  • if a single non-numerical character is entered, it is interpreted as bookmark key (this imposes the limitation on bookmark keys to be only alphabetic, non-numeral, but still we have sufficient number of keys available).
  • if a string of more than one character but not a number is entered, it is interpreted as bookmark name. (plus a code completion is activated offering relevant bookmark names)

This all needs to show the user whether the current entry actually leads anywhere - but we can simply change the color of the entered text - black as long as the entry is valid, red if it is not (i.e., line number is outside file boundaries, bookmark key does not exist, string is not part of any bookmark name). As long as the entry is red, the Go To button is accordingly disabled.

Improved Go To dialog would enable entering line number or bookmark key or bookmark name.

Extended Ctrl-TAB Switcher

Remark: Due to farther reaching consequences throughout IDE this feature is not planned for 7.2.

Currently the switcher displays a simple list of opened files. Repeated TAB presses while still holding Ctrl navigates through the list. Releasing the shortcut keys makes the choice.

This should be extended to enable similar navigation through bookmarks, but also through other potentially useful entities (e.g., breakpoints). The straightforward idea is to permit the use of arrow keys. Up and down arrows would just navigate the current list, left and right would switch among lists. An API would probably be needed to allow registering new browsable lists.

Bookmark Line Annotation Symbol

The annotation symbol is used to mark lines with bookmarks in editor. When mouse over, it will show the bookmark name. Right-click will enable editing bookmark properties (changing name or key) or opening Bookmark Manager with the current bookmark shown in it.

Bookmark Scope and Possible Conflicts

Bookmarks will be stored on a per-project basis. A conflict in name and shortcut may thus arise across opened projects.

  • Name conflicts can be resolved by using 'extended' names consisting of project-bookmark name. When defining the name in Bookmark Manager the name would turn red while typing as long as the name being typed is in conflict.
  • Conflict in shortcuts can be bypassed when navigating by automatically preferring the shortcut in closer scope (navigate to project in focus instead of other project). Additionally, repeated pressing of the same shortcut would cycle through conflicting bookmarks. When defining a shortcut for a bookmark the user can either ask for a free shortcut or can define a shortcut directly. If defining directly and the shortcut has been previously defined for a different bookmark in the same project, a confirmation/warning is displayed. If the shortcut exists already in another opened project, the definition is accepted but displayed in red.

Bookmark Manager warns about conflicting names and/or shortcuts by showing them in red in the table; a tooltip would show conflicting bookmark description.

Open Problems / Criticism

  • preferably the Go To functionality should be unified in one dialog. However, currently this is not viable in case of Go To (Ctrl-G) and Go To Bookmark (Ctrl-J) dialogs as it would inevitably add more steps for the user. It is not possible to distinguish purely from text input whether the entered text should represent line number, bookmark key or bookmark name.
  • some users do not like the idea of a Go To Bookmark dialog as in many IDEs there is support for straight navigation to bookmarks through keyboard shortcuts. However, in such cases a series of shortcuts is usually defined (Ctrl-0 to Ctrl-9) what is not possible in NB. Moreover, these solutions also typically limit the number of directly accessible shortcuts (typically to 10). A seemingly viable option is to define sequential shortcuts, e.g., Ctrl-J followed by key, but such solution is considered bad practice from UEX point of view.
  • arguably the Go To Bookmark dialog should be as small and simple as possible to maximally limit the interference with user's intention to navigate quickly. It's scoping options should be more restricted than in the proposal above, and more scoping options should be moved to Bookmark Manager only.


The previous version of this document is archived at EditorBookmarks72_Unused.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo