Interface IBilingualDocument

Contains all the data required to display a document in the side-by-side edit control.

Inherited Members

Namespace: SdlSdl.DesktopEditorEditorApi

Assembly: Sdl.DesktopEditor.EditorApi.dll

Syntax

public interface IBilingualDocument : IDisposable

Remarks

The bilingual document contains separate documents for the source and the target edit controls, allowing them to show different content. Note however that all nodes in both the source and the target document do refer to the very same filter framework objects for the actual data, they just provide different wrappers for accessing it.

The document must be explicitly disposed of when no longer needed. Disposing the document raises the Disposing event, which should be handled by controls using the document in case the document is disposed of before the control.

Properties

ContentInput

Provides an implementation of a bilingual content processor that can be used to read content into the document e.g. when used with a filter framework IMultiFileConverter.

Declaration

IBilingualDocumentGenerator ContentInput { get; }

Property Value

Type	Description
IBilingualDocumentGenerator

Remarks

The ItemFactory and PropertiesFactory properties will be automatically set when the bilingual processor is used to process content through the filter framework.

Examples

This example shows how to read content from a file into the document using the filter framework.

void LoadFile(IBilingualDocument document, IFileTypeManager manager, string filePath)
{
  IMultiFileConverter converter = manager.GetConverterToBilingual(filePath, document.ContentInput);
  converter.Parse();
}

ContentOutput

Provides an implementation of a bilingual parser that can be used to read content from the document, e.g. when used with the filter framework to save a file.

Declaration

IBilingualParser ContentOutput { get; }

Property Value

Type	Description
IBilingualParser

Examples

This example shows how to save the content of a document to a bilingual
file in the default bilingual file format using the filter framework.

void SaveAsBilingual(IBilingualDocument document, IFileTypeManager manager, string filePath)
{
  IMultiFileConverter converter = manager.GetConverterToDefaultBilingual(document.ContentOutput, filePath);
  converter.Parse();
}

DocumentProperties

The filter framework properties for the document.

Declaration

IDocumentProperties DocumentProperties { get; }

Property Value

Type	Description
IDocumentProperties

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 whether the document will 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.

ItemFactory

The factory used when new bilingual content items need to be created.

Declaration

IDocumentItemFactory ItemFactory { get; set; }

Property Value

Type	Description
IDocumentItemFactory

Remarks

When the document is loaded by using it as a bilingual content processor through the filter framework this property is automatically set to the factory communicated by the framework.

PropertiesFactory

The factory used when new properties objects need to be created.

Declaration

IPropertiesFactory PropertiesFactory { get; }

Property Value

Type	Description
IPropertiesFactory

Remarks

This is a convenience accessor to the properties factory in the ItemFactory.

Source

Document used in the Source edit control.

Declaration

IFrameworkDocument Source { get; }

Property Value

Type	Description
IFrameworkDocument

Target

Document used in the target edit control.

Declaration

IFrameworkDocument Target { get; }

Property Value

Type	Description
IFrameworkDocument

UndoBuffer

Common undo buffer used by the bilingual document. This buffer is common to the bilingual document, the source and the target. Calling the undo buffer directly in the source or target documents will refer back to this undo buffer.

Declaration

IUndoBuffer UndoBuffer { get; }

Property Value

Type	Description
IUndoBuffer

Methods

ApplySegmentPair(ISegmentPairProperties)

Insert a new segment pair with the specified properties spanning the current active ranges in the source and target documents.

Declaration

void ApplySegmentPair(ISegmentPairProperties segmentPairProperties)

Parameters

Type	Name	Description
ISegmentPairProperties	segmentPairProperties	Properties for the new segment pair, they must not use the same segment ID as any existing segment in the paragraph.

LockSegment(ParagraphUnitId, SegmentId)

Use this method to lock a segment pair (disable it from interactive editing).

Declaration

void LockSegment(ParagraphUnitId paragraphUnitId, SegmentId segmentId)

Parameters

Type	Name	Description
ParagraphUnitId	paragraphUnitId	The paragraph unit containing the segment.
SegmentId	segmentId	The segment to lock.

Exceptions

Type	Condition
EditException	Thrown when the content inside the segment cannot be locked.

RemoveSegmentPair(ParagraphUnitId, ISegmentPairProperties)

Delete the segment pair with the specified properties object from the source and target documents. All content inside the source and target segments is preserved and moved into their parent containers, only the segment containers are removed.

Declaration

void RemoveSegmentPair(ParagraphUnitId paragraphUnitId, ISegmentPairProperties segmentPairProperties)

Parameters

Type	Name	Description
ParagraphUnitId	paragraphUnitId	The ID of the paragraph unit containing the segment.
ISegmentPairProperties	segmentPairProperties	The properties of the segment pair that is to be removed. These must be the properties of an existing segment pair in the paragraph.

Remarks

This operation is added to the undo buffer.

Note that this operation may change the row structure of the source and target edit controls, which among other things can mean that row numbers may change for existing rows in the document.

The document active range of the source and target documents is preserved during this operation - after completion the active range will span the same (or corresponding) content in the document even if content container nodes have been merged and/or split in the process.

UnlockSegment(ParagraphUnitId, SegmentId)

Use this method to unlock a segment pair (enable it for interactive editing).

Declaration

void UnlockSegment(ParagraphUnitId paragraphUnitId, SegmentId segmentId)

Parameters

Type	Name	Description
ParagraphUnitId	paragraphUnitId	The paragraph unit containing the segment.
SegmentId	segmentId	The segment to unlock.

UpdateDocumentProperties(IDocumentProperties)

Use this method to explicitly update document properties (e.g. change the target language) to ensure that both the source and target documents get properly notified of the changes.

Declaration

void UpdateDocumentProperties(IDocumentProperties properties)

Parameters

Type	Name	Description
IDocumentProperties	properties	Updated properties for the document. This should be a clone of a document properties object for this document (accessible through the DocumentProperties property) with relevant changes applied.

Remarks

Changes to the source and/or target language will be propagated to all paragraph units in the document.

This code example shows how to properly change the target language of a document.

void ChangeTargetLanguage(IBilingualDocument doc, Language newTargetLanguage)
{
  IDocumentProperties properties = (IDocumentProperties)doc.DocumentProperties.Clone();
  properties.TargetLanguage = newTargetLanguage;
  doc.UpdateDocumentProperties(properties);
}

UpdateFileProperties(IFileProperties)

Use this method to explicitly update file properties (e.g. changes to comments etc.) to ensure that both the source and target documents get properly notified of the changes.

Declaration

void UpdateFileProperties(IFileProperties properties)

Parameters

Type	Name	Description
IFileProperties	properties	Updated properties for the file. This should be a clone of a file properties object for an existing file node in the source or target document, with relevant changes applied.

Remarks

The file ID is used to identify the file to update in the document. This is expected to be unique, and should never change.

Note that file properties changes are contained in the Undo buffer, so they can be reversed by the undo commands.

This code example shows how to properly change the PreferredTargetEncoding of a file. (The file container node can be from the source or the target document, it does not matter as both reference the same underlying file properties object from the filter framework.)

void ChangeTargetEncoding(IBilingualDocument doc, IFileContainerNode fileNode, Codepage newTargetEncoding)
{
  IFileProperties properties = (IFileProperties)file.FileProperties.Clone();
  properties.FileConversionProperties.PreferredTargetEncoding = newTargetEncoding;
  doc.UpdateFileProperties(properties);
}

UpdateParagraphUnitProperties(IParagraphUnitProperties)

Use this method to explicitly update ParagraphUnit properties (e.g. changes to status, edited comments etc.).

Declaration

void UpdateParagraphUnitProperties(IParagraphUnitProperties properties)

Parameters

Type	Name	Description
IParagraphUnitProperties	properties	Updated properties for the ParagraphUnit. This should be a clone of a ParagraphUnit properties object for an existing ParagraphUnit in the document, with relevant changes applied.

Remarks

The ParagraphUnit ID is used to identify the ParagraphUnit to update in the document.

Note that ParagraphUnit properties changes are contained in the Undo buffer, they can be reversed by the undo commands.

This code example shows how to properly change the status of a ParagraphUnit. (The ParagraphUnit node can be from the source or the target document, it does not matter as both reference the same underlying ParagraphUnitProperties object from the filter framework.)

void ChangeParagraphUnitStatus(IBilingualDocument doc, IParagraphUnitContainerNode paragraphUnitNode, ParagraphUnitStatus newStatus)
{
  IParagraphUnitProperties properties = (IParagraphUnitProperties)paragraphUnitNode.ParagraphUnit.Properties.Clone();
  properties.Status = newStatus;
  doc.UpdateParagraphUnitProperties(properties);
}

UpdateSegmentProperties(ParagraphUnitId, ISegmentPairProperties)

Use this method to explicitly update segment pair properties (e.g. changes to translation origin etc.) to ensure that both the source and target documents get properly notified of the changes.

Declaration

void UpdateSegmentProperties(ParagraphUnitId paragraphUnitId, ISegmentPairProperties properties)

Parameters

Type	Name	Description
ParagraphUnitId	paragraphUnitId	ID of the Paragraph Unit where the segment appears.
ISegmentPairProperties	properties	Updated properties for the segment pair. This should be a clone of a segment pair properties object for an existing segment pair in the document, with relevant changes applied.

Remarks

The Paragraph Unit ID plus the segment ID is used to identify the segment to update. The Paragraph Unit ID is unique, and the segment ID should be unique within the source/target of the ParagraphUnit. These IDs should never change.

Note that segment pair properties changes are contained in the Undo buffer, so they can be reversed by the undo commands.

This code example shows how to properly change the translation origin of a segment. (The segment node can be from the source or the target, it does not matter as both reference the same underlying segment pair properties object from the filter framework.)

void SetToTranslated(IBilingualDocument doc, ISegmentContainerNode segmentNode)
{
  ISegmentPairProperties properties = (ISegmentPairProperties)node.Segment.Properties.Clone();
  properties.TranslationOrigin.OriginType = DefaultTranslationOrigin.Interactive;
  doc.UpdateSegmentProperties(node.Segment.ParentTransUnit.Properties.TransUnitId, properties);
}

Events

ContentChanged

Fired when content in the source or target document is changed in any way.

Declaration

event EventHandler<FrameworkDocumentContentChangedEventArgs> ContentChanged

Event Type

Type	Description
EventHandler FrameworkDocumentContentChangedEventArgs

Remarks

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

Disposing

Raised by the document when it is about to be disposed. If a control references the document this is a good time to disconnect from it.

Declaration

event EventHandler Disposing

Event Type

Type	Description
EventHandler

DocumentPropertiesChanged

Raised after document properties have been updated through a call to UpdateDocumentProperties(IDocumentProperties).

Declaration

event EventHandler<DocumentPropertiesChangedEventArgs> DocumentPropertiesChanged

Event Type

Type	Description
EventHandler DocumentPropertiesChangedEventArgs

FilePropertiesChanged

Raised after file properties have been updated through a call to UpdateFileProperties(IFileProperties).

Declaration

event EventHandler<FilePropertiesChangedEventArgs> FilePropertiesChanged

Event Type

Type	Description
EventHandler FilePropertiesChangedEventArgs

ParagraphUnitPropertiesChanged

Raised after paragraph unit properties have been updated through a call to UpdateParagraphUnitProperties(IParagraphUnitProperties).

Declaration

event EventHandler<ParagraphUnitPropertiesChangedEventArgs> ParagraphUnitPropertiesChanged

Event Type

Type	Description
EventHandler ParagraphUnitPropertiesChangedEventArgs

SegmentPropertiesChanged

Raised after segment pair properties have been updated through a call to UpdateSegmentProperties(ParagraphUnitId, ISegmentPairProperties), LockSegment(ParagraphUnitId, SegmentId) or UnlockSegment(ParagraphUnitId, SegmentId).

Declaration

event EventHandler<SegmentPropertiesChangedEventArgs> SegmentPropertiesChanged

Event Type

Type	Description
EventHandler SegmentPropertiesChangedEventArgs

Extension Methods

WindowsControlUtils.ForWindowFromFrameworkElement(object, Action<Window>)