How do I use my own configuration files?
ScintillaNET uses simple XML files to automatically set its vast amount of properties. To ScintillaNET a
language can be thought of as a named configuration. The entire configuration scheme is very flexible and allows for a very fine degree of control. In this topic however I'll describe the most common scenario: Using ConfigurationManager.Language + ConfigurationManager.CustomLocation to load your own configurations.
While the entire loading process of the ConfigurationManager is a topic in of itself here is what happens
by default, whenever the ConfigrationManager.Language property is set:
- Scintilla's built in default configuration is loaded
- If found, the built in configuration for the language is loaded
- If found, the Custom default configuration is loaded
- If found, the Custom language configuration is loaded
- If found, the user's default configuration is loaded
- If found, the user's language configuration is loaded
So what you need to do is supply a value for ConfigurationManager.CustomLocation. CustomLocation is a path, you have the option of either supplying a file name or a folder name.
Lets start with using a single file:
If you choose to use a file name, all your configurations must be in this file. This can be an absolute path, like "c:\MyApp\ScintillaNET.xml" or it can be a relative path like "ScintillaNET.xml". Relative paths are loaded relative to
your executing assembly.
So lets say you have a Windows Forms application loaded in visual studio and a form with a ScintillaNET control on it.
Add a new XML file to your project, name it ScintillaNET.xml
Look at the properties of the file, change the value of "Copy to Output Directory" to "Copy if newer". This way the configuration file gets copied to bin/debug, otherwise the file won't be found during debugging.
Edit ScintillaNET.xml and set it to the following
<?xml version="1.0" encoding="utf-8" ?>
<ScintillaNET>
<Language Name="default">
<Styles>
<Style Name="Default" FontName="Consolas"/>
</Styles>
</Language>
<Language Name="pascal">
<Indentation TabWidth="2" UseTabs="false"/>
<Lexer StreamCommentPrefix="{ " StreamCommentSuffix=" }">
<Keywords List="0">var</Keywords>
<Keywords List="1">string</Keywords>
</Lexer>
<Styles>
<Style Name="CHARACTER" ForeColor="Black" BackColor="Red"/>
</Styles>
</Language>
</ScintillaNET>
In this configuration file we specified two languages, the first is default, the second pascal. The default configuration is always loaded for any language, and the pascal configuration is loaded when the Language is set to pascal. As you can see we set the default font to Consolas. We did this in the default configuration so that it will be applied to all languages, if we were to place it in the pascal config it would only be loaded for the pascal language. The full schema of the configuration files is not yet documented but you can use the existing built in configurations as a guide.
Now to use this configuration load the form hosting ScintillaNET in the Windows Forms designer. In the property explorer expand ConfigrationManager. Set the CustomLocation property =
ScintillaNET.xml and Language property =
pascal.
Now run the program. In the ScintillaNET control enter the following text:
var s : String[5];
s := 'test';
First notice that the Font has changed from the default Courier New to Consolas (assuming the font is loaded on your PC). Now look at the syntax highlighting.
var should be blue,
5 orange, and
'test' black with a red background. Even though we only specified the CHARACTER style the others picked up styles from the built in default. The pascal language isn't even configured in the built in languages configuration, but the built in default has styles defined for many of the common lexer styles. This means when building your own configuration files you should start off by looking at what the default styling is for your given language, then configure only the changes you want to make.
Also notice that it's not just styles that have changed, if you hit the tab key notice that it inserts 2 spaces. Also if you invoke the Lexing.StreamComment() method it will insert Pascal style comments { xxx }.
CustomLocation can also be a folder path. In this case ScintillaNET attempts to find files name
language.xml in the folder specified by CustomLocation. So say you had a subfolder relative to your application called "My Styles". In this folder you would put default.xml and pascal.xml.
default.xml:
<?xml version="1.0" encoding="utf-8" ?>
<ScintillaNET>
<Language Name="default">
<Styles>
<Style Name="Default" FontName="Consolas"/>
</Styles>
</Language>
</ScintillaNET>
pascal.xml:
<?xml version="1.0" encoding="utf-8" ?>
<ScintillaNET>
<Language Name="pascal">
<Indentation TabWidth="2" UseTabs="false"/>
<Lexer StreamCommentPrefix="{ " StreamCommentSuffix=" }">
<Keywords List="0">var</Keywords>
<Keywords List="1">string</Keywords>
</Lexer>
<Styles>
<Style Name="CHARACTER" ForeColor="Black" BackColor="Red"/>
</Styles>
</Language>
</ScintillaNET>
Now change CustomLocation to "My Styles". The exact same behavior should appear at the end, this is just an alternative way to organize your configuration files.