A summary of what this plugin can do:
- Compatible with Sublime Text v.2 and v.3
- Scroll to selection commands - center chosen selection on the middle line:
- Scroll to previous selection (backwards)
- Scroll to next selection (forwards)
- Scroll to first selection
- Scroll to last selection
- Automatic scroll cycling, from last selection to first and visa-versa
- Clear to selection commands - clear all selections leaving a single cursor at:
- Clear to first selection (not really needed, see 'Description' section)
- Clear to last selection
- Clear to selection on, or nearest to, the middle line (conceptually the 'current' selection)
- Clear to middle line of visible area (ignore selection positions, just put cursor on middle line)
- User feedback status messages, e.g. "scroll at selection: 5 of 11" or "cleared at selection: 3 of 5"
- Settings to disable user feedback status messages and to prevent scroll cycling
Multiple Selection Scroller is a Sublime Text plugin which provides commands to allow scrolling forwards and backwards through the current selections by moving the visible region so that the next/previous selection is centered on the middle line. Cycling from the last selection up to the first and visa-versa is automatic. Commands to scroll straight to the first and to the last selection complete its scrolling functionality.
Multiple Selection Scroller also provides commands to clear the selections whilst leaving a single cursor at the first selection, at the last selection, or at the selection on, or nearest to, the middle line (conceptually the 'current' selection / the one you just scrolled to) and moving the visible region so that the single cursor is centered on the middle line. It also has a command to clear the selections whilst leaving a single cursor at the end of the middle line of the visible region (this ignores the positions of the selections and does not move the visible region) - in other words clear the selections and leave a cursor on the middle line of the current scroll position.
Note: Clearly the selection clearing command which leaves a cursor at the first selection is not really needed as the same thing is performed by pressing the escape key. It has only been included in the plugin's functionality to allow users to assign that task to the same key groupings as the other selection scrolling commands and to avoid the complex context based bindings associated with the escape key which are in the system default .sublime-keymap file.
User feedback is given in the form of status messages. This tells the user which selection has just been placed on the middle line if scrolling (e.g. "scroll at selection: 5 of 11"), or at which selection the cursor has been left if clearing the selections (e.g. "cleared at selection: 3 of 5").
The plugin has settings to disable user feedback status messages and to prevent scroll cycling.
Please be aware that there is a known design limitation of the plugin. Selections above the middle line on the first page of the buffer can not be moved to the middle line, Sublime Text has no scroll_above_beginning setting. If the scroll_past_end setting is set to true, which it is by default, then the first selection below the middle line on the last page of the buffer can be moved to the middle line, but any subsequent selections can not be. In both cases any remaining selections either above or below the middle line will be in the visible region on the screen so easy to spot. It should be noted that this limitation does not interfere with scroll cycling which continues to work correctly. [In real-world usage I have not found this inconvenient when it occurs, which is rarely.]
The scrolling in this demo does not appear very smooth, this is because a low frame rate was used to keep the demo's file size down. The scrolling performed by the plugin is done by Sublime Text and it will be just as smooth as your usual scrolling is.
The demo shows both selection scrolling and selection clearing functionality.
- Sublime Text v.2 or v.3
- Tested using: ST v.2 Build 2221 (Linux 64 bit).
- Tested using: ST v.3 Build 3065 (Linux 64 bit).
Recommended: Using PackageControl the Sublime Text Package Manager.
- Open the
Command Palettein Sublime Text and selectPackage Control: Install Package. - When the package list has loaded, select
MultipleSelectionScroller.
Not Recommended: Install Manually:
- Create a directory called
MultipleSelectionScroller(or whatever you prefer) in your Sublime TextPackagesdirectory. - Put the files from this repository into that directory either by using
gitor by downloading the zip file on the GitHub page. - Sublime Text v.2 users must extract the files from the zip file.
- Sublime Text v.3 users can simply rename the file replacing
.zipwith.sublime-packageor extract the files if preferred. - Clearly if you install manually then you will not receive automatic package updates, inconvenient if a bug is found.
- Note: If you are concerned that a keys file will be added that will interfere with your config, be assured that no
.sublime-keymapwill ever be added to this package.
The Multiple Selection Scroller plugin has two optional settings with which the plugin's default behaviour can be altered.
- By default, when scrolling, the plugin will cycle from the last selection up to the first, and from the first down to the last. This can be disabled by setting the
MultipleSelectionScroller.scroll_cyclingsetting tofalse. - By default user feedback is given in the form of status messages. This can be disabled by setting the
MultipleSelectionScroller.quietsetting totrue.
e.g. Add these settings to your Preferences.sublime-settings file:
// Disable scroll cycling:
"MultipleSelectionScroller.scroll_cycling": false,
// Disable user feedback status messages:
"MultipleSelectionScroller.quiet": true,
The Multiple Selection Scroller plugin does not provide a .sublime-keymap file to set its keys.
Choosing keys that will suit all users is not possible - the chosen keys will always interfere with the existing keys of some users. The README_KEYS.md file, linked below, contains suggestions and examples of various key bindings that can be copied and pasted into your user Default (OS).sublime-keymap file and altered to suit your configuration.
Please follow this link to read the README_KEYS.md file.
Command and Arguments:
Command name: multiple_selection_scroller
Either a scroll_to or a clear_to arg MUST be used in the command call.
scroll_to - move the visible region centering the selection on the middle line.
-------------------------------------------------------------------------------------
Command Arg Value Description
-------------------------------------------------------------------------------------
scroll_to previous_sel Scroll to previous selection (backwards)
scroll_to next_sel Scroll to next selection (forwards)
scroll_to first_sel Scroll to first selection
scroll_to last_sel Scroll to last selection
clear_to - clear the selections leaving a single cursor at the chosen location.
-------------------------------------------------------------------------------------
Command Arg Value Description
-------------------------------------------------------------------------------------
clear_to first_sel Clear to first selection
clear_to last_sel Clear to last selection
clear_to middle_sel Clear to selection on/nearest the middle line
clear_to visible_area Clear to the middle line of the visible region
(regardless of selections, clear to current pos)
-------------------------------------------------------------------------------------
Settings File:
Two settings may optionally be used in the Preferences.sublime-settings file.
MultipleSelectionScroller.quiet - control user feedback status messages.
-------------------------------------------------------------------------------------
Setting Value Description
-------------------------------------------------------------------------------------
MultipleSelectionScroller.quiet true Do not display status messages
MultipleSelectionScroller.quiet false Display status messages (default)
-------------------------------------------------------------------------------------
MultipleSelectionScroller.scroll_cycling - control scroll cycling.
-------------------------------------------------------------------------------------
Setting Value Description
-------------------------------------------------------------------------------------
MultipleSelectionScroller.scroll_cycling true Enable scroll cycling (default)
MultipleSelectionScroller.scroll_cycling false Disable scroll cycling
The MIT License (MIT)
Copyright (c) 2015 mattst@i-dig.info / https://github.com/mattst
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.