Navigator Plugin
Authors:
-
Dale Anson
-
Alan Ezust
-
Shlomy Reinstein
Version: 2.7
Build Date: June 22 2016
Introduction:
The Navigator Plugin provides a set of "Back" and "Forward" actions similar to a web browser. This is surprisingly
handy. It also provides a "go to line" dialog that can be used to replace jEdit's built in "go to line" dialog.
In addition, Navigator also provides an independent "user stack", where the current position is only pushed in response to "Push Current Position". With this, it is possible to navigate to positions on the user stack via actions "Go To Top" or "Swap Caret with Top", and "Pop Position".
Configuration:
The Navigator configuration has these options:
-
Group history items by file - if checked, the popup history will list only the last location visited in a file. This
makes it easy to quickly jump back to the last place you were working in a file.
-
Group history items by line - if checked, the popup history will list only the first location visited in a line. This
means that clicking in the same line at a different offset in that line will not be recorded in the history.
-
Show Navigator on toolbar - see below for more information about showing the Navigator "Back" and "Forward" buttons.
-
Scope:
-
View scope
-
EditPane scope
See the section "How Navigator Works" for a discussion of the difference between View and EditPane scope.
The scope can also be toggled using the Navigator menu. If you find yourself regularly switching between scopes, you
can assign a shortcut to the toggle action. If you never split your Views, then you it doesn't matter which of these
you use.
-
Maximum History Size - the maximum number of positions that Navigator will remember in either the back history
or the forward history.
-
Show line text in history - in addition to showing the file name and line number of a position, the history
popup can also show the text of the line at that position, which can be helpful in finding the right position
to jump to.
-
Show syntax highlighting in history list - when showing the text at the position, the popup can also display that
text with the syntax highlighting used in the text area.
-
Show stripes in history list - selecting this option will cause the history list items to be displayed with
alternating colors in the list, which can make it easier to pick out the item you want. On the other hand,
depending on the look and feel you are using, this can be horribly ugly.
-
Visible rows in history list - you can choose how many rows you'd like to see at once in the history list.
The default is 10 rows.
Moving Around with Navigator
The Navigator works in a "visible" or an "invisible" way. I find it is handy to assign shortcut keys for the actions
"back" and "forward" so movement can be done with the keyboard only.
Tip: Bind the actions to Alt+RIGHT and Alt+LEFT and get used to them, because those shortcuts work in
IE/Firefox/Konqueror/Chrome/Opera/most browsers too.
Navigator keeps track of the caret positions within the files you have visited. Going back takes you to those
previous positions, then it is possible to go forward. The default settings record by caret position, which
provides the most granularity for the history. If you want to go back or forward to a different file, you can use the
Back file or Forward file actions. I've assigned Alt+PageDown and Alt+PageUp for these, which makes it very
convenient to move quickly between locations in two files while still maintaining the granular navigation history
within a file.
With 'group by line' selected, movements within a line are not recorded, so some granularity is lost. Each 'back' or
'forward' will move to the next line, not any position within a line.
With 'group by file' selected, only the last location visited within a file is recorded, so a lot of granularity
is lost. Each 'back' or 'forward' will move to the next file, not any position within a file. Using the 'back by file'
or 'forward by file' actions is probably more useful than using 'group by file'.
The Navigator buttons can become visible in many ways. Adding buttons directly via Global Options - Toolbar
is not recommended. Instead use one of these methods below.
-
Go to Plugins - Plugin Options - Navigator and check "Show Navigator on toolbar". This was broken for about 7 years,
is finally fixed in the 2.0 release and is probably the best choice if you generally use the jEdit tool bar.
-
Go to Global Options - Docking and add a dockable for the Navigator to one of the docking areas. These buttons will
grey out if the corresponding stacks are empty and will give you easy control of the Navigator settings.
It is possible to access the previously visited locations directly. From the main menu to Plugins - Navigator, then
choose either "Back List" or "Forward List" or "Combined List", then you can pick a specific location from the list popup. You can also
assign a shortcut to these lists (Alt+1, Alt+2, and Alt+3, perhaps) by going to the main menu, Utilities, Global Options,
Shortcuts, choose Plugin: Navigator, and set the shortcut keys.
Other ways to access the previously visited locations:
- Dock the Navigator dockable in one of the docking areas. The dockable shows the back and forward lists.
- Right click on one of the Navigator arrow buttons. The corresponding list will popup.
- Add "Show back list" and/or "Show forward list" to the text area context menu.
Using the "Go to line" dialog
Navigator provided a "Go to line" dialog that can be used as a replacement for jEdit's built in "Go to line dialog.
The Navigator dialog has a few features that the jEdit dialog lacks:
- Remembers the last line entered so it is easy to go back to that line.
- Displays a history list of previous lines visited within the current buffer, which helps in moving around
in a file.
To use the Navigator "Go to line" dialog rather than the jEdit "Go to line" dialog, just check the box in the Navigator
options. The keyboard shortcut that previously activated the jEdit "Go to line" dialog will now show the Navigator
"Go to line" dialog.
How Navigator works
Navigator tracks PositionChanging EditBus messages. Going back moves the caret to the
previous position. If that previous position happened to be in a different file, then that file will be opened.
PositionChanging messages can be sent by the core or plugins, to notify
Navigator that the current position should be saved. Each mouse click will cause one to be sent.
When core or a plugin jumps the caret to another position in the same buffer, it should send a PositionChanging
message for that editpane.
Some jEdit terminology: A View is a
main jEdit window. You can open more Views by using the View menu and selecting "New View". Within a View, an
EditPane
is the part of the View that contains the text area. You can open more EditPanes by using the View menu and selecting
one of the "Splitting" options. Each split is an EditPane.
View Scope:
In View scope, Navigator remembers edit panes. So if you have a split pane, and are scrolling and clicking back and forth
between the panes, going back (or forward) will also set focus on the appropriate edit pane, even if you have the
same file open in both panes. This works for as many splits as you have.
If you close an edit pane, the history for those files is NOT lost. Quite often, you'll have just one edit pane
in your View, you'll split the view to compare a file or to see different parts of the same file,
then you'll close the view. The history will be retained for any PositionChanging events that were
tracked during the split. The splits won't be restored as you go back or forward, though.
Each View has its own Navigator and history. This means that if you regularly work with two Views
open, going back in one View will not take you the other View, rather, the caret will move to the previous location
in the current view. If you close a View, the history for that View is lost.
History is not persisted between jEdit sessions, so if you close jEdit, the history is lost.
EditPane Scope:
In EditPane scope, Navigator keeps a separate history for each EditPane. Going back or forward will cause the
caret to move only within the current EditPane. To go back and forward in a different EditPane, you'll have
to switch to that EditPane.
If you close an EditPane, the history for files within that EditPane is lost.
If you change scope, no history is lost. This means that you can be using View scope, change to EditPane scope to limit
back and forward browsing to the current EditPane, then switch back to View scope to browse the entire history. Keep in
mind that while in EditPane scope, if you close an EditPane then the history for that EditPane will be lost.
Changelog
-
Version 2.6
- plugin patch 176: Navigator Popup Key Handling (Makarius)
- Fix for bug 1796, show tool bar buttons correctly when view is toggled from full screen mode. This fix requires
at least jEdit 5.3pre1 since it requires the new ViewUpdate message state added in that version.
-
Version 2.5
- German localization.
- Documentation update.
- Replaced property hacking with an actual toolbar class.
- Fixed group by line, it wasn't actually working since last release.
- #3520045 - added patch from Tom Power for jump by file.
-
Version 2.4
- #2093226 - Manual Position Stack (A. Ezust)
- #3501932 - Fix EditPane Leaks (K. Satoda)
-
Version 2.1
- Fix for tracker 2824226, Navigator hangs when opening multiple files at once.
- Fixed a bug when jumping back, if 'current' was not the current position, it was pushed to the backHistory stack but the location wasn't changed (only after the next 'back' it would change).
- Fix for tracker 2824680, keep line numbers in history, not caret positions. Added option to group by line.
- Restored a method that was inadvertently removed to get the toolbar for the Navigator dockable.
-
Version 2.0
-
Navigator mapped to Views again, so each View has its own Navigator. EditPanes are tracked also,
so if you have the same file open in a split pane, Navigator will correctly go back and forth appropriately. This
is a better fix for bug 2493691.
-
Added option for View or EditPane scope. Originally, Navigator worked on View scope, then Alan changed it to
EditPane scope in version 1.2. Now there is an option for the user to choose which scope is preferred. I find
View scope particularly nice when doing diffs.
-
Added "Clear" action to plugin menu so the history can be cleared.
-
Lots of code clean up, removed unused methods, restructured history model.
-
Fixed the "add to toolbar" option so it is no longer buggy. It's still a hack, but it's a clean hack.
-
Modified the history popups to also show the actual text of the line. This can make it easier to jump
to the right line since there is now a little bit of context displayed with the location. The text
can also be syntax highlighted if desired.
-
Added text field to option panel so user can set the maximum size of the history.
-
Added text field to option panel so user can set the number of rows displayed in the history popup.
-
Added ability to show the back and forward history combined in a single list.
-
Added unit tests.
-
Version 1.7, all from Shlomy
- Fixed bug #2493691: Navigator move to the wrong offset. When jumping
to a history location which is open in jEdit in another edit pane, that
edit pane could be made current in the view, but the caret location was set
in the originator edit pane (where the navigator jump command was issued).
- Added an option to group history items by file - i.e. several history
positions in the same file will show up in the pop up as a single item - of
the first position in that file.
- Made some cleanup, got rid of compilation warnings of unused
variables.
- Made the history model a bit simpler, avoiding the redundant
"terminating null" in the history vector.
-
Version 1.6
-
Navigator truly mapped to EditPanes now (Alan Ezust)
-
Updated for jedit 4.3pre15 (using PositionChanging EBMessage).
-
#2011801: Do not hold closed buffers in memory (Kazutoshi Satoda)
-
Version 1.5
-
Popup History shows line numbers instead of caret positions. (shlomy reinstein)
-
Memory leaks removed (Chris Grindstaff)
-
Version 1.4
-
New popup history actions: back list and forward list, for non-sequential history jumps. (shlomy reinstein)
-
Version 1.2
-
Creates one Navigator for each EditPane, instead of each View. This means each editpane has its own navigation
history. (alan ezust)
-
Version 1.1 (alan ezust)
-
Listens to new (4.3pre3) EBMessage event: EditPaneUpdate.BUFFER_CHANGING.
-
Bugfixes
-
Version 1.0 (Dale Anson)
-
Initial release.
-
Bugfixes