jsRichEdit Design and Description

At design time in the Form Designer, jsRichEdit consists of a single PaintBox subclass. It can be placed on a Form, a SubForm, a Container, or a NoteBook. Simply ensure that the form's metric property is set to 6 - Pixels, select the jsRichEdit class on the Component Palette, and drop it anywhere on the Form, Container, or NoteBook, or instantiate it as you would any other class within a SubForm. The form.metric property *must* be set to 6 - Pixels for proper function of jsRichEdit at runtime. The form.metric setting is checked in jsRichEdit.onDesignOpen, and if form.metric # 6, jsRichEdit will display a reminder message regarding the correct form.metric setting. The form.metric setting is checked at runtime in jsRichEdit.onOpen and if form.metric # 6, the jsRichEdit object will release itself.

At runtime, a jsRichEdit object is really a cluster of 2 objects - the jsRichEdit PaintBox subclass, and a common controls rich edit editor window. During onOpen, jsRichEdit creates a rich edit editor window which is parented to the jsRichEdit PaintBox and positioned and sized the same as the jsRichEdit object. In effect, we now have 2 objects stacked directly on top of each other. At the bottom, directly on the surface of the form or container, is the jsRichEdit PaintBox. On top of the jsRichEdit Paintbox is the rich edit editor window.

The remaining function of the jsRichEdit object is to serve as the dBL 'bridge' between the application dBL code and the rich edit editor via the windows API. Through many properties and methods, the advanced word processing functionality of the rich edit editor can be directly exploited using relatively simple dBL application code. To understand 'why' there are so many properties and methods in jsRichEdit and to understand how to best use and take full advantage of jsRichEdit and the underlying rich edit technology, it would help to first understand some basic terminology and to understand the underlying rich edit technology.

The rich edit editor is a message-based window rather than a function-based window. All rich edit editor functionality is implemented via messages sent to the editing window. Some of these messages use complex data structures to pass information to and from the rich edit editor. The jsRichEdit class implements methods (functions) which provide wrappers for the messages and structures. Most methods encapsulate a single specific message supported by the rich edit editor by creating and filling any necessary data structures, sending the appropriate message to the editor, and then retrieving any returned data as necessary from the associated data structures, and setting values to appropriate properties of the jsRichEdit object as necessary for subsequent use in dBL code.

The rich edit editor technology can be basically viewed in 5 major groups of functionality:
It is the first 2 groups, paragraph formatting and character formatting, that are the most important to understand. One other point to note is the rich edit editor has 2 basic modes of operation - plaintext and richtext.

In rich edit technology, a paragraph is always delimited by a carriage return. A paragraph begins with the first character in the file, or the first character after a carriage return, and ends with a carriage return or the last character in the file. In richtext mode, each paragraph has attributes which are unique to that paragraph. Attributes can be assigned to each paragraph for indentation, bulleting and nubering, vertical space before and after the paragraph, spacing between lines within the paragraph, etc. In plaintext mode, all paragraphs are unformatted as there is no concept of paragraph attributes and only simple line wrapping is supported for formatting the display and printing of plain text.

In rich edit technology, using richtext mode, each individual character can have distinct attributes for font name, size, weight (bolding), color, etc. In plaintext mode, all characters in the file have the same format. That is, all characters have the same font attributes such as the font name, size, weight (bolding), color, etc. Essentially, in plaintext mode, the rich edit editor functions similarly to the dBL Editor class when editor.evalTags is set to false or similarly to the Notepad application.

The jsRichEdit class comprises many properties and methods that support the individual paragraph and character formatting options.

The property member names that begin with "font" are the property members that support character formatting. The method members that begin with "getFont" or "setFont" are method members which support character formatting. For example, the property member that indicates the current font size is named fontSize. The method to change the current font is named setFontSize. There is a single setFont* method for changing each individual font characteristic. There is a single method called getCharFormat which sets all of the font* properties to the font attributes of the current character.

The property member names that begin with "para" are the property members that support paragraph formatting. The method members that begin with "getPara" or "setPara" are method members which support paragraph formatting. For example, the property member that indicates the current paragraph alignment is named paraAlignment. The method to change the current paragraph's alignment is named setParaAlignment. There is a single method called getParaFormat which sets all of the para* properties to the paragraph attributes of the current paragraph.

There are many other property and method members that control editor style options (ses* property members), editor control options (eco* property members), editor modes, the current view, saving and loading the editor contents, etc. For those properties and methods which represent a single distinct rich edit characteristic or function, the jsRichEdit property and method member naming is derived from the defined API for the rich edit editor.

The jsRichEdit class also supports the concept of a dataLink. With simple hooks into a few rowset events, the jsRichEdit class can save to and read from any character-based table field. When in plaintext mode, the contents of the editor are saved to the dataLink field in plaintext formst. When in richtext mode, the contents of the editor are saved to the dataLink field in richtext format. Because rich text is simply an imbedded character tag format similar to HTML, the richtext format can be saved to almost any character-based field type.

The significant differences between the rich edit editor and the dBL Editor class are:
One other point to note is that the rich edit editor supports imbedding OLE objects (images, spreadsheets, etc) in the text. This requires system hooks and abilities that are not currently supported by the EXTERN system and therefore are not supported in jsRichEdit.

When saving formatted text in richtext mode, the resulting file is significantly larger than the actual character count. This is due to the RTF formatting tags that are streamed and imbedded within the text in the output file. RTF formatting is somewhat similar to HTML formatting in that distinct tags are imbedded within the text to 'tag' paragraph and character formatting attributes. If you view an RTF file in a plaintext editor, you will see the RTF tags.

Because the jsRichEdit class is, in the most simple definition, a dBL 'wrapper' for the operating system's common controls rich edit editor, the most authoritative resource for information regarding rich edit technology, operation, and reference can be found at MSDN Online - Rich Edit Controls. Also, be sure to search MSDN for other articles and information and examples of using rich edit.