EDITOR MANUAL

Standard Editing

Text editing works similarly to most editors with the added feature of automatic syntax styling. The editor can hold multiple files in memory at one time but only one file will be visible. The editor's initial configuration only allows one file to be in memory at once but this can be modified by changing the value of the buffers property. Rectangular regions of text can be selected in the editor by holding down the Alt key on Windows or the Ctrl key on GTK+ while dragging the mouse over the text.

There are two panes in the editor, 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 Edit | Vertical Split command can be used to move the output pane beneath the editing pane.

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

For example, open a new document, type:
    print "Hello"

>si printhi
hello
>Done

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

print "hello"
mistake

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

>si printhi
syntax error
    

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.

The editor 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.

On Windows, the editor defaults to executing tools as command line programs. Executing a GUI program in this mode results in that program being run without displaying a window. The command.subsystem option can be used to define tools that run in GUI mode. The default subsystem, 0, is for command line programs, 1 is for programs which create their own windows, and 2 is for using the ShellExecute call. ShellExecute is a good way to open HTML files and similar as it handles this similarly to a user opening the file from the shell. 3 is for calling an internal extension or director extension, 4 is for calling the Windows specific HtmlHelp program and 5 is for calling the Windows specific WinHelp function.

Command line arguments

Command line arguments to the editor 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 the editor to print the file and then exit.

A group of properties can be saved as a property set file (with the extension ".properties") and the import command used on the command line:
For example,
editor "-import c:\os\web_work" editor.html

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

Commands use C style escape sequences which include:

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 the editor to open the file before performing the command.

Sources

The editor 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. Setting more than 10 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 plain text files with the extension ".ses".

Use File | Load Session and File | Save Session to load/save sessions. You can turn on/off "last session autoloading" using the editor 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 loose 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 the editor 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.

Find and Replace

the editor 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.
The editor supports basic regular expressions with tagging.

Keyboard commands

Keyboard commands in the editor mostly follow common Windows and GTK+ conventions. Keyboard equivalents of menu commands are listed in the menus. Some less common commands with no menu equivalent are:

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.

Each line in the files looks like "abbreviation=expansion". An expansion may contain new line characters indicated by '\n' and a caret position indicated by the '|' character. Some simple examples are included in the distributed Abbreviations file.

Folding

The editor supports folding for C++/C/Java/JavaScript. Fold points are based upon counting braces for the other languages. The fold point markers can be clicked to expand and contract folds. Ctrl+Shift+Click in the fold margin will expand or contract all the top level folds. Ctrl+Click on a fold point to toggle it and perform the same operation on all children. Shift+Click on a fold point to show all children.

Properties file

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

There are three properties files used, a global properties file called "the editorGlobal.properties", a per user file called "user.properties" (with a dot for the GTK+ version: ".user.properties") and a local one called "editor.properties" which may be present in the same directory as the file being edited. On Windows, both the global and user properties files are in the directory of the executable. 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/the editor. If the "EDITOR_HOME" environment variable is set on either Windows or GTK+ then it is where both the global and user properties files are found. Settings in the local properties file override those in the user properties file which override those in the global properties files.

The user properties file is intended for customisation by the user, leaving the global properties file to contain the default options distributed with the editor. 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 the global.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 the editor.properties file in that directory contains an entry setting the command to "jvc".

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. 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:

FilePath is the full path of the current file.
FileDir is the directory of the current file without a trailing slash.
FileName is the base name of the current file.
FileExt is the extension of the current file.
FileNameExt is $(FileName).$(FileExt).
CurrentSelection is the value of the currently selected text but not if selection is more than 1000 characters.
CurrentWord is the value of word which the caret is within or near.
EditorDefaultHome is the directory in which the Global Options file is found.
EditorUserHome is the directory in which the User Options file is found.

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)

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 must be in the same directory as the current file and a ".properties" extension is assumed.

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' or 'PLAT_WIN' 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

The editor 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.

License for Scintilla and Scite is Copyright 1998-2002 by Neil Hodgson neilh@scintilla.org. All Rights Reserved
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.
Windows(c) is a trademark of Microsoft Corp.