Scintilla icon Scintilla コンポーネントデザインScintilla Component Design

最上位の構造 Top level structure

Scintilla は C++ コードによる三つの大きな層から成っています。

Scintilla consists of three major layers of C++ code

この構造の第一の目的は、環境依存のコードと非依存の核コードを分離することにあります。これによって Scintilla を新しい環境に移植しやすくなり、大部分のコードの読み手は環境の細かい点に気をつかわなくてよくなります。環境依存の問題を最小限にし、コードの肥大化を防ぐために Scintilla は C++ の保守的な部分集合を用いています。これは例外の処理や実行時型情報を使用せず、標準 C++ ライブラリと限定的なテンプレートの使用を意味します。

The primary purpose of this structure is to separate the platform dependent code from the platform independent core code. This makes it easier to port Scintilla to a new platform and ensures that most readers of the code do not have to deal with platform details. To minimise portability problems and avoid code bloat, a conservative subset of C++ is used in Scintilla with no exception handling, run time type information or use of the standard C++ library and with limited use of templates.

現時点では Windows と GTK+/Linux に対応しており、また wxWidgets(訳注:wxWindows は改称しています)が多くの点でとても似ています。いずれもウィンドウ・メニュー・ビットマップに関する機能を持ち、これらは一般的に同じように動作します。つまり、どれもがウィンドウを動かしたり赤い線を引いたりできます。ある環境で時々一度の呼び出しでなく連続した複数回の呼び出しを必要とすることがあります。さらにそれ以外に深刻な違いが出ることがあります。Windows でのクリップボード読み出しは同期的に行えますが、GTK+ のクリップボードは要求呼び出しが必要で、それはクリップボードのデータを含むメッセージが非同期的に帰ってくることになります。wxWidgets 環境はその公式サイトから入手可能です。

The currently supported platforms, Windows, GTK+/Linux and wxWindows are fairly similar in many ways. Each has windows, menus and bitmaps. These features generally work in similar ways so each has a way to move a window or draw a red line. Sometimes one platform requires a sequence of calls rather than a single call. At other times, the differences are more profound. Reading the Windows clipboard occurs synchronously but reading the GTK+ clipboard requires a request call that will be asynchronously answered with a message containing the clipboard data. The wxWindows platform is available from the wxWindows site

可搬ライブラリ Portability Library

これは環境依存の能力の上に被さる、とても小さくて薄い層です。

This is a fairly small and thin layer over the platform's native capabilities.

可搬ライブラリは Platform.h で定義され、各環境で一回ずつ実装されます。Windows のいろいろなメソッドは PlatWin.cxx に、GTK+ のそれは PlatGTK.cxx に定義されます。

The portability library is defined in Platform.h and is implemented once for each platform. PlatWin.cxx defines the Windows variants of the methods and PlatGTK.cxx the GTK+ variants.

ここに挙げるいくつかのクラスは環境依存のオブジェクト識別子を保持し、それら環境依存のオブジェクトの代理のように振る舞います。従って利用者側の大部分のコードは、どの環境で動作しているかを気にせずに各環境のオブジェクトを操作することができます。時々、下層のオブジェクト識別子にアクセスする必要がありますが、この識別子は GetID で提供されています。下層の環境依存識別子は typedef で共通名に置きかえられているので、GetID で得られた識別子はクライアントコードで必要になるその場所で変換されます。

Several of the classes here hold platform specific object identifiers and act as proxies to these platform objects. Most client code can thus manipulate the platform objects without caring which is the current platform. Sometimes client code needs access to the underlying object identifiers and this is provided by the GetID method. The underlying types of the platform specific identifiers are typedefed to common names to allow them to be transferred around in client code where needed.

Point, PRectangle

Point と PRectangle は共通して使われる幾何学的基本要素を保持する単純なクラスです。PRectangle が保持している右端と下端の値は Mac や Windows のように自分自身を矩形に含めません。つまり通常どの端の値も指示する矩形に含まれる GTK+ とは違う形になっています。 Rectangle と呼ばないのは Windows でマクロ名の形で定義されているからです。

These are simple classes provided to hold the commonly used geometric primitives. A PRectangle follows the Mac / Windows convention of not including its bottom and right sides instead of including all its sides as is normal in GTK+. It is not called Rectangle as this may be the name of a macro on Windows.

Colour, ColourPair, Palette

Colour は環境毎の色の識別子を保持しています。Windows では COLORREF, GTK+ では GdkColor となります。Windows では色の構成要素である赤、緑、青の要素が各 8 bit を上限とします。ColourPairs は全ての色がいつも使えるわけではないという理由で用いられます。Windows と GTK+ の両方で共通する 8 ビットカラーモードでは 256 色のみが一度に同時に使えます。そのため、アプリケーションが dull red (#400000) を要求するとそれに近い既表示色、例えば #800000 とか #330000 が割り当てられます。16 色とか 2 色のあー度では更に少ない選択肢となり、アプリケーションはこの数に制限された色を使わなくてはなりません。

Colour holds a platform specific colour identifier - COLORREF for Windows and GdkColor for GTK+. The red, green and blue components that make up the colour are limited to the 8 bits of precision available on Windows. ColourPairs are used because not all possible colours are always available. Using an 8 bit colour mode, which is a common setting for both Windows and GTK+, only 256 colours are possible on the display. Thus when an application asks for a dull red, say #400000, it may only be allocated an already available colour such as #800000 or #330000. With 16 or 2 colour modes even less choice is available and the application will have to use the limited set of already available colours.

Palette オブジェクトは一組の色を保持し、適切な呼び出しでこれらの色を割り当てたり、環境が決めたどの色が使えるかを知ることができたりします。

A Palette object holds a set of colour pairs and can make the appropriate calls to ask to allocate these colours and to see what the platform has decided will be allowed.

Font

Font は環境依存のフォント識別子を保持します。Windows では HFONT, GTK+ では GdkFont* です。識別子を「所有」するわけではないので各環境のフォントオブジェクトはその解体子で削除されたりはしません(訳注:わかったようなわからんような)。利用者側のコードは適切に Destroy を呼び出さなくてはなりません。

Font holds a platform specific font identifier - HFONT for Windows, GdkFont* for GTK+. It does not own the identifier and so will not delete the platform font object in its destructor. Client code should call Destroy at appropriate times.

Surface

Surface は各環境における「描画作業を行える場」の概念を抽象的に覆ったものです。Surface はウィンドウのようなすでに作られた描画場と、描画やその後に他の Surface へ複製可能なビットマップとの両方を扱います。Windows では HDC と可能な範囲の HBITMAP を、GTK+ では GdkDrawable* と可能な範囲の GdkPixmap* を抽象的に内包します。他の環境依存オブジェクトは描画行動に必要となったときに作られ、また正しく解体されます。

Surface is an abstraction over each platform's concept of somewhere that graphical drawing operations can be done. It may wrap an already created drawing place such as a window or be used to create a bitmap that can be drawn into and later copied onto another surface. On Windows it wraps a HDC and possibly a HBITMAP. On GTK+ it wraps a GdkDrawable* and possibly a GdkPixmap*. Other platform specific objects are created (and correctly destroyed) whenever required to perform drawing actions.

描画処理には多角形描画、塗りつぶしを伴う多角形描画、線、矩形、楕円、テキスト描画が含まれます。テキストの高さと幅は他の内容同様に計測可能です。各処理は矩形の中に限定することができます。呼び出しの度毎にすべての引数が渡されるため、ほとんどの場合状態を持ちません。これに対する例外は MoveTo と LineTo によるものです。

Drawing operations provided include drawing filled and unfilled polygons, lines, rectangles, ellipses and text. The height and width of text as well as other details can be measured. Operations can be clipped to a rectangle. Most of the calls are stateless with all parameters being passed at each call. The exception to this is line drawing which is performed by calling MoveTo and then LineTo.

Window

Window は各環境のウィンドウへの代理処理を受け持ちます。ウィンドウが見えるようにすること、動かすこと、再描画すること、「破壊(destroy) 」することなどが行われます。環境に基づく識別子を保有しており、Windows では HWND, GTK+ では GtkWidget* がこれにあたります。

Window acts as a proxy to a platform window allowing operations such as showing, moving, redrawing, and destroying to be performed. It contains a platform specific window identifier - HWND for Windows, GtkWidget* for GTK+.

ListBox

ListBox は Window のサブクラスで、各環境のリストボックスへの代理処理を受け持ちます。項目の追加、獲得、選択などを行います。

ListBox is a subclass of Window and acts as a proxy to a platform listbox adding methods for operations such as adding, retrieving, and selecting items.

Menu

Menu はポップアップメニューを作るための小さな補助クラスです。各環境のメニュー識別子を保有しており、Windows では HMENU, GTK+ では GtkItemFactory* がこれにあたります。メニューの構築にかかる大部分の作業は各環境へのイベントへのアクセスが必要です。これは「環境依存のイベントと API」層で処理されます。

Menu is a small helper class for constructing popup menus. It contains the platform specific menu identifier - HMENU for Windows, GtkItemFactory* for GTK+. Most of the work in constructing menus requires access to platform events and so is done in the Platform Events and API layer.

Platform

Platform は各環境個別の機能を利用するときに使われるクラスです。システム全体に適用される変数、例えばダブルクリックスピードやクロム色(訳注:よく見るけどどういう意味?)は Platform を介して利用できます。DebugPrint のような実用系関数もここから利用できます。

The Platform class is used to access the facilities of the platform. System wide parameters such as double click speed and chrome colour are available from Platform. Utility functions such as DebugPrintf are also available from Platform.

核コードCore Code

Scintilla の大部分は環境非依存コードです。これは CellBuffer, ContractionState, Document, Editor, Indicator, LineMarker, Style, ViewStyle, KeyMap, ScintillaBase, CallTip, AutoComplete の各基礎クラスから成っています。

The bulk of Scintilla's code is platform independent. This is made up of the CellBuffer, ContractionState, Document, Editor, Indicator, LineMarker, Style, ViewStyle, KeyMap, ScintillaBase, CallTip, and AutoComplete primary classes.

CellBuffer

CellBuffer はテキストとスタイル情報、アンドゥスタック、行へのマーカー割り当て、折りたたみ構造を保持しています。

A CellBuffer holds text and styling information, the undo stack, the assignment of line markers to lines, and the fold structure.

一素子(cell)は文字に1パイトと関係づけられたスタイルを含んでいます。現在の素子バッファは素子の連続体です。素子連続対はテキストと、各行の開始位置および各行に割り当てられた多様なマーカーを含んでいます。

A cell contains a character byte and its associated style byte. The current state of the cell buffer is the sequence of cells that make up the text and a sequence of line information containing the starting position of each line and any markers assigned to each line.

アンドゥスタックは素子バッファ上で行われた行動の流れを記憶しています。行動とはテキストの挿入、削除、またはやり直しの開始です。「やり直しの開始」はテキストの挿入と削除の流れをグループにし、まとめてやり直しを可能とするために利用されます。同様に、再実行(redo)は連続体の中のバッファへ各行動を再度適用します。挿入された文字のスタイルは初期状態では常に 0 です。直接入力した文字、InsertString 呼び出しなどで挿入された文字、アンドゥや再実行でもこれは同じです。利用者側のコードは好みのタイミングで文字をスタイル付けするための応答ができます。スタイル情報はアンドゥ行動用には記録されません。

The undo stack holds a sequence of actions on the cell buffer. Each action is one of a text insertion, a text deletion or an undo start action. The start actions are used to group sequences of text insertions and deletions together so they can be undone together. To perform an undo operation, each insertion or deletion is undone in reverse sequence. Similarly, redo reapplies each action to the buffer in sequence. Whenever a character is inserted in the buffer either directly through a call such as InsertString or through undo or redo, its styling byte is initially set to zero. Client code is responsible for styling each character whenever convenient. Styling information is not stored in undo actions.

Document

Document は CellBuffer と高次元の抽象化に関する処理を行います。単語や DBCS 文字の連続体、行末文字の連続形などがそれです。スタイル処理を管理したり、他のオブジェクトに文書の変化を通知したりすることで実装されます。

A document contains a CellBuffer and deals with some higher level abstractions such as words, DBCS character sequences and line end character sequences. It is responsible for managing the styling process and for notifying other objects when changes occur to the document.

Editor

Scintilla の中央に位置するのが Editor オブジェクトです。文書を表示し、ユーザの行動やコンテナからの要求に応じます。文書表示用に ContractionState, Indicator, LineMarker, Style, ViewStyle の各オブジェクトを、キー入力を機能につなぐために KeyMap クラスを保有しています。各行が見えるかどうかは ContractionState に保持されていて、文書の各行を表示行に対応させたり、その逆を行ったりすることにも使われます。

The Editor object is central to Scintilla. It is responsible for displaying a document and responding to user actions and requests from the container. It uses ContractionState, Indicator, LineMarker, Style, and ViewStyle objects to display the document and a KeyMap class to map key presses to functions. The visibility of each line is kept in the ContractionState which is also responsible for mapping from display lines to documents lines and vice versa.

文書オブジェクト一つに多数の Editor オブジェクトを接続することもあります。文書の変更は DocWatcher の仕組みにより各 Editor オブジェクトに公告されます。

There may be multiple Editor objects attached to one Document object. Changes to a document are broadcast to the editors through the DocWatcher mechanism.

ScintillaBase

ScintillaBase は Editor のサブクラスで、コールチップの表示や自動補完リスト、コンテキストメニューといった窓口となる機能を追加されています。これらの機能は CallTip や AutoComplete の各オブジェクトを使います。このクラスは必須のものではありません。そのため上記の追加機能を要求されない場合は、低負荷の Scintilla 実装では省略されます。

ScintillaBase is a subclass of Editor and adds extra windowing features including display of calltips, autocompletion lists and context menus. These features use CallTip and AutoComplete objects. This class is optional so a lightweight implementation of Scintilla may bypass it if the added functionality is not required.

環境依存のイベントと APIPlatform Events and API

各巻今日毎に異なる仕組みでイベントを受け取ります。Windows ではイベントはメッセージと COM で受け取り、GTK+ ではコールバック関数が用いられます。

Each platform uses different mechanisms for receiving events. On Windows, events are received through messages and COM. On GTK+, callback functions are used.

各環境向けに ScintillaBase と Editor 各クラスから派生したクラスがあります。Windows 用に ScintillaWin, GTK+ 用に ScintillaGTK となっています。これらのクラスは各環境のイベントの仕組みに接続し、Editor や ScintillaBase の仮想メソッドの一部を実装しなくてはなりません。例えば、Windows では同期的クリップボード、GTK+ は非同期的クリップボードを持っています。この層はその差違を吸収する必要があります。

For each platform, a class is derived from ScintillaBase (and thus from Editor). This is ScintillaWin on Windows and ScintillaGTK on GTK+. These classes are responsible for connecting to the platforms event mechanism and also to implement some virtual methods in Editor and ScintillaBase which are different on the platforms. For example, this layer has to support this difference between the synchronous Windows clipboard and the asynchronous GTK+ clipboard.

この層には拡張 API が定義されています。Windows ではメッセージ、GTK+ では関数呼び出しというように各環境が異なるスタイルの API を定義しているからです。単一の環境用に複数の API を定義することも許されています。GTK+ で現在利用できる API は Windows のそれに似ていて、GTK+ の習慣にならうものではありません。このことを理由に各環境の(ここでは GTK+ の)習慣に合わせた第二の API を実装することも可能です。

The external API is defined in this layer as each platform has different preferred styles of API - messages on Windows and function calls on GTK+. This also allows multiple APIs to be defined on a platform. The currently available API on GTK+ is similar to the Windows API and does not follow platform conventions well. A second API could be implemented here that did follow platform conventions.