From 8faaa86decc48348e20d3bad04cea463a5b98fd6 Mon Sep 17 00:00:00 2001 From: "brade%netscape.com" Date: Tue, 1 Apr 2003 09:54:28 +0000 Subject: [PATCH] correct some API changes; add a few more commands; still incomplete (NOT PART OF BUILD) --- editor/docs/Editor_Embedding_Guide.html | 1221 ++++++++++++----------- 1 file changed, 643 insertions(+), 578 deletions(-) diff --git a/editor/docs/Editor_Embedding_Guide.html b/editor/docs/Editor_Embedding_Guide.html index 3cfd9098df7..2b3b987d7a5 100644 --- a/editor/docs/Editor_Embedding_Guide.html +++ b/editor/docs/Editor_Embedding_Guide.html @@ -1,635 +1,700 @@ - - - - - embeddocs + - +

A Guide to Embedding The Gecko Editor

-11/5/02
-
- +11/5/02 original by Michael Judge <mjudge@netscape.com>
+3/27/03 updates by Kathleen Brade <brade@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, -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.
+

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;
-    nsIWebBrowser->GetContentDOMWindow(getter_AddRefs(domWindow));

-

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

-

    editingSession->MakeWindowEditable(domWindow, -PR_TRUE);
-

- +    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:
+

+

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

- +

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

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

-
-
- -


-

- - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + +
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)   + 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_copy", "cmd_delete", "cmd_cut", +
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
+

+
+
+


+cmd_insertHTML
+cmd_insertLinkNoUI
+cmd_insertImageNoUI
+cmd_insertHR
+

+


+

+ + + + + + + + + + + + + + + + + + + + + + + +
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 +
Description
+ 		operates on the current selection to copy, delete, cut and paste  respectively
-
GetCommandState
- 		*"state_enabled" (boolean)
DoCommand
- 		no parameter 

-
-
GetCommandState
+ 		*"state_enabled" (boolean)
DoCommand
+ 		no parameter 

+
+
- -

-


-

- +

- - - - + + + - - - - - - - - - - - - - - - - - - - +"cmd_deleteWordBackward", +"cmd_deleteToBeginningOfLine", "cmd_deleteToEndOfLine",
+ + + + + + + + + + + + + + + + + + +
Command
- 		"cmd_deleteCharBackward", "cmd_deleteCharForward", +
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 

-
-
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_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 

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

*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"

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

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

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

- +described above, it is possible to call the following methods.

GetBooleanValue
- GetLongValue
- GetDoubleValue
- GetStringValue
- GetCStringValue
- GetISupportsValue

- +GetLongValue
+GetDoubleValue
+GetStringValue
+GetCStringValue
+GetISupportsValue

All of these take pointers to values except for GetStringValue which
- demands a reference to an nsAString.

- +demands a reference to an nsAString.

commandParam->GetBooleanValue("state_enabled",&boolval);

-
+