Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-07 20:17:37 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
7923efc8ec
gecko-dev/editor/public/nsITextEditor.h

385 lines
16 KiB
C++
Raw Blame History

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* The contents of this file are subject to the Netscape Public License
* Version 1.0 (the "NPL")=0; you may not use this file except in
* compliance with the NPL. You may obtain a copy of the NPL at
* http://www.mozilla.org/NPL/
*
* Software distributed under the NPL is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
* for the specific language governing rights and limitations under the
* NPL.
*
* The Initial Developer of this code under the NPL is Netscape
* Communications Corporation. Portions created by Netscape are
* Copyright (C) 1998 Netscape Communications Corporation. All Rights
* Reserved.
*/
#ifndef nsITextEditor_h__
#define nsITextEditor_h__
#define NS_ITEXTEDITOR_IID \
{/* afe65c90-bb82-11d2-86d8-000064657374*/ \
0xafe65c90, 0xbb82, 0x11d2, \
{0x8f, 0xd8, 0x0, 0x00, 0x64, 0x65, 0x73, 0x74} }
#include "nsIEditor.h"
#include "nscore.h"
class nsISupportsArray;
class nsIAtom;
class nsIOutputStream;
class nsString;
class nsIFileSpec;
#define TEXT_EDITOR_FLAG_PLAINTEXT 0x01 // only plain text entry is allowed via events
#define TEXT_EDITOR_FLAG_SINGLELINE 0x02 // enter key and CR-LF handled specially
#define TEXT_EDITOR_FLAG_PASSWORD 0x04 // text is not entered into content, only a representative character
#define TEXT_EDITOR_FLAG_READONLY 0x08 // editing events are disabled. Editor may still accept focus.
#define TEXT_EDITOR_FLAG_DISABLED 0x10 // all events are disabled (like scrolling). Editor will not accept focus.
#define TEXT_EDITOR_FLAG_FILTER 0x20 // text input is limited to certain character types, use mFilter
// XXX Text filters are extremely preliminary and should not yet be used!
// Need to work with international group to rationalize restricted input
#define TEXT_EDITOR_FILTER_NUMBERS 0x01 // ignore numbers
#define TEXT_EDITOR_FILTER_LETTERS 0x02 // ignore a-z,A-Z
#define TEXT_EDITOR_FILTER_NONALPHANUMBERIC 0x04 // accept only numbers and letters
/**
* The general text editor interface.
* <P>
* Use to edit text represented as a DOM tree.
* This interface is used for both plain text and rich text (attributed text).
* Different types of text fields are instantiated as a result of installing the
* proper GUI Manager and Edit Rules. For example,
* a single line plain text editor is instantiated by using the SingleLinePlainTextGUIManager
* to limit UI and the SingleLinePlainTextEditRules to filter input and output.
*/
class nsITextEditor : public nsISupports
{
public:
static const nsIID& GetIID() { static nsIID iid = NS_ITEXTEDITOR_IID; return iid; }
/** Initialize the text editor
* @param aDoc the document being edited. Cannot be changed after Init
* @param aPresShell the presentation shell displaying aDoc. Cannot be changed after Init
*/
NS_IMETHOD Init(nsIDOMDocument *aDoc,
nsIPresShell *aPresShell)=0;
/** return the edit flags for this editor */
NS_IMETHOD GetFlags(PRUint32 *aFlags)=0;
/** set the edit flags for this editor. May be called at any time. */
NS_IMETHOD SetFlags(PRUint32 aFlags)=0;
/** get the length of the document in characters */
NS_IMETHOD GetDocumentLength(PRInt32 *aCount)=0;
/**
* SetTextProperties() sets the aggregate properties on the current selection
*
* @param aProperty the property to set on the selection
* @param aAttribute the attribute of the property, if applicable. May be null.
* Example: aProperty="font", aAttribute="color"
* @param aValue if aAttribute is not null, the value of the attribute. May be null.
* Example: aProperty="font", aAttribute="color", aValue="0x00FFFF"
*/
NS_IMETHOD SetTextProperty(nsIAtom *aProperty,
const nsString *aAttribute,
const nsString *aValue)=0;
/**
* GetTextProperties() gets the aggregate properties of the current selection.
* All object in the current selection are scanned and their attributes are
* represented in a list of Property object.
*
* @param aProperty the property to get on the selection
* @param aAttribute the attribute of the property, if applicable. May be null.
* Example: aProperty="font", aAttribute="color"
* @param aValue if aAttribute is not null, the value of the attribute. May be null.
* Example: aProperty="font", aAttribute="color", aValue="0x00FFFF"
* @param aFirst [OUT] PR_TRUE if the first text node in the selection has the property
* @param aAny [OUT] PR_TRUE if any of the text nodes in the selection have the property
* @param aAll [OUT] PR_TRUE if all of the text nodes in the selection have the property
*/
NS_IMETHOD GetTextProperty(nsIAtom *aProperty,
const nsString *aAttribute,
const nsString *aValue,
PRBool &aFirst, PRBool &aAny, PRBool &aAll)=0;
/**
* RemoveTextProperties() deletes the properties from all text in the current selection.
* If aProperty is not set on the selection, nothing is done.
*
* @param aProperty the property to reomve from the selection
* @param aAttribute the attribute of the property, if applicable. May be null.
* Example: aProperty="font", aAttribute="color"
* nsIEditProperty::allAttributes is special. It indicates that
* all content-based text properties are to be removed from the selection.
*/
NS_IMETHOD RemoveTextProperty(nsIAtom *aProperty, const nsString *aAttribute)=0;
/**
* DeleteSelection removes all nodes in the current selection.
* @param aDir if eLTR, delete to the right (for example, the DEL key)
* if eRTL, delete to the left (for example, the BACKSPACE key)
*/
NS_IMETHOD DeleteSelection(nsIEditor::ECollapsedSelectionAction aAction)=0;
/**
* InsertText() Inserts a string at the current location, given by the selection.
* If the selection is not collapsed, the selection is deleted and the insertion
* takes place at the resulting collapsed selection.
* It is expected that this would be used for Paste.
*
* NOTE: what happens if the string contains a CR?
*
* @param aString the string to be inserted
*/
NS_IMETHOD InsertText(const nsString& aStringToInsert)=0;
/**
* SetMaxTextLength sets a limit on the number of characters the document is allowed to contain.
* Any text insertion will truncate the inserted string to respect this number
* It is somewhat expensive to set this property, so do so only when necessary.
* A value of -1 means there is no limit.
*/
NS_IMETHOD SetMaxTextLength(PRInt32 aMaxLength)=0;
/**
* The handler for the ENTER key.
* @see nsIEditor::InsertBreak
*/
NS_IMETHOD InsertBreak()=0;
/** turn the undo system on or off
* @param aEnable if PR_TRUE, the undo system is turned on if it is available
* if PR_FALSE the undo system is turned off if it was previously on
* @return if aEnable is PR_TRUE, returns NS_OK if the undo system could be initialized properly
* if aEnable is PR_FALSE, returns NS_OK.
*/
NS_IMETHOD EnableUndo(PRBool aEnable)=0;
/** Undo reverses the effects of the last Do operation, if Undo is enabled in the editor.
* It is provided here so clients need no knowledge of whether the editor has a transaction manager or not.
* If a transaction manager is present, it is told to undo and the result of
* that undo is returned.
* Otherwise, the Undo request is ignored and an error NS_ERROR_NOT_AVAILABLE is returned.
*
*/
NS_IMETHOD Undo(PRUint32 aCount)=0;
/** returns state information about the undo system.
* @param aIsEnabled [OUT] PR_TRUE if undo is enabled
* @param aCanUndo [OUT] PR_TRUE if at least one transaction is currently ready to be undone.
*/
NS_IMETHOD CanUndo(PRBool &aIsEnabled, PRBool &aCanUndo)=0;
/** Redo reverses the effects of the last Undo operation
* It is provided here so clients need no knowledge of whether the editor has a transaction manager or not.
* If a transaction manager is present, it is told to redo and the result of the previously undone
* transaction is reapplied to the document.
* If no transaction is available for Redo, or if the document has no transaction manager,
* the Redo request is ignored and an error NS_ERROR_NOT_AVAILABLE is returned.
*
*/
NS_IMETHOD Redo(PRUint32 aCount)=0;
/** returns state information about the redo system.
* @param aIsEnabled [OUT] PR_TRUE if redo is enabled
* @param aCanRedo [OUT] PR_TRUE if at least one transaction is currently ready to be redone.
*/
NS_IMETHOD CanRedo(PRBool &aIsEnabled, PRBool &aCanRedo)=0;
/** BeginTransaction is a signal to the editor that the caller will execute multiple updates
* to the content tree that should be treated as a single operation,
* in the most efficient way possible.<br>
* All transactions executed between a call to BeginTransaction and EndTransaction
* will be undoable as an atomic action.<br>
* EndTransaction must be called after BeginTransaction.<br>
* Calls to BeginTransaction can be nested, as long as EndTransaction is called once per BeginTransaction.
*/
NS_IMETHOD BeginTransaction()=0;
/** EndTransaction is a signal to the editor that the caller is finished updating the content model.
* BeginTransaction must be called before EndTransaction is called.
* Calls to BeginTransaction can be nested, as long as EndTransaction is called once per BeginTransaction.
*/
NS_IMETHOD EndTransaction()=0;
/* the following methods are the convenience methods to make text editing easy for the embedding App
* all simple getter and setter methods use Get/Set/RemoveProperties
* we're looking for a balance between convenience and API bloat, since many of these actions can be
* achieved in other ways.
*/
// Selection and navigation -- exposed here for convenience
/** move the selection up (towards the beginning of the document.)
* @param aIncrement the amount to move the Selection
* legal values are nsIEditor::Line, nsIEditor::Page
*/
NS_IMETHOD MoveSelectionUp(nsIAtom *aIncrement, PRBool aExtendSelection)=0;
/** move the selection down (towards the end of the document.)
* @param aIncrement the amount to move the Selection
* legal values are nsIEditor::Line, nsIEditor::Page
*/
NS_IMETHOD MoveSelectionDown(nsIAtom *aIncrement, PRBool aExtendSelection)=0;
/** move the selection by some increment.
* The dir attribute for the document is used to decide if "next" is LTR or RTL
* @param aIncrement the amount to move the Selection
* legal values are nsIEditor::Word, nsIEditor::Sentence, nsIEditor::Paragraph
* @param aExtendSelection
*/
NS_IMETHOD MoveSelectionNext(nsIAtom *aIncrement, PRBool aExtendSelection)=0;
NS_IMETHOD MoveSelectionPrevious(nsIAtom *aIncrement, PRBool aExtendSelection)=0;
/** select the next portion of the document
* The dir attribute for the document is used to decide if "next" is LTR or RTL
* @param aType the kind of selection to create.
* legal values are nsIEditor::Word, nsIEditor::Sentence, nsIEditor::Paragraph
* nsIEditor::Document
* @param aExtendSelection
*/
NS_IMETHOD SelectNext(nsIAtom *aIncrement, PRBool aExtendSelection)=0;
/** select the previous portion of the document
* The dir attribute for the document is used to decide if "next" is LTR or RTL
* @param aType the kind of selection to create.
* legal values are nsIEditor::Word, nsIEditor::Sentence, nsIEditor::Paragraph
* nsIEditor::Document
* @param aExtendSelection
*/
NS_IMETHOD SelectPrevious(nsIAtom *aIncrement, PRBool aExtendSelection)=0;
/** select the entire contents of the document */
NS_IMETHOD SelectAll()=0;
/** sets the document selection to the beginning of the document */
NS_IMETHOD BeginningOfDocument()=0;
/** sets the document selection to the end of the document */
NS_IMETHOD EndOfDocument()=0;
/** Respond to the menu 'Save' command; this may put up save UI if the document
* hasn't been saved yet.
*/
NS_IMETHOD Save()=0;
/** Respond to the menu 'Save As' command; this will put up save UI
* @param aSavingCopy true if we are saving off a copy of the document
* without changing the disk file associated with the doc.
* This would correspond to a 'Save Copy As' menu command.
*/
NS_IMETHOD SaveAs(PRBool aSavingCopy)=0;
/** cut the currently selected text, putting it into the OS clipboard
* What if no text is selected?
* What about mixed selections?
* What are the clipboard formats?
*/
NS_IMETHOD Cut()=0;
/** copy the currently selected text, putting it into the OS clipboard
* What if no text is selected?
* What about mixed selections?
* What are the clipboard formats?
*/
NS_IMETHOD Copy()=0;
/** paste the text in the OS clipboard at the cursor position, replacing
* the selected text (if any)
*/
NS_IMETHOD Paste()=0;
/** paste the text in the OS clipboard at the cursor position
* as a quotation (whose representation is dependant on the editor type),
* replacing the selected text (if any)
* @param aCitation The "mid" URL of the source message
*/
NS_IMETHOD PasteAsQuotation()=0;
/** insert a string as quoted text,
* as a quotation (whose representation is dependant on the editor type),
* replacing the selected text (if any)
* @param aQuotedText The actual text to be quoted
* @param aCitation The "mid" URL of the source message
*/
NS_IMETHOD InsertAsQuotation(const nsString& aQuotedText)=0;
/** scroll the viewport up (towards the beginning of the document.)
* @param aIncrement the amount to scroll
* legal values are nsIEditor::Line, nsIEditor::Page
*/
NS_IMETHOD ScrollUp(nsIAtom *aIncrement)=0;
/** scroll the viewport down (towards the end of the document.)
* @param aIncrement the amount to scroll
* legal values are nsIEditor::Line, nsIEditor::Page
*/
NS_IMETHOD ScrollDown(nsIAtom *aIncrement)=0;
/** scroll the viewport so the selection is in view.
* @param aScrollToBegin PR_TRUE if the beginning of the selection is to be scrolled into view.
* PR_FALSE if the end of the selection is to be scrolled into view
*/
NS_IMETHOD ScrollIntoView(PRBool aScrollToBegin)=0;
// Input/Output
NS_IMETHOD OutputTextToString(nsString& aOutputString, PRBool aSelectionOnly)=0;
NS_IMETHOD OutputHTMLToString(nsString& aOutputString, PRBool aSelectionOnly)=0;
NS_IMETHOD OutputTextToStream(nsIOutputStream* aOutputStream, nsString* aCharsetOverride, PRBool aSelectionOnly)=0;
NS_IMETHOD OutputHTMLToStream(nsIOutputStream* aOutputStream, nsString* aCharsetOverride, PRBool aSelectionOnly)=0;
/** Get and set the body wrap width
* @param aWrapColumn - the column to wrap at. This is set as a COLS attribute
* on a PRE block.
*
* Special values:
* 0 = wrap to window width
* -1 = no wrap at all
*
*/
NS_IMETHOD GetBodyWrapWidth(PRInt32 *aWrapColumn)=0;
NS_IMETHOD SetBodyWrapWidth(PRInt32 aWrapColumn)=0;
// Miscellaneous Methods
/** Apply the style sheet, specified by aURL, to the
* text editor's document.
*/
NS_IMETHOD ApplyStyleSheet(const nsString& aURL)=0;
/*
NS_IMETHOD CheckSpelling()=0;
NS_IMETHOD SpellingLanguage(nsIAtom *aLanguage)=0;
*/
/* The editor doesn't know anything about specific services like SpellChecking.
* Services can be invoked on the content, and these services can use the editor if they choose
* to get transactioning/undo/redo.
* For things like auto-spellcheck, the App should implement nsIDocumentObserver and
* trigger off of ContentChanged notifications.
*/
// IME Editing Methods
NS_IMETHOD BeginComposition(void)=0;
NS_IMETHOD SetCompositionString(const nsString& aCompositionString, nsIDOMTextRangeList* aTextRangeList)=0;
NS_IMETHOD EndComposition(void)=0;
// Logging Methods
NS_IMETHOD StartLogging(nsIFileSpec *aLogFile)=0;
NS_IMETHOD StopLogging()=0;
};
#endif //nsIEditor_h__
Reference in New Issue View Git Blame Copy Permalink