You are currently viewing a snapshot of taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to, please file a bug.

You are here: Editor project page > Editor Plaintext Embedding

Embedding a Plaintext-Only Editor

In the NS 6.0 codebase, the editor is always an html editor, and plaintext editing is a special case of html.

Clients who want to embed the editor into other applications must take the whole editor, even if all that is needed is plaintext text fields.

This document discusses what's needed to separate the plaintext functionality from the rest of the html functionality.

What is a Plaintext Editor?

The plaintext editor is intended to be a lightweight replacement for native text fields and text areas.

Many clients will require features such as undo/redo (the transaction manager) and international input methods (IME) in a plaintext editor; others will not. So these sorts of features need to be separate and optional.

The plaintext editor is explicitly not intended to be a "rich-text editor" which allows changes such as bold, italic, etc. While there is definitely a need for a rich-text editing interface (distinct from more elaborate editing functionality such as table editing), most clients requesting a plaintext editor do not need this functionality. Rich text editing should be a separate interface.

API changes

The first step in implementation is to separate the interfaces in nsIHTMLEditor into those which really are oriented toward HTML editing, and those which are needed for plaintext editing. Here's a first stab at listing the methods needed for plaintext editing (which should be removed from nsIHTMLEditor and moved into nsIPlaintextEditor):

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * The Original Code is code.
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 * Contributor(s): 

#ifndef nsIPlaintextEditor_h__
#define nsIPlaintextEditor_h__

#define NS_IPLAINTEXTEDITOR_IID                  \
{ /* b5f39ed4-1dd1-11b2-9d00-fd54d6f54962 */     \
0xb5f39ed4, 0x1dd1, 0x11b2,                      \
{ 0x9d, 0x00, 0xfd, 0x54, 0xd6, 0xf5, 0x49, 0x62 } }

class nsIPlaintextEditor : public nsISupports
  static const nsIID& GetIID() 
  { static nsIID iid = NS_IHTMLEDITOR_IID; return iid; }

  /* ------------ Document info methods -------------- */

  /** get the length of the document in characters */
  NS_IMETHOD GetDocumentLength(PRInt32 *aCount)=0;

  NS_IMETHOD SetMaxTextLength(PRInt32 aMaxTextLength)=0;
  NS_IMETHOD GetMaxTextLength(PRInt32& aMaxTextLength)=0;

   * EditorKeyPress consumes a keyevent.
   * @param aKeyEvent    key event to consume
  NS_IMETHOD EditorKeyPress(nsIDOMKeyEvent* aKeyEvent)=0;

  /* ------------ content methods -------------- */

   * TypedText responds to user typing.
   * Provides a logging bottleneck for typing.
   * @param aString    string to type
   * @param aAction    action to take: insert text, insert BR, insert break
  NS_IMETHOD TypedText(const nsString& aString, PRInt32 aAction)=0;

   * InsertText() Inserts a string at the current location,
   * given by the selection.
   * If the selection is not collapsed, the selection is deleted
   * and the insertion takes place at the resulting collapsed selection.
   * NOTE: what happens if the string contains a CR?
   * @param aString   the string to be inserted
  NS_IMETHOD InsertText(const nsString& aStringToInsert)=0;

  /** Create a collapsed selection just after aElement
    * XXX could we parameterize SelectElement(before/select/after>?
    * The selection is set to parent-of-aElement with an
    *   offset 1 greater than aElement's offset
    *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
    *   be useful for other elements.
    * @param aElement  An element in the document
  NS_IMETHOD SetCaretAfterElement(nsIDOMElement* aElement)=0;

    * Set selection to start of document
  NS_IMETHOD SetCaretToDocumentStart()=0;
#endif /* nsIPlaintextEditor_h__ */

While we're at it, the drag/drop interfaces should be split off into a separate API, since they're not related to either html or plaintext but might be useful for either type of editor:

#ifndef nsIEditorDragDrop_h__
#define nsIEditorDragDrop_h__

#define NS_IEDITORDRADGROP_IID                   \
{ /* 3d492712-1dd2-11b2-9062-f1a3dbd0ca24 */     \
 0x3d492712, 0x1dd2, 0x11b2,                     \
{ 0x90, 0x62, 0xf1, 0xa3, 0xdb, 0xd0, 0xca, 0x24 { }

class nsIEditorDragDrop : public nsISupports
  static const nsIID& GetIID() 
  { static nsIID iid = NS_IHTMLEDITOR_IID; return iid; }

   * CanDrag decides if a drag should be started
   * (for example, based on the current selection and mousepoint).
  NS_IMETHOD CanDrag(nsIDOMEvent *aEvent, PRBool &aCanDrag)=0;

   * DoDrag transfers the relevant data (as appropriate)
   * to a transferable so it can later be dropped.
  NS_IMETHOD DoDrag(nsIDOMEvent *aEvent)=0;

   * InsertFromDrop looks for a dragsession and inserts the
   * relevant data in response to a drop.
  NS_IMETHOD InsertFromDrop(nsIDOMEvent *aEvent)=0;

#endif /* nsIEditorDragDrop_h__ */

Memory savings

Next, of course, these plaintext methods must be pulled out into a separate library. The preferred option is to keep the current editor library much like it is today, implementing both plaintext and html editing services, but add another, much smaller, library which implements only nsIPlaintextEditor, which embedding clients could use if they didn't care about html editing. This allows for the possibility that a plaintext-only editor might wish to avoid using the dom/html model altogether, for speed and simplicity, unlike a dual-mode editor such as the one used at present.

The first step will probably be to separate the plaintext methods into a separate file, and provide build flags which make it possible to build only the plaintext parts of the editor library.

Maintained by the editor team: