From 9a84531cb2821fe9243c70639640ada17e977bbd Mon Sep 17 00:00:00 2001 From: "brade%netscape.com" Date: Mon, 2 Dec 2002 20:43:24 +0000 Subject: [PATCH] documentation; not part of a build git-svn-id: svn://10.0.0.236/trunk@134623 18797224-902f-48f8-a5cc-f745e15eee43 --- .../editor/docs/Editor_Embedding_Guide.html | 635 ++++++++++++++++++ mozilla/editor/docs/midas-spec.html | 439 ++++++++++++ 2 files changed, 1074 insertions(+) create mode 100644 mozilla/editor/docs/Editor_Embedding_Guide.html create mode 100644 mozilla/editor/docs/midas-spec.html diff --git a/mozilla/editor/docs/Editor_Embedding_Guide.html b/mozilla/editor/docs/Editor_Embedding_Guide.html new file mode 100644 index 00000000000..3cfd9098df7 --- /dev/null +++ b/mozilla/editor/docs/Editor_Embedding_Guide.html @@ -0,0 +1,635 @@ + + + + + + + + + + embeddocs + + +

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

+
+ + diff --git a/mozilla/editor/docs/midas-spec.html b/mozilla/editor/docs/midas-spec.html new file mode 100644 index 00000000000..c768813fa5e --- /dev/null +++ b/mozilla/editor/docs/midas-spec.html @@ -0,0 +1,439 @@ + + + + + + Midas Specification + + + + + Last revised:  November 15, 2002
+
+ Midas is rich text editing controls for a document.
+
+ +

Enabling Midas:

+ +
Given a document, you can add the attribute +"designMode" and set it to "on" to get an editable document.  For example, +in JavaScript, if you have an iframe with an id of 'edit', you can get its +contentDocument and set designMode to "on" like this:
+ +
document.getElementById("edit").contentDocument.designMode="on"; +
+
+ Right now, you can't completely turn off editing by setting designMode to +"off."  Setting designMode to "off" will prevent certain operations +from being handled but typing and other actions are still possible.
+
+
+ +

Invoking Commands:

+

execCommand
+

+ +
Given a document that has Midas enabled, +you can invoke specific commands on the document by calling execCommand with +3 parameters.  For example, in JavaScript, if you have an editable document, +you can invoke the bold command by calling this:
+ +
editableDocument.execCommand("Bold", +false, null);
+ Notes:  If you haven't set designMode to "On", you will get an error. + This could also happen if you call execCommand with the wrong document.
+
+ There are 3 required parameters for execCommand:
+ +
    +
  1. command string
    2. +
  2. boolean flag for showing UI
    3. +
  3. value string
    4. + +
+ The first parameter is a string which contains the command.  The second +parameter is a boolean flag.  If it is set to true, you will get an +error (NS_ERROR_NOT_IMPLEMENTED).  The third parameter is a string which +is the value.  Some commands will require details such as the particular +size you want to set when setting a font size.
+
+ The section on Supported Commands will document each command and any corresponding +values needed.
+
+ +
+
+

queryCommandEnabled

+
This command operates on the editable document.  There is +one required parameter (the command string).  The result is a boolean +which is true if the command is can be done given the current selection and/or +caret position.  The result is false if the command should not be invoked +(execCommand) given the current selection and/or caret position.
+
+
+

queryCommandState

+
xxx
+
+
+

queryCommandValue

+
xxx
+
+
+

Supported Commands:

+ +
The following list of commands is presented +in alphabetical order.  The commands may be mixed case or whatever makes +your code more readable.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
command
+ 		value
+ 		explanation / behavior
+
backcolor
+ 		????
+ 		This command is untested right now.
+ This command will set the background color of the document.
bold
+ 		none
+ 		If there is no selection, the insertion +point will set bold for subsequently typed characters.  
+
+If there is a selection and all of the characters are already bold, the bold +will be removed.  Otherwise, all selected characters will become bold.
+
copy
+ 		none
+ 		If there is a selection, this command +will copy the selection to the clipboard.  If there isn't a selection, +nothing will happen.
+
+ note:  the shortcut key will automatically trigger this command (typically +accel-C)
+
createlink
+ 		url (href)
+ 		This command will not do anything if no selection +is made.  If there is a selection, a link will be inserted around the +selection with the url parameter as the href of the link.
+
cut
+ 		none
+ 		If there is a selection, this command +will copy the selection to the clipboard and remove the selection from the +edit control.  If there isn't a selection, nothing will happen.
+
+ note:  the shortcut key will automatically trigger this command (typically +accel-X)
+
delete
+ 		none
+ 		This command will delete all text and objects that +are selected.
+
fontname
+ 		????
+ 		This command will set the fontface for a selection +or at the insertion point if there is no selection.
+
fontsize
+ 		????
+ 		This command will set the fontsize for a selection +or at the insertion point if there is no selection.
+
forecolor
+ 		????
+ 		This command is untested right now.
+ This command will set the text color of the selection or at the insertion +point.
+
formatblock
+ 		????
+
+
heading
+ 		????
+
+
indent
+ 		none
+ 		Indent the block where the caret is +located.
+
inserthorizontalrule
+ 		none
+ 		This command will insert a horizontal rule (line) +at the insertion point.
+
+Does it delete the selection?
+
insertimage
+ 		url (src)
+ 		This command will insert an image (referenced by url) +at the insertion point.
+
+ Does it delete the selection?
+
insertorderedlist
+ 		none
+
+
insertunorderedlist
+ 		none
+
+
italic
+ 		none
+ 		If there is no selection, the insertion +point will set italic for subsequently typed characters.  
+
+If there is a selection and all of the characters are already italic, the +italic will be removed.  Otherwise, all selected characters will become +italic.
justifycenter
+ 		none
+
+
justifyfull
+ 		none
+
+
justifyleft
+ 		none
+
+
justifyright
+ 		none
+
+
outdent
+ 		none
+ 		Outdent the block where the caret +is located.  If the block is not indented prior to calling outdent, +nothing will happen.
+
+note:  is an error thrown if no outdenting is done?
+
paste
+ 		none
+ 		This command is disabled for the +time being to prevent security exploits.
+
+This command will paste the contents of the clipboard at the location of +the caret.  If there is a selection, it will be deleted prior to the +insertion of the clipboard's contents.
+
+ note:  the shortcut key will automatically trigger this command (typically +accel-V)
redo
+ 		none
+ 		This command will redo the previous +undo action.  If undo was not the most recent action, this command will +have no effect.
+
+ note:  the shortcut key will automatically trigger this command (typically +accel-shift-Z)
removeformat
+ 		none
+
+
selectall
+ 		none
+ 		This command will select all of the +contents within the editable area.
+
+ note:  the shortcut key will automatically trigger this command (typically +accel-A)
+
strikethrough
+ 		none
+ 		If there is no selection, the insertion point will +set strikethrough for subsequently typed characters.  
+
+If there is a selection and all of the characters are already striked, the +strikethrough will be removed. Otherwise, all selected characters will have +a line drawn through them.
+
subscript
+ 		none
+ 		If there is no selection, the insertion point will +set subscript for subsequently typed characters.  
+
+ If there is a selection and all of the characters are already subscripted, +the subscript will be removed. Otherwise, all selected characters will be +drawn slightly lower than normal text.
+
superscript
+ 		none
+ 		If there is no selection, the insertion point will +set superscript for subsequently typed characters.  
+
+ If there is a selection and all of the characters are already superscripted, +the superscript will be removed. Otherwise, all selected characters will +be drawn slightly higher than normal text
+
underline
+ 		none
+ 		If there is no selection, the insertion +point will set underline for subsequently typed characters.  
+
+If there is a selection and all of the characters are already underlined, +the underline will be removed. Otherwise, all selected characters will become +underlined.
undo
+ 		none
+ 		This command will undo the previous +action.  If no action has occurred in the document, then this command +will have no effect.
+
+ note:  the shortcut key will automatically trigger this command (typically +accel-Z)
+
unlink
+ 		none
+
+
+
+
+
+ +