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>
4/09/03 updates by Ian Oeschger <oeschger@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); 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(commandManager));
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" (cstring) |
| DoCommand |
"state_attribute" (cstring) "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 |
| Command |
cmd_insertHTML, cmd_insertLinkNoUI, cmd_insertImageNoUI, cmd_insertHR |
| Description |
XXX |
| GetCommandState |
"state_attribute" (cstring) |
| DoCommand |
"state_attribute" (cstring) |
| 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:
Create an nsICommandParams with the contract ID for the command-params component (NS_COMMAND_PARAMS_CONTRACTID is defined in nsICommandParams.idl as "@mozilla.org/embedcomp/command-params;1"):
// create params for command
nsCOMPtr
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 arethere 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);