Home

CursorRuler is a plugin for the Sublime Text editor which marks the current cursor position(s) using dynamic rulers.

Why Is This Useful?

1. It can be used for alignment purposes in places where Sublime Text's built-in indent guides aren't able to show up. For example, inside multiple rows of single-line comments or multiple assignment statements across different code blocks.

2. When used alongside line highlighting it creates a crosshair effect which can be a useful visual aid.

Features

• Use multiple dynamic rulers to create different highlighting styles including a "thickening" effect which can be used to simulate column highlighting.

• Option to synchronize rulers when using multiple views of the same file.

• Supports multiple cursors.

• Toggle activation through the command palette.

• Compatible with Sublime Text 2 and Sublime Text 3.

Installation

See Installation.

Usage

Having the plugin enabled is all that's required to start seeing your cursors have rulers track them.

Available Commands

CursorRuler: Toggle Enabled/Disabled - Turns CursorRuler off if it's on and vice versa.

CursorRuler: Wrap Lines - Does proper line wrapping. For details look here.

Settings

See Settings.

Tips

You may want to distinguish the cursor rulers from any normal static rulers you may have set. Unfortunately, I'm not aware of a way to set different visual styles for different rulers. However, one option to workaround this is to set multiple rulers around where a single ruler would normally be. For example, if your rulers setting in your user preferences was set like this:

{
  "rulers": [80, 150]
}

then you could do this:

{
  "rulers": [80, 80.25, 150, 150.25]
}

to make your normal rulers "thicker" and therefore distinguishable from the cursor rulers.

Also, you may instead consider making your cursor rulers have a thicker style than your normal rulers.

Ruler Colors

Speaking of ruler visual style, there's apparently no way to set the color of rulers directly. Rulers get their colors from your color scheme's foreground and background settings. The background setting overrides the foreground setting.

Despite the current lack of ability to directly set colors for rulers (as of ST2 build 2219 and ST3 build 3030) there's thankfully a workaround for it described here.

Basically, you need to change the overall default foreground color and/or background color of your color scheme and then add a rule for the text and source scopes which is used to override the default colors. For example, if we had a default foreground color which is meant to be used as the ruler and gutter foreground color:

<key>foreground</key>
<string>#00FFFF77</string>

then we would add

<dict>
  <key>name</key>
  <string>Text and Source Base Colors</string>
  <key>scope</key>
  <string>text, source</string>
  <key>settings</key>
  <dict>
    <key>foreground</key>
    <string>#E6E1DC</string>
  </dict>
</dict>

in order for us to define our actual default foreground color.

As a sidenote, gutter text foreground color can be defined directly:

<key>gutterForeground</key>
<string>#0000FF77</string>

as well as the gutter text background color:

<key>gutter</key>
<string>#0000FF33</string>

Notes

• In ST3 the standard shortcut key for the Wrap Paragraph at Ruler menu item (⌥⌘Q on OS X, Alt+Q on Linux and Windows) is rebound to instead use the CursorRuler: Wrap Lines command for doing proper line wrapping. However, using the Wrap Paragraph at Ruler menu item without the shortcut key still uses the normal wrapping command. It seems there isn't a way to override ST's default menu items in that sort of way. For details look here.

• While moving a selected group of text with the mouse the insertion-point cursor is not shown with its own dynamic ruler. Though, this is probably preferable since this distinguishes the editing cursors from the insertion-point cursors.

• The positioning of the cursor rulers is scaled according to the font size. The larger the font size the greater the chance that gaps will get introduced into "thick" cursor ruler styles like the column highlighting style. The size of the gaps are also dependent upon the font size.

• Using the column-like highlighting style while using a variable-width font looks strange. Perhaps this should considered a bug?

• In ST3 build 3012 and older the add_on_change() method was not implemented and therefore CursorRuler will not use it. In ST2 and also ST3 build 3013 and later it is available and CursorRuler will use it.

• After you save changes to your user settings or your CursorRuler settings the changes take effect once the cursor state changes.

Known Minor Bugs

• If CursorRuler is added to the ignored_packages list in the user preferences then upon saving the preferences any open files that have cursor rulers on them will retain those rulers as permanent static rulers. The only way to remove those static rulers would be to either no longer ignore the plugin or reopen the files that are affected.

• On ST2 it doesn't work on previewed files. Perhaps this is beneficial as an indicator for when you're looking at previewed files?

Related Plugins

Cross - I just found out about this today (2013-02-20). This predates CursorRuler by about a month.

More Info

• Release Notes