pjs/editor/docs/Editor_Embedding_Guide.html

<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
  <meta http-equiv="Content-Type"
 content="text/html; charset=iso-8859-1">
  <meta name="Author" content="mike judge">
  <title></title>
</head>
<body>
<h1><b> A Guide to Embedding The Gecko Editor</b></h1>
11/5/02 original by Michael Judge &lt;<a
 href="mailto:mjudge@netscape.com">mjudge@netscape.com</a>&gt;<br>
3/27/03 updates by Kathleen Brade &lt;<a
 href="mailto:brade@netscape.com">brade@netscape.com</a>&gt;<br>
<h2>In the Beginning there is MakeEditable</h2>
<p>Given an nsIWebBrowser instance, get a nsIDOMWindow from the
GetContentDOMWindow call.&nbsp; Then simply call
nsIWebBrowser-&gt;do_GetInterface on the nsIWebBrowser to retrieve the
nsIEditingSession from it.&nbsp; From there you call
editingSession-&gt;MakeWindowEditable(domWindow, editortype,
PR_TRUE);&nbsp;&nbsp;&nbsp; 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.&nbsp; In calling this method the editor is
created underneath and the event listeners etc. are all prepared.<br>
</p>
<p><i>&nbsp;&nbsp;&nbsp; nsCOMPtr&lt;nsIDOMWindow&gt; domWindow;<br>
&nbsp;&nbsp;&nbsp; nsresult rv =
nsIWebBrowser-&gt;GetContentDOMWindow(getter_AddRefs(domWindow));<br>
&nbsp;&nbsp;&nbsp; if (NS_FAILED(rv)) return NS_ERROR_FAILURE; // we
are not setup??!!<br>
</i></p>
<p><i>&nbsp;&nbsp;&nbsp; nsCOMPtr&lt;nsIEditingSession&gt;
editingSession;<br>
&nbsp;&nbsp;&nbsp;
nsIWebBrowser-&gt;do_GetInterface(getter_AddRefs(editingSession));<br>
&nbsp;&nbsp;&nbsp; if (editingSession)<br>
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
editingSession-&gt;MakeWindowEditable(domWindow, "html", PR_TRUE);</i></p>
<p>The valid editor types are:<br>
</p>
<ul>
  <li>"text" (similar to NotePad or a textarea; does not allow for html)</li>
  <li>"textmail" (similar to "text" but html can be inserted; intended
for plaintext mail usage and handling of citations)</li>
  <li>"html" (this is the default type if no type is specified; it
allows for all html tags to be inserted)<br>
  </li>
  <li>"htmlmail" (this is much like "html" except there are a few
editing rules / behaviors that differ such as splitting of mail quotes)<br>
  </li>
</ul>
<h2>Editor Commands</h2>
<p>To do anything meaningful you of course need to call commands and<br>
receive updates. First get the nsICommandManager from the nsIWebBrowser<br>
using do_GetInterface.</p>
<p><i>&nbsp;&nbsp;&nbsp; nsCOMPtr&lt;nsICommandManager&gt;
commandManager;<br>
&nbsp;&nbsp;&nbsp;
nsIWebBrowser-&gt;do_GetInterface(getter_AddRefs(commandMgr));</i><br>
</p>
<p>To call a command use DoCommand:</p>
<p><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><i>commandManager</i><i>-&gt;DoCommand(aCommand,
aCommandParams);</i> </p>
<p>&nbsp;&nbsp;&nbsp; <i>aCommand</i> is a const char * to a supported
command name (see list below).<br>
&nbsp;&nbsp;&nbsp; <i>aCommandParams</i> 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)</p>
<p>To see if a command is enabled use IsCommandEnabled</p>
<p><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><i>commandManager</i><i>-&gt;IsCommandEnabled(aCommand,
retval)</i> </p>
<p>To get the current command state of a given command use
GetCommandState: </p>
<p><i>&nbsp;&nbsp;&nbsp;&nbsp;</i><i>commandManager</i><i>-&gt;GetCommandState(aCommand,aCommandParams)</i> <br>
&nbsp;</p>
<h3>Index of Commands and Parameters</h3>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">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<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">acts upon the current selection to
apply style<br>
(cmd_tt is fixed width or "teletype" style)<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_all"(boolean),
"state_begin"(boolean),<br>
"state_end"(boolean), "state_mixed"(boolean)<br>
"state_enabled" (boolean)<br>
      </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameters<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%">see also cmd_removeStyles<br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_removeLinks<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">removes the existing link from the
selection (if any)<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_enabled"(boolean)<br>
???<br>
      </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameters<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_ol, cmd_ul, cmd_dt, cmd_dd<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">converts selection to appropriate
list or list item; inserts new list if no selection (cmd_ol, cmd_ul)<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_enabled"(boolean)<br>
???<br>
      </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameters<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%">see also cmd_removeList<br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_indent, cmd_outdent<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">indents/outdents the line(s) of the
current selection<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_enabled"(boolean)<br>
???<br>
      </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameters<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<p> </p>
<p> </p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_increaseFont, cmd_decreaseFont<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">acts upon the current selection to
adjust font size (uses &lt;big&gt; and &lt;small&gt; tags).<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_enabled" </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameters<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_undo, cmd_redo<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">undoes/redoes last executed command.
&nbsp;(only available if txmgr.dll is present)<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_enabled" </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameters<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_fontColor<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">acts upon the current selection to
set the font color<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (cstring)<br>
      </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (cstring) **<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_backgroundColor<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">sets the background color of
&nbsp;the document<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (cstring) </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (cstring) ** </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_fontFace<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">sets the font face for the current
selection<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (string) </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (cstring or
string) <br>
&nbsp;&nbsp; "Helvetica, Arial, sans-serif"<br>
&nbsp;&nbsp; "Times New Roman, Times, serif"<br>
&nbsp;&nbsp; "Courier New, Courier, monospace" <br>
[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]<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">cmd_align<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">sets the alignment for the lines
contained in the current selection<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (cstring) </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">"state_attribute"
(cstring)&nbsp;"left","right","center", "full"???&nbsp; XXXX<br>
      </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
cmd_insertHTML<br>
cmd_insertLinkNoUI<br>
cmd_insertImageNoUI<br>
cmd_insertHR<br>
</p>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">"cmd_charSet" XXXXX </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">sets the charset for the document.
there must be a clear undo stack or this will not work<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">"state_attribute" (cstring)<br>
      </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">"state_attribute"
(cstring)&nbsp;&nbsp; </td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">"cmd_copy",&nbsp;"cmd_delete",&nbsp;"cmd_cut",
"cmd_paste",&nbsp;"cmd_cutOrDelete"</td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">operates on the current selection to
copy, delete, cut and paste&nbsp; respectively<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">*"state_enabled" (boolean) </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameter&nbsp;</td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">"cmd_deleteCharBackward",&nbsp;"cmd_deleteCharForward",
"cmd_deleteWordForward",<br>
"cmd_deleteWordBackward",
"cmd_deleteToBeginningOfLine",&nbsp;"cmd_deleteToEndOfLine",<br>
      </td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">deletes relative to the current
selection end point.<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">*"state_enabled" (boolean) </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameter&nbsp;</td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">"cmd_scrollTop",&nbsp;"cmd_scrollBottom",&nbsp;"cmd_scrollPageUp",&nbsp;"cmd_scrollPageDown",<br>
"cmd_selectTop",
"cmd_selectBottom",&nbsp;"cmd_selectLineNext",&nbsp;"cmd_selectLinePrevious",<br>
"cmd_selectCharPrevious",
"cmd_selectCharNext",&nbsp;"cmd_selectBeginLine",&nbsp;"cmd_selectEndLine",<br>
"cmd_selectWordPrevious", "cmd_selectWordNext",&nbsp;</td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">scrolls relative to the current
selection end point.<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">*"state_enabled" (boolean) </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameter&nbsp;</td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p><br>
</p>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
  <tbody>
    <tr>
      <td valign="top">Command<br>
      </td>
      <td valign="top" width="75%">"cmd_movePageUp",&nbsp;"cmd_movePageDown",&nbsp;"cmd_moveTop",&nbsp;"cmd_moveBottom",<br>
"cmd_lineNext",
"cmd_linePrevious",&nbsp;"cmd_charPrevious",&nbsp;"cmd_charNext",&nbsp;"cmd_beginLine",<br>
"cmd_endLine", "cmd_wordPrevious",&nbsp;"cmd_wordNext"</td>
    </tr>
    <tr>
      <td valign="top">Description<br>
      </td>
      <td valign="top" width="75%">scrolls relative to the current
selection end point.<br>
      </td>
    </tr>
    <tr>
      <td valign="top">GetCommandState<br>
      </td>
      <td valign="top" width="75%">*"state_enabled" (boolean) </td>
    </tr>
    <tr>
      <td valign="top">DoCommand<br>
      </td>
      <td valign="top" width="75%">no parameter&nbsp;</td>
    </tr>
    <tr>
      <td valign="top"><br>
      </td>
      <td valign="top" width="75%"><br>
      </td>
    </tr>
  </tbody>
</table>
<p>*Note: GetCommandState in these cases will return whether or not it
is <br>
possible to call DoCommand.&nbsp; This will not really give you any
concrete <br>
information on the state of the current indent and outdent .<br>
**Note: for color values, use the cstring representation of RRGGBB. i.e.<br>
RED="#FF0000" and BLACK="#000000"<br>
<br>
</p>
<h2>nsICommandParams&nbsp; </h2>
<h3>Creating:</h3>
<i>- how do you create an nsICommandParams? -saari</i><br>
<br>
<h3>Writing:</h3>
Once you have created an nsICommandParams you call the "Set" methods.
<p>SetBooleanValue<br>
SetLongValue<br>
SetDoubleValue<br>
SetStringValue<br>
SetCStringValue<br>
SetISupportsValue<br>
RemoveValue</p>
<p>Each will take a name value pair.&nbsp; In the case of
SetBooleanValue for<br>
example you use a boolean as the second parameter.</p>
<p>&nbsp;&nbsp;&nbsp;<i>
commandParam-&gt;SetCStringValue("state_attribute","left");</i><br>
</p>
<h3>Reading:</h3>
For reading you may go after individual name/value pairs you know are<br>
there or you may iterate through all the name/value pairs and<br>
programatically pull off data.
<p>First<br>
GetNext (returns the next name in the name/value pair list)<br>
HasMoreElements<br>
GetValueType (numeric enum type see nsICommandParams for values)</p>
<p>If the name/value pair is known or it was obtained using the methods<br>
described above, it is possible to call the following methods.</p>
<p>GetBooleanValue<br>
GetLongValue<br>
GetDoubleValue<br>
GetStringValue<br>
GetCStringValue<br>
GetISupportsValue</p>
<p>All of these take pointers to values except for GetStringValue which<br>
demands a reference to an nsAString.</p>
<p>commandParam-&gt;GetBooleanValue("state_enabled",&amp;boolval);<br>
</p>
<br>
</body>
</html>