Color
b.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.SOFT_LIGHT
BlendMode.HARD_LIGHT
BlendMode.COLOR_DODGE
BlendMode.COLOR_BURN
BlendMode.DARKEN
BlendMode.LIGHTEN
BlendMode.DIFFERENCE
BlendMode.EXCLUSION
BlendMode.HUE
BlendMode.SATURATION
BlendMode.COLOR
BlendMode.LUMINOSITY
b.CMYK
Used with b.colorMode() to set the color space.
b.color(Get)
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
b.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
b.fill(fillColor)
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
b.fillTint(tint)
Sets the tint of the color used to fill shapes.
Parameters:
-
– tint (Number)
Number from 0 to 100
b.lerpColor(c1, c2, amt)
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
b.noFill()
Disables filling geometry. If both noStroke() and noFill() are called, newly drawn shapes will be invisible.
b.noStroke()
Disables drawing the stroke (outline). If both noStroke() and noFill() are called, nothing will be drawn to the screen.
b.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
b.RGB
Used with b.colorMode() to set the color space.
b.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
b.strokeTint(tint)
Sets the tint of the color used to draw lines and borders around shapes.
Parameters:
-
– tint (Number)
Number from 0 to 100
Data
Array Functions
b.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.
Conversion
b.binary(num, [numBits])
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)
number of digits to return
Returns:
String: A formatted string
b.hex(value, [len])
Convert a number to a hex representation.
Parameters:
-
– value (Number)
The number to convert
-
– len (Number)
The length of the hex number to be created, default: 8
Returns:
String: The hex representation as a string
b.unbinary(binaryString)
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
b.unhex(hex)
Convert a hex representation to a number.
Parameters:
-
– hex (String)
The hex representation
Returns:
Number: The number
CSV
b.CSV.decode(String)
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
b.CSV.delimiter([delimiter])
Sets the delimiter of the CSV decode and encode function.
Parameters:
-
– delimiter (String)
Optional Sets the delimiter for CSV parsing
Returns:
String: Returns the current delimiter if called without argument
b.CSV.encode(Array)
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
HashList
b.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.
b.HashList.clear()
Deletes all the key -> value pairs in this HashList.
b.HashList.get(key)
This gets a value by its key.
Parameters:
-
– key (Any)
The key to look for
Returns:
Any: The value
b.HashList.getKeys()
Returns an array with all keys.
Returns:
Array: An array with all the keys
b.HashList.getKeysByValues()
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
b.HashList.getSortedKeys()
Returns an array with all keys in a sorted order from higher to lower magnitude.
Returns:
Array: An array with all the keys
b.HashList.hasKey(key)
Checks for the existence of a given key.
Parameters:
-
– key (Any)
The key to check
Returns:
Boolean:
b.HashList.hasValue(value)
Checks if a certain value exists at least once in all of the key -> value pairs.
Parameters:
-
– value (Any)
Returns:
Boolean:
b.HashList.remove(key)
This removes a key -> value pair by its key.
Parameters:
-
– key (Any)
The key to delete
Returns:
Any: The value before deletion
b.HashList.set(key, value)
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
Input
b.loadString(fileOrString)
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.
b.loadStrings(file)
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
b.shellExecute(cmd)
Executes a shell command and returns the result, currently Mac only. BE CAREFUL!
Parameters:
-
– cmd (String)
The shell command to execute
Returns:
String:
JSON
b.JSON.decode(String)
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.
b.JSON.encode(Object)
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
String Functions
b.endsWith(str, suffix)
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
b.isURL(url)
Checks whether an URL string is valid.
Parameters:
-
– url (String)
An url string to be checked
Returns:
Boolean: Returns either true or false
b.join(array, separator)
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
b.nf(value, leftDigits, rightDigits)
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:
-
– value (Number)
The Number to convert
-
– leftDigits (Number)
-
– rightDigits (Number)
Returns:
String: The formatted string
b.nfc(value, leftDigits, rightDigits)
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:
-
– value (Number)
The Number to convert
-
– leftDigits (Number)
-
– rightDigits (Number)
Returns:
String: The formatted string
b.nfp(value, leftDigits, rightDigits)
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:
-
– value (Number)
The Number to convert
-
– leftDigits (Number)
-
– rightDigits (Number)
Returns:
String: The formatted string
b.nfs(value, leftDigits, rightDigits)
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:
-
– value (Number)
The Number to convert
-
– leftDigits (Number)
-
– rightDigits (Number)
Returns:
String: The formatted string
b.split(str, [delim])
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)
The string used to separate the data
Returns:
Array: Array of strings
b.splitTokens(str, [tokens])
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)
list of individual characters that will be used as separators
Returns:
Array: Array of strings
b.startsWith(str, prefix)
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
b.trim(str)
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
b.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:
-
– s (String)
The String to trim
Type-Check
b.isArray(obj)
Checks whether a var is an Array, returns true if this is the case
Parameters:
-
– obj (Object|String|Number|Boolean)
The object to check
Returns:
Boolean: returns true if this is the case
b.isNumber(num)
Checks whether a var is a number, returns true if this is the case
Parameters:
-
– num (Object|String|Number|Boolean)
The number to check
Returns:
Boolean: returns true if this is the case
b.isString(str)
Checks whether a var is a string, returns true if this is the case
Parameters:
-
– str (Object|String|Number|Boolean)
The string to check
Returns:
Boolean: returns true if this is the case
Vector
b.Vector(x, y, [z])
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:
-
– x (Number)
-
– y (Number)
-
– z (Number)
b.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)
The y component
-
– z (Number)
The z component
b.Vector.angleBetween(v1, v2)
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
b.Vector.array()
Returns this vector as an array [x,y,z].
Returns:
Array: [x,y,z]
b.Vector.cross(v, [y], [z])
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)
The y component
-
– z (Number)
The z component
Returns:
Number: The cross product
b.Vector.dist(v, [y], [z])
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)
The y component
-
– z (Number)
The z component
Returns:
Number: The distance
b.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)
The y component
-
– z (Number)
The z component
b.Vector.dot(v, [y], [z])
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)
The y component
-
– z (Number)
The z component
Returns:
Number: The dot product
b.Vector.get()
Gets a copy of the vector, returns a Vector object.
Returns:
Vector: A copy of the vector
b.Vector.heading()
The 2D orientation (heading) of this vector in radian.
Returns:
Number: A radian angle value
b.Vector.limit(high)
Normalizes the length of this vector to the given parameter.
Parameters:
-
– high (Number)
The value to scale to.
b.Vector.mag()
Calculates the magnitude (length) of the vector and returns the result as a float
Returns:
Number: The length
b.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)
The y component
-
– z (Number)
The z component
b.Vector.normalize()
Normalizes the length of this vector to 1.
b.Vector.set(v, [y], [z])
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)
The y component
-
– z (Number)
The z component
b.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)
The y component
-
– z (Number)
The z component
b.Vector.toString()
Returns data about this vector as a string.
Returns:
String: The x, y and z components as a string.
Document
Attributes
b.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
b.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
b.strokeWeight(weight)
Sets the width of the stroke used for lines and the border around shapes.
Parameters:
-
– weight (Number)
The width of the stroke
Image
b.image(img, x, [y], [w], [h])
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)
The y position on the current page. Ignored if x is not a number.
-
– w (Number)
The width of the rectangle to add the image to. Ignored if x is not a number.
-
– h (Number)
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.
b.imageMode([mode])
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)
Either b.CORNER, b.CORNERS, or b.CENTER
Returns:
String: The current mode
b.transformImage(img, x, y, width, height)
Transforms position and size of an image. The image fit options are always "contentToFrame".
Parameters:
-
– img (Graphic)
The image to transform
-
– x (Number)
New x
-
– y (Number)
New y
-
– width (Number)
New width
-
– height (Number)
New height
Misc Document
b.projectFolder()
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
Multi-Getters
b.characters(item, [cb])
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: 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.
b.items(container, [cb])
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: 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.
b.label(label)
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
b.labels(label, [cb])
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: 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.
b.lines(item, [cb])
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: 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.
b.nameOnPage()
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
b.paragraphs(item, [cb])
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: 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.
b.selection()
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
b.selections([cb])
Returns the currently selected object(s)
Parameters:
-
– cb (Function)
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).
b.stories(doc, [cb])
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: 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.
b.words(item, [cb])
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: 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.
Page
b.addPage([location])
Adds a new page to the document. Set the optional location parameter to either b.AT_END (default), b.AT_BEGINNING, b.AFTER or b.BEFORE. b.AFTER and b.BEFORE will use the current page as insertion point.
Parameters:
-
– location (String)
The location placement mode
Returns:
Page: The new page
b.AFTER
Used with b.addPage() to set the position of the new page in the book.
b.AT_BEGINNING
Used with b.addPage() to set the position of the new page in the book.
b.AT_END
Used with b.addPage() to set the position of the new page in the book.
b.BEFORE
Used with b.addPage() to set the position of the new page in the book.
b.BLEED
Used with b.canvasMode() to set the canvas to the full current page plus the bleed.
b.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)
Top bleed or all if only one
-
– right (Number)
Right bleed
-
– bottom (Number)
Bottom bleed
-
– left (Number)
Left bleed
b.canvasMode()
Use this to set the dimensions of the canvas. Choose between b.PAGE (default), b.MARGIN, b.BLEED resp. b.FACING_PAGES, b.FACING_MARGINS 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();
b.FACING_BLEEDS
Used with b.canvasMode() to set the canvas to use the current facing pages plus bleeds.
b.FACING_MARGINS
Used with b.canvasMode() to set the canvas to use the current facing pages minus margins.
b.FACING_PAGES
Used with b.canvasMode() to set the canvas to use the current facing pages.
b.Group([pItem], name)
Returns an array of the items that were within the Group before b.ungroup() was called
Parameters:
-
– pItem (Object|String)
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
b.layer([layer])
Returns the current layer and sets it if argument layer is given.
Parameters:
-
– layer (Layer|String)
The layer or layer name to set the current layer to
Returns:
Layer: The current layer instance
b.MARGIN
Used with b.canvasMode() to set the canvas to the full current page minus the margins.
b.margins([top], [right], [bottom], [left], [pageNumber])
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)
Top margin or all if only one
-
– right (Number)
Right margin
-
– bottom (Number)
Bottom margin
-
– left (Number)
Left margin
-
– pageNumber (Number)
Sets margins to selected page, currentPage() if left blank
Returns:
Object: Current page margins with these properties: top, right, bottom, left
b.page([page])
Returns the current page and sets it if argument page is given. Numbering starts with 1.
Parameters:
-
– page (Page|Number|PageItem)
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
b.PAGE
Used with b.canvasMode() to set the canvas to the full current page.
b.pageCount()
The number of all pages in the current document.
Returns:
: The amount of pages.
b.pageNumber([pageObj])
Returns the current page number of either the current page or the given Page object.
Parameters:
-
– pageObj (Page)
Optional: The page you want to know the number of.
Returns:
Number: The page number within the document.
b.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: The page to be removed as Page object or page number.
Primitives
b.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).
b.arc(cx, cy, w, h, startAngle, endAngle, mode)
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
b.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 ()
Set b.CLOSE if the new Path should be auto-closed.
b.CENTER
Center, used for drawing modes.
b.CHORD
Chord, used for arc() modes.
b.CLOSE
Close, used for endShape() modes.
b.CORNER
Corner, used for drawing modes.
b.CORNERS
Corners, used for drawing modes.
b.ellipse(x, y, w, h)
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:
-
– x (Number)
Location X
-
– y (Number)
Location Y
-
– w (Number)
Width
-
– h (Number)
Height
Returns:
Oval: New oval (n.b. in Adobe Scripting the corresponding type is Oval, not Ellipse)
b.endShape()
The endShape() function is the companion to beginShape() and may only be called after beginShape().
Returns:
GraphicLine|Polygon: newShape
b.line(x1, y1, x2, y2)
Draws a line (a direct path between two points) to the page.
Parameters:
-
– x1 (Number)
Point A x-value
-
– y1 (Number)
Point A y-value
-
– x2 (Number)
Point B x-value
-
– y2 (Number)
Point B y-value
Returns:
GraphicLine: New GraphicLine
b.OPEN
Open, used for arc() modes.
b.PIE
Pie, used for arc() modes.
b.RADIUS
Radius, used for drawing modes.
b.rect(x, y, w, h)
Draws a rectangle on the page.
Parameters:
-
– x (Number)
Position X
-
– y (Number)
Position Y
-
– w (Number)
Width
-
– h (Number)
Height
Returns:
Rectangle: New rectangle
b.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)
position xAnchorLeft-value
-
– yAnchorLeft (Number)
position yAnchorLeft-value
-
– xAnchorRight (Number)
position xAnchorRight-value
-
– yAnchorRight (Number)
position yAnchorRight-value
Transformation
b.applyMatrix(matrix)
Multiplies the current matrix by the one specified through the parameters.
Parameters:
-
– matrix (Matrix2D)
The matrix to be applied
b.bounds(obj)
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
b.duplicate(item)
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
b.itemHeight(pItem, [height])
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)
The new height
Returns:
Number: The current height
b.itemPosition(pItem, [x], [y])
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)
The new x coordinate
-
– y (Number)
The new y coordinate
Returns:
Object: Returns an object with the fields x and y
b.itemSize(pItem, [width], [height])
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)
The new width
-
– height (Number)
The new height
Returns:
Object: Returns an object with the fields width and height
b.itemWidth(pItem, [width])
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)
The new width
Returns:
Number: The current width
b.itemX(pItem, [x])
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)
The new x position
Returns:
Number: The current x position
b.itemY(pItem, [y])
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)
The new y position
Returns:
Number: The current y position
b.matrix([matrix])
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)
The matrix to be set as new current matrix
Returns:
Matrix2D: Returns the current matrix
b.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.
b.printMatrix()
Prints the current matrix to the console window.
b.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.
b.resetMatrix()
Replaces the current matrix with the identity matrix.
b.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
b.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.
b.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
b.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.
Type-Check
b.isText(obj)
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
Units
b.CM
Used with b.units() to set the coordinate system to centimeters.
b.IN
Used with b.units() to set the coordinate system to inches.
b.MM
Used with b.units() to set the coordinate system to millimeters.
b.PT
Used with b.units() to set the coordinate system to points.
b.PX
Used with b.units() to set the coordinate system to pixels.
Misc Document
b.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
b.close([saveOptions], [file])
Closes the current document.
Parameters:
-
– saveOptions (SaveOptions|Boolean)
The indesign SaveOptions constant or either true for triggering saving before closing or false for closing without saving.
-
– file (File)
Optional: The indesign file instance to save the document to
b.doc([doc])
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)
The document to set the current document to
Returns:
Document: The current document instance
b.guideX(x)
Creates a vertical guide line at the current spread and current layer.
Parameters:
-
– x (Number)
Position of the new guide
Returns:
Guide: New guide
b.guideY(y)
Creates a horizontal guide line at the current spread and current layer.
Parameters:
-
– y (Number)
Position of the new guide
Returns:
Guide: New guide
b.remove(obj)
Removes the provided Page, Layer, PageItem, Swatch, etc.
Parameters:
-
– obj (PageItem)
The object to be removed
b.units([units])
Sets the units of the document (like right clicking the rulers). The default units of basil.js are PT.
Parameters:
-
– units (Constant)
Supported units: PT, PX, CM, MM or IN
Returns:
Constant: Current unit setting
Environment
Date
b.day()
The day() function returns the current day as a value from 1 - 31.
Returns:
Number:
b.hour()
The hour() function returns the current hour as a value from 0 - 23.
Returns:
Number:
b.millis()
Returns the number of milliseconds (thousandths of a second) since starting an applet.
Returns:
Number:
b.millisecond()
The millisecond() function differs from millis(), in that it returns the exact millisecond (thousandths of a second) of the current time.
Returns:
Number:
b.minute()
The minute() function returns the current minute as a value from 0 - 59.
Returns:
Number:
b.month()
The month() function returns the current month as a value from 1 - 12.
Returns:
Number:
b.second()
The second() function returns the current second as a value from 0 - 59.
Returns:
Number:
b.timestamp()
The timestamp() function returns the current date formatted as YYYYMMDD_HHMMSS for useful unique filenaming.
Returns:
String:
b.weekday()
The weekday() function returns the current weekday as a string from Sunday, Monday, Tuesday...
Returns:
String:
b.year()
The year() function returns the current year as an integer (2012, 2013 etc).
Returns:
Number:
modes
b.MODEHIDDEN
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.
b.MODESILENT
Used with b.go() to set Performance Mode. Disables ScreenRedraw during processing.
b.MODEVISIBLE
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
Misc Environment
b.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
b.go([modes])
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: Switch performanceMode
b.height
System variable which stores the height of the current page.
b.loop(framerate)
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.
b.noLoop()
EXPERIMENTAL! Stops basil from continuously executing the code within draw().
b.VERSION
The basil version
b.width
System variable which stores the width of the current page.
Math
Calculation
b.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
b.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
b.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
b.dist(x1, y1, x2, y2)
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
b.exp(a)
Returns Euler's number e (2.71828...) raised to the power of the value parameter.
Parameters:
-
– a (Number)
value
Returns:
Number:
b.floor(a)
Calculates the closest int value that is less than or equal to the value of the parameter.
Parameters:
-
– a (Number)
value
Returns:
Number:
b.lerp(value1, value2, amt)
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:
-
– value1 (Number)
first value
-
– value2 (Number)
second value
-
– amt (Number)
between 0.0 and 1.0
Returns:
Number: The mapped value
b.log(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:
Number:
b.mag(a, b, [c])
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:
-
– a (Number)
x-coordinate
-
– b (Number)
y-coordinate
-
– c (Number)
z-coordinate
Returns:
Number: the magnitude
b.map(value, istart, istop, ostart, ostop)
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
b.max(param1, param2, param3)
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
b.min(param1, param2, param3)
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
b.norm(aNumber, low, low)
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
b.pow(num, exponent)
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 3*3*3*3*3 and pow(3, -5) is equivalent to 1 / 3*3*3*3*3
Parameters:
-
– num (Number)
base of the exponential expression
-
– exponent (Number)
power of which to raise the base
Returns:
Number: the result
b.round(value)
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
b.sq(aNumber)
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:
Number:
Constants
b.EPSILON
Epsilon
b.HALF_PI
Half Pi
b.KAPPA
Kappa
b.PI
Pi
b.QUARTER_PI
Quarter Pi
b.SINCOS_LENGTH
Sin Cos Length
b.TWO_PI
Two Pi
Random
b.noise(x, [y], [z])
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)
Coordinate in y space
-
– z (Number)
Coordinate in z space
Returns:
Number: the noise value
b.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
b.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:
-
– seed (Number)
b.random([low], [high])
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)
The low border of the range
-
– high (Number)
The high border of the range
Returns:
Number: A random number
Trigonometry
b.acos(value)
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:
Number:
b.asin(value)
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:
Number:
b.atan(value)
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:
Number:
b.atan2(y, x)
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:
-
– y (Number)
the y coordinate
-
– x (Number)
the x coordinate
Returns:
Number:
b.cos(rad)
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:
Number:
b.degrees(aAngle)
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
b.radians(aAngle)
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
b.sin(rad)
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:
Number:
b.sqrt(val)
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:
Number:
b.tan(rad)
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:
Number:
Output
b.download(url, [file])
Downloads an URL to a file, currently Mac only.
Parameters:
-
– url (String)
The download url
-
– file (String|File)
A relative file path in the project folder or a File instance
b.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
b.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
b.printInfo()
Print numerous information about the current environment to the console
b.println(msg)
Prints a message line to the console output in the ExtendScript editor.
Parameters:
-
– msg (String)
The message to print
b.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)
Whether to show the export dialog
b.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)
Whether to show the export dialog
b.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
b.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
Story
b.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.AT_BEGINNING and b.AT_END.
Parameters:
-
– story (Story)
The story
-
– itemOrString (PageItem|String)
The itemOrString either a PageItem, a String or one the following constants: b.AT_BEGINNING and b.AT_END.
-
– insertionPointOrMode (InsertionPoint|String)
InsertionPoint or one the following constants: b.AT_BEGINNING and b.AT_END.
b.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)
b.storyCount()
The number of all stories in the current document.
Returns:
Number: count The amount of stories.
Typography
b.characterStyle(name)
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.
b.objectStyle(name)
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.
b.paragraphStyle(name)
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.
b.text(txt, x, y, w, h)
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
b.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.AWAY_FROM_BINDING_SIDE
Justification.CENTER_ALIGN
Justification.CENTER_JUSTIFIED
Justification.FULLY_JUSTIFIED
Justification.LEFT_ALIGN
Justification.RIGHT_ALIGN
Justification.RIGHT_JUSTIFIED
Justification.TO_BINDING_SIDE -
– yAlign (String)
The vertical text alignment to set. Must be one of the InDesign VerticalJustification enum values: VerticalJustification.BOTTOM_ALIGN
VerticalJustification.CENTER_ALIGN
VerticalJustification.JUSTIFY_ALIGN
VerticalJustification.TOP_ALIGN
b.textFont(fontName, [fontStyle])
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)
The Font style e.g. Bold
Returns:
String: currFont The name of the current font
b.textKerning([kerning])
Returns the current kerning and sets it if argument kerning is given.
Parameters:
-
– kerning (Number)
The value to set.
Returns:
Number: The current kerning.
b.textLeading([leading])
Returns the spacing between lines of text in units of points and sets it if argument leading is given.
Parameters:
-
– leading (Number|String)
The spacing between lines of text in units of points or the default Indesign enum value Leading.AUTO.
Returns:
Number|String: The current leading.
b.textSize([pointSize])
Returns the current font size in points and sets it if argument pointSize is given.
Parameters:
-
– pointSize (Number)
The size in points to set.
Returns:
Number: The current point size.
b.textTracking([tracking])
Returns the current tracking and sets it if argument tracking is given.
Parameters:
-
– tracking (Number)
The value to set.
Returns:
Number: The current tracking.
b.typo(item, property, [value])
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)
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.