Bookmarks Documentation

bookmark website header

Bookmarks

Navigate your code.

 

AboutDocumentationDownload

 

Bookmarks is now part of RAD Studio! Read more here.

Looking for the About page? Click here.

Looking for the Support page? Click here.

Overview

The Parnassus Bookmarks plugin completely replaces the IDE’s inbuilt bookmarks functionality. It is not a ‘bookmark manager’ like some IDE plugins provide, which wraps the IDE’s bookmarks – it is a complete replacement. The plugin provides shortcuts to place, move and delete bookmarks; paints in the code editor to indicate the location of bookmarks; and includes a docked window to show bookmarks in the current file or all open files. It also addresses a number of QC items.

Installation and uninstallation

Close all instances of Delphi, C++ Builder or RAD Studio before running the installer. To install, run the setup file, and choose which versions of the IDE you want to install for. Click through, and once finished open Delphi. You will be shown a screen listing the plugin as installed.

To uninstall, close all instances of the IDE. Run the uninstaller from ‘Add/Remove Programs’ (XP) or ‘Programs and Features’ (Vista and above.) Once complete, restart the IDE.

Code editor

Adding bookmarks

To add a bookmark, press Ctrl+B (for Bookmark.) A bookmark will be automatically added at the current line. You will see a small visual animation indicating the location of the new bookmark.

Unlike the inbuilt IDE’s functionality, you don’t need to remember which bookmarks are already set, and set a specific bookmark (set bookmark 5, for example.) Instead just press Ctrl+B. A number will be automatically chosen, if one is available. If you have more than ten bookmarks already set in the file, there are no more number keys, but the bookmark is still accessible via the navigation shortcuts and the docked window. If you really want to set a specific bookmark number, you can do so via Ctrl+Shift+[0-9].

There is no limit on the number of bookmarks you can set in a file.

Going to bookmarks

To go to the bookmark you just set, press Ctrl+[0-9] or double-click on it in the dockable Bookmarks window.

To cycle between all bookmarks in the current file, press Ctrl+Alt+Right Arrow or Ctrl+Alt+Left Arrow. This takes you to the next or previous bookmark in the file, sorted by line number.

The dockable window also shows bookmarks set in other files, not just the one currently shown in the code editor (look in the Open Files tab to see all bookmark, or the Current File tab for just bookmarks in the file in the current / active edit window.) Double-clicking on any bookmark will navigate to it and switch file if necessary..

Removing bookmarks

To remove a bookmark, make sure the cursor is on the line where a bookmark is set. Press Ctrl+B again. This time, the bookmark is removed. You will see a small visual animation indicating it was deleted.

You can also add and remove bookmarks from the docked window individually or all at once (see below) or, when the cursor is on the line where the bookmark is set, by pressing Ctrl+Shift+0-9, where 0-9 is its number.

Bookmarks are saved so unless you remove them manually they will be there next time you open the IDE.

Caret bookmarks

Caret bookmarks are meant for quick code navigation when you don’t want to keep the marker around – for example, to save where you were while you navigate in another unit, and then jump back to your location with a single keypress. Caret bookmarks remember the character position as well as the line – useful for copying, jumping back, and pasting immediately – and vanish when you jump to them and when the code they’re in changes.

To add a caret bookmark, press Ctrl+Shift+B. Just like normal bookmarks, only one exists per line, so remove one by placing the cursor on the line and pressing Ctrl+Shift+B again.

Caret bookmarks are navigated to in time order. To jump back to the last placed temporary bookmark, press Escape. This navigates to the bookmark’s location – both line and character – and removes the bookmark. You can place an infinite number of caret bookmarks and press Escape to go back in time to each one.

If you want to toggle quickly between locations, mark the first with Ctrl+Shift+B. At the second location, when you want to return to the first, press Shift+Escape. This navigates back, but places a marker where you were. This means that pressing Shift+Escape repeatedly will toggle back and forth between two places.

Caret bookmarks are temporary. They are removed when you navigate to them, when you close the file they are located in, and when you close the IDE. Only normal bookmarks are persistent.

Visual symbols

Bookmarks are shown in the code editor gutter with a small red icon. The icon contains the bookmark number (0-9) or a hash symbol (#) if there were already ten bookmarks at the time it was added.

When code is folded, the folded line will include icons for all bookmarks in the folded section. The gutter will show a special folded-bookmark icon with an ellipsis (…) and on the right, where the IDE paints an expansion ellipsis, are icons for all bookmarks in the folded area.

Temporary bookmarks draw a small chevron at their location in a line of code, at the position where the caret will be located when the bookmark is jumped to.  They also draw a similar shape in the gutter indicating that there is a temporary bookmark on that line. You can have both normal and temporary bookmarks on the one line.

Animations

The Bookmarks plugin makes light use of animation as an indicative interface element. Adding and removing bookmarks show an animation flowing in or fading out of the gutter. Trying to set an already-set bookmark shows a bouncy animation indicating the location of the existing bookmark, either where it is onscreen, or if it is offscreen then at the top or bottom of the code editor.

Shortcuts

Adding and removing bookmarks

  • Ctrl+B: adds a bookmark at the current line, or removes one already set at the current line
  • Ctrl+Shift+[0-9]: adds a bookmark at the current line, with the specified number. If the bookmark already exists, a small animation will show the current location and it will not be changed. Press the shortcut again quickly to move the bookmark to the current line.
    • You can turn off this warning showing the current location in the Settings dialog. Pressing Ctrl+Shift+[0-9] will then always set the bookmark.
  • Ctrl+Shift+B: adds a caret bookmark and the current line and characters, or removes one already set at the current line.

Navigation

  • Ctrl+Alt+Left Arrow and Ctrl+Alt+Right Arrow: move to the closest bookmarks before and after the current line. In other words, press one of these to cycle forwards or backwards through all bookmarks in the current file. These cycle by file location, not by bookmark number, and are useful if you can’t remember a bookmark number, or if you want to examine each area you tagged.
  • Ctrl+[0-9]: move to the specified bookmark. The cursor will be moved to the beginning of that line, and the line made visible onscreen.
  • Escape: jumps to the most recently placed caret bookmark. Shift+Escape does the same, but leaves a caret bookmark where you were before jumping.

Docked window

The docked window lists all bookmarks and also gives access to some other functionality. Open it by navigating to the IDE’s View menu, then clicking the ‘Bookmarks by Parnassus’ item. The window can be docked and tabbed with other IDE windows, such as the Tool Palette, Structure View, or Breakpoints. To reopen in the same position when you reopen the IDE, save the current IDE desktop layout from the IDE’s Desktop toolbar, normally located to the right of the menu.

docked-window-heavy-shadow-2-caretThe Bookmarks window has three tabs at the bottom. ‘Current File’ lists all bookmarks in the current source file. ‘Open Files’ lists all bookmarks in all open files in the IDE. ‘Caret’ lists all caret bookmarks.

Double-click a bookmark to navigate to that bookmark.

For Pascal-language files, each bookmark shows context about where it is located: in large text, the method, type or similar in which it is located; in small text, the section of the file (uses, type, implementation, etc) as well as the file name and line number. For non-Pascal files, bookmarks simply list the contents of the line of code, and the file name and line number.

The toolbar buttons allow you to:

  • Add a new bookmark at the current line, if one is not already set (this is equivalent to pressing Ctrl+B)
  • Add a new caret bookmark at the current line and character, if one is not already on that line (this is equivalent to pressing Ctrl+Shift+B)
  • Go to the selected bookmark (click in the list to select.) Note you can double-click to go to a bookmark immediately.
  • Delete the selected bookmark
  • Delete all bookmarks shown in the current tab
  • Give a name or description to the selected bookmark
  • Go to the previous or next bookmark in the current file (this is equivalent to pressing Ctrl+Left Arrow or Ctrl+Right Arrow.)

The small Parnassus logo will open the Parnassus IDE Plugins website page.

Settings

To access the Settings dialog, in the docked Bookmarks window, click the Settings button with a small gear icon. Alternatively, go to the IDE’s Tools menu and click Options, then navigate to Third Party > Parnassus > Bookmarks in the tree view.

For both normal bookmarks and caret bookmarks, you can turn animations on or off. (The animation is the small red transparent shape that zooms and fades in to indicate a new bookmark, zooms and fades out to indicate a deleted bookmark, or, coloured dark blue, zooms out and in to indicate the location of an existing bookmark.)

You can also change the size of the animated indicator onscreen.

It is also possible disable prevention of overwriting an existing bookmark. (This shows the location of the bookmark when you try to set one that already exists with a dark blue location indicator. For example, if bookmark 1 already exists, pressing Ctrl+Shift+1 will show a dark blue animation at the location of bookmark 1, instead of moving the existing bookmark to the new location.) At any time while the dark blue warning is shown onscreen, you can press the shortcut again to indicate you do want move the bookmark.

You can change the amount of time the warning is shown, and so the amount of time in which you can move the bookmark, with the drop-down combo box.

In addition, you can also change many of the shortcut keys. This is not recommended, since the existing ones were chosen carefully. In addition, there is no way to know which shortcuts have already been taken by the IDE or other plugins, so you need to set them and test if they work. However, this is available for power users who prefer complete customization.

Bookmarks generally bookmark a line.  When you navigate to a bookmark, the cursor is placed at the start of the line, ignoring whitespace – the first useful text. However, you can change this behaviour so that bookmarks will remember and restore the full caret position when creating and navigating to a bookmark.  This means that the cursor will be placed at the same character index in a line as it was when the bookmark was created.  Bookmarks saved from old pre-v1.3 versions, or bookmarks created by clicking in the editor gutter (marking a line, not a character) will always retain the default behaviour.

Finally, you can turn off being able to create and delete bookmarks with the mouse in the code editor gutter. You can also highlight this area of the gutter: with this setting turned on, the area of the gutter where bookmarks draw, and which can be clicked on to create or remove a bookmark is tinted very slightly red.

Look and feel: you can configure which elements are drawn in the docked bookmark list, including the bookmark number,r name or description, unit section, and line of code. The code preview can be syntax highlighted, or in a plan version of the editor or UI font, and the font can be shrunk a couple of point sizes in order to fit more of the code line onscreen.

Default settings

Animations default to on for normal bookmarks, with ‘Normal’ size. Animations default to off for caret bookmarks, and if turned on default to ‘Small’ size. Overwriting warning / prevention defaults to on. Using the mouse in the gutter is on.

QC items

As well as improving on the IDE’s inbuilt bookmarks and adding new functionality, the Bookmarks plugin addresses a number of items in Quality Central.

Expand list of addressed QCs
  • 90782: It is easy to forget that you have already set bookmark (say) 1, and so accidentally overwrite bookmark 1. The QC requests a message that the bookmark already exists, when trying to set a bookmark.
    Parnassus Bookmarks solves this several ways:

    • The default way to add a bookmark is not by pressing a key combination for a specific bookmark number, but just by pressing Ctrl+B. You will get a number automatically assigned if one is available. It will not overwrite an existing bookmark.
    • Also 2989: If you try to set a bookmark by pressing the shortcut keys for a specific number, such as Ctrl+Shift+1, and that bookmark already exists, the first time you press it no bookmark will be added. Instead a small animation will appear showing you where the bookmark is located. If you really do want to overwrite or move the bookmark, press the shortcut again within a small amount of time, and this time the bookmark will be moved.
  • 57610 This requests a list of bookmarks in the file browser. Parnassus Bookmarks does not implement this as specified in the QC, but does add its own dedicated window listing all bookmarks, which can be docked with the file browser, project manager or other windows. (The QC goes on to request some additional non-bookmark functionality out of scope for this plugin.)
  • 35715: This QC points out that the Tool Palette is not useful when code editing and the space should be used for something else, specifically suggesting using it for a list of bookmarks. You can dock the Bookmarks window over the Tool Palette, and so when writing code in the editor you can make that window visible instead. Remember to save your desktop so the docked window retains its position when reopening the IDE or when changing from debugging back to normal operation.
  • 47866: This points out that the colors used for the bookmark icons in the code editor gutter make them hard to read. Parnassus Bookmarks addresses this by using a bold dark red background and bright white text. We hope this is both pleasant to look at and much more readable.
  • 3283: This requests ‘global bookmarks’, ie using bookmark numbers 1-9 once across all files, not just within a file. Parnassus Bookmarks does not implement this as suggested – we believe having only nine bookmarks across all your open files would not be useful. However, the dockable window lists all bookmarks in all open files, and you can use it to see and navigate to bookmarks in any file, ‘globally’. Double-clicking a bookmark will switch the IDE to that file, and navigate to the appropriate line.
  • 1514: This QC and its comments are similar to several of the above, and discuss accidentally overwriting an existing bookmark when creating a new one, having an indicator which bookmarks are set, and being able to click an ‘indicator’ to jump to a bookmark. These problems are addressed both by smart prevention of overwriting bookmarks, and the docked bookmark list which both shows all bookmarks in the file, and allows you to navigate to them.
  • 89021: This QC requests an OpenTools API interface for notifying of bookmark changes, so that plugins that interact with bookmarks do not need to poll for changes. Parnassus Bookmarks completely replaces the IDE’s implementation, and does not poll. In addition, the plugin provides its own API allowing other IDE plugins to enumerate bookmarks, add or remove bookmarks, and receive notifications (without polling) when bookmarks are added, removed, or change.

API

The Bookmarks plugin provides a public API allowing other IDE plugins to access bookmarks, register for notifications, etc. Please see the separate API documentation.

Miscellaneous notes and questions

Supported Delphi & C++ Builder Versions

Bookmarks is compatible with Delphi and C++Builder XE, XE2, XE3, XE4, XE5, XE6, XE7, XE8, 10.0 Seattle, 10.1 Berlin, 10.2 Tokyo, and 10.3 Rio and newer – now acquired by Embarcadero.

Parnassus Plugins

All plugins by Parnassus are registered with a meta-plugin, which provides access to settings, licence information, and documentation. You will see this meta-plugin the first time you open the IDE after installing a new plugin. To see it again, open the IDE’s Help menu and click the ‘Parnassus Plugins’ menu item near the bottom.

Support and Licensing

The Bookmarks plugin is free. Please report any bugs using the bug report form.

The Bookmarks plugin and associated files are offered with NO WARRANTY express or implied. Parnassus accepts no responsibility for any damages resulting from the use of this software. It is not freely redistributable. Copyright © 2014 Parnassus OÜ. All rights reserved.

Release Notes

Version [unreleased] (2018-02-11)

  • Acquired by Embarcadero; included in the upcoming version of RAD Studio. Read more here.

Version 1.5.2 (2017-04-06)

  • New feature: support for 10.2 Tokyo
  • New feature: Bookmarks are present in the View > Editor submenu in Tokyo

Version 1.5.0 (2016-03-22)

  • New feature: Code preview: The line of code where a bookmark is located can now be shown in the dockable Bookmarks list. This code snippet is syntax-highlighted by default (for both Delphi and C++) and can also be shown in a plain version of the editor font or the UI font. Its size can also be shrunk in order to fit more of the line of code onscreen.
  • New feature: You can now configure what is displayed in the dockable Bookmarks list. Turn on or off any element – the bookmark number, the bookmark name or description, line code, unit section, and file name and number.
  • Tweak: The Ctrl+LeftArrow and Ctrl+RightArrow key combinations (configurable) used to cycle through the previous and next bookmarks in the current unit. There is now an option for these to navigate through all bookmarks in all units, so when you press the ‘next’ shortcut and are already at the last shortcut in a unit, you will navigate to the first shortcut in the next unit. Bookmarks are sorted by filename and then by bookmark number.
  • Bugfix: The images on the splash screen were designed for the orange splash screen of RAD Studio Seattle Update 0. However, different SKUs have different colour splash screens, which changed again with Update 1. The splash screen icon now looks correct on any splash screen, including any future versions.
  • Bugfix: A crash caused by the Delphi exception handler being unloaded before plugins are unloaded.
  • New: the Bookmarks API has been extended to give access to caret bookmarks.

Version 1.4.0 (2015-09-03)

  • Support for RAD Studio 10 Seattle
  • Bugfix: A long-standing crash on exit should finally be gone. This affected some users often, but others never, and was caused by the IDE unloading plugins in an unusual order
  • New feature: Update notifications! If there is a new version of any installed Parnassus plugin, you will get a small notification when the IDE starts
  • Bug fix: Bookmarks did not draw correctly when they were inside a collapsed / folded region
  • Tweak: Bookmark settings are now integrated into the Delphi Options dialog, instead of being their own standalone dialog.

Version 1.3.5 (2015-03-08)

  • Support for RAD Studio XE8

Version 1.3.4 (2015-03-05)

  • New feature: Press F2 to rename a bookmark in the code editor. In other words, if there is a bookmark on the current line of the code editor, press F2 to rename it. This shortcut can be changed using the new customizable shortcut support added in v1.3.
  • Bugfix: The shortcut controls in the settings were too narrow to display the full shortcut on German editions of Windows.
  • Bugfix: the hint text “Press Ctrl+B to place a new bookmark” displayed on the dockable bookmark form when the bookmark list was empty did not change to reflect customized shortcuts.
  • Bugfix: ‘Escape’ to jump back to the previous caret bookmark is not editable. The hotkey on the Settings dialog is now not editable, and has a note specifying that, and also that you can add Shift in order to drop a caret bookmark as you jump.
  • Change: small optimizations, especially for bookmarks in C++ files – Bookmarks no longer attempts to parse them as Pascal.

Version 1.3 (2015-03-02)

  • New feature: Customize the shortcuts Bookmarks uses
  • New feature: Bookmarks can optionally remember not just the line they were placed on, but the character index or column in that line
  • New feature: You can highlight the area of the editor gutter that can be clicked to add a bookmark
  • Bugfix: Bookmarks v1.2 and earlier installed in XE5 and earlier caused compatibility problems if you also had PngComponents installed. This is now resolved and both can be installed at the same time
  • Change: the internal parser has been replaced with DelphiAST
  • Bugfix: some visual glitches and incorrect window placement when using the IDE in Classic Undocked mode have been fixed
  • Change: The version number is now shown on the IDE splash screen, and the full version number of both Bookmarks and its utility DLLs is shown in the IDE About box.
  • Change: this version now uses DDetours version 2.
  • API changes:
    • Support for character positions for bookmarks: you can create a bookmark at a specific character index in a line, and retrieve the character index for a bookmark.
    • You can create a bookmark with a specific bookmark number / index, such as 17, and access by this index. Previously bookmarks were limited to numbers 1-9 and 0, and creating outside this area worked – Bookmarks has always supported more than ten bookmarks – but did not give a usable ID to retrieve the bookmark by. Now you can create and retrieve by any arbitrary >0 index at the API level. Users still see bookmarks exactly as before; that is, bookmarks outside the 1-9/0 range show a # symbol.  User-visible behaviour is unchanged.
    • TPnAPIFileVersion has a VersionOrBetter method, for easier version comparison (thanks to Nicholas Ring for suggesting and donating this code.)

Version 1.2 (2014-12-05)

  • Bugfix: Pasting a duplicate line of code caused a bookmark to jump ahead one line to the newly pasted duplicate. Bookmarks will now remain on the first of two adjacent identical lines.
  • Bugfix: List out of bounds exception viewing a form as text
  • Bugfix: All bookmarks were removed from a unit when using class completion or event handler addition / removal, and the method prototype and IDE-generated method body were more than 250 lines away from each other
  • Bugfix: Moving the mouse over the getter while selecting text, and releasing the mouse button, did not stop the selection following the mouse
  • New feature: Bookmarks can now be assigned a custom name / description
  • Tweak: There is now a setting to disable adding or removing bookmarks by clicking in the editor gutter
  • Tweak: Temporary bookmarks are now called “caret” bookmarks

Version 1.1 (2014-10-27)

  • First public release

Discussions about this page on Google+