189 lines
9.1 KiB
HTML
Executable File
189 lines
9.1 KiB
HTML
Executable File
<?xml version="1.0"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta name="generator" content="SciTE" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
<title>
|
|
SciTE Extension Interface
|
|
</title>
|
|
<style type="text/css">
|
|
.example {
|
|
color: #00A000;
|
|
font-weight: bold;
|
|
}
|
|
DIV.example {
|
|
background: #F7FCF7;
|
|
border: 1px solid #C0D7C0;
|
|
margin: 0.3em 3em;
|
|
padding: 0.3em 0.6em;
|
|
font-size: 80%;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
<table bgcolor="#000000" width="100%" cellspacing="0" cellpadding="0" border="0">
|
|
<tr>
|
|
<td>
|
|
<img src="SciTEIco.png" border="3" height="64" width="64" alt="Scintilla icon" />
|
|
</td>
|
|
<td>
|
|
<a href="index.html" style="color:white;text-decoration:none"><font size="5">
|
|
SciTE Extension Interface</font></a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h3>
|
|
Purpose.
|
|
</h3>
|
|
<p>Some people want to create enhanced versions of the SciTE editor, while
|
|
still receiving the benefits of new SciTE features. This could be for an
|
|
editor designed for a particular environment such as developing games,
|
|
to incorporate a scripting capability within SciTE or to allow SciTE to be
|
|
controlled by another process through an IPC mechanism.</p>
|
|
<p>There are two example extensions.
|
|
The <a href="SciTEDirector.html">SciTE Director Interface</a> allows
|
|
SciTE on Windows to be controlled by an external application such as a
|
|
project manager.
|
|
The <a href="SciTELua.html">SciTE Lua Scripting Extension</a> is an
|
|
integration of the Lua scripting language into SciTE, done using the Extension
|
|
interface.</p>
|
|
<h3>
|
|
Extension Interface.
|
|
</h3>
|
|
<div class="example">
|
|
bool Initialise(ExtensionAPI *host_);<br />
|
|
bool Finalise();<br />
|
|
bool Clear();<br />
|
|
bool Load(const char *filename);<br />
|
|
bool InitBuffer(int index);<br />
|
|
bool ActivateBuffer(int index);<br />
|
|
bool RemoveBuffer(int index);<br />
|
|
bool OnOpen(const char *path);<br />
|
|
bool OnSwitchFile(const char *path);<br />
|
|
bool OnSave(const char *path);<br />
|
|
bool OnChar(char ch);<br />
|
|
bool OnExecute(const char *s);<br />
|
|
bool OnSavePointReached();<br />
|
|
bool OnSavePointLeft();<br />
|
|
bool OnStyle(unsigned int, int, int, Accessor *);<br />
|
|
bool OnDoubleClick();<br />
|
|
bool OnUpdateUI();<br />
|
|
bool OnMarginClick();<br />
|
|
bool OnMacro(const char *, const char *);<br />
|
|
bool SendProperty(const char *);<br />
|
|
bool OnKey(int keyval, int modifiers);<br />
|
|
bool OnDwellStart(int pos, const char *word);<br />
|
|
bool OnClose(const char *filename);<br />
|
|
</div>
|
|
<p>An extension must implement the Extension interface defined in scite/src/Extender.h
|
|
Only the first 4 methods must be implemented although an implementation can be as
|
|
simple as just returning false. The other methods have empty default implementations.
|
|
Methods added to this interface in the future should have default implementations so
|
|
existing extensions will continue to compile.</p>
|
|
<p>Each method returns a bool indicating whether the method handled all processing that
|
|
is needed and so no additional processing is required. Normally, false is returned to indicate
|
|
that further processing may be done.</p>
|
|
<p>The extension should use the Initialise and Finalise methods to allocate
|
|
and deallocate resources. The ExtensionAPI pointer should be saved in the
|
|
Initialise method so the extension can communicate back to SciTE.</p>
|
|
<p>The Clear and Load methods are used to support extensions that need
|
|
to load a resource such as a script file when a file is opened. When a file is
|
|
opened in SciTE, first the extension is asked to clear any data associated with
|
|
the previous file through Clear. Then SciTE checks for a property called
|
|
"extension" which matches the file name, so for x.cpp, looks for extension.*.cpp.
|
|
A file with this name is searched for in standard property file locations and if found
|
|
Load is called with the path as an argument.</p>
|
|
<p>The InitBuffer, ActivateBuffer, and RemoveBuffer methods provide the necessary hooks
|
|
so that extensions have a mechanism to associate data with a specific buffer, similar
|
|
to the way SciTE itself remembers the monospace setting of each buffer. InitBuffer is
|
|
called whenever a new document is opened in a given buffer. The buffer might be a newly
|
|
allocated one, or it might be recycled if the maximum number of buffers has been reached.
|
|
Once the buffer has been initialized, it will be the active buffer. Thereafter,
|
|
ActivateBuffer is called whenever the user switches to another loaded buffer.
|
|
RemoveBuffer is called when an existing buffer is closed. Thereafter, the indexes of
|
|
the buffers that come after the removed buffer are shifted down by one. After
|
|
RemoveBuffer, the extension will receive an InitBuffer or ActivateBuffer to establish
|
|
the new active buffer.</p>
|
|
<p>OnExecute is called only when an extension command is executed. These are
|
|
indicated in properties as subsystem 3.</p>
|
|
<p>Other methods are called upon events occurring in SciTE allowing an extension
|
|
to respond to those events.</p>
|
|
<h3>
|
|
ExtensionAPI Interface.
|
|
</h3>
|
|
<div class="example">
|
|
enum Pane { paneEditor=1, paneOutput=2, paneFindOutput=3 };<br />
|
|
sptr_t Send(Pane p, unsigned int msg, uptr_t wParam=0, sptr_t lParam=0);<br />
|
|
char *Range(Pane p, int start, int end);<br />
|
|
void Remove(Pane p, int start, int end);<br />
|
|
void Insert(Pane p, int pos, const char *s);<br />
|
|
void Trace(const char *s);<br />
|
|
char *Property(const char *key);<br />
|
|
void SetProperty(const char *key, const char *val);<br />
|
|
uptr_t GetInstance();<br />
|
|
void ShutDown();<br />
|
|
void Perform(const char *actions);<br />
|
|
void DoMenuCommand(int cmdID);<br />
|
|
void UpdateStatusBar(bool bUpdateSlowData);<br />
|
|
</div>
|
|
<p>An extension can call back into SciTE using this interface which is a simplified
|
|
way to access the functionality of SciTE.</p>
|
|
<p>As well as the normal editor pane and output pane, this interface allows for
|
|
a future feature where a third pane may be used for the output of search
|
|
commands. This is currently mapped to the output pane.</p>
|
|
<p>Send allows sending messages to the Scintilla control contained in each pane.</p>
|
|
<p>Range retrieves text from the pane. This must be deleted with delete[].
|
|
Remove and Insert are used to remove and insert text in a pane.</p>
|
|
<p>Trace displays a string at the end of the output pane.</p>
|
|
<p>SciTE's properties can be read and written with Property and
|
|
SetProperty. The result from Property should be deleted with delete[].</p>
|
|
<p>GetInstance is Windows specific and returns the HINSTANCE of
|
|
the application which is needed when accessing platform facilities.</p>
|
|
<p>ShutDown is equivalent to the user choosing the Quit menu item.
|
|
If there are any unsaved files loaded, then the user is asked whether to save them
|
|
and may cancel from this dialog. So under some circumstances, the application will
|
|
continue to run after ShutDown is called.</p>
|
|
<p>Perform takes a string containing an action, a ':' character, and an argument.
|
|
Currently the only known action is open and then the argument is a path.
|
|
This is used by the <a href="SciTEDirector.html">Director extension</a>
|
|
to relay commands from another application.
|
|
In the future more actions will be possible through this method.</p>
|
|
<h3>
|
|
Attaching the extension.
|
|
</h3>
|
|
<p>Extensions are currently added explicitly by code in the start up function.
|
|
On Windows, the DirectorExtension is attached with code similar to this simplified
|
|
example:</p>
|
|
<div class="example">
|
|
DirectorExtension director;<br />
|
|
Extension *extender = &director;<br />
|
|
//...<br />
|
|
SciTEWin MainWind(extender);
|
|
</div>
|
|
<p>It would be better to move to an implicit attachment mechanism similar to the
|
|
way lexers are attached to Scintilla, determining which extensions are used
|
|
by simply linking their object files into SciTE. It would also be good to
|
|
allow run-time attachment of extensions housed in DLLs or shared object libraries.</p>
|
|
<h3>
|
|
Multiplexing.
|
|
</h3>
|
|
<p>SciTE supports multiple extensions at a time. A multiplexer extension
|
|
maintains a list of extensions and calls each in turn for each method. Once an extension
|
|
returns true indicating processing should stop, the multiplexer returns without traversing
|
|
any remaining list members. However, for some methods such as Initialise and Finalise,
|
|
the remaining extensions are traversed regardless of the return value of the previous
|
|
extension.</p>
|
|
<h3>
|
|
Thread safety.
|
|
</h3>
|
|
<p>In general, SciTE is a single threaded application. However, on Windows, command
|
|
tools call OnExecute from a separate worker thread. The SingleThreadExtension adapter
|
|
class can be used to wrap an extension so that OnExecute calls are marshalled to the
|
|
main thread. Of course, this is not necessary if your extension is thread safe, or
|
|
if it does not implement OnExecute, or if it is a GTK-specific extension.
|
|
</body>
|
|
</html>
|
|
|