diff --git a/basil.js b/basil.js
index f0d4b3d..286ef21 100644
--- a/basil.js
+++ b/basil.js
@@ -2663,7 +2663,7 @@ var isString = pub.isString = function(str) {
};
/**
- * @summary Checks wether a var is an InDesign text object.
+ * @summary Checks whether a var is an InDesign text object.
* @description Checks whether a var is an InDesign text object, returns `true` if this is the case.
* NB: a InDesign text frame will return `false` as it is just a container holding text. So you could say that `isText()` refers to all the things inside a text frame.
*
@@ -4009,6 +4009,71 @@ pub.objectStyle = function(itemOrName, props) {
return style;
};
+/**
+ * @summary Paste one page item into another.
+ * @description Paste the source page item into the destination item, which then acts like a clipping mask. Optionally, set to a variable, to immediately access the new page item inside your destination.
+ *
+ * @cat Document
+ * @subcat Page Items
+ * @method pasteInto
+ *
+ * @param {PageItem} source The page item to copy.
+ * @param {PageItem} destination The page item to paste the source into.
+ * @return {Object} The new page item inside the destination.
+ *
+ * @example
Use ellipse as clipping mask for textframe.
+ * noStroke();
+ * textSize(50);
+ *
+ * fill(0);
+ * var myText = text(LOREM, 0, 0, width, height);
+ *
+ * noFill();
+ * var myMask = ellipse(width / 2, height / 2, width / 2, height / 2);
+ *
+ * myMaskItem = pasteInto(myText, myMask);
+ *
+ * property(myMaskItem, 'fillColor', color(0, 255, 0));
+ *
+ * @example Use ellipse as clipping mask for rect.
+ * noStroke();
+ *
+ * fill(255, 0, 0);
+ * var myRect = rect(0, 0, width / 2, height / 2);
+ *
+ * fill(0, 0, 255);
+ * var myMask = ellipse(width / 2, height / 2, width / 2, height / 2);
+ *
+ * myMaskItem = pasteInto(myRect, myMask);
+ *
+ * property(myMaskItem, 'fillColor', color(255, 0, 255));
+ */
+pub.pasteInto = function(source, destination) {
+ checkNull(source);
+ checkNull(destination);
+
+ // temp store previous selection
+ var tempSelection = app.selection;
+
+ // set source to app clipboard
+ app.selection = source;
+ app.copy();
+
+ // paste source into destination
+ app.selection = destination;
+ app.pasteInto();
+
+ // return selection
+ app.selection = tempSelection;
+
+ // return new pageItem inside destination
+ if(destination.pageItems[0].hasOwnProperty('texts')){
+ return destination.pageItems[0].texts[0];
+ }else{
+ return destination.pageItems[0];
+ }
+};
+
/**
* @summary Returns the first selected object or selects an object.
* @description If no argument is given, returns the first currently selected object. If a page item is given as argument, the page item will be selected.
@@ -4940,7 +5005,7 @@ pub.SCRIPTNAME = scriptName;
* @subcat Constants
* @property VERSION {String}
*/
-pub.VERSION = "2.0.0-beta";
+pub.VERSION = "2.0.0-beta 2021-01-04";
// ----------------------------------------
// src/includes/image.js
diff --git a/changelog.txt b/changelog.txt
index 32b812a..3e4ce4d 100644
--- a/changelog.txt
+++ b/changelog.txt
@@ -60,6 +60,7 @@ basil.js x.x.x DAY MONTH YEAR
+ Added saveCSV() to stringify data and save it as CSV file in one step
+ Added CSV.parse() and CSV.stringify() to replace CSV.decode() and CSV.encode()
parse and stringify accept optional 2nd parameter for custom delimiter.
++ Added pasteInto() enabling using page items as clipping masks
* translate(), rotate() and scale() now behave like they do in Processing and change the current matrix
* basil scripts will by default use the user's default units or the current units of the document,
diff --git a/src/includes/data.js b/src/includes/data.js
index 7d93c46..63d423a 100644
--- a/src/includes/data.js
+++ b/src/includes/data.js
@@ -1200,7 +1200,7 @@ var isString = pub.isString = function(str) {
};
/**
- * @summary Checks wether a var is an InDesign text object.
+ * @summary Checks whether a var is an InDesign text object.
* @description Checks whether a var is an InDesign text object, returns `true` if this is the case.
* NB: a InDesign text frame will return `false` as it is just a container holding text. So you could say that `isText()` refers to all the things inside a text frame.
*
diff --git a/src/includes/document.js b/src/includes/document.js
index 7805264..8d57b67 100644
--- a/src/includes/document.js
+++ b/src/includes/document.js
@@ -1218,6 +1218,71 @@ pub.objectStyle = function(itemOrName, props) {
return style;
};
+/**
+ * @summary Paste one page item into another.
+ * @description Paste the source page item into the destination item, which then acts like a clipping mask. Optionally, set to a variable, to immediately access the new page item inside your destination.
+ *
+ * @cat Document
+ * @subcat Page Items
+ * @method pasteInto
+ *
+ * @param {PageItem} source The page item to copy.
+ * @param {PageItem} destination The page item to paste the source into.
+ * @return {Object} The new page item inside the destination.
+ *
+ * @example Use ellipse as clipping mask for textframe.
+ * noStroke();
+ * textSize(50);
+ *
+ * fill(0);
+ * var myText = text(LOREM, 0, 0, width, height);
+ *
+ * noFill();
+ * var myMask = ellipse(width / 2, height / 2, width / 2, height / 2);
+ *
+ * myMaskItem = pasteInto(myText, myMask);
+ *
+ * property(myMaskItem, 'fillColor', color(0, 255, 0));
+ *
+ * @example Use ellipse as clipping mask for rect.
+ * noStroke();
+ *
+ * fill(255, 0, 0);
+ * var myRect = rect(0, 0, width / 2, height / 2);
+ *
+ * fill(0, 0, 255);
+ * var myMask = ellipse(width / 2, height / 2, width / 2, height / 2);
+ *
+ * myMaskItem = pasteInto(myRect, myMask);
+ *
+ * property(myMaskItem, 'fillColor', color(255, 0, 255));
+ */
+pub.pasteInto = function(source, destination) {
+ checkNull(source);
+ checkNull(destination);
+
+ // temp store previous selection
+ var tempSelection = app.selection;
+
+ // set source to app clipboard
+ app.selection = source;
+ app.copy();
+
+ // paste source into destination
+ app.selection = destination;
+ app.pasteInto();
+
+ // return selection
+ app.selection = tempSelection;
+
+ // return new pageItem inside destination
+ if(destination.pageItems[0].hasOwnProperty('texts')){
+ return destination.pageItems[0].texts[0];
+ }else{
+ return destination.pageItems[0];
+ }
+};
+
/**
* @summary Returns the first selected object or selects an object.
* @description If no argument is given, returns the first currently selected object. If a page item is given as argument, the page item will be selected.
diff --git a/src/includes/environment.js b/src/includes/environment.js
index bbdcbcf..7730bf6 100644
--- a/src/includes/environment.js
+++ b/src/includes/environment.js
@@ -452,4 +452,4 @@ pub.SCRIPTNAME = scriptName;
* @subcat Constants
* @property VERSION {String}
*/
-pub.VERSION = "2.0.0-beta";
+pub.VERSION = "2.0.0-beta 2021-01-04";