An Image object represents a single image, whether it be inline or floating.
Existing images can be obtained using commands like:
Document.allImages
Text.imageAtIndex
Image Type Commands
Image.newFromFileAtPath imageFilePath v1.3
Attempts to load the graphic from the file at the given path, returning an Image object for it. If the file does not exist, or is not an image, returns the @undefined value.
New images can be inserted using the Text object’s insertAtIndex command.
Image.selectedImage v1.3
Returns the Image object selected in the active document, or the @undefined value if none.
Image.selectedInlineImage v1.3
Returns the Image object selected in the active document, but only if it is inline and not floating, otherwise the @undefined value is returned.
Image.selectedFloatingImage v1.3
Returns the Image object selected in the active document, but only if it is floating and not inline, otherwise the @undefined value is returned.
Image.insertInlineImage image v1.3
Replaces the contents of the active document’s selection with the given image, inserting it inline.
Image.addFloatingImage image v1.3
Adds a floating image to the active document, attaching its anchor to the currently selected text. This command return @true on success, or @false if the selection does not allow floating images.
Image.removeFloatingImage image v1.3
Removes the floating image from the active document selection, which must currently select all or part of the text the image anchor is applied to. This command return @true on success, or @false if the selection does not contain the floating image.
Note: to remove inline images, just delete the representative range/character.
Image Object Properties
.name v1.3
The name of the image, likely obtained from the original file. If no name is known, returns the @undefined value. Read-only.
.displaySize v2.0
Returns a Size object for the current display size (in points) of this image as it appears on the page, taking into account scaling, cropping, and other constraints. You can use this property to change the display size of the image.
To retrieve the original size of the image use the sourceSize property.
.width v1.3
Returns the display width (in points) of the image as it appears on the page, taking into account scaling and cropping.
Note: as of v2.0.5 this property value can be changed reliably.
.height v1.3
Returns the display height (in points) of the image as it appears on the page, taking into account scaling and cropping.
Note: as of v2.0.5 this property value can be changed reliably.
Returns a Size object for the original/natural size (in points) of this image. Read-only.
.sourceWidth v1.3
Returns the width (in points) of the data the image is constructed from. Read-only.
.sourceHeight v1.3
Returns the height (in points) of the data the image is constructed from. Read-only.
.cropInsets v2.1.2
Returns a Rect object describing how the image is cropped on each size. The returned rect does not represent a region in the image; instead each rect property specifies the amount (in points) that a particular side of the image is cropped. Therefore an image with no cropping returns a rect whose left, top, right, and bottom are all zero.
The crop insets are in terms of the source content’s size (ie: sourceSize) and not the image’s current display size.
.setCropInsets insets, [resize] v2.1.2
Changes the cropping for the image, using the given Rect object’s properties as insets. For more on how this should be represented by the rect, see the cropInsets property above.
If resize is @true then the image’s display size is adjusted to account for the cropping. This preserves the current aspect ratio for the image and is the default. If resize is explicitly given as @false then the image is not resized. This will result in aspect ratio distortion, but leaves the current display size unchanged.
.dataType v3.0
Returns a string indicating the type of data used to construct the image. This string matches the file name extension for the data format. For example: "jpg" is returned for JPEG data, "png" for PNG data, etc. If the image data format is unknown, returns the undefined value. Read-only.
NOTE: although this property was introduced in v2.1.3 it was incorrectly removed in a subsequent version. The property has been restored in v3.0.
.isEquation v2.1.1
Returns @true if the image represents a math equation (eg: MathType), otherwise @false. The value of this property is Nisus Writer’s best guess as to whether or not an image is an equation, but is not certain. Read-only.
.isFloating v2.0.5
Returns @true if the image is floating (text wraps around the image), or returns @false if the image is inline. Note: if the image is contained inside a floating text box, but the image is still an inline character graphic, this property is @false. Read-only.
.floatingContent v2.0.5
If the image is a floating image then returns the FloatingContent object representing that image. If the image is an inline image, or an inline image contained in a floating text box, returns @undefined. Read-only.
.fileName v2.0
If the original image’s file name is known, returns that name (including extension). If the name is not known, returns the @undefined value. Read-only.
.bareFileName v3.2
Returns the image’s file name without its extension. This never returns the @undefined value. This property can be changed.
.fileSize v2.0
If the image’s original (lossless) data is known, returns the number of bytes required for that data. If the data is not calculated, returns the @undefined value. Read-only.
Note: this size is not necessarily the number of bytes required to save the image in a document on disk. For example, RTF documents employ image escaping and redundancy that can greatly increase the size of the file. However, if using the Nisus Compressed RTF file format (ZRTF), the image size reported here will be representative of the size required on disk (though afterwards ZRTF files are compressed, reducing the size of the overall saved file).
Returns the Shadow object that is drawn for the image, or the undefined value if none. Changes to the returned shadow will not automatically update the image, you must set the image’s shadow property. See the example in the Shadow object reference.
.linkBackInfo v2.1.2
If the image has LinkBack data this returns a Hash containing information on the source data. This information may take any form, as determined by the LinkBack server application. If the image has no LinkBack source, returns the @undefined value. Read-only.
.linkedFilePath v2.1.2
If the image is linked to some file on disk, returns the path of that target. For images that are not linked returns the @undefined value. Read-only.
.retainsLinkedFileData v2.1.2
If the image is linked to some file on disk, returns @true if the file’s data is in duplicated in the document independently, in case the target file goes missing. Otherwise returns @false. Read-only.
Returns the Text object to which this image is anchored, or the @undefined value if it is not in a document. Read-only.
Note: the returned text object follows reference semantics and holds the entire text area where the image exists (eg: the whole document body).
.anchorTextRange v2.0.5
Returns the Range object representing the specific character range in the anchorText object where the image is anchored. Returns the @undefined value if this content is not applied in a document. Read-only.
For an inline image the range is that of the single character that servers as a placeholder for the image in the text.
For a floating image the range is that of the paragraph to which the image is currently anchored.
Image Object Commands
.copy v1.3
Creates and returns an exact copy of the image object that is independent from the original.
.imageByConvertingToDataType fileExtension v3.1
Creates and returns a copy of the image, but converted to the data type used by the given file extension. For example, if the given file extension is “jpg” then returns an image using JPEG data. Other aspects of the image remain unchanged, eg: display size, cropping, etc.
If the given data type is unknown or the conversion fails, returns the undefined value.
.writeToFolderAtPath folderPath, [baseFileName] v2.0.5
Saves the image to a file within the given folder, which must exist.
If a baseFileName is given and not an empty string, then will try to use that file name (plus a file extension appropriate for the image data type). If no base name is given, one will be chosen automatically; the original image name will be used if it is known. In either case, the file name is made to be unique within the destination folder.
Returns the full path of the saved image file, or @undefined on failure.
.writeWebImageToFolderAtPath folderPath, [baseFileName], [isResize] v2.0.5
This works like the writeToFolderAtPath command, except the image data will be converted to a web-friendly file format as needed (eg: PNG, JPEG, or GIF).
Additionally, the isResize argument will control the size of the saved image: if @true then the saved data will match the current display size of the image in Nisus Writer. If the argument is not specified, or is @false, then the full original image size is used.
Image Object - Examples
The following example shows how to load an image from disk, set the display size, and insert it into a document:
$image = Image.newFromFileAtPath("~/Pictures/anne.jpg")
$image.width = 100 # resize to be square shaped
$image.height = 100
# Insert into document. Could also use Text.insertAtIndex
Image.insertInlineImage($image)
If we wanted to (re)save this image to disk:
$path = $image.writeToFolderAtPath('~/Desktop')
# path would be '~/Desktop/lana.pdf'
Or if we wanted to save in a web friendly file format:
$path = $image.writeWebImageToFolderAtPath('~/Desktop', 'abc')
# path would be '~/Desktop/abc.jpg'
| Previous Chapter FloatingContent Object |
<< index >> |
Next Chapter Link Object |