* first version

fcl/shedit/README

@@ -0,0 +1,130 @@
+# $Id$
+
+! Note: This version is not completed yet !
+
+
+This is SHEdit for Free Pascal, an object-oriented text editor engine with
+support for:
+- syntax highlighting
+- clipboard (cut, copy & paste)
+- undo/redo buffers
+- fully customizable behaviour
+- multiple views (editors) for a single document at a time
+- completely independent of any toolkit; it even can be used both in text and
+  in graphics modes
+
+
+Architecture
+------------
+
+There are three basic classes in SHEdit:
+- Document
+- Editor
+- Renderer
+
+The document class (TTextDoc) in doc_text.pp is quite simple, it just
+stores a text (ASCII) document as a collection of strings.
+What you have to know about TTextDoc is that it stores a 32-bit value for
+each line, which it doesn't modify on its own. The lower 8 bits of these
+LineFlags are reserved for syntax highlighting (SH): The first bit determines
+if the other SH flags are valid; and the remaining 7 bits can be used to
+indicate SH states which do not end at the end of the line.
+
+
+The editor itself is encapsulated in the class TSHTextEdit (in unit shedit.pp).
+It can only work in conjunction with a renderer, which is responsible for
+displaying the document. When you create a TSHTextEdit, the constructor expects
+two arguments: The document to use, and the renderer to use.
+
+The renderer itself is declared as an abstract interface class (i.e. all
+methods are 'virtual abstract'), this interface is called ISHRenderer.
+When you want to use SHEdit in your own programs, you will have to provide
+an implementation of the methods declared in ISHRenderer. There is a reference
+implementation for GTK, gtkdemo.
+
+
+Renderer interface
+------------------
+
+This interface is quite simple; just note that SHEdit expects all corrdinates
+relative to the upper left corner of the document (0/0), and it uses the
+cell size (width and height) of the characters as base unit. For example,
+the coordinate X=3/Y=2 references the fourth character in the third line.
+
+
+procedure InvalidateLines(y1, y2: Integer);
+  The renderer should initiate the redrawing of the lines between y1 and y2.
+  It is recommended to use the Invalidate commands of the underlying graphics
+  or windowing toolkit; but an implementation may choose to simply call
+  TSHTextEdit.DrawContent.
+
+procedure ClearRect(x1, y1, x2, y2: Integer);
+  The renderer must clear the given rectangle in the background (whitespace)
+  color.
+
+procedure DrawTextLine(x1, x2, y: Integer; s: PChar);
+  This is the most complex method: The renderer has to draw a complete line of
+  text, which is given in "s". The vertical position is line "y", x1 and x2
+  specify a horizontal clipping span.
+  "s" has a very special format, as it contains highlighting tags:
+  You can process "s" character by character, as usual. BUT when you encounter
+  a special escape character (LF_Escape, defined in doc_text.pp) the renderer
+  has to switch to the font style/color given in the following character. This
+  character is just a index in the range ASCII #1..#255, the renderer must know
+  himself what to do with this index. These highlighting tags are generated by
+  a special highlighting function, see below.
+
+procedure ShowCursor(x, y: Integer);
+procedure HideCursor(x, y: Integer);
+  The cursor should be drawn or be hidden, its position is given in "x" and
+  "y". SHEdit does its own reference counting, i.e. it won't call HideCursor
+  for an already invisible cursor, and it won't call ShowCursor for a visible
+  cursor. If the cursor position changes, SHEdit will call HideCursor with
+  the old position and then ShowCursor with the new position as arguments.
+
+function GetVertPos: Integer;
+  This function shall return the vertical scrolling position of the window
+  which is managed by the renderer.
+
+procedure SetVertPos(y: Integer);
+  Sets the vertical scrolling position.
+
+function GetPageHeight: Integer;
+  Gets the height of the visible part of the document.
+
+procedure SetLineCount(count: Integer);
+  SHEdit calls this method if the number of lines in the document has changed.
+
+function GetClipboard: String;
+  GetClipboard is called by SHEdit if the user wants to paste the contents of
+  the clipboard into the document. GetClipboard must check if the system's
+  clipboard contains valid text data and return it; if not, it has to return
+  an empty string.
+
+procedure SetClipboard(Content: String);
+  This method is used to set the content of the clipboard after a
+  "ClipboardCut" or "ClipboardCopy" action occured.
+
+
+
+Highlighters and document type specific features
+------------------------------------------------
+
+TSHTextEdit does not perform any syntax highlighting, and it always acts as a
+normal text editor without any fancy extra feature.
+This can easily be changed by deriving your own class from TSHTextEdit.
+Currently there are two special editor classes: TSHPasEdit (unit sh_pas.pp) and
+TSHXMLEdit (unit sh_xml.pp).
+
+TSHPasEdit supports syntax highlighting for Pascal sources, and it adds auto
+indent facilities to SHEdit (currently, when you press the Enter key, it will
+add as many spaces as the previous line to the new created line).
+
+TSHXMLEdit just adds syntax highlighting for XML and DTD documents.
+
+Please note that currently there is no framework for handling with different
+kinds of documents. It is up to the program which wants to use SHEdit to
+determine which editor class to use.
+
+
+- Sebastian Guenther, sg@freepascal.org