Computers & Writing Systems
Specifications for Graphite-enabled Edit Control
UNESCO project Initiative B@bel
A complete index of all SIL's contributions to UNESCO‘s project Initiative B@bel can be found here.
This document describes the specifications for the Graphite-enabled edit control that is being developed by SIL International in accordance with their contract with UNESCO.
Download: The completed edit control can be found here.
2. Phases of development
The control will be developed in a series of phases, as follows:
The edit control will consist of a DLL for an ActiveX control that can be embedded within a host application. The control will run on Windows 2000 and XP operating systems.
3.1. COM interface support
3.1.1. Phase 1
The first phase of development will support a simple COM interface that is adequate to initialize the control with data.
Properties must be set before the control is opened. Required properties are:
Also the standard ActiveX control mechanism will be used to set the physical height and width of the control.
3.1.2. Phase 2
3.1.3. Phase 3
Later versions of the control will support standard COM interfaces ITextDocument and ITextRange. Later phases will require support of ITextSelection, ITextFont, and ITextPara. The following methods will be implemented:
3.1.4. Phase 4
Phase 4 involves adding the Text Object Model interfaces to the control. This will involve implementing the methods named below. The behavior of these methods is specified in Microsoft's MSDN documentation.
3.1.5. Phase 6
Support of character and paragraph styles will require implementation of ITextFont and ITextPara.
3.1.6. Phase 8
4. XHTML format
The control will support the following subset of the XHTML format described in the document “XHTML Format for WorldPad File Equivalence”.
4.1. Phase 3
Tags: html, body, p, span.
Style properties: font-family, font-size (both absolute and relative sizes).
4.2. Phase 5
Style properties: direction (e.g., style=“direction: rtl”).
4.3. Phase 6
Style properties: style, font-style, font-weight, color, background-color [optional, since it is not required by Paratext], vertical-align, text-decoration, text-align, text-indent, margin-left/right/top/bottom, line-height (single, 1, double spacing).
5. Layout capabilities
5.1. Single-line control [Phase 1]
For a single-line edit control, the entire text will be displayed on a single line that scrolls horizontally. Typing off the trailing side (i.e., in a left-to-right control, the left side) of the control will cause the control to scroll horizontally; similarly deleting or moving the selection with the arrow keys will scroll to keep the selection visible. No scroll bar is required.
Insertion of paragraph-breaking characters such as the Return key will be ignored. Pasting data or reading data from a file that includes paragraph-breaking characters will have the effect of inserting just the first line of the text.
For phase 1, the single-line edit control will be able to handle approximately 256 characters of data with good performance. Later phases will signficantly raise that limit or remove it altogether.
5.2. Multi-line control [Phase 2]
A multi-line edit control will provide automatic line wrapping for text in a single paragraph. The wrapping behavior will be based on the behavior of the Graphite font or the white-space character properties of data that is not rendered with Graphite. A vertical and/or horizontal scroll bar will be available, if requested.
Paragraph breaks will occur wherever there is paragraph formatting in the HTML-based text or return characters in plain text. In plain text, the characters or character sequences listed in the table in section 5.1 will cause paragraph breaks. A small amount of vertical leading will be used to visually separate paragraphs. Paragraph-level formatting such as line spacing and indentation are not required.
A multi-line edit control will be able to handle approximately 2000 characters of data with good performance at phase 2. Later phases will require good performance for many pages of text.
5.3. Multilingual layout support [Phase 5]
Both the single- and multi-line controls will be capable of right-to-left (as well as left-to-right) layout. The layout direction is specified by a parameter passed from the host application. Mixing of left-to-right and right-to-left paragraphs in a single control is not required.
Both forms of the control are likewise required to handle a mixture of fonts, some of which may require right-to-left directionality and others left-to-right. The multi-line control should correctly handle the problem trailing white-space in mixed-direction paragraphs according to the Unicode bidirectional algorithm (i.e., trailing white space in an “upstream” run of text is treated as if it were “downstream” and thus moved to the end of the line).
6. Editing capabilities
6.1. Typing [Phase 1]
In a multi-line control, the Return key will produce a paragraph break. In a single-line control, the Return key will be ignored.
When a range selection exists, the Delete key will delete the range of text and create an insertion-point selection at the location of the deletion. When an insertion point exists, the Delete key will delete the character that is (logically) ahead of the insertion point. In either case the resulting insertion-point will have the properties of the (first) deleted character. Note that when working with supplementary-plane Unicode characters, a character may consist of two 16-bit items. [Phase 5]
When a range selection exists, the Backspace key will delete the range of text and create an insertion-point selection at the location of the deletion. When an insertion point exists, the Backspace key will delete the character that is (logically) before the insertion point. In either case, the resulting insertion-point will have the properties of the (first) deleted character.
6.2. Creating and manipulating selections [Phase 1]
6.2.1. Clicking the mouse
A single mouse click will produce an insertion point at the closest location between two characters or at the beginning or end of the text. The insertion point will have the properties (i.e., subsequent typing will produce characters with the properties) of the closest character receiving the click.
Dragging the mouse will produce a range selection extending to the point where the mouse is released.
More sophisticated drag features such as word-level selection are not required.
Drag-and-drop editing of text is low priority.
Shift-clicking will produce a range selection extending from the previous insertion-point or range anchor to the point where the mouse is released.
Whole-word selection when shift-clicking is not required.
6.2.4. Arrow keys
There are two possible modes of behavior for arrow keys.
184.108.40.206. Logical mode [Phase 1]
In a left-to-right control, the right arrow key will move an insertion point forward in the data to the next legitimate insertion point. When starting from a range selection, the right arrow key will reduce the selection to the trailing end of the range.
Similarly, the left arrow key will move an insertion point backward in the data to the next legitimate insertion point. When starting from a range selection, the left arrow key will reduce the selection to the leading end of the range.
The directions are reversed in a right-to-left control [Phase 5]. The right arrow key will move an insertion point backward, or reduce a range to the leading end. The left arrow key will move an insertion point forward, or reduce a range to the trailing end.
The shifted arrow keys extend the selection to the location that would be the result of pressing the normal arrow key. When starting from a range selection, it is the current end-point of the range that is used to determine the next end-point.
220.127.116.11. Visual mode [Phase 9]
In visual mode, the left arrow key moves an insertion point selection to the next viable position to the left, and the right arrow key moves it similarly to the right. This requires interaction with the rendering engine which knows the physical arrangement of the glyphs.
When starting from a range selection, the right arrow key behaves identically to logical mode.
The shifted arrow keys extend the selection to the location that would be the result of pressed the normal arrow key.
6.2.5. Home and End keys
18.104.22.168. Logical mode [Phase 2]
The Home key moves the selection to just before the (logically) first character on the line, and the End key moves the selection to just after the (logically) last character on the line.
The Shift-Home key extends the selection from the current anchor point to just before the first character on the line, and the Shift-End key extends the selection to just after the last character on the line. When starting from a range selection, the current line is considered to be the one containing the end-point of the range, not the anchor.
22.214.171.124. Visual mode [Phase 9]
In visual mode, in a left-to-right paragraph, the Home key moves the selection to the left-most viable location on the current line, and the End key moves the selection to the right-most viable location. In a right-to-left paragraph, the Home key moves the selection to the right-most location, and the End key moves the selection to the left-most location.
The Shift-Home key extends the selection from the current anchor point to the left-most viable location on the current line (or right-most, in a right-to-left paragraph). The Shift-End key extends the selection from the current anchor point to the right-most viable location on the current line (or left-most, in a right-to-left paragraph). When starting from a range selection, the current line is considered to be the one containing the end-point of the range, not the anchor.
Double-clicking will create a range selection covering a single word of text.
Determining correct word boundaries for scripts that do not use white space between words is not required.
Handling triple-clicking, e.g., to select a paragraph, is not required.
6.3. Formatting [Phase 3]
For phases 3 – 5, the only formatting options that are required relate to font and size.
The control will be initialized with a default font, which will be used for all plain text and any formatted text where font is unspecified. For text specified in HTML, the font will be indicated by the font-family style property as discussed in the HTML specification.
The control will be initialized with a default font, which will be used for all plain text and any formatted text where font is unspecified. For text specified in HTML, the font will be indicated by the font-size style property as discussed in the HTML specification.
Font size can be indicated in either absolute or relative terms. Absolute terms means the exact point size is indicated, such as 18 points. Relative means a percentage of the default font size, such as 150% for a font that is larger than the default font size of the control.
6.3.3. UI for setting font and size
The edit control may include a right-click menu option to allowing the setting of font and size. Choosing this item brings up a small dialog containing font and size combo-boxes. [This is an optional feature.]
7. Input and rendering capabilities
7.1. Keyboard input
The control will be compiled as a Unicode window, which means that data received from the keyboard will be 16-bit Unicode characters. It is expected that various system keyboards as well as Keyman keyboards will be used to generate input. However, it is not required to programmatically or automatically choose any keyboard, for instance, as a result of clicking, using arrow keys, or changing the font.
The control will be able to render using the Graphite engine as well as generate simple rendering needed for basic Roman text. (Good support for Uniscribe rendering is available using the same interface as the Graphite engine.)
The Graphite engine will be used for any range of text that uses a Graphite-enabled font.
Behaviors required for complex scripts, such as split cursors and bidirectionality, will be provided by using the Graphite engine.
(c) Copyright 2003 UNESCO and SIL International Inc.