API Docs for: see header basil.js
Show:

b Class

Defined in: basil.js:44

Item Index

Methods

Methods

abs

(
  • val
)

Calculates the absolute value (magnitude) of a number. The absolute value of a number is always positive.

Parameters:

  • val Number

    An arbitrary number

Returns:

The absolute value of that number

acos

(
  • value
)
Number

The inverse of cos(), returns the arc cosine of a value. This function expects the values in the range of -1 to 1 and values are returned in the range 0 to PI (3.1415927).

Parameters:

  • value Number

    the value whose arc cosine is to be returned

Returns:

addPage

(
  • [location]
)
Page

Adds a new page to the document. Set the optional location parameter to either b.ATEND (default), b.ATBEGINNING, b.AFTER or b.BEFORE. b.AFTER and b.BEFORE will use the current page as insertion point.

Parameters:

  • [location] String optional

    The location placement mode

Returns:

Page: The new page

addPath

()

addPath() is used to create multi component paths. Call addPath() to add the so far drawn vertices to a single path. New vertices will then end up in a new path. endShape() will then return a multi path object. All component paths will account for the setting (see b.CLOSE) given in beginShape(shapeMode).

addToStory

(
  • story
  • itemOrString
  • insertionPointOrMode
)

Adds a page item or a string to an existing story. You can control the position of the insert via the last parameter. It accepts either an InsertionPoint or one the following constants: b.ATBEGINNING and b.ATEND.

Parameters:

  • story Story

    The story

  • itemOrString PageItem | String

    The itemOrString either a PageItem, a String or one the following constants: b.ATBEGINNING and b.ATEND.

  • insertionPointOrMode InsertionPoint | String

    InsertionPoint or one the following constants: b.ATBEGINNING and b.ATEND.

applyMatrix

(
  • matrix
)

Multiplies the current matrix by the one specified through the parameters.

Parameters:

  • matrix Matrix2D

    The matrix to be applied

arc

(
  • cx
  • cy
  • w
  • h
  • startAngle
  • endAngle
  • mode
)
GraphicLine | Polygon

The arc() function draws an arc in the display window. Arcs are drawn along the outer edge of an ellipse defined by the x, y, width and height parameters. The origin or the arc's ellipse may be changed with the ellipseMode() function. The start and stop parameters specify the angles at which to draw the arc.

Parameters:

  • cx Number

    x-coordinate of the arc's center

  • cy Number

    y-coordinate of the arc's center

  • w Number

    width of the arc's ellipse

  • h Number

    height of the arc's ellipse

  • startAngle Number

    starting angle of the arc (radians)

  • endAngle Number

    ending angle of the arc (radians)

  • mode String

    optional property defines rendering technique of arc, b.OPEN (default), b.CHORD, or b.PIE

Returns:

GraphicLine | Polygon: newShape (n.b. in Adobe Scripting the corresponding type is a Path Item) TODO(S) - fix overlapping points bug

asin

(
  • value
)
Number

The inverse of sin(), returns the arc sine of a value. This function expects the values in the range of -1 to 1 and values are returned in the range 0 to PI (3.1415927).

Parameters:

  • value Number

    the value whose arc sine is to be returned

Returns:

atan

(
  • value
)
Number

The inverse of tan(), returns the arc tangent of a value. This function expects the values in the range of -1 to 1 and values are returned in the range 0 to PI (3.1415927).

Parameters:

  • value Number

    the value whose arc tangent is to be returned

Returns:

atan2

(
  • y
  • x
)
Number

Calculates the angle (in radians) from a specified point to the coordinate origin as measured from the positive x-axis. Values are returned as a float in the range from PI to -PI. The atan2() function is most often used for orienting geometry to the position of the cursor. Note: The y-coordinate of the point is the first parameter and the x-coordinate is the second due the the structure of calculating the tangent.

Parameters:

Returns:

beginShape

(
  • shapeMode
)

Using the beginShape() and endShape() functions allow creating more complex forms. beginShape() begins recording vertices for a shape and endShape() stops recording. After calling the beginShape() function, a series of vertex() commands must follow. To stop drawing the shape, call endShape(). The value of the parameter tells whether the paths to create from the provided vertices have to be closed or not (to connect the beginning and the end).

Parameters:

  • shapeMode Object

    Set b.CLOSE if the new Path should be auto-closed.

binary

(
  • num
  • [numBits]
)
String

Converts a byte, char, int, or color to a String containing the equivalent binary notation. For example color(0, 102, 153, 255) will convert to the String "11111111000000000110011010011001". This function can help make your geeky debugging sessions much happier.

Parameters:

  • num Number

    value to convert

  • [numBits] Number optional

    number of digits to return

Returns:

String: A formatted string

bleeds

(
  • [top]
  • [right]
  • [bottom]
  • [left]
)

Sets the document bleeds. If one value is given, all 4 are set equally. If 4 values are given, the top/right/bottom/left document bleeds will be adjusted. Calling the function without any values, will return the document bleed settings.

Parameters:

  • [top] Number optional

    Top bleed or all if only one

  • [right] Number optional

    Right bleed

  • [bottom] Number optional

    Bottom bleed

  • [left] Number optional

    Left bleed

blendMode

(
  • obj
  • blendMode
)

Sets the Effects blendMode property of an object.

Parameters:

  • obj Object

    The object to set blendMode property

  • blendMode Number

    The blendMode must be one of the InDesign BlendMode enum values: BlendMode.NORMAL
    BlendMode.MULTIPLY
    BlendMode.SCREEN
    BlendMode.OVERLAY
    BlendMode.SOFTLIGHT
    BlendMode.HARD
    LIGHT
    BlendMode.COLORDODGE
    BlendMode.COLOR
    BURN
    BlendMode.DARKEN
    BlendMode.LIGHTEN
    BlendMode.DIFFERENCE
    BlendMode.EXCLUSION
    BlendMode.HUE
    BlendMode.SATURATION
    BlendMode.COLOR
    BlendMode.LUMINOSITY

bounds

(
  • obj
)
Object

The function calculates the geometric bounds of any given object. Use b.itemX(), b.itemY(), b.itemPosition(), b.itemWidth(), b.itemHeight() and b.itemSize() to modify PageItems. In case the object is any kind of text, then additional typographic information baseline and xHeight are calculated

Parameters:

  • obj Text | Object

    The object to calculate the geometric bounds

Returns:

Object: Geometric bounds object with these properties: width, height, left, right, top, bottom and for text: baseline, xHeight

canvasMode

()

Use this to set the dimensions of the canvas. Choose between b.PAGE (default), b.MARGIN, b.BLEED resp. b.FACINGPAGES, b.FACINGMARGINS and b.FACING_BLEEDS for book setups with facing page. Please note: Setups with more than two facing pages are not yet supported. Please note that you will loose your current MatrixTransformation. You should set the canvasMode before you attempt to use b.translate(), b.rotate() and b.scale();

ceil

(
  • val
)

Calculates the closest int value that is greater than or equal to the value of the parameter. For example, ceil(9.03) returns the value 10.

Parameters:

  • val Number

    An arbitrary number

Returns:

The next highest integer value

characters

(
  • item
  • [cb]
)
Characters

If no callback function is given it returns a Collection of items otherwise calls the given callback function with each character of the given document, story, text frame, paragraph, line or word.

Parameters:

  • item Document | Story | TextFrame | Paragraph | Line | Word

    The document, story, text frame, paragraph, line or word instance to iterate the characters in

  • [cb] Function optional

    Optional: The callback function to call with each character. When this function returns false the loop stops. Passed arguments: character, loopCount

Returns:

Characters: You can use it like an array.

characterStyle

(
  • name
)
CharachterStyle

Returns the character style with the given name. If the style does not exist it gets created.

Parameters:

  • name String

    The name of the character style to return.

Returns:

CharachterStyle: The character style instance.

clear

(
  • container
)

Removes all PageItems in the given Document, Page, Layer or Group.

Parameters:

  • container Document | Page | Layer | Group

    The container where the PageItems sit in

close

(
  • [saveOptions]
  • [file]
)

Closes the current document.

Parameters:

  • [saveOptions] SaveOptions | Boolean optional

    The indesign SaveOptions constant or either true for triggering saving before closing or false for closing without saving.

  • [file] File optional

    Optional: The indesign file instance to save the document to

color

(
  • Get
)
Color

Creates a new RGB or CMYK color and adds the new color to the document, or gets a color by name from the document. The default color mode is RBG.

Parameters:

  • Get String | Numbers

    color: the color name. Create new color: R,G,B,name or C,M,Y,K,name or Grey,name. Name is always optional

Returns:

Color: found or new color

colorMode

(
  • colorMode
)

Sets the colormode for creating new colors with b.color() to RGB or CMYK. The default color mode is RBG.

Parameters:

  • colorMode Number

    Either b.RGB or b.CMYK

constrain

(
  • aNumber
  • aMin
  • aMax
)

Constrains a value to not exceed a maximum and minimum value.

Parameters:

  • aNumber Number

    the value to constrain

  • aMin Number

    minimum limit

  • aMax Number

    maximum limit

Returns:

The constrained value

cos

(
  • rad
)
Number

Calculates the cosine of an angle. This function expects the values of the angle parameter to be provided in radians (values from 0 to PI*2). Values are returned in the range -1 to 1.

Parameters:

  • rad Number

    a value in radians

Returns:

CSV.decode

(
  • String
)
Array

Function parses a string as CSV-object Array. Usage: var arr = b.CSV.decode(str); var str = b.CSV.encode(arr);

Parameters:

  • String String

    to be parsed as CSV-object.

Returns:

Array: Returns CSV-object Array

CSV.delimiter

(
  • [delimiter]
)
String

Defined in includes/data.js:87

Sets the delimiter of the CSV decode and encode function.

Parameters:

  • [delimiter] String optional

    Optional Sets the delimiter for CSV parsing

Returns:

String: Returns the current delimiter if called without argument

CSV.encode

(
  • Array
)
String

Function convert an javascript array of objects to a CSV-string. Usage: var str = b.CSV.encode(arr); var arr = b.CSV.decode(str);

Parameters:

  • Array Array

    to be converted to a CSV-string

Returns:

String: Returns CSV-string

day

() Number

The day() function returns the current day as a value from 1 - 31.

Returns:

degrees

(
  • aAngle
)
Number

Converts a radian measurement to its corresponding value in degrees. Radians and degrees are two ways of measuring the same thing. There are 360 degrees in a circle and 2*PI radians in a circle. For example, 90° = PI/2 = 1.5707964. All trigonometric methods in Processing require their parameters to be specified in radians.

Parameters:

  • aAngle Number

    an angle in radians

Returns:

Number: The given angle in degree

delay

(
  • milliseconds
)

Suspends the calling thread for a number of milliseconds. During a sleep period, checks at 100 millisecond intervals to see whether the sleep should be terminated.

Parameters:

  • milliseconds Number

    The delay time in milliseconds

dist

(
  • x1
  • y1
  • x2
  • y2
)
Number

Calculates the distance between two points.

Parameters:

  • x1 Number

    the x-coordinate of the first point

  • y1 Number

    the y-coordinate of the first point

  • x2 Number

    the x-coordinate of the second point

  • y2 Number

    the y-coordinate of the second point

Returns:

Number: The distance

doc

(
  • [doc]
)
Document

Sets or possibly creates the current document and returns it. If the param doc is not given the current document gets set to the active document in the application. If no document at all is open, a new document gets created.

Parameters:

  • [doc] Document optional

    The document to set the current document to

Returns:

Document: The current document instance

download

(
  • url
  • [file]
)

Downloads an URL to a file, currently Mac only.

Parameters:

  • url String

    The download url

  • [file] String | File optional

    A relative file path in the project folder or a File instance

duplicate

(
  • item
)
Object

Duplicates the given page after the current page or the given pageitem to the current page and layer. Use b.rectMode() to set center point.

Parameters:

  • item PageItem | Page

    The item to duplicate

Returns:

Object: Returns the new item

ellipse

(
  • x
  • y
  • w
  • h
)
Oval

Defined in includes/shape.js:4

Draws an ellipse (oval) in the display window. An ellipse with an equal width and height is a circle. The first two parameters set the location, the third sets the width, and the fourth sets the height.

Parameters:

Returns:

Oval: New oval (n.b. in Adobe Scripting the corresponding type is Oval, not Ellipse)

ellipseMode

(
  • mode
)

The origin of the ellipse is modified by the ellipseMode() function. The default configuration is ellipseMode(CENTER), which specifies the location of the ellipse as the center of the shape. The RADIUS mode is the same, but the width and height parameters to ellipse() specify the radius of the ellipse, rather than the diameter. The CORNER mode draws the shape from the upper-left corner of its bounding box. The CORNERS mode uses the four parameters to ellipse() to set two opposing corners of the ellipse's bounding box. The parameter must be written in "ALL CAPS".

Parameters:

  • mode String

    Either b.CENTER, b.RADIUS, b.CORNER, or b.CORNERS

endShape

() GraphicLine | Polygon

The endShape() function is the companion to beginShape() and may only be called after beginShape().

Returns:

GraphicLine | Polygon: newShape

endsWith

(
  • str
  • suffix
)
Boolean

Checks whether a string ends with a specific character or string.

Parameters:

  • str String

    A string to be checked

  • suffix String

    The string to look for

Returns:

Boolean: Returns either true or false

exp

(
  • a
)
Number

Returns Euler's number e (2.71828...) raised to the power of the value parameter.

Parameters:

Returns:

fill

(
  • fillColor
)

Defined in includes/color.js:4

Sets the color used to fill shapes.

Parameters:

  • fillColor Color | Swatch | Numbers

    Accepts a Color/swatch or a string with the name of a color. Or values: C,M,Y,K / R,G,B / Grey

fillTint

(
  • tint
)

Sets the tint of the color used to fill shapes.

Parameters:

  • tint Number

    Number from 0 to 100

floor

(
  • a
)
Number

Calculates the closest int value that is less than or equal to the value of the parameter.

Parameters:

Returns:

forEach

(
  • collection
  • cb
)

Used to run a function on all elements of an array. Please note the existance of the convenience methods b.stories(), b.paragraphs(), b.lines(), b.words() and b.characters() that are used to iterate through all instances of the given type in the given document.

Parameters:

  • collection Array

    The array to be processed.

  • cb Function

    The function that will be called on each element. The call will be like function(item,i) where i is the current index of the item within the array.

go

(
  • [modes]
)

Defined in includes/core.js:20

Run the sketch! Has to be called in every sketch a the very end of the code. You may add performance setting options when calling b.go():

b.go(b.MODEVISIBLE) or alternatively: b.go()

b.go(b.MODESILENT)
b.go(b.MODEHIDDEN)

Currently there is no performance optimization in b.loop()

Parameters:

  • [modes] MODESILENT | MODEHIDDEN | MODEVISIBLE optional

    Optional: Switch performanceMode

Group

(
  • [pItem]
  • name
)
Group

Returns an array of the items that were within the Group before b.ungroup() was called

Parameters:

  • [pItem] Object | String optional

    The Group or name of Group name instance

  • name String

    The name of the Group, only when creating a Group from Page Item(s)

Returns:

Group: the Page Item(s) that were grouped

Group

(
  • [pItem]
  • name
)
Group

Returns the Group instance and sets it if argument Group is given.

Parameters:

  • [pItem] Array optional

    The PageItems array (must be at least 2) or name of Group name instance

  • name String

    (optional) The name of the Group, only when creating a Group from Page Item(s)

Returns:

Group: the current Group instance

guideX

(
  • x
)
Guide

Creates a vertical guide line at the current spread and current layer.

Parameters:

  • x Number

    Position of the new guide

Returns:

Guide: New guide

guideY

(
  • y
)
Guide

Creates a horizontal guide line at the current spread and current layer.

Parameters:

  • y Number

    Position of the new guide

Returns:

Guide: New guide

HashList

()

HashList is a data container that allows you to store information as key -> value pairs. As usual in JavaScript mixed types of keys and values are accepted in one HashList instance.

HashList.clear

()

Deletes all the key -> value pairs in this HashList.

HashList.get

(
  • key
)
Any

This gets a value by its key.

Parameters:

  • key Any

    The key to look for

Returns:

Any: The value

HashList.getKeys

() Array

Returns an array with all keys.

Returns:

Array: An array with all the keys

HashList.getKeys

() Array

Returns an array with all keys.

Returns:

Array: An array with all the keys

HashList.getKeysByValues

() Array

Returns an array of all keys that are sorted by their values from highest to lowest. Please note that this only works if you have conistently used Numbers for values.

Returns:

Array: An array with all the keys

HashList.getSortedKeys

() Array

Returns an array with all keys in a sorted order from higher to lower magnitude.

Returns:

Array: An array with all the keys

HashList.hasKey

(
  • key
)
Boolean

Checks for the existence of a given key.

Parameters:

  • key Any

    The key to check

Returns:

HashList.hasValue

(
  • value
)
Boolean

Checks if a certain value exists at least once in all of the key -> value pairs.

Parameters:

  • value Any

Returns:

HashList.remove

(
  • key
)
Any

This removes a key -> value pair by its key.

Parameters:

  • key Any

    The key to delete

Returns:

Any: The value before deletion

HashList.set

(
  • key
  • value
)
Any

This sets a key -> value pair. If a key is already existing, the value will be updated. Please note that Functions are currently not supported as values.

Parameters:

  • key Any

    The key to use

  • value Any

    The value to set

Returns:

Any: The value after setting

hex

(
  • value
  • [len]
)
String

Convert a number to a hex representation.

Parameters:

  • value Number

    The number to convert

  • [len] Number optional

    The length of the hex number to be created, default: 8

Returns:

String: The hex representation as a string

hour

() Number

The hour() function returns the current hour as a value from 0 - 23.

Returns:

image

(
  • img
  • x
  • [y]
  • [w]
  • [h]
)
Rectangle | Oval | Polygon

Defined in includes/image.js:4

Adds an image to the document. If the image argument is given as a string the image file must be in the document's data directory which is in the same directory where the document is saved in. The image argument can also be a File instance which can be placed even before the document was saved. The second argument can either be the x position of the frame to create or an instance of a rectangle, oval or polygon to place the image in. If x and y positions are given and width and height are not given, the frame's size gets set to the original image size.

Parameters:

  • img String | File

    The image file name in the document's data directory or a File instance

  • x Number | Rectangle | Oval | Polygon

    The x position on the current page or the item instance to place the image in

  • [y] Number optional

    The y position on the current page. Ignored if x is not a number.

  • [w] Number optional

    The width of the rectangle to add the image to. Ignored if x is not a number.

  • [h] Number optional

    The height of the rectangle to add the image to. Ignored if x is not a number.

Returns:

Rectangle | Oval | Polygon: The item instance the image was placed in.

imageMode

(
  • [mode]
)
String

Modifies the location from which images draw. The default mode is imageMode(CORNER), which specifies the location to be the upper left corner and uses the fourth and fifth parameters of image() to set the image's width and height. The syntax imageMode(CORNERS) uses the second and third parameters of image() to set the location of one corner of the image and uses the fourth and fifth parameters to set the opposite corner. Use imageMode(CENTER) to draw images centered at the given x and y position. If no parameter is passed the currently set mode is returned as String.

Parameters:

  • [mode] String optional

    Either b.CORNER, b.CORNERS, or b.CENTER

Returns:

String: The current mode

inspect

(
  • obj
  • maxlevel
)

Prints out all properties and values off an object in a recursive manner to the console. Useful for inspecting (or debugging) nested variable. the default value for the recursion is maxlevel = 2.

Parameters:

  • obj Object

    : the Object to inspect

  • maxlevel Number

    Optional: recursion limit, default maxlevel = 2

isArray

(
  • obj
)
Boolean

Checks whether a var is an Array, returns true if this is the case

Parameters:

Returns:

Boolean: returns true if this is the case

isNumber

(
  • num
)
Boolean

Checks whether a var is a number, returns true if this is the case

Parameters:

Returns:

Boolean: returns true if this is the case

isString

(
  • str
)
Boolean

Checks whether a var is a string, returns true if this is the case

Parameters:

Returns:

Boolean: returns true if this is the case

isText

(
  • obj
)
Boolean

Checks whether a var is an indesign text object, returns true if this is the case NB: a indesign TextFrame will return false as it is just a container holding text. So you could say that isText() refers to all the things inside a TextFrame.

Parameters:

  • obj Character | InsertionPoint | Line | Paragraph | TextColumn | TextStyleRange | Word

    The object to check

Returns:

Boolean: returns true if this is the case

isURL

(
  • url
)
Boolean

Checks whether an URL string is valid.

Parameters:

  • url String

    An url string to be checked

Returns:

Boolean: Returns either true or false

itemHeight

(
  • pItem
  • [height]
)
Number

Scales the given PageItem to the given height. If height is not given as argument the current height is returned.

Parameters:

  • pItem PageItem

    The PageItem to alter

  • [height] Number optional

    The new height

Returns:

Number: The current height

itemPosition

(
  • pItem
  • [x]
  • [y]
)
Object

Moves the given PageItem to the given position. If x or y is not given as argument the current position is returned.

Parameters:

  • pItem PageItem

    The PageItem to alter

  • [x] Number optional

    The new x coordinate

  • [y] Number optional

    The new y coordinate

Returns:

Object: Returns an object with the fields x and y

items

(
  • container
  • [cb]
)
PageItems

If no callback function is given it returns a Collection of items otherwise calls the given callback function for each of the PageItems in the given Document, Page, Layer or Group.

Parameters:

  • container Document | Page | Layer | Group

    The container where the PageItems sit in

  • [cb] Function | Boolean optional

    Optional: The callback function to call for each PageItem. When this function returns false the loop stops. Passed arguments: item, loopCount.

Returns:

PageItems: array or PageItems.

itemSize

(
  • pItem
  • [width]
  • [height]
)
Object

Scales the given PageItem to the given size. If width or height is not given as argument the current size is returned.

Parameters:

  • pItem PageItem

    The PageItem to alter

  • [width] Number optional

    The new width

  • [height] Number optional

    The new height

Returns:

Object: Returns an object with the fields width and height

itemWidth

(
  • pItem
  • [width]
)
Number

Scales the given PageItem to the given width. If width is not given as argument the current width is returned.

Parameters:

  • pItem PageItem

    The PageItem to alter

  • [width] Number optional

    The new width

Returns:

Number: The current width

itemX

(
  • pItem
  • [x]
)
Number

Positions a PageItem at the designated spot on the x axis. If no x argument is given the current x position is returned.

Parameters:

  • pItem PageItem

    The PageItem to alter

  • [x] Number optional

    The new x position

Returns:

Number: The current x position

itemY

(
  • pItem
  • [y]
)
Number

Positions a PageItem at the designated spot on the y axis. If no y argument is given the current y position is returned.

Parameters:

  • pItem PageItem

    The PageItem to alter

  • [y] Number optional

    The new y position

Returns:

Number: The current y position

join

(
  • array
  • separator
)
String

Combines an array of Strings into one String, each separated by the character(s) used for the separator parameter. To join arrays of ints or floats, it's necessary to first convert them to strings using nf() or nfs().

Parameters:

  • array Array

    A string array

  • separator String

    The separator to be inserted

Returns:

String: The joined string

JSON.decode

(
  • String
)
Object

Defined in includes/data.js:5

Function parses and validates a string as JSON-object. Usage: var obj = b.JSON.decode(str); var str = b.JSON.encode(obj);

Parameters:

  • String String

    to be parsed as JSON-object.

Returns:

Object: Returns JSON-object or throws an error if invalid JSON has been provided.

JSON.encode

(
  • Object
)
String

Defined in includes/data.js:35

Function convert an javascript object to a JSON-string. Usage: var str = b.JSON.encode(obj); var obj = b.JSON.decode(str);

Parameters:

  • Object Object

    to be converted to a JSON-string

Returns:

String: Returns JSON-string

label

(
  • label
)
PageItem

Returns the first item that is tagged with the given label in the InDesign Script Label pane (Window -> Utilities -> Script Label). Use this instead of b.labels, when you know you just have one thing with that label and don't want to deal with a single-element array.

Parameters:

  • label String

    The label identifier

Returns:

PageItem: The first PageItem of all the hits

labels

(
  • label
  • [cb]
)
PageItem

Returns items tagged with the given label in the InDesign Script Label pane (Window -> Utilities -> Script Label).

Parameters:

  • label String

    The label identifier

  • [cb] Function optional

    Optional: The callback function to call with each item in the search result. When this function returns false the loop stops. Passed arguments: item, loopCount

Returns:

PageItem: Array of concrete PageItem instances, e.g. TextFrame or SplineItem.

layer

(
  • [layer]
)
Layer

Returns the current layer and sets it if argument layer is given.

Parameters:

  • [layer] Layer | String optional

    The layer or layer name to set the current layer to

Returns:

Layer: The current layer instance

lerp

(
  • value1
  • value2
  • amt
)
Number

Calculates a number between two numbers at a specific increment. The amt parameter is the amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc. The lerp function is convenient for creating motion along a straight path and for drawing dotted lines.

Parameters:

Returns:

Number: The mapped value

lerpColor

(
  • c1
  • c2
  • amt
)
Color

Calculates a color or colors between two color at a specific increment. The amt parameter is the amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc. N.B.: Both color must be either CMYK or RGB.

Parameters:

  • c1 Color

    Input color 1

  • c2 Color

    Input color 2

  • amt Number

    The Amount to interpolate between the two colors

Returns:

Color: Interpolated color

line

(
  • x1
  • y1
  • x2
  • y2
)
GraphicLine

Draws a line (a direct path between two points) to the page.

Parameters:

Returns:

GraphicLine: New GraphicLine

lines

(
  • item
  • [cb]
)
Lines

If no callback function is given it returns a Collection of items otherwise calls the given callback function with each line of the given document, story, text frame or paragraph.

Parameters:

  • item Document | Story | TextFrame | Paragraph

    The document, story, text frame or paragraph instance to iterate the lines in

  • [cb] Function optional

    Optional: The callback function to call with each line. When this function returns false the loop stops. Passed arguments: line, loopCount

Returns:

Lines: Array of lines.

linkTextFrames

(
  • textFrameA
  • textFrameB
)

Links the stories of two textframes to one story. Text of first textframe overflows to second one.

Parameters:

  • textFrameA TextFrame
  • textFrameB TextFrame

loadString

(
  • fileOrString
)
String

Reads the contents of a file or loads an URL into a String. If the file is specified by name as String, it must be located in the document's data directory.

Parameters:

  • fileOrString String | File

    The text file name in the document's data directory or a File instance or an URL

Returns:

String: String file or URL content.

loadStrings

(
  • file
)
String[]

Reads the contents of a file or loads an URL and creates a String array of its individual lines. If the file is specified by name as String, it must be located in the document's data directory.

Parameters:

  • file String | File

    The text file name in the document's data directory or a File instance or an URL

Returns:

String[]: Array of the individual lines in the given File or URL

log

(
  • number
)
Number

Calculates the natural logarithm (the base-e logarithm) of a number. This function expects the values greater than 0.0.

Parameters:

  • number Number

    must be greater then 0.0

Returns:

loop

(
  • framerate
)

Defined in includes/core.js:75

EXPERIMENTAL!

Causes basil to continuously execute the code within draw() when InDesign is idle.

targetengine "loop"; must be at the very top in the script file.

If noLoop() is called, the code in draw() stops executing. It is essential to call noLoop() or execute the script lib/stop.jsx when the script is finished! The framerate property determines how often draw() is called per second, e.g. a framerate of 20 will 20times call draw() per second.

Parameters:

  • framerate Number

    The framerate per second, determines how often draw() is called per second.

mag

(
  • a
  • b
  • [c]
)
Number

Calculates the magnitude (or length) of a vector. A vector is a direction in space commonly used in computer graphics and linear algebra. Because it has no "start" position, the magnitude of a vector can be thought of as the distance from coordinate (0,0) to its (x,y) value. Therefore, mag() is a shortcut for writing "dist(0, 0, x, y)".

Parameters:

Returns:

Number: the magnitude

map

(
  • value
  • istart
  • istop
  • ostart
  • ostop
)
Number

Re-maps a number from one range to another. In the example above, the number '25' is converted from a value in the range 0..100 into a value that ranges from the left edge (0) to the right edge (width) of the screen.

Numbers outside the range are not clamped to 0 and 1, because out-of-range values are often intentional and useful.

Parameters:

  • value Number

    the value to be mapped

  • istart Number

    start of the input range

  • istop Number

    end of the input range

  • ostart Number

    start of the output range

  • ostop Number

    end of the output range

Returns:

Number: the mapped value

margins

(
  • [top]
  • [right]
  • [bottom]
  • [left]
  • [pageNumber]
)
Object

Sets the margins of a given page. If 1 value is given, all 4 sides are set equally. If 4 values are given, the current page will be adjusted. Adding a 5th value will set the margin of a given page. Calling the function without any values, will return the margins for the current page.

Parameters:

  • [top] Number optional

    Top margin or all if only one

  • [right] Number optional

    Right margin

  • [bottom] Number optional

    Bottom margin

  • [left] Number optional

    Left margin

  • [pageNumber] Number optional

    Sets margins to selected page, currentPage() if left blank

Returns:

Object: Current page margins with these properties: top, right, bottom, left

matrix

(
  • [matrix]
)
Matrix2D

Returns the current matrix as a Matrix2D object for altering existing PageItems with b.transform(). If a Matrix2D object is provided to the function it will overwrite the current matrix.

Parameters:

  • [matrix] Matrix2D optional

    The matrix to be set as new current matrix

Returns:

Matrix2D: Returns the current matrix

max

(
  • param1
  • param2
  • param3
)
Number

Determines the largest value in a sequence of numbers.

Parameters:

  • param1 Number | Array

    Either the first value or an array of Numbers

  • param2 Number

    Another value to be compared

  • param3 Number

    Another value to be compared

Returns:

Number: The highest value

millis

() Number

Returns the number of milliseconds (thousandths of a second) since starting an applet.

Returns:

millisecond

() Number

The millisecond() function differs from millis(), in that it returns the exact millisecond (thousandths of a second) of the current time.

Returns:

min

(
  • param1
  • param2
  • param3
)
Number

Determines the smallest value in a sequence of numbers.

Parameters:

  • param1 Number | Array

    Either the first value or an array of Numbers

  • param2 Number

    Another value to be compared

  • param3 Number

    Another value to be compared

Returns:

Number: The lowest value

minute

() Number

The minute() function returns the current minute as a value from 0 - 59.

Returns:

month

() Number

The month() function returns the current month as a value from 1 - 12.

Returns:

nameOnPage

() Object

Returns the first item on the active page that is named by the given name in the Layers pane (Window -> Layer).

Returns:

Object: The first object on the active page with the given name

nf

(
  • value
  • leftDigits
  • rightDigits
)
String

Utility function for formatting numbers into strings. There are two versions, one for formatting floats and one for formatting ints. The values for the digits, left, and right parameters should always be positive integers.

As shown in the above example, nf() is used to add zeros to the left and/or right of a number. This is typically for aligning a list of numbers. To remove digits from a floating-point number, use the int(), ceil(), floor(), or round() functions.

Parameters:

Returns:

String: The formatted string

nfc

(
  • value
  • leftDigits
  • rightDigits
)
String

Utility function for formatting numbers into strings and placing appropriate commas to mark units of 1000. There are two versions, one for formatting ints and one for formatting an array of ints. The value for the digits parameter should always be a positive integer.

Parameters:

Returns:

String: The formatted string

nfp

(
  • value
  • leftDigits
  • rightDigits
)
String

Utility function for formatting numbers into strings. Similar to nf() but puts a "+" in front of positive numbers and a "-" in front of negative numbers. There are two versions, one for formatting floats and one for formatting ints. The values for the digits, left, and right parameters should always be positive integers.

Parameters:

Returns:

String: The formatted string

nfs

(
  • value
  • leftDigits
  • rightDigits
)
String

Utility function for formatting numbers into strings. Similar to nf() but leaves a blank space in front of positive numbers so they align with negative numbers in spite of the minus symbol. There are two versions, one for formatting floats and one for formatting ints. The values for the digits, left, and right parameters should always be positive integers.

Parameters:

Returns:

String: The formatted string

noFill

()

Disables filling geometry. If both noStroke() and noFill() are called, newly drawn shapes will be invisible.

noise

(
  • x
  • [y]
  • [z]
)
Number

Returns the Perlin noise value at specified coordinates. Perlin noise is a random sequence generator producing a more natural ordered, harmonic succession of numbers compared to the standard random() function. It was invented by Ken Perlin in the 1980s and been used since in graphical applications to produce procedural textures, natural motion, shapes, terrains etc.

The main difference to the random() function is that Perlin noise is defined in an infinite n-dimensional space where each pair of coordinates corresponds to a fixed semi-random value (fixed only for the lifespan of the program). The resulting value will always be between 0.0 and 1.0. basil.js can compute 1D, 2D and 3D noise, depending on the number of coordinates given. The noise value can be animated by moving through the noise space. The 2nd and 3rd dimension can also be interpreted as time.

The actual noise is structured similar to an audio signal, in respect to the function's use of frequencies. Similar to the concept of harmonics in physics, perlin noise is computed over several octaves which are added together for the final result.

Another way to adjust the character of the resulting sequence is the scale of the input coordinates. As the function works within an infinite space the value of the coordinates doesn't matter as such, only the distance between successive coordinates does (eg. when using noise() within a loop). As a general rule the smaller the difference between coordinates, the smoother the resulting noise sequence will be. Steps of 0.005-0.03 work best for most applications, but this will differ depending on use.

Parameters:

  • x Number

    Coordinate in x space

  • [y] Number optional

    Coordinate in y space

  • [z] Number optional

    Coordinate in z space

Returns:

Number: the noise value

noiseDetail

(
  • octaves
  • fallout
)

Adjusts the character and level of detail produced by the Perlin noise function. Similar to harmonics in physics, noise is computed over several octaves. Lower octaves contribute more to the output signal and as such define the overal intensity of the noise, whereas higher octaves create finer grained details in the noise sequence. By default, noise is computed over 4 octaves with each octave contributing exactly half than its predecessor, starting at 50% strength for the 1st octave. This falloff amount can be changed by adding an additional function parameter. Eg. a falloff factor of 0.75 means each octave will now have 75% impact (25% less) of the previous lower octave. Any value between 0.0 and 1.0 is valid, however note that values greater than 0.5 might result in greater than 1.0 values returned by noise().

By changing these parameters, the signal created by the noise() function can be adapted to fit very specific needs and characteristics.

Parameters:

  • octaves Number

    number of octaves to be used by the noise() function

  • fallout Number

    falloff factor for each octave

noiseSeed

(
  • seed
)

Sets the seed value for noise(). By default, noise() produces different results each time the program is run. Set the value parameter to a constant to return the same pseudo-random numbers each time the software is run.

Parameters:

noLoop

()

EXPERIMENTAL!

Stops basil from continuously executing the code within draw().

norm

(
  • aNumber
  • low
  • low
)
Number

Normalizes a number from another range into a value between 0 and 1.

Identical to map(value, low, high, 0, 1);

Numbers outside the range are not clamped to 0 and 1, because out-of-range values are often intentional and useful.

Parameters:

  • aNumber Number

    The value to be normed

  • low Number

    The lowest value to be expected

  • low Number

    The highest value to be expected

Returns:

Number: The normalized value

noStroke

()

Disables drawing the stroke (outline). If both noStroke() and noFill() are called, nothing will be drawn to the screen.

objectStyle

(
  • name
)
ObjectStyle

Returns the object style with the given name. If the style does not exist it gets created.

Parameters:

  • name String

    The name of the object style to return.

Returns:

ObjectStyle: The object style instance.

opacity

(
  • obj
  • opacity
)

Sets the opacity property of an object.

Parameters:

  • obj Object

    The object to set opacity property

  • opacity Number

    The opacity value form 0 to 100

page

(
  • [page]
)
Page

Returns the current page and sets it if argument page is given. Numbering starts with 1.

Parameters:

  • [page] Page | Number | PageItem optional

    The page object or page number to set the current page to. If you pass a PageItem the current page will be set to it's containing page.

Returns:

Page: The current page instance

pageCount

()

The number of all pages in the current document.

Returns:

The amount of pages.

pageNumber

(
  • [pageObj]
)
Number

Returns the current page number of either the current page or the given Page object.

Parameters:

  • [pageObj] Page optional

    Optional: The page you want to know the number of.

Returns:

Number: The page number within the document.

paragraphs

(
  • item
  • [cb]
)
Paragraphs

If no callback function is given it returns a Collection of items otherwise calls the given callback function with each paragraph of the given document, story or text frame.

Parameters:

  • item Document | Story | TextFrame

    The story or text frame instance to iterate the paragraphs in

  • [cb] Function optional

    Optional: The callback function to call with each paragraph. When this function returns false the loop stops. Passed arguments: para, loopCount

Returns:

Paragraphs: Array of Paragraphs.

paragraphStyle

(
  • name
)
ParagraphStyle

Returns the paragraph style with the given name. If the style does not exist it gets created.

Parameters:

  • name String

    The name of the paragraph style to return.

Returns:

ParagraphStyle: The paragraph style instance.

popMatrix

()

Pops the current transformation matrix off the matrix stack. Understanding pushing and popping requires understanding the concept of a matrix stack. The pushMatrix() function saves the current coordinate system to the stack and popMatrix() restores the prior coordinate system. pushMatrix() and popMatrix() are used in conjuction with the other transformation methods and may be embedded to control the scope of the transformations.

pow

(
  • num
  • exponent
)
Number

Facilitates exponential expressions. The pow() function is an efficient way of multiplying numbers by themselves (or their reciprocal) in large quantities. For example, pow(3, 5) is equivalent to the expression 33333 and pow(3, -5) is equivalent to 1 / 33333

Parameters:

  • num Number

    base of the exponential expression

  • exponent Number

    power of which to raise the base

Returns:

Number: the result

print

(
  • msg
)

Prints a message to the console output in the ExtendScript editor, but unlike b.println() it doesn't return the carriage to a new line at the end.

Parameters:

  • msg String

    The message to print

printInfo

()

Print numerous information about the current environment to the console

println

(
  • msg
)

Prints a message line to the console output in the ExtendScript editor.

Parameters:

  • msg String

    The message to print

printMatrix

()

Prints the current matrix to the console window.

projectFolder

() Folder

Get the folder of the active document as a Folder object. Use .absoluteURI to access a string representation of the folder path.

Returns:

Folder: The folder of the the active document

pushMatrix

()

Pushes the current transformation matrix onto the matrix stack. Understanding pushMatrix() and popMatrix() requires understanding the concept of a matrix stack. The pushMatrix() function saves the current coordinate system to the stack and popMatrix() restores the prior coordinate system. pushMatrix() and popMatrix() are used in conjuction with the other transformation methods and may be embedded to control the scope of the transformations.

radians

(
  • aAngle
)
Number

Converts a degree measurement to its corresponding value in radians. Radians and degrees are two ways of measuring the same thing. There are 360 degrees in a circle and 2*PI radians in a circle. For example, 90° = PI/2 = 1.5707964. All trigonometric methods in Processing require their parameters to be specified in radians.

Parameters:

  • aAngle Number

    an angle in degree

Returns:

Number: The given angle in radians

random

(
  • [low]
  • [high]
)
Number

Generates random numbers. Each time the random() function is called, it returns an unexpected value within the specified range. If one parameter is passed to the function it will return a float between zero and the value of the high parameter. The function call random(5) returns values between 0 and 5. If two parameters are passed, it will return a float with a value between the the parameters. The function call random(-5, 10.2) returns values between -5 and 10.2.

One parameter sets the range from 0 to the given parameter, while with two parameters present you set the range from val1 - val2.

Parameters:

  • [low] Number optional

    The low border of the range

  • [high] Number optional

    The high border of the range

Returns:

Number: A random number

rect

(
  • x
  • y
  • w
  • h
)
Rectangle

Draws a rectangle on the page.

Parameters:

Returns:

Rectangle: New rectangle

rectMode

(
  • mode
)

Modifies the location from which rectangles draw. The default mode is rectMode(CORNER), which specifies the location to be the upper left corner of the shape and uses the third and fourth parameters of rect() to specify the width and height. The syntax rectMode(CORNERS) uses the first and second parameters of rect() to set the location of one corner and uses the third and fourth parameters to set the opposite corner. The syntax rectMode(CENTER) draws the image from its center point and uses the third and forth parameters of rect() to specify the image's width and height. The syntax rectMode(RADIUS) draws the image from its center point and uses the third and forth parameters of rect() to specify half of the image's width and height. The parameter must be written in "ALL CAPS".

Parameters:

  • mode String

    Either b.CORNER, b.CORNERS, b.CENTER, or b.RADIUS

remove

(
  • obj
)

Removes the provided Page, Layer, PageItem, Swatch, etc.

Parameters:

  • obj PageItem

    The object to be removed

removePage

(
  • [page]
)

Removes a page from the current document. This will either be the current Page if the parameter page is left empty, or the given Page object or page number.

Parameters:

  • [page] Page | Number optional

    Optional: The page to be removed as Page object or page number.

resetMatrix

()

Replaces the current matrix with the identity matrix.

rotate

(
  • angle
)

Rotates an object the amount specified by the angle parameter. Angles should be specified in radians (values from 0 to PI*2) or converted to radians with the radians() function. Objects are always rotated around their relative position to the origin and positive numbers rotate objects in a clockwise direction with 0 radians or degrees being up and HALF_PI being to the right etc. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling rotate(PI/2) and then rotate(PI/2) is the same as rotate(PI). If rotate() is called within the draw(), the transformation is reset when the loop begins again. Technically, rotate() multiplies the current transformation matrix by a rotation matrix. This function can be further controlled by the pushMatrix() and popMatrix().

Parameters:

  • angle Number

    The angle specified in radians

round

(
  • value
)
Number

Calculates the integer closest to the value parameter. For example, round(9.2) returns the value 9.

Parameters:

  • value Number

    The value to be rounded

Returns:

Number: The rounded value

savePDF

(
  • file
  • [showOptions]
)

Exports the current document as PDF to the documents folder. Please note, that export options default to the last used export settings.

Parameters:

  • file String | File

    The file name or a File instance

  • [showOptions] Boolean optional

    Whether to show the export dialog

savePNG

(
  • file
  • [showOptions]
)

Exports the current document as PNG (or sequence of PNG files) to the documents folder. Please note, that export options default to the last used export settings.

Parameters:

  • file String | File

    The file name or a File instance

  • [showOptions] Boolean optional

    Whether to show the export dialog

saveString

(
  • file
  • string
)

Writes a string to a file. If the given file exists it gets overridden.

Parameters:

  • file String | File

    The file name or a File instance

  • string String

    The string to be written

saveStrings

(
  • file
  • strings
)

Writes an array of strings to a file, one line per string. If the given file exists it gets overridden.

Parameters:

  • file String | File

    The file name or a File instance

  • strings String[]

    The string array to be written

scale

(
  • scaleX
  • scaleY
)

Increasing and decreasing the size of an object by expanding and contracting vertices. Scale values are specified as decimal percentages. The function call scale(2.0) increases the dimension of a shape by 200%. Objects always scale from their relative origin to the coordinate system. Transformations apply to everything that happens after and subsequent calls to the function multiply the effect. For example, calling scale(2.0) and then scale(1.5) is the same as scale(3.0). If scale() is called within draw(), the transformation is reset when the loop begins again. This function can be further controlled by pushMatrix() and popMatrix(). If only one parameter is given, it is applied on X and Y axis.

Parameters:

  • scaleX Number

    The amount to scale the X axis.

  • scaleY Number

    The amount to scale the Y axis.

second

() Number

The second() function returns the current second as a value from 0 - 59.

Returns:

selection

() Object

Returns the first currently selected object. Use this if you know you only have one selected item and don't want to deal with an array.

Returns:

Object: The first selected object

selections

(
  • [cb]
)
Object[]

Returns the currently selected object(s)

Parameters:

  • [cb] Function optional

    Optional: The callback function to call with each item in the selection. When this function returns false the loop stops. Passed arguments: item, loopCount

Returns:

Object[]: Array of selected object(s).

shellExecute

(
  • cmd
)
String

Executes a shell command and returns the result, currently Mac only.

BE CAREFUL!

Parameters:

  • cmd String

    The shell command to execute

Returns:

sin

(
  • rad
)
Number

Calculates the sine of an angle. This function expects the values of the angle parameter to be provided in radians (values from 0 to 6.28). Values are returned in the range -1 to 1.

Parameters:

  • rad Number

    a value in radians

Returns:

split

(
  • str
  • [delim]
)
Array

The split() function breaks a string into pieces using a character or string as the divider. The delim parameter specifies the character or characters that mark the boundaries between each piece. A String[] array is returned that contains each of the pieces.

If the result is a set of numbers, you can convert the String[] array to to a float[] or int[] array using the datatype conversion functions int() and float() (see example above).

The splitTokens() function works in a similar fashion, except that it splits using a range of characters instead of a specific character or sequence.

Parameters:

  • str String

    the String to be split

  • [delim] String optional

    The string used to separate the data

Returns:

Array: Array of strings

splitTokens

(
  • str
  • [tokens]
)
Array

The splitTokens() function splits a String at one or many character "tokens." The tokens parameter specifies the character or characters to be used as a boundary.

If no tokens character is specified, any whitespace character is used to split. Whitespace characters include tab (\t), line feed (\n), carriage return (\r), form feed (\f), and space. To convert a String to an array of integers or floats, use the datatype conversion functions int() and float() to convert the array of Strings.

Parameters:

  • str String

    the String to be split

  • [tokens] String optional

    list of individual characters that will be used as separators

Returns:

Array: Array of strings

sq

(
  • aNumber
)
Number

Squares a number (multiplies a number by itself). The result is always a positive number, as multiplying two negative numbers always yields a positive result. For example, -1 * -1 = 1.

Parameters:

  • aNumber Number

    The value to be squared

Returns:

sqrt

(
  • val
)
Number

Calculates the square root of a number. The square root of a number is always positive, even though there may be a valid negative root. The square root s of number a is such that s*s = a. It is the opposite of squaring.

Parameters:

  • val Number

    The value to be calculated

Returns:

startsWith

(
  • str
  • prefix
)
Boolean

Checks whether a string starts with a specific character or string.

Parameters:

  • str String

    A string to be checked

  • prefix String

    The string to look for

Returns:

Boolean: Returns either true or false

stories

(
  • doc
  • [cb]
)
Stories

If no callback function is given it returns a Collection of items otherwise calls the given callback function with each story of the given document.

Parameters:

  • doc Document

    The document instance to iterate the stories in

  • [cb] Function optional

    Optional: The callback function to call with each story. When this function returns false the loop stops. Passed arguments: story, loopCount;

Returns:

Stories: Array of Stories.

storyCount

() Number

The number of all stories in the current document.

Returns:

Number: count The amount of stories.

stroke

(
  • strokeColor
)

Sets the color used to draw lines and borders around shapes.

Parameters:

  • strokeColor Color | Swatch | Numbers

    Accepts a Color/swatch or a string with the name of a color. Or values: C,M,Y,K / R,G,B / Grey

strokeTint

(
  • tint
)

Sets the tint of the color used to draw lines and borders around shapes.

Parameters:

  • tint Number

    Number from 0 to 100

strokeWeight

(
  • weight
)

Sets the width of the stroke used for lines and the border around shapes.

Parameters:

  • weight Number

    The width of the stroke

tan

(
  • rad
)
Number

Calculates the ratio of the sine and cosine of an angle. This function expects the values of the angle parameter to be provided in radians (values from 0 to PI*2). Values are returned in the range infinity to -infinity.

Parameters:

  • rad Number

    a value in radians

Returns:

text

(
  • txt
  • x
  • y
  • w
  • h
)
TextFrame

Creates a text frame on the current layer on the current page in the current document. The text frame gets created in the position specified by the x and y parameters. The default document font will be used unless a font is set with the textFont() function. The default document font size will be used unless a font size is set with the textSize() function. Change the color of the text with the fill() function. The text displays in relation to the textAlign() and textYAlign() functions. The width and height parameters define a rectangular area.

Parameters:

  • txt String

    The text content to set in the text frame.

  • x Number

    x-coordinate of text frame

  • y Number

    y-coordinate of text frame

  • w Number

    width of text frame

  • h Number

    height of text frame

Returns:

TextFrame: The created text frame instance

textAlign

(
  • align
  • [yAlign]
)

Sets the current horizontal and vertical text alignment.

Parameters:

  • align String

    The horizontal text alignment to set. Must be one of the InDesign Justification enum values: Justification.AWAYFROMBINDINGSIDE
    Justification.CENTER
    ALIGN
    Justification.CENTERJUSTIFIED
    Justification.FULLY
    JUSTIFIED
    Justification.LEFTALIGN
    Justification.RIGHT
    ALIGN
    Justification.RIGHTJUSTIFIED
    Justification.TO
    BINDING_SIDE

  • [yAlign] String optional

    The vertical text alignment to set. Must be one of the InDesign VerticalJustification enum values: VerticalJustification.BOTTOMALIGN
    VerticalJustification.CENTER
    ALIGN
    VerticalJustification.JUSTIFYALIGN
    VerticalJustification.TOP
    ALIGN

textFont

(
  • fontName
  • [fontStyle]
)
String

Returns the current font and sets it if argument fontName is given.

Parameters:

  • fontName String

    The name of the font to set e.g. Helvetica

  • [fontStyle] String optional

    The Font style e.g. Bold

Returns:

String: currFont The name of the current font

textKerning

(
  • [kerning]
)
Number

Returns the current kerning and sets it if argument kerning is given.

Parameters:

  • [kerning] Number optional

    The value to set.

Returns:

Number: The current kerning.

textLeading

(
  • [leading]
)
Number | String

Returns the spacing between lines of text in units of points and sets it if argument leading is given.

Parameters:

  • [leading] Number | String optional

    The spacing between lines of text in units of points or the default Indesign enum value Leading.AUTO.

Returns:

Number | String: The current leading.

textSize

(
  • [pointSize]
)
Number

Returns the current font size in points and sets it if argument pointSize is given.

Parameters:

  • [pointSize] Number optional

    The size in points to set.

Returns:

Number: The current point size.

textTracking

(
  • [tracking]
)
Number

Returns the current tracking and sets it if argument tracking is given.

Parameters:

  • [tracking] Number optional

    The value to set.

Returns:

Number: The current tracking.

timestamp

() String

The timestamp() function returns the current date formatted as YYYYMMDD_HHMMSS for useful unique filenaming.

Returns:

transform

(
  • obj
  • matrix
)

Transforms the given PageItem with the given Matrix2D object.

Parameters:

  • obj PageItem

    The item to be transformed

  • matrix Matrix2D

    The matrix to be applied

transformImage

(
  • img
  • x
  • y
  • width
  • height
)

Transforms position and size of an image. The image fit options are always "contentToFrame".

Parameters:

translate

(
  • tx
  • ty
)

Specifies an amount to displace objects within the page. The x parameter specifies left/right translation, the y parameter specifies up/down translation. Transformations apply to everything that happens after and subsequent calls to the function accumulates the effect. For example, calling translate(50, 0) and then translate(20, 0) is the same as translate(70, 0). This function can be further controlled by the pushMatrix() and popMatrix().

Parameters:

  • tx Number

    The amount of offset on the X axis.

  • ty Number

    The amount of offset on the Y axis.

trim

(
  • str
)
String | Array

Removes whitespace characters from the beginning and end of a String. In addition to standard whitespace characters such as space, carriage return, and tab, this function also removes the Unicode "nbsp" character.

Parameters:

  • str String | Array

    A string or an array of strings to be trimmed

Returns:

String | Array: Returns the input in a trimmed way

trimWord

(
  • s
)

Removes multiple, leading or trailing spaces and punctuation from "words". E.g. converts "word!" to "word". Especially useful together with b.words();

Parameters:

typo

(
  • item
  • property
  • [value]
)
String[] | Number[] | Object[]

Sets text properties to the given item. If the item is not an instance the text property can be set to, the property gets set to the direct descendants of the given item, e.g. all stories of a given document.

If no value is given and the given property is a string, the function acts as a getter and returns the corresponding value(s) in an array. This can either be an array containing the value of the concrete item (e.g. character) the values of the item's descendants (e.g. paragraphs of given text frame).

Parameters:

  • item Document | Spread | Page | Layer | Story | TextFrame | Text

    The object to apply the property to.

  • property String | Object

    The text property name or an object of key/value property/value pairs. If property is a string and no value is given, the function acts as getter.

  • [value] String | Number | Object optional

    The value to apply to the property.

Returns:

String[] | Number[] | Object[]: The property value(s) if the function acts as getter or the items the property was assigned to.

unbinary

(
  • binaryString
)
Number

Converts a String representation of a binary number to its equivalent integer value. For example, unbinary("00001000") will return 8.

Parameters:

  • binaryString String

    value to convert

Returns:

Number: The integer representation

unhex

(
  • hex
)
Number

Convert a hex representation to a number.

Parameters:

  • hex String

    The hex representation

Returns:

Number: The number

units

(
  • [units]
)
Constant

Sets the units of the document (like right clicking the rulers). The default units of basil.js are PT.

Parameters:

  • [units] Constant optional

    Supported units: PT, PX, CM, MM or IN

Returns:

Constant: Current unit setting

Vector

(
  • x
  • y
  • [z]
)

Defined in includes/math.js:7

A class to describe a two or three dimensional vector. This datatype stores two or three variables that are commonly used as a position, velocity, and/or acceleration. Technically, position is a point and velocity and acceleration are vectors, but this is often simplified to consider all three as vectors. For example, if you consider a rectangle moving across the screen, at any given instant it has a position (the object's location, expressed as a point.), a velocity (the rate at which the object's position changes per time unit, expressed as a vector), and acceleration (the rate at which the object's velocity changes per time unit, expressed as a vector). Since vectors represent groupings of values, we cannot simply use traditional addition/multiplication/etc. Instead, we'll need to do some "vector" math, which is made easy by the methods inside the Vector class.

Constructor of Vector, can be two- or three-dimensional.

Parameters:

Vector.add

(
  • v
  • [y]
  • [z]
)

Adds x, y, and z components to a vector, adds one vector to another.

Parameters:

  • v Vector | Number

    Either a full vector or an x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Vector.angleBetween

(
  • v1
  • v2
)
Number static

Defined in includes/math.js:70

Static function. Calculates the angle between two vectors. Is meant to be called "static" i.e. Vector.angleBetween(v1, v2);

Parameters:

  • v1 Vector

    The first vector

  • v2 Vector

    The second vector

Returns:

Number: The angle

Vector.array

() Array

Returns this vector as an array [x,y,z].

Returns:

Array: [x,y,z]

Vector.cross

(
  • v
  • [y]
  • [z]
)
Number

Calculates the cross product from this vector to another as x, y, and z components or full vector.

Parameters:

  • v Vector | Number

    Either a full vector or an x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Returns:

Number: The cross product

Vector.cross

(
  • v1
  • v2
)
Number static

Defined in includes/math.js:55

Static function. Calculates the cross product of two vectors. Is meant to be called "static" i.e. Vector.cross(v1, v2);

Parameters:

  • v1 Vector

    The first vector

  • v2 Vector

    The second vector

Returns:

Number: The cross product

Vector.dist

(
  • v1
  • v2
)
Number static

Defined in includes/math.js:25

Static function. Calculates the Euclidean distance between two points (considering a point as a vector object). Is meant to be called "static" i.e. Vector.dist(v1, v2);

Parameters:

  • v1 Vector

    The first vector

  • v2 Vector

    The second vector

Returns:

Number: The distance

Vector.dist

(
  • v
  • [y]
  • [z]
)
Number

Calculates the distance from this vector to another as x, y, and z components or full vector.

Parameters:

  • v Vector | Number

    Either a full vector or an x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Returns:

Number: The distance

Vector.div

(
  • v
  • [y]
  • [z]
)

Divides this vector through x, y, and z components or another vector.

Parameters:

  • v Vector | Number

    Either a full vector or an x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Vector.dot

(
  • v
  • [y]
  • [z]
)
Number

Calculates the dot product from this vector to another as x, y, and z components or full vector.

Parameters:

  • v Vector | Number

    Either a full vector or an x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Returns:

Number: The dot product

Vector.dot

(
  • v1
  • v2
)
Number static

Defined in includes/math.js:40

Static function. Calculates the dot product of two vectors. Is meant to be called "static" i.e. Vector.dot(v1, v2);

Parameters:

  • v1 Vector

    The first vector

  • v2 Vector

    The second vector

Returns:

Number: The dot product

Vector.get

() Vector

Gets a copy of the vector, returns a Vector object.

Returns:

Vector: A copy of the vector

Vector.heading

() Number

The 2D orientation (heading) of this vector in radian.

Returns:

Number: A radian angle value

Vector.limit

(
  • high
)

Normalizes the length of this vector to the given parameter.

Parameters:

  • high Number

    The value to scale to.

Vector.mag

() Number

Calculates the magnitude (length) of the vector and returns the result as a float

Returns:

Number: The length

Vector.mult

(
  • v
  • [y]
  • [z]
)

Multiplies this vector with x, y, and z components or another vector.

Parameters:

  • v Vector | Number

    Either a full vector or an x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Vector.normalize

()

Normalizes the length of this vector to 1.

Vector.set

(
  • v
  • [y]
  • [z]
)

Defined in includes/math.js:87

Sets the x, y, and z component of the vector using three separate variables, the data from a Vector, or the values from a float array.

Parameters:

  • v Number | Array | Vector

    Either a vector, array or x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Vector.sub

(
  • v
  • [y]
  • [z]
)

Substract x, y, and z components or a full vector from this vector

Parameters:

  • v Vector | Number

    Either a full vector or an x component

  • [y] Number optional

    The y component

  • [z] Number optional

    The z component

Vector.toString

() String

Returns data about this vector as a string.

Returns:

String: The x, y and z components as a string.

vertex

(
  • x
  • y
  • [xAnchorLeft]
  • [yAnchorLeft]
  • [xAnchorRight]
  • [yAnchorRight]
)

Shapes are constructed by connecting a series of vertices. vertex() is used to specify the vertex coordinates lines and polygons. It is used exclusively within the beginShape() and endShape() functions.

Please use either vertex(x, y) or for drawing bezier shapes vertex(x, y, xAnchorLeft, yAnchorLeft, xAnchorRight, yAnchorRight). You can also mix the two approaches.

Parameters:

  • x Number

    position x-value

  • y Number

    position y-value

  • [xAnchorLeft] Number optional

    position xAnchorLeft-value

  • [yAnchorLeft] Number optional

    position yAnchorLeft-value

  • [xAnchorRight] Number optional

    position xAnchorRight-value

  • [yAnchorRight] Number optional

    position yAnchorRight-value

weekday

() String

The weekday() function returns the current weekday as a string from Sunday, Monday, Tuesday...

Returns:

words

(
  • item
  • [cb]
)
Words

If no callback function is given it returns a Collection of items otherwise calls the given callback function with each word of the given document, story, text frame, paragraph or line.

Parameters:

  • item Document | Story | TextFrame | Paragraph | Line

    The document, story, text frame, paragraph or line instance to iterate the words in

  • [cb] Function optional

    Optional: The callback function to call with each word. When this function returns false the loop stops. Passed arguments: word, loopCount

Returns:

Words: Array of Words.

year

() Number

The year() function returns the current year as an integer (2012, 2013 etc).

Returns:

Properties

AFTER

String

Used with b.addPage() to set the position of the new page in the book.

AT_BEGINNING

String

Used with b.addPage() to set the position of the new page in the book.

AT_END

String

Used with b.addPage() to set the position of the new page in the book.

BEFORE

String

Used with b.addPage() to set the position of the new page in the book.

BLEED

String

Used with b.canvasMode() to set the canvas to the full current page plus the bleed.

CENTER

String

Center, used for drawing modes.

CHORD

String

Chord, used for arc() modes.

CLOSE

String

Close, used for endShape() modes.

CM

String

Used with b.units() to set the coordinate system to centimeters.

CMYK

String

Used with b.colorMode() to set the color space.

CORNER

String

Corner, used for drawing modes.

CORNERS

String

Corners, used for drawing modes.

EPSILON

Number

Epsilon

FACING_BLEEDS

String

Used with b.canvasMode() to set the canvas to use the current facing pages plus bleeds.

FACING_MARGINS

String

Used with b.canvasMode() to set the canvas to use the current facing pages minus margins.

FACING_PAGES

String

Used with b.canvasMode() to set the canvas to use the current facing pages.

HALF_PI

Number

Half Pi

height

Number

System variable which stores the height of the current page.

IN

String

Used with b.units() to set the coordinate system to inches.

KAPPA

Number

Kappa

MARGIN

String

Used with b.canvasMode() to set the canvas to the full current page minus the margins.

MM

String

Used with b.units() to set the coordinate system to millimeters.

MODEHIDDEN

String

Used with b.go() to set Performance Mode. Processes Document in background mode. Document will not be visible until the script is done. If you are firing on a open document you'll need to save it before calling b.go(). The document will be removed from the display list and added again after the script is done. In this mode you will likely look at indesign with no open document for quite some time - do not work in indesign during this time. You may want to use b.println("yourMessage") in your script and look at the Console in estk to get information about the process.

MODESILENT

String

Used with b.go() to set Performance Mode. Disables ScreenRedraw during processing.

MODEVISIBLE

String

Default mode. Used with b.go() to set Performance Mode. Processes Document with Screen redraw, use this option to see direct results during the process. This will slow down the process in terms of processing time. This mode was also the default in Versions prior to 0.22

OPEN

String

Open, used for arc() modes.

PAGE

String

Used with b.canvasMode() to set the canvas to the full current page.

PIE

String

Pie, used for arc() modes.

PT

String

Used with b.units() to set the coordinate system to points.

PX

String

Used with b.units() to set the coordinate system to pixels.

QUARTER_PI

Number

Quarter Pi

RADIUS

String

Radius, used for drawing modes.

RGB

String

Used with b.colorMode() to set the color space.

SINCOS_LENGTH

Number

Sin Cos Length

TWO_PI

Number

Two Pi

VERSION

String

Defined in basil.js:50

The basil version

width

Number

System variable which stores the width of the current page.