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:
  1. Scintilla's built in default configuration is loaded
  2. If found, the built in configuration for the language is loaded
  3. If found, the Custom default configuration is loaded
  4. If found, the Custom language configuration is loaded
  5. If found, the user's default configuration is loaded
  6. 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.

Last edited Oct 16, 2009 at 8:43 PM by ChrisRickard, version 3

Comments

Lewtwo Nov 2, 2013 at 4:43 PM 
Another problem that is not mentioned is when you set the ConfigurationManager.Language
you must have a XML file for each and every language. Other wise you will get:

System.IO.FileNotFoundException was unhandled FileName=C:\ScintillaNET\XML\
Message=Could not find the custom configuration file.
Source=ScintillaNET

It would have been better to check for the existence of the file and default back to the internal sources since there are so few XML files available and there is precious little documentation on creating new ones.

ChrisRickard Apr 5, 2011 at 5:09 AM 
xorcist: Yes better range checking should be done. However the # keyword lists is dictated by the Scintilla native component. It's always 9 no matter what :)

ChrisRickard Apr 5, 2011 at 5:07 AM 
McArrow: The language config setting is used to determine what lexer Scintilla uses to highlight with. It has to be a language Scintilla knows about, and it will follow that language's rules. Also depending on a number of factors Unicode text tends to throw things off as well.

ChrisRickard Apr 5, 2011 at 5:04 AM 
trashhead: What you want to do is WAAAYYY beyond what ScintillaNET can do out of the box. At most you can get pretty colors from JavaScript code and set up a pre-canned list of AutoComplete items. What you want is basically a compiler that can take JavaScript fragments and give you structured source tree for any given context.

ChrisRickard Apr 5, 2011 at 4:59 AM 
spyke1: Yes, for Pascal "String" and "var" are both keywords. For example purposes I marked "string" to be styled using the 2nd Pascal keyword list "Classes".

spyke1 Feb 18, 2010 at 2:57 AM 
The example is a bad one. All of the keywords should be under one element like so: <Keywords List="0">var begin string etc...</Keywords>

trashhead Feb 15, 2010 at 10:30 AM 
Dont know if i misunderstood the meaning of the configuration file but I would like to do the following:
I have a program which interprets javascript code. In this code there are some objects added to the scripting environment.
For example, I have a static object called _work, this object contains a couple of fields and functions. How can I add autocompletion for this so that the user can easily see what fields and functions there is for the object ?

MinkoSoft Oct 29, 2009 at 1:55 PM 
When the full documentation will come out?

xorcist Sep 10, 2009 at 9:12 AM 
There is a logical bug in file "Lexing.cs" beginning from line 513 which will cause "IndexOutOfRange" exception:
<code>
private string[] _keywords = new string[] { "", "", "", "", "", "", "", "", "" };

public string this[int keywordSet]
{
get
{
return _keywords[keywordSet];
}
set
{
_keywords[keywordSet] = value;
NativeScintilla.SetKeywords(keywordSet, value);
}
}
</code>

As you can see, the string array "_keywords" is staticly dimensioned to 9, so if you try to define more than 9 keywords in the XML file you will get the exception.

Regards

PuyanLotfi May 13, 2009 at 6:17 AM 
I'm having the same issues with this: automatic highlighting stops working. It seems I have a choice between syntax highlighting and the font I want.

McArrow Mar 18, 2009 at 12:04 PM 
i have some problems using this example...
1 - automatic highlighting stops working when i change Language Name="pascal" to any other.
2 - even if i leave Language Name="pascal" and change <Keywords List="0">var</Keywords> "var" to "йцу" or any other - it stops working again.

DKIMZEY Nov 9, 2008 at 12:01 PM 
1. The install for ScintillaNet control does not include any of the xml files with keywords for standard languages. To obtain these you must download the source control
and look in the \Branches\2.0\ScintillaNet\Configuration\Builtin folder.