Class WordDocument

Namespace

ComOfficeKit

Assembly

ComOfficeKit.dll

A Word document (.docx).

public sealed class WordDocument : Document, IDisposable

Inheritance

object

Document

WordDocument

Implements

IDisposable

Inherited Members

Document.Open(string)

Document.Open(Stream, DocumentFormat)

Document.CreateBlank(DocumentFormat, string)

Document.RenderPage(int, double)

Document.ExportPdf(string)

Document.ExportPdf(Stream)

Document.Save()

Document.SaveAs(string)

Document.SaveAs(Stream)

Document.Dispose()

Document.Kind

Document.Format

Document.SourcePath

Document.PageCount

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

The first time a document is edited or its text is read, it opens an editing session; from then on its pages and its saves are the session's, so what is saved is the edited document.

Properties

BodyCount

How many top-level elements the body has, paragraphs and tables.

public int BodyCount { get; }

Property Value

int

Exceptions

ComOfficeKitException

EngineMismatch as for GetComments().

Caret

Where the editor's caret stands, as a position in the document, or null before it has one. A SceneEditor command leaves the caret where its edit does, so edits can follow on as a user's would.

public WordScenePosition? Caret { get; }

Property Value

WordScenePosition

Exceptions

ComOfficeKitException

EngineMismatch as for GetComments().

CommentCount

How many comments the document has, replies included.

public int CommentCount { get; }

Property Value

int

Exceptions

ComOfficeKitException

EngineMismatch as for GetComments().

ModelRevision

A number that moves with every change to the document, and only then: a snapshot such as GetComments()'s is current while it stays where it was when the snapshot was read.

public long ModelRevision { get; }

Property Value

long

Exceptions

ComOfficeKitException

EngineMismatch as for GetComments().

SceneEditor

The Apple SDK's WordSceneEditor on this document: its editing functions, each run by the engine as one undo step. A position or an id comes from a model read.

public WordSceneEditor SceneEditor { get; }

Property Value

WordSceneEditor

SelectionAnchor

The other end of the editor's selection, or null when nothing is selected.

public WordScenePosition? SelectionAnchor { get; }

Property Value

WordScenePosition

Exceptions

ComOfficeKitException

EngineMismatch as for GetComments().

Methods

Compare(string, string, string, string?)

Compares two Word documents and writes the revised one to destinationPath with every difference from the original as a tracked change: accepting them all gives the revised text, rejecting them all the original's. Body paragraphs and table cells are compared, word by word. Not compared: formatting, headers, footers, footnotes, text boxes, pictures, comments.

public static CompareResult Compare(string originalPath, string revisedPath, string destinationPath, string? author = null)

Parameters

originalPath string

The original, a .docx.

revisedPath string

The revised version: a .docx, or plain text (.txt, .md).

destinationPath string

Where to write the result, a .docx. When the two read the same nothing is written.

author string

The name the tracked changes carry; null for none.

Returns

CompareResult

What the comparison found.

Exceptions

ComOfficeKitException

UnsupportedFormat when the revised file is not .docx, .txt or .md; IO when a file cannot be read or written; Parse when a .docx cannot be read.

LicenseException

The licence does not allow comparing.

EditComment(string, string)

Replaces a comment's text: the Apple SDK's WordComment.editingText. One undo step.

public void EditComment(string id, string text)

Parameters

id string

The comment's Id.

text string

The new text; not empty.

Exceptions

ComOfficeKitException

InvalidArgument when no comment has id, or text holds a character a document cannot store, such as most control characters; EngineMismatch as for GetComments().

GetBody()

The body's top-level elements, each a paragraph or a whole table, as the Apple SDK's WordBodyElement. A snapshot, as GetScene()'s.

public IReadOnlyList<WordBodyElement> GetBody()

Returns

IReadOnlyList<WordBodyElement>

The elements.

Exceptions

ComOfficeKitException

EngineMismatch as for GetComments().

GetBody(int, int)

Part of GetBody(): at most count elements, from the one at from. Only that part is read, so a long document can be paged.

public IReadOnlyList<WordBodyElement> GetBody(int from, int count)

Parameters

from int

The first element's index, from 0. BodyCount gives an empty list.

count int

How many elements at most; fewer at the end.

Returns

IReadOnlyList<WordBodyElement>

The elements.

Exceptions

ComOfficeKitException

InvalidArgument when from is beyond BodyCount; EngineMismatch as for GetComments().

GetComments()

The document's comments, replies included, in the order the document keeps them, as the Apple SDK's WordComment. A snapshot: an edit does not change it. Read again when ModelRevision has moved.

public IReadOnlyList<WordComment> GetComments()

Returns

IReadOnlyList<WordComment>

The comments; empty when the document has none.

Exceptions

ComOfficeKitException

EngineMismatch when the engine beside this assembly writes another model than the one it was built for.

GetComments(int, int)

Part of GetComments(): at most count comments, from the one at from. Only that part is read, so a long list can be paged.

public IReadOnlyList<WordComment> GetComments(int from, int count)

Parameters

from int

The first comment's index, from 0. CommentCount gives an empty list.

count int

How many comments at most; fewer at the end.

Returns

IReadOnlyList<WordComment>

The comments.

Exceptions

ComOfficeKitException

InvalidArgument when from is beyond CommentCount; EngineMismatch as for GetComments().

GetFloatingImageData(Guid, int)

A floating picture's bytes, as GetImageData(Guid, Guid) reads an inline one's: one of a paragraph's FloatingImages.

public byte[] GetFloatingImageData(Guid paragraphId, int imageIndex)

Parameters

paragraphId Guid

The paragraph it is anchored in, Id.

imageIndex int

Its index among the paragraph's floating pictures, from 0.

Returns

byte[]

The bytes.

Exceptions

ComOfficeKitException

InvalidArgument when there is no such paragraph or picture, or the picture's file cannot be read.

GetImageData(Guid, Guid)

An inline picture's bytes, as the document holds them: the file its run's WordImage stands for, which the model leaves out, since its mediaURL is a file of the engine's process. They are PNG, JPEG, GIF, BMP or TIFF, as the file has them.

public byte[] GetImageData(Guid paragraphId, Guid runId)

Parameters

paragraphId Guid

The picture's paragraph, Id, wherever it is.

runId Guid

Its run, Id, whose Image it is.

Returns

byte[]

The bytes.

Exceptions

ComOfficeKitException

InvalidArgument when there is no such run, it holds no picture, or the picture's file cannot be read.

GetScene()

The whole document as the Apple SDK's WordDocumentScene: its body, sections, headers and footers, notes, comments, numbering and style defaults. A snapshot: an edit does not change it. For a long document, GetBody(int, int) reads the body in parts.

public WordDocumentScene GetScene()

Returns

WordDocumentScene

The document.

Exceptions

ComOfficeKitException

EngineMismatch as for GetComments(); InvalidArgument when the document holds a number JSON cannot carry.

GetText()

The body's text: its paragraphs separated by \n, a table's cells in reading order, each cell's paragraphs as paragraphs. Tabs, page breaks (U+000C) and line breaks (U+2028) appear as the document stores them. Headers, footers, text boxes and comments are not included.

public string GetText()

Returns

string

The text.

Exceptions

LicenseException

The licence does not allow reading the document.

ReplaceAll(string, string, StringComparison)

Replaces every match of find in GetText()'s text with replacement, in one edit. Matches are found from the start; one that overlaps an earlier match is skipped. Each replacement takes the formatting where it lands.

public int ReplaceAll(string find, string replacement, StringComparison comparison = StringComparison.Ordinal)

Parameters

find string

The text to find; not empty.

replacement string

The text to put in its place; empty deletes each match.

comparison StringComparison

How to compare: ordinal by default.

Returns

int

How many matches were replaced.

Exceptions

ComOfficeKitException

InvalidArgument when replacement holds a character a document cannot store, such as most control characters.

LicenseException

The licence does not allow editing.

SetCommentResolved(string, bool)

Resolves or reopens a comment's whole thread, as Word's Resolve does: the Apple SDK's WordComment.settingResolved. One undo step.

public void SetCommentResolved(string id, bool resolved)

Parameters

id string

The Id of any comment in the thread.

resolved bool

True to resolve, false to reopen.

Exceptions

ComOfficeKitException

InvalidArgument when no comment has id; EngineMismatch as for GetComments().