embeddocs
Author: mike judge

# A Guide to Embedding The Gecko Editor

11/5/02

## 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, PR_TRUE); The first parameter is the nsIDOMWindow you just retrieved and the second is whether you want the window editable or not. In calling this method the editor is created underneath and the event listeners etc. are all prepared.

nsCOMPtr<nsIDOMWindow> domWindow;
nsIWebBrowser->GetContentDOMWindow(getter_AddRefs(domWindow));

nsCOMPtr<nsIEditingSession> editingSession;
nsIWebBrowser->do_GetInterface(getter_AddRefs(editingSession));

editingSession->MakeWindowEditable(domWindow, PR_TRUE);

## Editor Commands

To do anything meaningful you of course need to call commands and
recieve 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
Description | acts upon the current selection to apply style
GetCommandState | "state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean)
DoCommand | no parameters

Command | cmd_indent, cmd_outdent
Description | indents 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.
GetCommandState | "state_enabled"
DoCommand | no parameters

Command | cmd_undo, cmd_redo
Description | undoes/redoes last executed command. (only availabe 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" (cstring)
DoCommand | "state_attribute" (cstring) *** "Helvetica, Arial, sans-serif", "Times New Roman, Times, serif", "Courier New, Courier, monospace"

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"

Command | "cmd_charSet"
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"
***Font Face is a cstring of the following values : "Helvetica, Arial,
sans-serif", "Times New Roman, Times, serif", "Courier New, Courier,
monospace"

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