Multiple​Selection​Scroller

Multiple Selection Scroller - Plugin for Sublime Text

Features

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:
  1. Scroll to previous selection (backwards)
  2. Scroll to next selection (forwards)
  3. Scroll to first selection
  4. 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:
  1. Clear to first selection (not really needed, see 'Description' section)
  2. Clear to last selection
  3. Clear to selection on, or nearest to, the middle line (conceptually the 'current' selection)
  4. 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

Description

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.

Known Design Limitation (Not a Bug)

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.]

Demo

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.

Requirements / Tested

• 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).

Installation

Recommended: Using PackageControl the Sublime Text Package Manager.

• Open the Command Palette in Sublime Text and select Package 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 Text Packages directory.
• Put the files from this repository into that directory either by using git or 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 .zip with .sublime-package or 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-keymap will ever be added to this package.

Setup — Settings

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_cycling setting to false.
• By default user feedback is given in the form of status messages. This can be disabled by setting the MultipleSelectionScroller.quiet setting to true.

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,

Setup — Keys

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.

Reference

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

License

The MIT License (MIT)

Copyright © 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.