SciTE Documentation

Standard Editing

Text editing in SciTE works similarly to most Macintosh or Windows editors with the added feature of automatic syntax styling. SciTE can hold multiple files in memory at one time but only one file will be visible. Rectangular blocks of text can be selected in SciTE by holding down the Alt key on Windows or the Ctrl key on GTK+ while dragging the mouse over the text. The modifier key used on GTK+ can be changed with the rectangular.selection.modifier property.

There are two panes in SciTE, the editing pane and the output pane. The output pane is located either to the right of the editing pane or below it. Initially it is of zero size, but it can be made larger by dragging the divider between it and the editing pane. The Options | Vertical Split command can be used to move the output pane beneath the editing pane.

SciTE can perform commands to compile or run source files with the output from these commands directed into the output pane.

For example, if Python is installed on the machine, open a new document, type:

print "Hi"

as that document's text.

print "hi"

>python -u printhi.py
hi
>Exit code: 0

SciTE partially understands the error messages produced by Python, GCC, Visual C++, Borland C++, PHP and other tools which use the same format as one of these. To see this, add a mistake to the Python file by adding a second line to make the file:

print "hi"
mistake

Perform the Tools | Go command. The results should look like:

>python -u printhi.py
hi
Traceback (innermost last):
  File "printhi.py", line 2, in ?
    mistake
NameError: mistake
>Exit code: 1

While it is easy to see where the problem is in this simple case, when a file is larger the Tools | Next Message command can be used to view each of the reported errors. Upon performing Tools | Next Message, the first error message in the output pane is highlighted with a yellow background, and an error indicator is displayed for the appropriate line in the editing pane. The caret is moved to this line and the pane is scrolled if needed to show the line. SciTE now looks like this:

SciTE understands both the file name and line number parts of error messages in most cases so can open another file (such as a header file) if errors were caused by that file. This feature may not work where the file name is complicated by containing spaces or ".."

If command execution has failed and is taking too long to complete then the Tools | Stop Executing command can be used.

Command subsystem

Tools can be executed in various modes by SciTE which are called "subsystems". Different subsystems are supported on Windows, GTK+ and OS X. The default subsystem is 0.

Command line arguments

Command line arguments to SciTE include file names, commands and properties. Commands and properties are preceded by "-" and are differentiated by the use in commands of ':' as the first character that is not '.' or alphabetic. Properties use the syntax used in property set files and override any properties set in property files. If there is no value given for a property, it is set to 1. Double quotes may be placed around arguments that contain spaces but they must be placed around the whole argument, not just around a file name, so "-open:x y.txt" works but -open:"x y.txt" doesn't. On Linux, the standard shell quoting is available. The "-p" argument causes SciTE to print the file and then exit.

For Windows:
The command line arguments "-" and "--" (without the quotes) are special in that they read the stdin stream into the last buffer ("-"), or the output pane ("--"))
The command line argument "-@" (without the quotes) is special in that file names are read from stdin and opened.
Note: when reading stdin into the output pane, when the property split.vertical is 0, the output pane is increased to its maximum height. When the property split.vertical is 1, the output pane is increased to approximately half of the screen width.
Note: If stdin is not redirected, these arguments are effectively ignored.

A few commands are currently available although this will expand in the future. These commands are available:

Command line arguments are evaluated left to right in two phases because opening files requires the user interface to be available and there is also a need to set some user interface properties before the user interface is displayed. The first phase process arguments until just before the first file name would be opened. The second phase processes the remaining arguments.

So, if you need to perform e.g. a find: or a goto: command on a file, you must put the command after the filename, to allow SciTE to open the file before performing the command.

For Windows:
If any simple file name on the command line matches a directory name, the file open dialog appears - this is dependent upon the property "open.dialog.in.file.directory"

If the property "buffers" is greater than one and the file name matches either a existing file or by means of a wildcard search, one or more files, the matching files are loaded up to the property "buffers" count. Directories are not considered a match in this case

If the file name is an extension, optionally preceded by a path, and no such simple file name exists, the file open dialog appears, with the given extension as the filter.

If the file name contains no extension, the property "source.default.extensions" is used to provide default extensions to attempt to match the file name to an existing file.

Buffers

SciTE may be configured to use between 1 and 100 buffers each containing a file. The default is 1 and this effectively turns off buffers. With more than one buffer, the Buffers menu can be used to switch between buffers, either by selecting the file name or using the Previous (F6) and Next (Shift+F6) commands. A tab is displayed for each buffer in the tab bar although this can be turned off with the View | Tab Bar command. A tab may be closed by clicking on it with the middle mouse button. Setting large numbers of buffers may cause problems as some menus are fixed in length and thus files beyond that length may not be accessible.

When all the buffers contain files, then opening a new file causes a buffer to be reused which may require a file to be saved. In this case an alert is displayed to ensure the user wants the file saved.

Sessions

A session is a list of file names. You can save a complete set of your currently opened buffers as a session for fast batch-loading in the future. Sessions are stored as properties files with the extension ".session".

Use File | Load Session and File | Save Session to load/save sessions. You can turn on/off "last session autoloading" using SciTE properties variable "save.session".

If "buffers" variable is set to "0" session management is turned off.

Loading previously saved session will close your currently opened buffers. However you will not lose your edits, because you will be asked to save unsaved buffers first.

Opening a specific file from command line overrides "save.session" variable state. When you start SciTE loading a specific file from command line last session will not restore even if "save.session" variable is set to "1". This makes "save.session" safe to use - you will never open a couple of files when you are trying to open just one, specific file.

By setting "session.bookmarks" and "session.folds" variables bookmarks and folding states of the currently opened buffers are saved in session files and restored when sessions are loaded.

Languages understood by SciTE

SciTE currently is able to syntax style these languages (* denotes support for folding):

• Abaqus*
• Ada
• ANS.1 MIB definition files*
• APDL
• Assembler (NASM, MASM)
• Asymptote*
• AutoIt*
• Avenue*
• Batch files (MS-DOS)
• Baan*
• Bash*
• BlitzBasic*
• Bullant*
• C/C++/C#*
• Clarion*
• cmake*
• conf (Apache)*
• CSound*
• CSS*
• D
• diff files*
• E-Script*
• Eiffel*
• Erlang*
• Flagship (Clipper / XBase)*
• Flash (ActionScript)*
• Fortran*
• Forth*
• GAP*
• Gettext
• Haskell
• HTML*
• HTML with embedded JavaScript, VBScript, PHP and ASP*
• Gui4Cli*
• IDL - both MSIDL and XPIDL*
• INI, properties* and similar
• InnoSetup*
• Intel HEX*
• Java*
• JavaScript*
• LISP*
• LOT*
• Lout*
• Lua*
• Make
• Matlab*
• Metapost*
• MMIXAL
• MSSQL
• nnCron
• NSIS*
• Objective Caml*
• Opal
• Octave*
• Pascal/Delphi*
• Perl, most of it except for some ambiguous cases*
• PL/M*
• Progress*
• PostScript*
• POV-Ray*
• PowerBasic*
• PowerShell*
• PureBasic*
• Python*
• R*
• Rebol*
• Ruby*
• Scheme*
• scriptol*
• Specman E*
• Spice
• Smalltalk
• SQL and PLSQL
• S-Record
• TADS3*
• TeX and LaTeX
• Tcl/Tk*
• VB and VBScript*
• Verilog*
• VHDL*
• XML*
• YAML*

Running and building commands for some of these languages have been set up but should be checked as they will have to be modified to work for many people.

To keep menus to a reasonable length some languages are included but have been commented out in global options. These should be enabled by removing the comment character '#'.

Language settings are determined from the file extension but this can be changed by selecting another language from the Language menu. The language menu can be changed with the menu.language property.

Find and Replace

Either dialogs or strips may be used for find and replace, with dialogs being the default. Strips are similar to find in web browsers, appearing at the bottom of the window and are smaller and less distracting than dialogs. They are specified with the find.use.strip and replace.use.strip properties.

SciTE has options to allow searching for words, regular expressions, matching case, in the reverse direction, wrapping around the end of the document. C style backslash escapes which are listed in the command line arguments section, may be used to search and replace control characters. Replacements can be made individually, over the current selection or over the whole file. When regular expressions are used tagged subexpressions can be used in the replacement text. Regular expressions will not match across a line end.

SciTE supports basic regular expressions with tagging.

On Windows, pressing Shift+Enter when the focus is in a text entry field will search in the opposite of the current direction, so will normally search backwards.

Keyboard commands

Keyboard commands in SciTE mostly follow common Windows and GTK+ conventions. All movement keys (arrows, page up/down, home and end) allow to extend or reduce a stream selection when holding the Shift key, and a rectangular selection when holding the Shift and Alt keys. Some keys may not be available with some national keyboards or because they are taken by the system such as by a window manager on GTK+. The user.shortcuts setting may be used to assign a key to a function. Note that Home key behaviour is changed by the vc.home.key option. Keyboard equivalents of menu commands are listed in the menus. Some less common commands with no menu equivalent are:

On Windows, a search can be performed in the opposite direction by using Shift+Enter in the Find or Replace strips or dialogs.

Abbreviations

To use an abbreviation, type it and use the Expand Abbreviation command or the Ctrl+B key. The abbreviation is replaced by an expansion defined in the Abbreviations file. You can open the Abbreviations file with a command in the Options menu and add abbreviations. There is a default abbreviations file but a different abbreviations file can be set for particular file extensions.

Each line in the files looks like "abbreviation=expansion".
The abbreviations names can have any character (except perhaps control chars, surely for CR and LF), including high Ascii chars (accented chars).
Names have properties files limits: they cannot start with sharp (#) or space or tab (but can have spaces inside); and they cannot have '=' character inside.
Abbreviations names are limited to 32 characters. It is probably enough for abbreviations...

An expansion may contain new line characters indicated by '\n' and a caret position indicated by the '|' character. To include a literal '|' character, use '||'.
Some simple examples are included in the distributed Abbreviations file.
When expanding, the names don't need to be separated from the previous text. Ie. if you define 'é' as 'é', you can expand it inside a word.
When multiple abbreviation names match, the longest matching name will be expanded.

Folding

SciTE supports folding for many languages (see the list of languages understood by SciTE for more information.) Fold points are based upon indentation for Python and on counting braces for the other languages.

The fold point markers (in the fold margin) can be clicked to expand and contract folds. Normal clicking does not alter the fold state of child fold points; naturally the children are hidden when the parent fold is contracted, but when the parent is expanded again, each child is still folded or not, as before.

Ctrl+Click on a fold point toggles it and performs the same operation on all children.

Shift+Click on a fold point does not toggle that fold, it expands all the child folds.

Ctrl+Shift+Click in the fold margin expands or contracts all the top level folds. "Toggle all folds" in the View menu does the same; it toggles only top-level folds.

Tip: To open a large code block with all its children folded, fold it with Ctrl+Click, then open it with a normal click. Then on opening a child fold, you will see that the grandchild folds are still closed; if you want those 'grandchild' folds open, Shift+Click the child fold.

Properties file

Much of SciTE's behaviour can be changed by editing the properties files.

There are four properties files used:

• Local properties file called "SciTE.properties" which may be present in the same directory as the file being edited.
• Directory properties file called "SciTEDirectory.properties" which may be present in the same or in a parent directory as the file being edited.
• User properties file called "SciTEUser.properties" on Windows and ".SciTEUser.properties" on GTK+
• Global properties file called "SciTEGlobal.properties"

Settings in the local properties file override those in the directory properties file which overrides those in the user properties file which override those in the global properties files. Environment variables are also available as properties and these are overridden by an explicit setting in one of the properties files.

The directory properties file can be used as project options file where user commands and compile, build commands should work in the same manner in subdirectories of a project. The benefit is that local properties files in subdirectories can be replaced by one properties file which is located at the root of the project. The evaluation of the directory properties file is disabled by default and must be enabled by setting the variable properties.directory.enable to 1 in the user or global properties file.

The user properties file is intended for customisation by the user, leaving the global properties file to contain the default options distributed with SciTE. The main use of the local properties files is to change the effects of the Compile, Build and Go commands for the files in a directory. For example, I use the javac compiler from the Java Development Kit for most work, so SciTEGlobal.properties sets the command for compiling .java files to "javac". If I want to use the jvc compiler for the files in one directory, then the SciTE.properties file in that directory contains an entry setting the command to "jvc".

On Windows, the global properties file is located in the directory of the executable. The user properties file is looked for in the user profile directory as set in the USERPROFILE environment variable, or in the directory of the executable if USERPROFILE is not set. For GTK+ the user properties file is found in the user's home directory and the global properties in a directory set at build time - normally /usr/share/scite. If the "SciTE_HOME" environment variable is set on either Windows or GTK+ then it is where both the global and user properties files are found.

There are commands in the Options menu for opening each of the properties files.

The files are in approximately the same format as Java properties files which have a simple text format. Lines that start with '#' or that are completely blank are comments. Other lines are of the form

variable=value

For long values, a '\' character at the end of the line continues that value on the next line. Space characters are significant so x =1 defines a variable called "x ". Values may include the values of other variables by using $(variablename). There are some variables set by the environment to access the name of the current file as well:

Some features use file name patterns to see which variable to use. For example, the lexer variable can be specialised for a particular file, or a group of files based upon wildcard matching so:
lexer.makefile=makefile indicates that the lexer called "makefile" should be used on files called "makefile".
lexer.*.cxx=cpp indicates that the lexer called "cpp" should be used on files with a "cxx" extension.
Variable substitution is available on the left hand side of file pattern assignments and look like this:
file.patterns.html=*.html;*.htm;*.asp;*.shtml
command.go.$(file.patterns.html)=file://$(FilePath)

Wildcard matching only works where the wildcard is at the start of a file specification, so "*.mak" will match "proj.mak" but "Makefile*" will not match "Makefile.in".

Properties files are not treated as having a particular encoding, however individual property values may be treated as having an encoding. For file names, commands, and user interface text, this is UTF-8 so it may be easier to edit properties files as UTF-8 by inserting a coding cookie as explained later. Other properties may be treated as byte sequences (like word.characters.filepattern) or in an implicit encoding (such as keywords.filepattern matching the document encoding) so that it may be better to edit these settings using a non-UTF-8 encoding. Where both UTF-8 and non-UTF-8 values are wanted, two files can be used with different encodings and an import statement to include one in the other.

Importing properties files and conditional logic

The 'import' statement includes a properties file as if the text were inline at that point. The imported properties file is either relative to the base file or absolute and a '.properties' extension is assumed. Therefore an "import Lua" statement in c:\os\scite\bin\SciTEGlobal.properties will import c:\os\scite\bin\Lua.properties. Any import statements in imported files are relative to directory of the original file, rather than the current file.

All of the properties files in a directory can be imported with "import *". This does not import generic properties files like user properties or abbreviations. The set of files that are imported can be controlled with the imports.include and imports.exclude properties.

Imported files are not scope walls: properties may be redefined in another file. Thus, if a file contains both "import cplusplus", "import java", and "style.cpp.1=fore:$(comment.colour)" then cplusplus.properties contains "comment.colour=#800000" and java.properties contains "comment.colour=#008000" then the last definition wins and is active for the definitions in the base file as well as any definitions in cplusplus.properties and java.properties.

The 'if' statement takes one argument which is a symbol that may be defined earlier in this property set file or in a base property set. If the symbol evaluates to '0' then the test fails. An empty string or not present symbol evaluates to 0. Into the very top property set is inserted one of 'PLAT_GTK' with value '1', 'PLAT_WIN' with value '1', or 'PLAT_MAC' with value '1'. For both PLAT_GTK and PLAT_MAC, 'PLAT_UNIX' is inserted with value '1'. If the test succeeds then following indented statements are executed. When a non-indented statement is found the if clause is finished. Only simple set statements are allowed in if clauses. The evaluation of if statements occurs at read time, not at evaluation time.

Command parameters and prompting

SciTE has 4 properties $(1) .. $(4) which can be used to run commands with changeable parameters. To set the parameter values, use the View | Parameters command to view the modeless Parameters dialog which shows the current values of these parameters and allows setting new values. The accelerator keys for the main window remain active while this dialog is displayed, so it can be used to rapidly run a command several times with different parameters. Alternatively, a command can be made to display the modal Parameters dialog when executed by starting the command with a '*' which is otherwise ignored. If the modeless Parameters dialog is already visible, then the '*' is ignored.

Encodings

SciTE will automatically detect the encoding scheme used for Unicode files that start with a Byte Order Mark (BOM). The UTF-8 and UTF-16 encodings are recognised including both Little Endian and Big Endian variants of UTF-16.

UTF-8 files will also be recognised when they contain a coding cookie on one of the first two lines. A coding cookie looks similar to "coding: utf-8" ("coding" followed by ':' or '=', optional whitespace, optional quote, "utf-8") and is normally contained in a comment:

For other encodings set the code.page and character.set properties.

Defined variables in properties files

Some properties are only available on Windows, GTK+, or. OS X.

caret.policy.{x|y}<param> interaction:

Indicator definition

Properties that define indicators look like

The structure uses commas between attributes and a colon between an attribute name and value:

Samples:

Supporting a new language

For languages very similar to existing supported languages, which may only differ in a minor feature such as the keywords used, the existing lexers can often be reused. The set of keywords can then be changed to suit the new language. Java and JavaScript could have reasonably reused the C++ lexer. The Java lexer was added only to support doc comments.

For languages that can not be lexed with the existing lexers, a new lexer can be coded in C++.  These can either be built into Scintilla, or put into an external module and loaded when SciTE runs (See lexerpath).

The open.filter should be modified to include the file extensions used for the new language and entries added for command.compile, command.build, command.go and command.go.needs for the language.

Creating API files

The .api files can be generated by hand or by using a program. There are also downloadable ready-to-use .api files.

For C/C++ headers, an API file can be generated using ctags and then the tags2api Python script (which assumes C/C++ source) on the tags file to grab complete multiple line function prototypes. Some common headers surround parameter lists with a __P macro and may have comments. The cleanapi utility may be used on these files.

To generate an API file for Python modules, there is a gen_python script.

To generate an API file for Java classes, there is a ApiBuilder.java program.

Open Selected Filename

This command opens the file for the file name selected in either the edit or output pane. It uses the current selection or searches around the caret to try to find a file name based on which characters are normally used in a path. If there is no extension then an extension may be inferred from the current file using the open.suffix property which defaults to .properties in a .properties file. If the file name is followed by a number (in a format similar to ctags, grep output, or Visual Studio messages) then that line is displayed in the opened file. If the file name is an absolute path then it is opened directly otherwise it is looked for in the current directory and then in the directory specified by the openpath property. On Windows, web, ftp, mail and news URLs are handled by opening their associated application.

SciTE in other languages

SciTE can be and has been translated into other languages.

Building SciTE

The procedure for building and installing SciTE is described in the README file in the scite directory.

Extending SciTE

There are two formal extension interfaces for SciTE, the SciTE Extension Interface is for extending SciTE with code compiled into the SciTE executable and the SciTE Director Interface is for manipulating SciTE on Windows from another application.