Editor Embedding Guide

This article is in need of a technical review.

In the Beginning there is MakeEditable

Given an nsIWebBrowser instance, get an 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 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

You need to call commands and receive updates in order to make any changes to the content on the browser. Below is the sequence of steps that need to be followed for the same:

1. Get the nsICommandManager from the nsIWebBrowser using do_GetInterface:

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

2. Call a command -- 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).

3. Verify if a command is enabled -- IsCommandEnabled:

commandManager->IsCommandEnabled(aCommand, retval)

4. Get the current command state of a given command -- GetCommandState:

commandManager->GetCommandState(aCommand,aCommandParams)

Index of Commands and Parameters

cmd_bold

Toggles bold style on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Example
normal bold

cmd_italics

Toggles italics style on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Example
normal italics

cmd_underline

Toggles underline on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Example
normal underline

cmd_tt

Toggles teletype style (monospace font) on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Example
normal teletype

cmd_strikethrough

Toggles strikethrough style on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Example
normal strikethrough

cmd_superscript

Toggles superscript style on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Example
normal superscript

cmd_subscript

Toggles subscript style on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Example
normal subscript

cmd_nobreak

Toggles nobreak style on selection. Text is not wrapped by word.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This one is not visually notable in the general case.

cmd_em

Toggles emphasis on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style. Most browsers display it the same as italics.

cmd_strong

Toggles strong on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style. Most browsers display it the same as bold.

cmd_cite

Toggles cite on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style. It is visually the same as italics.

cmd_abbr

Toggles abbreviation on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style.

cmd_acronym

Toggles acronym on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style.

cmd_code

Toggles code on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style. Typically it is displayed with monospace font.

cmd_samp

Toggles program output sample style on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style. Typically it is displayed with monospace font.

cmd_var

Toggles variable style on selection.

GetCommandState
"state_all"(boolean), "state_begin"(boolean), "state_end"(boolean), "state_mixed"(boolean), "state_enabled" (boolean)
DoCommand
no parameters
Note
This is logical style. Typically it is displayed with monospace font.

Removes the existing link from the selection (if any).

GetCommandState
"state_enabled"(boolean), ???
DoCommand
no parameters

cmd_ol

Makes ordered list from selection or inserts new list if there is no selection.

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters
Note
See also cmd_removeList

cmd_ul

Makes unordered list from selection or inserts new list if there is no selection.

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters
Note
See also cmd_removeList

cmd_dt

Inserts list item (dt element).

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters
Note
See also cmd_removeList

cmd_dd

Inserts list item (dd element).

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters
Note
See also cmd_removeList

cmd_removeList

Removes list from selection.

GetCommandState
???
DoCommand
no parameters

cmd_indent

Indents current selection.

GetCommandState
"state_enabled"(boolean), ???
DoCommand
no parameters

cmd_outdent

Outdents current selection.

GetCommandState
"state_enabled"(boolean), ???
DoCommand
no parameters

cmd_increaseFont

Increases font size (uses <big> tag).

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters

cmd_decreaseFont

Decreases font size (uses <small> tag).

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters

cmd_undo

Undoes last executed command.

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters
Note
Only available if txmgr.dll is present.

cmd_redo

Redoes last executed command.

GetCommandState
"state_enabled"(boolean)
DoCommand
no parameters
Note
Only available if txmgr.dll is present.

cmd_fontColor

Acts upon the current selection to set the font color.

GetCommandState
"state_attribute" (cstring)
DoCommand
"state_attribute" (cstring)
Note
For color values, use the cstring representation of RRGGBB, e.g., RED="#FF0000" and BLACK="#000000".

cmd_backgroundColor

Sets the background color of the document.

GetCommandState
"state_attribute" (cstring)
DoCommand
"state_attribute" (cstring)
Note
For color values, use the cstring representation of RRGGBB, e.g., RED="#FF0000" and BLACK="#000000".

cmd_fontFace

Sets the font face for the current selection.

GetCommandState
"state_attribute" (cstring)
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 of base functionality and in no way imply that this command won't handle other fonts.

cmd_align

Sets the alignment for the lines contained in the current selection.

GetCommandState
"state_attribute" (cstring)
DoCommand
"state_attribute" (cstring)
"left", "right", "center", "justify"

cmd_insertHTML

cmd_insertLinkNoUI

cmd_insertImageNoUI

cmd_insertHR

cmd_charSet

Sets the charset for the document.

GetCommandState
"state_attribute" (cstring)
DoCommand
"state_attribute" (cstring)
Note
There must be a clear undo stack or this will not work.

cmd_copy

Copies current selection.

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 command.

cmd_cut

Cuts current selection.

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 command.

cmd_delete

Deletes current selection.

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 command.

cmd_paste

Pastes into current selection or if there is no selection at the cursor position.

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 command.

cmd_cutOrDelete

Cuts or deletes current selection.

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 command.

cmd_deleteCharBackward

Deletes one character backward relative to the current selection end point. Acts like backspace key.

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 command.

cmd_deleteCharForward

Deletes one character forward relative to the current selection end point. Acts like delete key.

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 command.

cmd_deleteWordBackward

Deletes from beginning of word to the current selection end point. Acts as Ctrl+Backspace.

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 command.

cmd_deleteWordForward

Deletes from current selection end point to the end of word. Acts as Ctrl+Delete.

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 command.

cmd_deleteToBeginningOfLine

Deletes everything from beginning of line 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 command.

cmd_deleteToEndOfLine

Deletes everything from current selection end point to the end of line.

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 command.

cmd_deleteToEndOfLine

Deletes everything from current selection end point to the end of line.

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 command.

cmd_scrollTop

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 command.

cmd_scrollBottom

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 command.

cmd_scrollPageUp

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 command.

cmd_scrollPageDown

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 command.

cmd_selectTop

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 command.

cmd_selectBottom

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 command.

cmd_selectLineNext

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 command.

cmd_selectLinePrevious

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 command.

cmd_selectCharPrevious

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 command.

cmd_selectCharNext

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 command.

cmd_selectBeginLine

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 command.

cmd_selectEndLine

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 command.

cmd_selectWordPrevious

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 command.

cmd_selectWordNext

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 command.

cmd_movePageUp

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 command.

cmd_movePageDown

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 command.

cmd_moveTop

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 command.

cmd_moveBottom

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 command.

cmd_lineNext

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 command.

cmd_linePrevious

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 command.

cmd_charPrevious

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 command.

cmd_charNext

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 command.

cmd_beginLine

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 command.

cmd_endLine

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 command.

cmd_wordPrevious

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 command.

cmd_wordNext

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 command.

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

Original Document Information

 

Document Tags and Contributors

Last updated by: kscarfone,