Interface IDocument

The document is the container for all data displayed in the editor.

Inherited Members
System.IDisposable.Dispose()
Namespace: Sdl.DesktopEditor.EditorApi
Assembly: Sdl.DesktopEditor.EditorApi.dll
Syntax
public interface IDocument : IDisposable
Remarks

The document content is typically manipulated through the Selection.

Properties

ActiveRange

The range in the document on which operations such as Delete(), Replace(IDocumentFragment) etc. are executed.

Declaration
ContentRange ActiveRange { get; }
Property Value
Type Description
ContentRange
Remarks

The range is intended as a read-only object. Changing its properties will NOT move the active range in the document. Use MoveActiveRange(ContentRange) to explicitly change the active range in the document.

API clients set the active range before executing methods on the document. The range is also updated by methods that modify document content.

IsDirty

If true this indicates that the document content has been changed since the last time this flag was reset.

Declaration
bool IsDirty { get; set; }
Property Value
Type Description
System.Boolean
Remarks

The edit control automatically sets this flag to true every time some content changes in the editor (through API or user action).

Set this flag to false when the document is saved. That allows you to keep track of whether any changes have been made to it in order to determine if the document may need to be saved again at a later point.

Since the editor does not provide Open/Save operations it is the API client's responsibility to reset this flag after such operations.

RootContainer

The root container of all content in the document.

Declaration
IAbstractContainerNode RootContainer { get; }
Property Value
Type Description
IAbstractContainerNode

UndoBuffer

The Undo/Redo buffer used for editing operations on the document content.

Declaration
IUndoBuffer UndoBuffer { get; }
Property Value
Type Description
IUndoBuffer
Remarks

Note: There is no need to go through the undo buffer to invoke the 'Undo' and 'Redo' commands for the editor. If the edit control is available it is preferable to call Undo() and Redo() directly as this will allow the control to update user selection and caret positioning.

Methods

Copy()

Gets a detached copy of the active range content.

Declaration
IDocumentFragment Copy()
Returns
Type Description
IDocumentFragment

A copy of the content contained in the active range.

CopyAsText(Boolean)

Get the plain text content of the active range, as suited for Windows clipboard operations.

If writeSegmentsAsLineBreaks is true we will write a line break for every segment.

Declaration
string CopyAsText(bool writeSegmentsAsLineBreaks)
Parameters
Type Name Description
System.Boolean writeSegmentsAsLineBreaks
Returns
Type Description
System.String

Delete()

Delete the current content of the active range.

Declaration
void Delete()
Remarks

After delete the ActiveRange spans the location of the deleted content.

Note that the range is not necessarily empty after this operation. For example, it may contain ghost tags.

MoveActiveRange(ContentRange)

Method allowing the client to set the ActiveRange to the range provided.

Declaration
void MoveActiveRange(ContentRange range)
Parameters
Type Name Description
ContentRange range

The range to move the active range to. This must be from the same document.

MoveActiveRange(IContentSelection)

Method allowing the client to set the ActiveRange to the location corresponding to the selection.

Declaration
void MoveActiveRange(IContentSelection selection)
Parameters
Type Name Description
IContentSelection selection

The selection corresponding to the range to move to. This must be from an edit control using the same document.

Replace(IDocumentFragment)

Replace the content of the active range with the content of the document fragment.

Declaration
void Replace(IDocumentFragment newContent)
Parameters
Type Name Description
IDocumentFragment newContent

The document fragment containing the content to replace.
Remarks

After execution the ActiveRange spans the inserted content.

Events

AfterEditOperationAborted

If an edit operation in the control is aborted (i.e. an exception is thrown) this event will be fired after the corresponding composite operation has been rolled back.

Declaration
event EventHandler<EditOperationAbortedEventArgs> AfterEditOperationAborted
Event Type
Type Description
System.EventHandler<EditOperationAbortedEventArgs>

ContentChanged

Fired when content in the document is changed in any way.

Declaration
event EventHandler<DocumentContentChangedEventArgs> ContentChanged
Event Type
Type Description
System.EventHandler<DocumentContentChangedEventArgs>
Remarks

This event is typcially fired immediately when the content is changed, which can be before the controls displaying the content have been updated.

EditOperationCompleting

This event is fired when a (composite) edit operation is completing. You can handle this event to determine what changes are allowed in the edit control, by examining the edit operations (e.g. using a visitor) and throwing a InvalidEditOperationException if the changes are not to your liking.

Declaration
event EventHandler<EditOperationCompletingEventArgs> EditOperationCompleting
Event Type
Type Description
System.EventHandler<EditOperationCompletingEventArgs>
Remarks

The message of the InvalidEditOperationException is passed to the AfterEditOperationAborted event and may be shown to the user to explain why the edit was not permitted.

Avoid throwing exceptions of other types in this event handler. If an exception of another type is thrown the operation will still be aborted, but the message passed to AfterEditOperationAborted will be what System.Exception.ToString() returns, which cannot be considered user friendly.

Important: Do not call AbortCompositeOperation(String) from this event handler. That could yield unpredictable results since the operation is completing as a result of a call to EndCompositeOperation() (or a similar internal mechanism inside the edit control implementation) and the number of calls to BeginCompositeOperation(String) must always match the number of calls to EndCompositeOperation() plus the number of calls to AbortCompositeOperation(String).

EditOperationStarting

This event is fired when a (composite) edit operation is started, there are no changes done at this moment to the internal document structure. You can handle this event to determine what changes are allowed in the edit control or do last minute modifications before new content is interted/deleted modified, by examining the edit operations (e.g. using a visitor) and throwing a InvalidEditOperationException if the changes are not to your liking.

Declaration
event EventHandler<EditOperationCompletingEventArgs> EditOperationStarting
Event Type
Type Description
System.EventHandler<EditOperationCompletingEventArgs>
Remarks

The message of the InvalidEditOperationException is passed to the AfterEditOperationAborted event and may be shown to the user to explain why the edit was not permitted.

Avoid throwing exceptions of other types in this event handler. If an exception of another type is thrown the operation will still be aborted, but the message passed to AfterEditOperationAborted will be what System.Exception.ToString() returns, which cannot be considered user friendly.

Important: Do not call AbortCompositeOperation(String) from this event handler. That could yield unpredictable results since the operation is completing as a result of a call to EndCompositeOperation() (or a similar internal mechanism inside the edit control implementation) and the number of calls to BeginCompositeOperation(String) must always match the number of calls to EndCompositeOperation() plus the number of calls to AbortCompositeOperation(String).

Extension Methods