# A Guide to Embedding The Gecko Editor

11/5/02 original by Michael Judge <mjudge@netscape.com>
3/27/03 updates by Kathleen Brade <brade@netscape.com>

## 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, PR_FALSE); 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, the fourth is whether you want the editor to make the whole document editable, the fifth is whether you want to turn of scripts, plugins, ... 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, PR_FALSE, PR_TRUE, PR_FALSE);

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

Command | cmd_bold, cmd_italics, cmd_underline, cmd_tt, cmd_strikethru, cmd_superscript, cmd_subscript, cmd_nobreak, cmd_em, cmd_strong, cmd_cite, cmd_abbr, cmd_acronym, cmd_code, cmd_samp, cmd_var
Description | acts upon the current selection to apply style (cmd_tt is fixed width or "teletype" style)
GetCommandState | "state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean) "state_enabled" (boolean)
DoCommand | no parameters
| see also cmd_removeStyles

Command | cmd_removeLinks
Description | removes the existing link from the selection (if any)
GetCommandState | "state_enabled"(boolean) ???
DoCommand | no parameters

Command | cmd_ol, cmd_ul, cmd_dt, cmd_dd
Description | converts selection to appropriate list or list item; inserts new list if no selection (cmd_ol, cmd_ul)
GetCommandState | "state_enabled"(boolean) ???
DoCommand | no parameters
| see also cmd_removeList

Command | cmd_indent, cmd_outdent
Description | indents/outdents the line(s) of the current selection
GetCommandState | "state_enabled"(boolean) ???
DoCommand | no parameters

Command | cmd_increaseFont, cmd_decreaseFont
Description | acts upon the current selection to adjust font size (uses <big> and <small> tags).
GetCommandState | "state_enabled"
DoCommand | no parameters

Command | cmd_undo, cmd_redo
Description | undoes/redoes last executed command. (only available if txmgr.dll is present)
GetCommandState | "state_enabled"
DoCommand | no parameters

Command | cmd_fontColor
Description | acts upon the current selection to set the font color
GetCommandState | "state_attribute" (cstring)
DoCommand | "state_attribute" (cstring) **

Command | cmd_backgroundColor
Description | sets the background color of the document
GetCommandState | "state_attribute" (cstring)
DoCommand | "state_attribute" (cstring) **

Command | cmd_fontFace
Description | sets the font face for the current selection
GetCommandState | "state_attribute" (string)
DoCommand | "state_attribute" (cstring or string) "Helvetica, Arial, sans-serif" "Times New Roman, Times, serif" "Courier New, Courier, monospace" [any string is acceptable; the above strings should be considered examples or base functionality and in no way imply that this command won't handle other fonts]

Command | cmd_align
Description | sets the alignment for the lines contained in the current selection
GetCommandState | "state_attribute" (cstring)
DoCommand | "state_attribute" (cstring) "left","right","center", "full"??? XXXX

cmd_insertHTML
cmd_insertLinkNoUI
cmd_insertImageNoUI
cmd_insertHR

Command | "cmd_charSet" XXXXX
Description | sets the charset for the document. there must be a clear undo stack or this will not work
GetCommandState | "state_attribute" (cstring)
DoCommand | "state_attribute" (cstring)

Command | "cmd_copy", "cmd_delete", "cmd_cut", "cmd_paste", "cmd_cutOrDelete"
Description | operates on the current selection to copy, delete, cut and paste respectively
GetCommandState | *"state_enabled" (boolean)
DoCommand | no parameter

Command | "cmd_deleteCharBackward", "cmd_deleteCharForward", "cmd_deleteWordForward", "cmd_deleteWordBackward", "cmd_deleteToBeginningOfLine", "cmd_deleteToEndOfLine",
Description | deletes relative to the current selection end point.
GetCommandState | *"state_enabled" (boolean)
DoCommand | no parameter

Command | "cmd_scrollTop", "cmd_scrollBottom", "cmd_scrollPageUp", "cmd_scrollPageDown", "cmd_selectTop", "cmd_selectBottom", "cmd_selectLineNext", "cmd_selectLinePrevious", "cmd_selectCharPrevious", "cmd_selectCharNext", "cmd_selectBeginLine", "cmd_selectEndLine", "cmd_selectWordPrevious", "cmd_selectWordNext",
Description | scrolls relative to the current selection end point.
GetCommandState | *"state_enabled" (boolean)
DoCommand | no parameter

Command | "cmd_movePageUp", "cmd_movePageDown", "cmd_moveTop", "cmd_moveBottom", "cmd_lineNext", "cmd_linePrevious", "cmd_charPrevious", "cmd_charNext", "cmd_beginLine", "cmd_endLine", "cmd_wordPrevious", "cmd_wordNext"
Description | scrolls relative to the current selection end point.
GetCommandState | *"state_enabled" (boolean)
DoCommand | no parameter

*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:

- how do you create an nsICommandParams? -saari

### Writing:

Once you have created an nsICommandParams you call the "Set" methods.

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:

For reading you may go after individual name/value pairs you know are
there or you may iterate through all the name/value pairs and
programatically pull off data.

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);