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
Step by Step
- 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.
- 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.
- 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.
- 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.
- 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
- 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
specification document available as it describes the format, syntax, and
available tags that can be used in the style sheet.
Step by Step
- 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.
- 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.
A few important things to note about defining styles.
- The default_style should define all four of the attributes available
since it is used as the basis of the document.
- It is best to use the %(primary)s value for the font as this will
use the Primary Font choice from the users preferences.
- 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.
- 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.
- 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)
- 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.
- 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.
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
- 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.
- 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).