Home

Using Editra Style Sheets

Fri, 11/07/2008 - 02:03 — cody

Style Sheet Intro:


  Editra Style Sheets are a means by which the coloring/style scheme used to display code in the editor can be customized. They act as an abstraction layer on top of the way Scintilla configures style settings.

  Basically you can think of Editra Style Sheets (here in referred to as ESS) as being both similar in form and function to what Cascading Style Sheets are used for when styling a webpage. An ESS defines a set set of tags with given attributes that are used to display specific areas of text in highlight-able document. This document will discuss how to use/make and modify ESS's to customize the syntax highlighting of the editor to your liking.


Option 1: Using the Style Editor


  The Style Editor is a built in tool for creating custom style sheets. It allows you to begin defining your style sheet by using one of the existing sheets as a base or by starting with a completely blank slate. It also has a preview window which can display a test file for any of the supported languages. The preview window also serves to show which segments of code in the document use what tags, by clicking in a region of text in the preview window the corresponding tag will be selected in the above edit controls. Shown below is a screenshot of the Style Editor for reference in the following walkthrough.

Edtira's Style Editor

Step by Step

  1. Choose a starting point. Select an existing color scheme from the "Style Theme" drop-down box to start from or click on "New" to start from with blank style set.
  2. Select a preview file from the "Syntax Files" list to use in the Preview portion of the window. Styles created in this dialog will apply to all supported languages but it is often helpful to use a preview file that you are familiar with so that you know what the different text regions represent.
  3. You are free to start wherever you want but starting by defining the "default_style" tag is usually the best point to start from as it usually defines most of the documents presentation. Also all undefined style attributes in other tags will inherit the values from this style.

    • The "Foreground" button is used to define the color of the text
    • The "Background" button is used to define the color of the background behind a section of text. Its usually best not to define this and let it inherit from the default_style unless you have a better reason to do so.
    • The "Attributes" section contains some extra styling options that can be applied to the given region.
    • The font settings are are used to customize the font face and size used in a given section. Its best to use one of the %(xxx)s type values here as it will allow the style sheet to be compatible with all systems that the editor runs on. If you are only planning to use the sheet one system then feel free to use any of your favorite fonts here.
  4. Once you have defined the default_style just repeat the above step for each of the tags that you want to define. By either clicking on a section in the preview to get the next tag to work with or by working your way down the list.

  5. Once you have defined all the tags that you think are needed you may want to change the preview file to see how the styles look in different document types and also to see if there are some tags that you may not have defined from the previous. This step is important because not all lexers use every tag that is available.
  6. This is the last step. Click on the Export button to export your new style sheet and save it. If you don't export it you will loose all work you put into customizing the style set so be sure you click Export before closing the dialog. When you click Export a File Dialog will pop open. It will by default show the correct directory that you should save the sheet in so that Editra can find it, so type in the name of what you want to call your new style and click "Ok".

  Exporting the style sheet will automatically set it as your prefered style to use in the editor and update all open buffers to use it. If you want to change this from being the default open the Preferences Dialog and go to Document->Syntax Highlighting and change the selection in the "Color Scheme" combobox to the one you wish to use.

Note: If you saved the file with the same name as an existing one thats bundled with Editra (i.e Default, Midnight) then your style will override the system provided one. If you wish for the provided styles to still be available either rename your file or remove it from your config directory.


Option 2: Edit by Hand


  Editra Style Sheets are also relatively easy to create by hand, due to the simple and easy to read syntax they use. If you use Editra to edit/create your style sheet there is even highlighting and basic error checking available. Before starting you may want to have the technical specification document available as it describes the format, syntax, and available tags that can be used in the style sheet.

Step by Step

  1. To get started I suggest to make a copy of the default style sheet and use it as a template. The easiest way to do this is to open the Style Editor from the Tools Menu and Export a copy of the default style sheet to your Desktop. Alternatively you can also copy the file from the installation directory.
  2. Starting with the "default_style" tag is usually the best place to begin as it defines the baseline for most of the document as well being the style that all other undefined attributes in other tags will inherit values from. Shown below is the default_style definition as it appears in the default.ess style sheet. 
    default_style {  
            fore: #000000;
            back: #F6F6F6;
            face: %(primary)s;
            size: %(size)d;
}
    A few important things to note about defining styles.

    1. The default_style should define all four of the attributes available since it is used as the basis of the document.
    2. It is best to use the %(primary)s value for the font as this will use the Primary Font choice from the users preferences.
    3. The size of the font can also be defined using a format string %(size)d but you could also just specify the point size of font you want by putting a number here in instead.
    4. There are some additional style options that can be applied to the the main attributes by adding a modifier to the attribute line. The available modifiers are described in the Specifications Document, but here is a quick list for reference (bold, italic, underline, eol). Note that only one modifier can be specified per attribute. If you want to combine multiple modifiers they need to specified one per attribute on separate lines.
    5. There are also some special tags that are used to define special areas.
      • ctrl_char (defines how the whitespace characters are styled)
      • line_num (defines the style of the line numbers in the left column)
      • calltip (defines the style of the calltip window.)
      • margin_style (defines the fore/background of the two left most margins).
      • selection_stye (defines background color of text selection)
      • whitespace_style (defines style of whitespace markers)
  3. Now the next step is to define all the other tags that you want to be presented in different way than the "default_style" tag. Since all undefined attributes will inherit from the the default style you only need to define the attributes that you want to appear differently. This is usually just the "fore" and "back" attributes.

  4. Once you have a fairly complete sheet you will probably want to try loading it in the editor to see if it is parsed properly and also to check if the text is being presented as you want it to be. In order for Editra to load your style sheet you must place it at one of the following two paths. 
        $HOME/.Editra/styles/$YOUR_SHEET$
    $INSTALL_DIR/Editra/styles/$YOUR_SHEET$
    You should probably test it under a few different file types to see if it works well in other languages as well. Any parse errors that occur can be seen in the Editra Log
  5. There are some additional notes in the next section that you may want to look at but at this point your new style should be complete.


Additional Notes


  • Style sheets installed into the user config directory (i.e ~/.Editra/styles/) take precedence over any sheets that are bundled with the editor in the installation directory. This is only important if you chose to name your custom sheet with the same name as one of the existing ones.

  • The next enhancement of the Edtira Style Sheet specification will also include the capability to define styles that only apply to a given lexer through a tag class schema as well as allowing what tags are used by what lexers to be defined.

If you design a style sheet that you are fairly fond of and feel like sharing it, feel free to send it to me or post it at the Community Page. If its a complete and well defined style that works cross platform it may even be included in a future release of Editra (with your permission of course).