Document Type Commands
Document.new [display] v1.3
Creates a new blank document and returns the corresponding Document object. Optionally if display is false, then the document window is kept offscreen until the show command is used. The default is to display the document.
Document.newWithText textObject [display] v1.3
Creates a new document that contains just the contents of the given text object and returns the corresponding Document object. Optionally if display is false, then the document window is kept offscreen until the show command is used. The default is to display the document.
Document.open filePath, [display] v1.3
Opens the file at the given path and returns the corresponding Document object. Optionally if display is false, then the document window is kept offscreen until the show command is used. The default is to display the document.
Document.openWithOptions filePath, options v2.1.2
Opens the file at the given path and returns the corresponding Document object. The options argument should be a Hash specifying any combination of the following options:
|
"Display" |
If this value is false, then the document window is kept offscreen until the show command is used. |
|
"IgnoreRichText" |
If this value is true, then the file format’s rich text commands are ignored. This essentially forces the document to open as plain text, showing any internal data format codes. |
|
"NewFile" |
If this value is true, then the document window is opened as if it were a newly created file (it opens as an Untitled window). |
|
"TextEncoding" |
This value should be an IANA text encoding name. If omitted, the default is to detect the encoding automatically. |
Document.active v1.1
Returns a Document object for the frontmost document window. If no documents are open, returns the @undefined value.
Document.setActive documentObject v1.1
Makes the window for the given Document object frontmost. Returns @false if the document has been closed and cannot be made frontmost, otherwise @true.
Document.openDocuments v1.1
Returns an array containing a Document object for each open document window. The documents are ordered in the array in the order they appear on screen, from front to back.
Document.withDisplayName findName v2.0.5
Returns a Document object for the already open document window whose display name matches the given name. If no such document is open, returns the @undefined value.
Document.macroSource v2.1
Returns the Document object that holds the source code being executed, ie: the document that literally contains the command Document.macroSource being run. If the document is not already open in Nisus Writer, this will load it as necessary (but will not display it).
Note: the returned document represents the whole document, even if only part of its text is being executed via the menu “Run Selection As Macro”.
Returns a Document object that refers to the document that called the macro, or the @undefined value if there was no such document. This document is the one in which an embedded Link created with newRunMacroWithMenuPath was clicked.
Document Object Properties
.text v1.1
The Text object that holds all of the primary content in the document (eg: the main body). Other content in the document, like headers and table cells, are not contained in this object. Read-only.
Note: the returned text object follows reference semantics, eg: changes to it will change the contents of the document itself.
.allTexts v1.1
Returns an array that contains every Text object contained in the document, including the main body, headers, footers, table cells, footnotes, endnotes, and comments. Even empty (zero-length) text objects are visited. The order of the returned array is undefined. Read-only.
Note: the returned text objects follow reference semantics, eg: changes to them will change the contents of the document itself.
.allTextSelections v3.0
Returns an array of TextSelection objects that in total encompass all text in the document. Read-only.
Accessing this property does not consult or change the current selection (as created by the user). This property merely provides a convenient way of processing all text in the document. For example:
$doc = Document.active
$charCount = 0
ForEach $selection in $doc.allTextSelections
$charCount += $selection.length
End
Prompt "The document has $charCount characters."
.displayName v1.1
Returns the name of the document as shown to the user in the window title area. If a document has been saved, this is usually just the file name. If a document has not been saved, it may be “Untitled 2” or similar.
.filePath v1.1
Returns a full path to the document file on disk. If the document has not been saved, returns the @undefined value. See Text Object Commands (path additions) for ways to inspect this path. Read-only.
.convertedFilePath v2.0.1
If the document was converted from some format that requires importing (eg: a Classic Nisus Writer file) returns a full path to that file on disk. If the document was not converted, returns the @undefined value. Read-only.
.hasChanges v1.1
Returns @true if the document has unsaved changes, otherwise @false. Read-only.
.isVisible v1.3
Returns @true if the Document window is shown on screen, otherwise @false.
This property was read-only prior to v2.0, but is now read/write.
Note: once a macro has finished running, all hidden document windows are automatically shown.
.windowOrigin v2.1
Returns a Size object describing the top-left origin of the document’s window on the screen.
.windowSize v3.0
Returns a Size object describing the size of the document’s window on the screen.
.isMinimized v2.0
Returns @true if the Document window is minimized in the Dock, otherwise @false.
.isShowingSheet v2.0
Returns @true if the Document’s window has an attached sheet, otherwise @false. Read-only.
Returns an array of all Style objects in the document, sorted by their name. Read-only.
.characterStyles v1.2
Returns an array of all character Style objects in the document, sorted by their name. Read-only.
.paragraphStyles v1.2
Returns an array of all paragraph Style objects in the document, sorted by their name. Read-only.
.listStyles v1.2
Returns an array of all list Style objects in the document, sorted by their name. Read-only.
.noteStyles v1.2
Returns an array of all note Style objects in the document, sorted by their name. Read-only.
Returns an array of all Bookmark objects in the document. The notes will be sorted by their location in the document, from first to last. Read-only.
.bookmarkWithName findName v2.0.5
Returns the Bookmark object with the given name, or the @undefined value if no such bookmark exists. This only tests the bookmark’s unique name, not the displayable name (automatically named bookmarks have a unique internal name which is never displayed).
.bookmarksWithDisplayName findName v2.0.5
Returns all Bookmark objects that display the given name. If no such bookmarks exist the @undefined value is returned. This command may be slow, as it must update and test the display name of all automatically named bookmarks in the document.
Returns an array of all CrossReference objects in the document. Read-only.
Returns an array of all Note objects in the document (footnotes, endnotes and section notes). The notes will be sorted by their location in the document, from first to last. Read-only.
.footnotes v1.1
Returns an array of Note objects, one for each footnote in the document. The notes will be sorted by their location in the document, from first to last. Read-only.
.endnotes v1.1
Returns an array of Note objects, one for each endnote in the document. The notes will be sorted by their location in the document, from first to last. Read-only.
.sectionnotes v1.1
Returns an array of Note objects, one for each section note in the document. The notes will be sorted by their location in the document, from first to last. Read-only.
Returns an array of all Image objects (whether inline or floating) in the document. Read-only.
Returns an array of all FloatingContent in the document. The items will be sorted by their location in the document, from first to last. Read-only.
Returns an array of all Comment objects applied in the document. The comments will be sorted by their location in the document, from first to last. Read-only.
Returns an array of all TrackedChange objects applied in the document. The changes will be sorted by their location in the document, from first to last. Read-only.
.activeTocStyleName v2.1.4
Returns the name of the document’s active TOC style. Read-only.
Returns an array of names, one for each TOC style defined in the document. Read-only.
.activeTextIndexStyleName v2.1.4
Returns the name of the document’s active Text Index style. Read-only.
Returns an array of names, one for each Text Index style defined in the document. Read-only.
Document Object Commands
.insert content v2.0.5
Replaces the text currently selected in the document with the given content. The content can be any one of the following:
1. Any Text object. The return value is a TextSelection object describing the inserted text.
2. An Image object. The return value is the Image object that was copied and added to the text.
3. A CrossReference object. The return value is the CrossReference object that was copied and added to the text.
4. Any other value type will be converted to a string and inserted as a Text object.
The return value of this command differs depending on the type of value inserted (see above).
.insertText text, [options] v1.1
Replaces the text currently selected in the document with the text provided. Unless the options specify otherwise, the attributes on the inserted text are exactly preserved and the selection (as an insertion point) will be placed after the newly inserted text.
The options string is a sequence of letters that combines one or more of the following:
|
s |
Select all of the inserted text instead of placing the caret after it. |
|
a |
Apply the ambient attributes found in the document selection to the inserted text, eg: ignore the attributes on the text to be inserted. This is like using the menu Edit > Paste > Paste Text Only. |
|
u |
Sets the style conflict resolution mode to “user”. A style conflict occurs if the inserted text has a style whose name is the same as one found in the document, but has different settings. In this mode the user’s preferences are consulted on how to resolve the conflict. This is the default mode. |
|
r |
Sets the style conflict resolution mode to “rename”. In this mode the inserted style should be renamed so there is no conflict and attributes in the inserted text are exactly preserved. This can add new styles to the document. |
|
m |
Sets the style conflict resolution mode to “merge”. In this mode the styles in the document replace the conflicting styles in the inserted text. This can change the attributes of the inserted text, but will not introduce new styles into the document. |
|
q |
Apply the user’s QuickFix preferences to the inserted text, eg: fix typos, use smart punctuation, etc. |
Returns @true if the text was inserted, or @false if the replacement was not possible.
Returns the Style object with the given name, or the undefined value if no such style exists.
.addStyles textOrStyles, [mergeMode] v2.0
Adds all styles from textOrStyles to the document. The textOrStyles argument can be either a Text object or an array of Style objects.
If a conflict occurs (a style with the same name and different attributes) then mergeMode is consulted as to what to do. mergeMode should be one of the following strings:
|
“ignore” |
Ignore the conflict from the text object, eg: do not add it. This is the default. |
|
“replace” |
Replace the style in the document with the conflict from the text object. |
|
“rename” |
Rename the conflict from the text object so there is no conflict. |
.addNewStyle styleType, [name], [attributes], [parentStyle] v2.0.3
Adds a new style to the document, returning that new Style object or the @undefined value if the given arguments are incorrect in any way.
The styleType argument must be either “Character” or “Paragraph”. New list and note styles cannot be created with this command.
If the given name is already used by an existing style in the document, a unique version of the name is found/used instead. If no name is provided (or the @undefined value is given), a unique name will be automatically decided.
The attributes for the new style should be an Attributes object (eg: as returned by the attributesAtIndex command, etc) or a Text object whose first attributes should be used. If no attributes are given (or the @undefined value is given), the style will enforce no additional formatting.
The parentStyle should be another Style object which the new style will be based on. The given parent style does not necessarily have to come from the same document. However, if the document does not have a style with the given parent’s name and type, this is considered an error and this command will return the @undefined value. It is also considered an error if the parent style’s type is not valid for the new style (eg: one cannot base a character style on a paragraph style).
.removeStyle style v2.0.5
Removes the given Style object from the document. If the style was not part of this document, this command has no effect.
.properties v1.3
Returns a hash of all property names/values listed by the menu File > Document Properties. The predefined keys are "author", "company", "copyright", "title", "subject", "keywords", and "comments". Any custom user-defined properties are also included in the returned hash. Property keys/names are always returned as lowercase strings.
As of v2.0, also present in the properties is the key "autosavename", which is always the current name that the document would autosave with (or be used as the default value in the Save dialog). If you set this property, that value will be used for those purposes.
.setProperty name, value v1.3
Changes the value of a single document property as described in the properties command above. Property name are case insensitive.
To completely remove a custom user-defined property, pass the @undefined value. Predefined properties like "author" cannot be removed in this way, but will be set to the empty string.
.copy [display] v1.1
Makes an exact copy of the document that is independent of the existing object. The copied document is opened as an untitled window and made to be active/frontmost. This command returns a Document object for the newly activated document.
The display argument was added in v1.3 and specifies whether the document should be shown on screen. If the argument is not provided, the default is to show the document.
.markAsDiscardable v2.1
Marks the document as a temporary workspace used by a macro. This clears the undo history and disables it so no new actions are recorded. Any autosaved versions of the document will be deleted; future autosaves will be prevented. The user will not be prompted to keep the document when it is closed.
NOTE: if the user edits the document after the macro finishes running, autosave and undo will be re-enabled.
.clearUndoHistory v1.1
Removes all actions that had been previously recorded in the document’s undo history.
.clearAndDisableUndoHistory v1.1
Removes all actions from the document’s undo history and disables it so no new actions are recorded. The undo history will be automatically re-enabled when the macro is finished executing.
In general it is not advisable to clear and disable the undo history. However, it may be desirable in some cases where macro speed is more important.
.enableUndoHistory v1.1
Re-enables a previously disabled undo history.
.show v1.3
Makes the document window visible (if it is hidden) and active/frontmost.
.hide v1.3
Hides the document window, but keeps the document in memory. Note: once a macro has finished running, all hidden document windows are automatically shown.
.close [discardChanges] v1.3
Closes the document window. If there are outstanding changes, the user will be prompted about the close unless discardChanges is true.
| Previous Chapter Document Object |
<< index >> |
Next Chapter Document Commands |