CrossReference Object

Existing CrossReference objects can be obtained through commands like:
Document.allCrossReferences
Text.crossReferenceAtIndex

CrossReference Type Commands

CrossReference.selectedCrossReference v2.0.5

Returns the first CrossReference object that is selected in the active document, or the @undefined value if none.

CrossReference.selectedCrossReferences v2.0.5

Returns an array of all CrossReference objects that are selected in the active document, or the @undefined value if none.

CrossReference.newWithBookmark bookmark v2.0.5

Returns a new CrossReference object that uses the given Bookmark object as its source. The returned cross-reference can be inserted into a Text object using the insertAtIndex command.

CrossReference.newWithBookmarkName bookmarkName v2.0.5

Returns a new CrossReference object, which once inserted into a document will use as its source whatever bookmark matches the given name. That bookmark does not need to exist yet (ie: you may pass in any name). The returned cross-reference can be inserted into a Text object using the insertAtIndex command.

CrossReference Object Properties

.bookmark v2.0.5

Returns the Bookmark object which is being used as the source for the cross-reference. Returns the @undefined value if no such bookmark currently exists (eg: the cross-reference displays as “referenced content is missing”). Read-only.

.bookmarkName v2.0.5

Returns the name of the bookmark which this cross-reference is using as its source. Changing the value of this property will not alter the bookmark, but will instead retarget the cross-reference to use a different bookmark.

.referenceType v2.0.5

Note: this property is read-only, but the setReferenceType command can change it.

.isLinkInPDF v2.0.5

@true or @false, depending on whether the cross-reference should be hyperlinked to its source bookmark when a PDF is generated.

.includeAboveBelowSuffix v2.0.5

@true or @false, depending on whether the cross-reference should display the suffix “above” or “below” describing the relative location of the source bookmark in the document. This suffix is displayed in addition to whatever other information the cross-reference displays.

.markedText v2.0.5

Returns the Text object in which the cross-reference has been inserted, or the @undefined value if it is not inside any text.  Read-only.

Note: the returned text object follows reference semantics and holds the entire text area where the bookmark exists (eg: the whole document body).

.markedTextRange v2.0.5

Returns the Range object representing the specific character range in the markedText object where the cross-reference has been inserted. Returns the @undefined value if the cross-reference is not inside any text. Read-only.

.lastValidBookmarkPreview v3.0

Returns a string that holds a preview of the bookmarked text, from the last time a valid update was successfully completed. This is useful when a cross-reference’s source bookmark is missing. It may be helpful to know the text of the missing bookmark, when the bookmark’s name alone is insufficient. Read-only.

This can return the undefined value, if a successful update hasn’t yet been completed, or an update occurred with a version of Nisus Writer before v3.0.

Note: the returned string may be truncated or otherwise transformed. It is intended to aid a writer in remembering the missing bookmark, not as an exact substitute for it.

CrossReference Object Commands

.setReferenceType typeName v2.0.5

Changes the information the cross-reference displays. See the referenceType property for a list of valid type names. Returns @true on success, or @false if the given type name is invalid.

.currentDisplayText v2.0.5

Returns a Text object holding a copy of text the cross-reference currently displays in the document. This text might be stale (ie: not yet updated to be accurate).

.generatedDisplayText v2.0.5

Returns a Text object holding the text the cross-reference would display once it was inserted and updated in a document. By definition this text cannot be stale.

.updateDisplayText v2.0.5

Using this command forces the cross-reference to update in the document so that it displays updated accurate information. Normally Nisus Writer will update cross-references lazily as needed, eg: cross-references update in the background or if the user makes a printout/PDF.