Interface IDocument
The document is the container for all data displayed in the editor.
Inherited Members
Namespace: SdlSdl.DesktopEditorEditorApi
Assembly: Sdl.DesktopEditor.EditorApi.dll
Syntax
public interface IDocument : IDisposableRemarks
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 |
|---|---|
| bool |
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(bool)
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 |
|---|---|---|
| bool | writeSegmentsAsLineBreaks |
Returns
| Type | Description |
|---|---|
| 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> AfterEditOperationAbortedEvent Type
| Type | Description |
|---|---|
| EventHandlerEditOperationAbortedEventArgs |
ContentChanged
Fired when content in the document is changed in any way.
Declaration
event EventHandler<DocumentContentChangedEventArgs> ContentChangedEvent Type
| Type | Description |
|---|---|
| EventHandlerDocumentContentChangedEventArgs |
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> EditOperationCompletingEvent Type
| Type | Description |
|---|---|
| EventHandlerEditOperationCompletingEventArgs |
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> EditOperationStartingEvent Type
| Type | Description |
|---|---|
| EventHandlerEditOperationCompletingEventArgs |
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).