A Guide to Embedding The Gecko Editor

In the Beginning there is MakeEditable

Given an nsIWebBrowser instance, get a nsIDOMWindow from the GetContentDOMWindow call.  Then simply call nsIWebBrowser->do_GetInterface on the nsIWebBrowser to retrieve the nsIEditingSession from it.  From there you call editingSession->MakeWindowEditable(domWindow, editortype, PR_TRUE);    The first parameter is the nsIDOMWindow you just retrieved, the second is the editor type you want to create and the third is whether you want the window editable immediately or when the document is done loading.  In calling this method the editor is created underneath and the event listeners etc. are all prepared.

    nsCOMPtr<nsIDOMWindow> domWindow;
    nsresult rv = nsIWebBrowser->GetContentDOMWindow(getter_AddRefs(domWindow));
    if (NS_FAILED(rv)) return NS_ERROR_FAILURE; // we are not setup??!!

    nsCOMPtr<nsIEditingSession> editingSession;
    nsIWebBrowser->do_GetInterface(getter_AddRefs(editingSession));
    if (editingSession)
        editingSession->MakeWindowEditable(domWindow, "html", PR_TRUE);

The valid editor types are:

• "text" (similar to NotePad or a textarea; does not allow for html)
• "textmail" (similar to "text" but html can be inserted; intended for plaintext mail usage and handling of citations)
• "html" (this is the default type if no type is specified; it allows for all html tags to be inserted)
  
• "htmlmail" (this is much like "html" except there are a few editing rules / behaviors that differ such as splitting of mail quotes)
  

Editor Commands

To do anything meaningful you of course need to call commands and
receive updates. First get the nsICommandManager from the nsIWebBrowser
using do_GetInterface.

    nsCOMPtr<nsICommandManager> commandManager;
    nsIWebBrowser->do_GetInterface(getter_AddRefs(commandMgr));

To call a command use DoCommand:

    commandManager->DoCommand(aCommand, aCommandParams);

    aCommand is a const char * to a supported command name (see list below).
    aCommandParams could possibly be a null pointer or a pointer to a valid structure filled with relative parameters to aCommand. (see list below for legal params)

To see if a command is enabled use IsCommandEnabled

    commandManager->IsCommandEnabled(aCommand, retval)

To get the current command state of a given command use GetCommandState:

    commandManager->GetCommandState(aCommand,aCommandParams)
 

Index of Commands and Parameters

cmd_insertHTML
cmd_insertLinkNoUI
cmd_insertImageNoUI
cmd_insertHR

*Note: GetCommandState in these cases will return whether or not it is
possible to call DoCommand.  This will not really give you any concrete
information on the state of the current indent and outdent .
**Note: for color values, use the cstring representation of RRGGBB. i.e.
RED="#FF0000" and BLACK="#000000"

nsICommandParams 

Creating:

Writing:

SetBooleanValue
SetLongValue
SetDoubleValue
SetStringValue
SetCStringValue
SetISupportsValue
RemoveValue

Each will take a name value pair.  In the case of SetBooleanValue for
example you use a boolean as the second parameter.

    commandParam->SetCStringValue("state_attribute","left");

Reading:

First
GetNext (returns the next name in the name/value pair list)
HasMoreElements
GetValueType (numeric enum type see nsICommandParams for values)

If the name/value pair is known or it was obtained using the methods
described above, it is possible to call the following methods.

GetBooleanValue
GetLongValue
GetDoubleValue
GetStringValue
GetCStringValue
GetISupportsValue

All of these take pointers to values except for GetStringValue which
demands a reference to an nsAString.

commandParam->GetBooleanValue("state_enabled",&boolval);