adding pasteInto()

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,65 @@ 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 <caption>Use ellipse as clipping mask for textframe.</caption>
+ * 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 <caption>Use ellipse as clipping mask for rect.</caption>
+ * 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);
+
+  // set source to app clipboard
+  app.selection = source;
+  app.copy();
+
+  // paste source into destination
+  app.selection = destination;
+  app.pasteInto();
+
+  // 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.

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,

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.
  *

src/includes/document.js

@@ -1218,6 +1218,65 @@ 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 <caption>Use ellipse as clipping mask for textframe.</caption>
+ * 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 <caption>Use ellipse as clipping mask for rect.</caption>
+ * 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);
+
+  // set source to app clipboard
+  app.selection = source;
+  app.copy();
+
+  // paste source into destination
+  app.selection = destination;
+  app.pasteInto();
+
+  // 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.