<type>documentation</type>
<domain>edit</domain>
<id>bookmarks</id>
<title>Bookmarks</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Wing Pro can set bookmarks, in order to navigate code and keep track of notes for
unfinished tasks.  Bookmarks are defined in a way that allows them to move with
the bookmarked line, even if a file is edited outside of Wing.

**Setting Bookmarks**

``Toggle Bookmark`` in the ``Source`` menu sets or removes a bookmark at the current 
line, or clicked line if using the editor's right-click context menu.  A default 
name is used for the bookmark, based on where it is located.

``Set Named Bookmark`` in the ``Source`` menu displays a dialog to enter a name,
category, and notes for the bookmark.

In the VI/Vim keyboard personality, the ``m`` and ````` keys are supported, in
addition to the operations in the ``Source`` menu, which allow creating bookmarks with
names longer than one character. Emacs, Brief, and other keyboard personalities also
support bookmarks with their native key bindings.

Bookmarks are shown on the editor with background color change or underline. The
style and color of bookmark indicators can be changed with the `Editor > Bookmarks >
Bookmark Style <script:show_preferences_gui#prefname="edit.bookmark-style">`__ and 
`Editor > Bookmarks > Bookmark Color <script:show_preferences_gui#prefname="edit.qt-bookmark-color">`__ 
preferences.

Hovering the mouse over a bookmark in the editor shows a tooltip with the bookmark name, 
notes, and category.

**Bookmark Categories**

Bookmark categories provide a way to organize and filter which bookmarks are visible in
the display. Categories can be added, renamed, and removed with ``Edit Categories`` in the
``Bookmarks`` tool, bookmarks toolbar group, and bookmarks popup at the top right of any
editor with bookmarks.

Categories marked as ``Shared`` in the ``Edit Categories`` dialog are also stored in
preferences, so that they will appear in all projects. Categories can also be exported and
imported from this dialog.

**Traversing Bookmarks**

``Traverse Bookmarks`` in the ``Source`` menu, and the key bindings shown there, can also
be used to traverse all bookmarks. To traverse bookmarks in a single file, use the
bookmark popup at the top right of the editor.

To visit a bookmark by name, use ``Goto Bookmark`` in the ``Source`` menu. This shows a
dialog, or in some keyboard personalities an entry area at the bottom of the window, into
which a bookmark name can be typed. A list of possible completions will be displayed as
you type, and pressing ``Tab`` will select the current completion.

**Filtering Bookmarks**

The bookmarks that are visible on the display can be filtered by selecting a current
category in the ``Bookmarks`` tool, the bookmarks toolbar group, or the bookmark popup in
top right of the editor.

When ``Match Fragment`` is chosen, a fragment to match any of the bookmark properties can
be entered into the ``Bookmarks`` tool, which will be displayed if not already visible.

When bookmarks are filtered by category or fragment, the marks shown on the editor, in the
bookmarks menus, and in the ``Bookmarks`` tool will be limited to those that match the
filter.  This also limits traversal to only matching bookmarks.

**Bookmarks Tool**

A list of all defined bookmarks is available in the `Bookmarks`__ tool, from the ``Tools``
menu. The contents of this tool can be sorted by clicking on the column headers. A
bookmark name or category in the list can be edited by clicking on it.  Hovering the 
mouse over a bookmark  will display any notes entered for that bookmark.

__ script:show_panel#panel_type="bookmarks"

Right-click for a menu of operations, or select a bookmark and use the toolbar
in the top right of the tool. Multi-selection is possible by holding down
shift or other modifier keys. Double-clicking or middle-clicking will navigate to
the selected bookmark.

When the ``Bookmarks`` tool has focus, keyboard navigation is possible with the
arrow keys.  Pressing Enter will navigate to the selected bookmark.

The selected bookmarks or all bookmarks visible in the currently selected category
or filter can be exported and imported from the ``Bookmarks`` tool's ``Options`` menu
and toolbar icons.

**Bookmarks Toolbar**

Bookmarks can be set, removed, filtered, and traversed from the bookmarks toolbar group,
if it is shown.  To display the bookmarks toolbar group, right-click on the toolbar and 
check ``Bookmarks`` in ``Groups Shown``.

**Tracking Bookmarks Across External Edits**

Bookmarks are stored in the project and refer to a particular position
within a selected file.  Wing tries to store enough information about 
the bookmark so it can be moved to the correct location even if a file
is edited outside of Wing.

* **For Python files** Wing makes use of the enclosing scope (method, class, 
  or function), as well the contents of the bookmarked line to track the bookmark 

* **For all other types of files** bookmarks are defined by file name,
  line number, and contents of the bookmarked line.  
  
In either case, a bookmark's position may appear to slip if a file changes
enough so that Wing cannot find the bookmarked line.


