ext/scintilla/doc/Design.html

   1 <?xml version="1.0"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml">
   5   <head>
   6     <meta name="generator" content="HTML Tidy, see www.w3.org" />
   7     <meta name="generator" content="SciTE" />
   8     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   9     <title>
  10       Scintilla and SciTE
  11     </title>
  12   </head>
  13   <body bgcolor="#FFFFFF" text="#000000">
  14     <table bgcolor="#000000" width="100%" cellspacing="0" cellpadding="0" border="0">
  15       <tr>
  16         <td>
  17           <img src="SciTEIco.png" border="3" height="64" width="64" alt="Scintilla icon" />
  18         </td>
  19         <td>
  20           <a href="index.html" style="color:white;text-decoration:none"><font size="5">Scintilla
  21           Component Design</font></a>
  22         </td>
  23       </tr>
  24     </table>
  25     <h2>
  26        Top level structure
  27     </h2>
  28     <p>
  29        Scintilla consists of three major layers of C++ code
  30     </p>
  31     <ul>
  32       <li>
  33         Portability Library
  34       </li>
  35       <li>
  36         Core Code
  37       </li>
  38       <li>
  39         Platform Events and API
  40       </li>
  41     </ul>
  42     <p>
  43        The primary purpose of this structure is to separate the platform dependent code from the
  44       platform independent core code. This makes it easier to port Scintilla to a new platform and
  45       ensures that most readers of the code do not have to deal with platform details. To minimise
  46       portability problems and avoid code bloat, a conservative subset of C++ is used in Scintilla
  47       with no exception handling, run time type information or use of the standard C++
  48       library and with limited use of templates.
  49     </p>
  50     <p>
  51        The currently supported platforms, Windows, GTK+/Linux and wxWindows are fairly similar in
  52       many ways.
  53       Each has windows, menus and bitmaps. These features generally work in similar ways so each
  54       has a way to move a window or draw a red line. Sometimes one platform requires a sequence of
  55       calls rather than a single call. At other times, the differences are more profound. Reading
  56       the Windows clipboard occurs synchronously but reading the GTK+ clipboard requires a request
  57       call that will be asynchronously answered with a message containing the clipboard data.
  58       The wxWindows platform is available from the <a href="http://wxwindows.org/">wxWindows site</a>
  59     </p>
  60     <br />
  61     <h3>
  62        Portability Library
  63     </h3>
  64     <p>
  65        This is a fairly small and thin layer over the platform's native capabilities.
  66     </p>
  67     <p>
  68        The portability library is defined in Platform.h and is implemented once for each platform.
  69       PlatWin.cxx defines the Windows variants of the methods and PlatGTK.cxx the GTK+ variants.
  70     </p>
  71     <p>
  72        Several of the classes here hold platform specific object identifiers and act as proxies to
  73       these platform objects. Most client code can thus manipulate the platform objects without
  74       caring which is the current platform. Sometimes client code needs access to the underlying
  75       object identifiers and this is provided by the GetID method. The underlying types of the
  76       platform specific identifiers are typedefed to common names to allow them to be transferred
  77       around in client code where needed.
  78     </p>
  79     <h4>
  80        Point, PRectangle
  81     </h4>
  82     <p>
  83        These are simple classes provided to hold the commonly used geometric primitives. A
  84       PRectangle follows the Mac / Windows convention of not including its bottom and right sides
  85       instead of including all its sides as is normal in GTK+. It is not called Rectangle as this may be
  86       the name of a macro on Windows.
  87     </p>
  88     <h4>
  89        Colour, ColourPair, Palette
  90     </h4>
  91     <p>
  92        Colour holds a platform specific colour identifier - COLORREF for Windows and GdkColor for
  93       GTK+. The red, green and blue components that make up the colour are limited to the 8 bits of
  94       precision available on Windows. ColourPairs are used because not all possible colours are
  95       always available. Using an 8 bit colour mode, which is a common setting for both Windows and
  96       GTK+, only 256 colours are possible on the display. Thus when an application asks for a dull
  97       red, say #400000, it may only be allocated an already available colour such as #800000 or
  98       #330000. With 16 or 2 colour modes even less choice is available and the application will
  99       have to use the limited set of already available colours.
 100     </p>
 101     A Palette object holds a set of colour pairs and can make the appropriate calls to ask to
 102     allocate these colours and to see what the platform has decided will be allowed.
 103     <h4>
 104        Font
 105     </h4>
 106     <p>
 107        Font holds a platform specific font identifier - HFONT for Windows, GdkFont* for GTK+. It
 108       does not own the identifier and so will not delete the platform font object in its
 109       destructor. Client code should call Destroy at appropriate times.
 110     </p>
 111     <h4>
 112        Surface
 113     </h4>
 114     <p>
 115        Surface is an abstraction over each platform's concept of somewhere that graphical drawing
 116       operations can be done. It may wrap an already created drawing place such as a window or be
 117       used to create a bitmap that can be drawn into and later copied onto another surface. On
 118       Windows it wraps a HDC and possibly a HBITMAP. On GTK+ it wraps a GdkDrawable* and possibly a
 119       GdkPixmap*. Other platform specific objects are created (and correctly destroyed) whenever
 120       required to perform drawing actions.
 121     </p>
 122     <p>
 123        Drawing operations provided include drawing filled and unfilled polygons, lines, rectangles,
 124       ellipses and text. The height and width of text as well as other details can be measured.
 125       Operations can be clipped to a rectangle. Most of the calls are stateless with all parameters
 126       being passed at each call. The exception to this is line drawing which is performed by
 127       calling MoveTo and then LineTo.
 128     </p>
 129     <h4>
 130        Window
 131     </h4>
 132     <p>
 133        Window acts as a proxy to a platform window allowing operations such as showing, moving,
 134       redrawing, and destroying to be performed. It contains a platform specific window identifier
 135       - HWND for Windows, GtkWidget* for GTK+.
 136     </p>
 137     <h4>
 138        ListBox
 139     </h4>
 140     <p>
 141        ListBox is a subclass of Window and acts as a proxy to a platform listbox adding methods for
 142       operations such as adding, retrieving, and selecting items.
 143     </p>
 144     <h4>
 145        Menu
 146     </h4>
 147     <p>
 148        Menu is a small helper class for constructing popup menus. It contains the platform specific
 149       menu identifier - HMENU for Windows, GtkItemFactory* for GTK+. Most of the work in
 150       constructing menus requires access to platform events and so is done in the Platform Events
 151       and API layer.
 152     </p>
 153     <h4>
 154        Platform
 155     </h4>
 156     <p>
 157        The Platform class is used to access the facilities of the platform. System wide parameters
 158       such as double click speed and chrome colour are available from Platform. Utility functions
 159       such as DebugPrintf are also available from Platform.
 160     </p>
 161     <h3>
 162        Core Code
 163     </h3>
 164     <p>
 165        The bulk of Scintilla's code is platform independent. This is made up of the CellBuffer,
 166       ContractionState, Document, Editor, Indicator, LineMarker, Style, ViewStyle, KeyMap,
 167       ScintillaBase, CallTip,
 168       and AutoComplete primary classes.
 169     </p>
 170     <h4>
 171        CellBuffer
 172     </h4>
 173     <p>
 174        A CellBuffer holds text and styling information, the undo stack, the assignment of line
 175       markers to lines, and the fold structure.
 176     </p>
 177     <p>
 178        A cell contains a character byte and its associated style byte. The current state of the
 179       cell buffer is the sequence of cells that make up the text and a sequence of line information
 180       containing the starting position of each line and any markers assigned to each line.
 181     </p>
 182     <p>
 183        The undo stack holds a sequence of actions on the cell buffer. Each action is one of a text
 184       insertion, a text deletion or an undo start action. The start actions are used to group
 185       sequences of text insertions and deletions together so they can be undone together. To
 186       perform an undo operation, each insertion or deletion is undone in reverse sequence.
 187       Similarly, redo reapplies each action to the buffer in sequence. Whenever a character is
 188       inserted in the buffer either directly through a call such as InsertString or through undo or
 189       redo, its styling byte is initially set to zero. Client code is responsible for styling each
 190       character whenever convenient. Styling information is not stored in undo actions.
 191     </p>
 192     <h4>
 193        Document
 194     </h4>
 195     <p>
 196        A document contains a CellBuffer and deals with some higher level abstractions such as
 197       words, DBCS character sequences and line end character sequences. It is responsible for
 198       managing the styling process and for notifying other objects when changes occur to the
 199       document.
 200     </p>
 201     <h4>
 202        Editor
 203     </h4>
 204     <p>
 205        The Editor object is central to Scintilla. It is responsible for displaying a document and
 206       responding to user actions and requests from the container. It uses ContractionState, Indicator,
 207       LineMarker, Style, and ViewStyle objects to display the document and a KeyMap class to
 208       map key presses to functions.
 209       The visibility of each line is kept in the ContractionState which is also responsible for mapping
 210       from display lines to documents lines and vice versa.
 211     </p>
 212     <p>
 213        There may be multiple Editor objects attached to one Document object. Changes to a
 214        document are broadcast to the editors through the DocWatcher mechanism.
 215     </p>
 216     <h4>
 217        ScintillaBase
 218     </h4>
 219     <p>
 220        ScintillaBase is a subclass of Editor and adds extra windowing features including display of
 221       calltips, autocompletion lists and context menus. These features use CallTip and AutoComplete
 222       objects. This class is optional so a lightweight implementation of Scintilla may bypass it if
 223       the added functionality is not required.
 224     </p>
 225     <h3>
 226        Platform Events and API
 227     </h3>
 228     <p>
 229        Each platform uses different mechanisms for receiving events. On Windows, events are
 230       received through messages and COM. On GTK+, callback functions are used.
 231     </p>
 232     <p>
 233        For each platform, a class is derived from ScintillaBase (and thus from Editor). This is
 234       ScintillaWin on Windows and ScintillaGTK on GTK+. These classes are responsible for
 235       connecting to the platforms event mechanism and also to implement some virtual methods in
 236       Editor and ScintillaBase which are different on the platforms. For example, this layer has to
 237       support this difference between the synchronous Windows clipboard and the asynchronous GTK+
 238       clipboard.
 239     </p>
 240     <p>
 241        The external API is defined in this layer as each platform has different preferred styles of
 242       API - messages on Windows and function calls on GTK+. This also allows multiple APIs to be
 243       defined on a platform. The currently available API on GTK+ is similar to the Windows API and
 244       does not follow platform conventions well. A second API could be implemented here that did
 245       follow platform conventions.
 246     </p>
 247   </body>
 248 </html>
 249