A Guide to Installing ColorSchemeEditor for Sublime Text 3

Hello and welcome to my ColorSchemeEditor (referred to here as CSE) installation guide. The task of building and installation is rather complex, so I’ll give the details for Windows, OS X, and Linux here.

As far as prerequisites are concerned, if you want to build from scratch you’ll need a recent copy of Python 2.7. OS X users, make sure you install Python from python.org, MacPorts, or Homebrew, as the version of Python included with OS X is not complete, and most likely won’t work for this task. Next, Windows and OS X users will need to install wxPython 2.8 or 2.9 (not 3.0) from here (Windows users, pick either the 32– or 64-bit versions for py27, OS X users pick the Cocoa .dmg file). Linux users, you can install the wxpython or wxgtk packages from your package manager. On Ubuntu, for example, the package is called python-wxgtk2.8. Again, make sure you’re getting version 2.8 or 2.9.

OK, now that we have the prereqs out of the way, let’s get the source. First, at the command line, navigate to Sublime’s Packages directory. On Windows, this is either %APPDATA%\Sublime Text 3\Packages (for a standard install) or the Sublime Text 3\Data\Packages directory for a portable install, on OS X it’s ~/Library/Application Support/Sublime Text 3/Packages, and on Linux it’s ~/.config/sublime-text-3/Packages (the ~ symbol means your home directory). Once in Packages, run

git clone https://github.com/facelessuser/ColorSchemeEditor.git

This will create the plugin directory, called ColorSchemeEditor. Linux users, enter this directory, and open the file called version.json in Sublime. In the "linux" section at the top, change "max" to "0.0.9", then save the file and close it. Windows and OS X users don’t need to do this step, as theirs is already set to the correct value.

Next, navigate to some other directory, like /tmp on OS X/Linux, or perhaps a directory where you keep your development files. Even the Desktop would be fine. There, run

git clone -b GUI_Source https://github.com/facelessuser/ColorSchemeEditor.git CSE_GUI

This will clone another branch of the ColorSchemeEditor repo into a directory called CSE_GUI. Enter that directory, and run

git clone https://github.com/pyinstaller/pyinstaller.git

This clones the PyInstaller repo inside the CSE repo, as it is needed to build the binary. Once this is out of the way, we’re ready to build! From inside the CSE_GUI directory, simply run

python build.py -c subclrschm

and wait for a while. If you’re lucky, you’ll get an output with lots of INFO: lines, but no ERROR: messages. After it’s all done, navigate to the dist subdirectory, and your new binary should be there. On Windows it’ll be called subclrschm.exe, on OS X it’ll be subclrschm.app, and on Linux it’ll be subclrschm (no extension) and should already be marked as an executable. As a test, try running the binary now to see if everything worked. On Windows, just type subclrschm, on OS X type open subclrschm.app, and on Linux type ./subclrschm. You should see a new window open up that looks like this:

CSE opening dialog

Just click on the X at this time, hit Cancel in the next dialog box, and the program will quit. Congratulations, you’ve just built yourself a new binary!

The next part can be done either via the command line, or through your platform’s file explorer (Windows Explorer, Finder, Nautilus, etc.). Navigate back to the Packages directory mentioned earlier and enter the User subdirectory. Next, create a subclrschm directory, and inside that create a subclrschm-bin-platform directory, where platform is one of windows, osx, or linux . Inside this directory, create a file called version.json with the following contents:

    "version": "0.0.9"

Save the file and close it. If you edit this file in Sublime, you may get a notice to download the binary – just cancel it. When Sublime started, you may have gotten a notice about how it can’t compare versions, or something similar. Again, just ignore it. Finally, with Sublime closed, copy the binary from your CSE_GUI/dist directory to the one containing the version.json file you just created.

And that should be it! You can now restart Sublime and play with ColorSchemeEditor. To access it, open the Command Palette with Ctrl-Shift-P on Windows/Linux or Command ⌘-Shift-P on OS X and start typing colorscheme until the options appear. There are six options, only four of which I’ve ever used:

  • Color Scheme: Editor (file picker)
  • Color Scheme: Editor (new theme)
  • Color Scheme: Editor (current theme)
  • Color Scheme: Editor (pick installed theme)

Since I’m typically interested in modifying the theme that’s currently active, I usually use the current theme option. By default, CSE creates a temp folder (Packages/User/ColorSchemeEditorTemp) where it stores the modified version of the .tmTheme file and the associated .tmTheme-JSON file it uses internally. If you make any modifications to your current theme, the plugin automatically changes your preferences file to point to the temp folder’s copy – the original theme file itself isn’t modified. This can be changed by copying Packages/ColorSchemeEditor/color_scheme_editor.sublime-settings to your Packages/User folder and editing it there (make sure you keep the original!). In particular, setting "direct_edit": true will make changes to the original theme file, without creating the temp. Use at your own risk. The only exceptions to this are themes that reside in a .sublime-package archive in the Installed Packages folder (which is in the same parent directory as Packages) – since CSE can’t/won’t write inside these archives, a temp file will always be used.

Using the app itself is pretty self-explanatory. The first pane that opens up shows the global settings, for things like the activeGuide and stackGuide colors, caret, findHighlight, etc. Here’s as many as I’ve come across before (they’re all included in my Neon Theme):

  • activeGuide if indent_guide_options in your preferences contains draw_active, this is the color of the guide marking the innermost tab stop of the current indented section of your code where the caret is currently placed.
  • background the default background color of the text entry area.
  • caret the color of the caret (cursor).
  • findHighlight when using one of the Find options, a highlighted (found) piece of text has this color set as its background.
  • findHighlightForeground the color of the highlighted (found) text itself.
  • foreground the default text color.
  • guide if indent_guide_options in your preferences contains draw_normal, this is the color of the lines marking tab stops in indented sections of code. activeGuide and stackGuide override this color if draw_active is set. Both draw_normal and draw_active can be set at the same time.
  • inactiveSelection if text is selected, and the window loses focus, this is the color of the background of the selected text.
  • invisibles I’m not sure what this does. I have it set to bright green, and I can’t seem to see an effect anywhere…
  • lineHighlight if highlight_line is set to true in your preferences, this is the default background of the line containing the caret.
  • selection the background color of selected text.
  • selectionBorder the color of the 1-pixel border surrounding selected text.
  • stackGuide if indent_guide_options in your preferences contains draw_active, this is the color of the guides marking the tab stops at all indented sections of your code, out to the outermost line (not indented at all) where the caret is currently placed.

The second pane in CSE is Scope Settings. This is where all the scopes of a theme are listed, with their name, foreground and background colors, font style (bold and/or italic) and scope definition. There are buttons for moving individual scopes up and down, as well as for adding new and removing current scopes. To edit an existing one, just double-click on it and the editing window will pop up. In here are text boxes for name and scope definition, check boxes for bold, italic, and underline (even though underlining via color scheme isn’t supported in Sublime Text yet), and color boxes for both foreground and background. If you click on the color box your platform’s color picker appears, and once you’ve made your selection and closed it the current color is in the box, and its hex code is in an editable text box next to it, allowing you to manually enter colors if desired. If you don’t want either a foreground or background color, and just wish to go with the defaults as defined in the Global Settings pane, just delete the hex code and you’re all set. When you’ve picked your colors, hit the Apply button, and, if you’ve kept "live_edit": true in the color_scheme_editor.sublime-settings file, you’ll see your syntax highlighting in Sublime update in real time. This makes it easy to tell if you’ve gotten the right scope selector(s), and shows you your results in a larger context.

And that’s about it! ColorSchemeEditor allows very fine-grained control over individual colors and scopes, which makes it great for both tweaking existing themes and developing completely new ones. However, if you’d like to change all the attributes of a theme wholesale, such as applying a sepia tone, changing contrast and brightness, rotating the hue, etc., then there are a couple of other tools to check out. The first is @facelessuser‘s ThemeTweaker, which is a Sublime plugin. It takes some time to set up all the custom commands, although an example keymap is included, but the results are pretty cool once it’s ready. The second resource is @aziz‘s tmTheme Editor, which requires a pretty recent version of Google Chrome or Firefox to run due to its dependence on several HTML5 APIs that haven’t necessarily made it into other browsers (coughIEcough) yet. This is a graphical theme editor similar to CSE, and although it does have some drawbacks – for example, the regex engine isn’t the one used internally in Sublime, so not all scopes will look exactly the same, and the fonts aren’t configurable (yet) – it is a really good online alternative. You can enter your own test text, or you can pick from samples of JavaScript, CoffeeScript, HTML, CSS, Ruby, Java, and Python. Like ScopeAlways the current scope is shown on the bottom bar, allowing for customization on the fly. It also has some other cool features, like the ability to adjust brightness and contrast with sliders, and you can choose to invert, gray-scale, or sepia-tone the theme. One recent enhancement is the ability to just point at a piece of text, and the list of scopes in the theme will automatically scroll until the most relevant one is showing.

I hope all of this has been helpful. If you have any questions, just leave a comment below, or open an issue, and somebody should be able to help you. Good luck!

4 thoughts on “A Guide to Installing ColorSchemeEditor for Sublime Text 3

  1. Allen

    Hi Matt,

    I’m the developer of TmThemeEditor. Thanks for mentioning it. As you mentioned in the I tried to write the parser in javascript but I failed. the current version is using ruby with onuguruma regex parser and load precompiled text from the server.
    The future version, which I’m currently working on now, will have custom preview code feature by sending text to the server and parsing it with the ruby parser.

    1. Matt Morrison

      Hi Allen,
      I just checked out the most recent version of your site, and I really like it. The way you can just point at an element in the text, and it scrolls to the most relevant theme scope is really neat. The coloring tends to track with Sublime’s pretty well, although it’s not 100% – it probably never will be until Sublime is open-sourced 🙂 I haven’t used TextMate in a long time (since I’m very cross-platform these days), but I would imagine having its source available has been helpful. And speaking of cross-platform, I just noticed the app now works on Firefox! Awesome!

      One feature that would be neat to see that’s in ColorSchemeEditor – if you already have a color defined for foreground or background, there’s no way of just setting it back to null – you have to pick another color for it. For example, I have a scope that has a foreground and background color, and for some reason the background is bleeding into a bunch of other scopes. I’d like to remove it from the scope and see how it affects highlighting as a whole. Does that make sense?

      Anyways, keep up the good work, and I’ll keep on recommending people use your awesome resource! I see you have the source at https://github.com/aziz/tmTheme-Editor, I’ll have to look through it a little more deeply sometime.


  2. MattDMo Post author

    Code block:

    import sublime, sublime_plugin
    class ExampleCommand(sublime_plugin.TextCommand):
        def run(self, edit):
            self.view.insert(edit, 0, "Hello, World!")


    import sublime, sublime_plugin
    class ExampleCommand(sublime_plugin.TextCommand):
        def run(self, edit):
            self.view.insert(edit, 0, "Hello, World!")

Leave a Reply