ScintillaNET

Table of Contents

• Introduction
• Installation
  • Downloading and Unzipping
  • Configuring the Search Path
  • Adding to the Visual Studio Toolbox
• History
  • Release 2.2
  • Release 2.0.1
  • Release 2.0
  • Release V6-b1.1 Beta
  • Release V6-b1 Beta

Introduction

ScintillaNET is a powerful text editing control for Windows Forms applications and a managed wrapper around the versatile Scintilla Windows control. Created with the developer in mind, the ScintllaNET API makes it simple to add advanced text editing and syntax highlighting to your application or IDE (Integrated Developer Environment). In addition ScintillaNET adds features not found in other Scintilla wrappers such as Visual Studio style code snippets, integrated find and replace dialogs, true regular expression searches, multiple key-command bindings, and back/forward document navigation.

The ScintillaNET project is hosted on CodePlex at the following URL: http://scintillanet.codeplex.com/. The most up-to-the-minute source code, binaries, and documentation can be found at that location.

Installation

The following guide is provided for users who wish to use the ScintillaNET control in their projects.

Downloading and Unzipping

The ScintillaNET team regularly publishes new releases as features are added and bugs are fixed. These releases can easily be obtained from the ScintillaNET Downloads page on CodePlex. Files are distributed in both binary and source versions and then zip compressed.

1. Download the binaries recommended release package from the ScintillaNET Downloads page by clicking the appropriate link and selecting I Agree from the license terms-of-use popup. (Other releases and versions maybe be available but we encourage you to download the "binaries" version of the recommended release unless you have a specific reason not to).
2. Unzip the package using a third-party tool or by right-clicking on the file/icon in Windows Explorer and selecting Extract All... from the context menu and following the wizard.
3. Once unzipped you'll want to place the files in a location where they can easily be referenced by any of the projects you wish to use ScintillaNET with. For the purposes of this guide, we'll assume that the target directory is C:\ScintillaNET.
   • If the previous steps were completed successfully you should have a folder on your computer with at least the files ScintillaNet.dll and SciLexer.dll. Other license files and documentation may be included as well.

Configuring the Search Path

Failing to configure the search path or doing it incorrectly trips-up many users. ScintillaNET is a wrapper around an umanaged DLL and uses Platform Invoke (P-Invoke) calls from the managed ScintillaNet.dll to the native SciLexer.dll to perform its magic. In order for that to work the SciLexer.dll must be in one of the places Windows uses to locate DLLs. More information about the Search Path Used by Windows to Locate a DLL can be found on the MSDN website. Of the many ways that Windows can use to find the SciLexer.dll, the instructions below illustrate how to modify your PATH environmental variable.

64 bit Windows

ScintillaNet now ships with an SciLexer compiled for 64bit: SciLexerx64.dll. ScintillaNet will load the appropriate version (at run time) based on the platform and and the process architecure of the host process. Note that Visual Studio itself is a 32bit process so both dlls are required for design time support even when developing on a 64bit version of Windows.

1. Right-click on the My Computer icon on the Desktop or in the Start Menu and select Properties from the context menu.
2. Select the Advanced tab.
3. Click the Environment Variables button.
4. Add the "C:\ScintillaNET" folder (assuming that is the location of the downloaded files, or substitute an alternate location) to the Path variable in the User Variables list.
   1. If there is no Path variable in the User Variables list, add one by clicking New and inputing the value "Path" in the Variable Name field and "C:\ScintillaNET" in the Variable Value field.
   2. If there is already a Path variable in the User Variables list, select the Path variable and then click Edit to modify. Append "C:\ScintillaNET" to the end of the Variable Value field separating it from any previous value(s) with a semicolon.
5. Close all open Visual Studio or Visual C# applications and restart them for the changes to take effect.

Adding to the Visual Studio Toolbox

Adding the ScintillaNET control to the Visual Studio (or Visual C# Express Edition) toolbox makes adding it to one of your forms as easy as dragging and dropping.

1. With the Windows Forms designer open in Visual Studio, right-click on the ToolBox window and select Choose Items... from the context menu.
2. From the Choose Toolbox Items dialog, select the .NET Framework Components tab and then click the Browse... button.
3. Navigate to the location of the ScintillaNet.dll file on your system ("C:\ScintillaNET\ScintillaNet.dll" in our example) and after selecting the file, click the Open button.
4. When the Open dialog closes, one or more ScintillaNET components will have been added to the list.
5. Ensure that the entry named "Scintilla" is checked and then click the OK button.
   • The Scintilla control should now be listed in the Toolbox. Simply drag it onto a form in the designer to begin using it.

Deployment

When deploying your application the managed ScintillaNet.dll must be made available to the host application. Typically this means having it in the same directory as the executable. GAC deployment and assembly binding can also work but is more complicated because of the unmanaged dll dependencies. The ScintillaNet team recommends that you do NOT deploy SciLexer.dll and SciLexerx64.dll to a shared location like the Windows System directory. Instead deploy to a path private to your application, like the application's installation directory.

History

Release 2.3 (In Development)

TBD

Release 2.2

10/21/2009
Chris Rickard

Primarily this is a bugfix release. Only a couple new features are included and they are there because they fix/workaround an existing issue.

Breaking Changes

• All members and strings containing WhiteSpace have been changed to Whitespace. Whitespace is the accepted spelling and is the spelling used by the .NET framework. (Ignore System.Xml.Schema.XmlSchemaWhiteSpace :) Along the same lines INativeScintilla.GetViewWS() changed to INativeScintilla.GetViewWs().
• Various members' access changed from public to private or internal. In these cases it didn't make much sense to expose them publicly so in theory noone should be using them thus this won't break anyones code.
• Most of the EventArg classes changed their properties to be read-only. This is consistent with the style used by the .NET framework. This may potentially break code, initialize all the variables in the constructor where appropriate. If there is a legitimate need to set an EventArg property after construction I'll add it back in.
• Markers and Lines.VisibleLines implementations were buggy and have been fixed. If you were using them before and made workarounds to compensate for the buggy behavior this will most likely break it.
• DwellEnd event changed from EventHandler to EventHandler<ScintillaMouseEventArgs>
• In the static Utilities class PtrToStringUtf8 and MarshalStr have been removed and replaced IntPtrToString.

New Features

• New property Caption sets the Win32 Window Text/Caption. This was introduced to make an elegant workaround. The Control.Text property is usually used but has proven to be problematic because of ScintillaNet's Text implementation. Also we don't want to load a 100mb file in the document then have Windows try to echo this property, it adds a ton of unneeded overhead. Caption now controls this completely, it defaults to the Scintilla control's Type Name (ScintillaNet.Scintilla unless subclassed) but can be changed.
• UseWhitespaceForeColor/UseWhitespaceBackColor control wether or not the corresponding Whitespace colors are used or inherit from the default style.
• Style class now has an indexer overload that takes a string. The style names are specific to each lexer and can be found in the ScintillaNet project under Configuration/BuiltIn/LexerStyleNames.
• SelectionForeColor/SelectionBackColor now supports the Transparent color. When Transparent selection colors don't override styled text colors. While this is inconsistent with other properties like WhitespaceForeColor that have a corresponding UseXXX property I think it's more intuitive and I may change the others in the future. Note that only Transparent is supported, alpha values in any other color are ignored.

Issues Fixed with this Release

Release 2.0.1

8/4/2008
Chris Rickard

For ScintillaNET core this is primarily a maintenance release. It is based off of changeset 34880 and includes a few bug fixes from the 2.0 release.

The big change with this release is that I've now included a setup file which should help new developers get started more easily. It copies the SciLexer.dll to the system directory and creates the registry entries to list Scintilla in the list of available components for the VS Toolbox.

I'm not including the source in this release, please take the latest from the Source Code tab.

Download and run the MSI to have the installer set up your development environment. NOTE if you already have SciLexer.dll in your system directory it will be overwritten with version 1.7.6, which is the latest Scintilla at the time of this release.

OR

Download the ZIP file if you want to do a manual installation, read the included readme.txt for instructions on how to set up your development environment.

Release 2.0

2/16/2008
Chris Rickard

This is the first release of ScintillaNET based off the 2.0 branch. The entire API has been re-written and is not compatible with 1x versions. All built in features of Scintilla are completely implemented with both a Scintilla like API (INativeScintilla) and an abstracted API that hides much of the flat API nature of Scintilla (Scintilla control). Many common things that were difficult to do with ScintillaNET 1x are now made easier with the new API. Also many new features that are not inherent with by Scintilla have been added. These include Print Preview, Find and Replace dialogs (with full regular expression support!), GoTo line dialog, document navigation, drop markers (like CodeRush), (Visual Studio-like) Code Snippets.

The majority of Scintilla's properties can be designed using the Windows Forms designer property grid. This is probably the easiest way to get started with many of the features, as you get immediate feedback of changes.

Lastly a brand new configuration system has been created. It uses a multiple layered configuration approach that is both very powerful and very easy to get started with.

Documentation is still non-existent. I promise it will start trickling in. For now the best way to learn is to open up the SCide example project and see what it does.

Read the readme.txt included in both downloads for instructions on how to get started in setting up your development environment.

Release V6-b1.1 Beta

3/11/2007

This release uses the DockPanel suite to implement a MDI interface. It also supports the SciTE configuration file format, allowing syntax highlighting/folding support for most code formats.

There are still quite a few items in progress, but I thought it was a good time to give everyone a sample of what we've been working on.

Release V6-b1 Beta

1/30/2007

The v6-a1 was the first public CodePlex release and I feel we are way past due for another :D

Beta 1 mainly features a full basic Scintilla implementation and a good basic event system.

Higher level features included in this release are Smart Indenting and built in Find and Replace Controls/Dialogs for your enjoyment. See Release notes for full details.

Sorry but no help yet. *Maybe* by b2 I'll have gone through and added all the XML comments then use an SCDoc project to generate the reference chm.