diff --git a/basil.js b/basil.js index f0d4b3d..dc320ee 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. 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.