API Docs for: see header basil.js
Show:

File: includes/structure.js

// ----------------------------------------
// Structure

/**
 * 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.
 *
 * @cat Environment
 * @method delay
 * @param  {Number} milliseconds  The delay time in milliseconds
 */
pub.delay = function (milliseconds) {
  $.sleep(milliseconds);
};

/**
 * 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.
 *
 * @cat Document
 * @subcat Multi-Getters
 * @method stories
 * @param  {Document} doc The document instance to iterate the stories in
 * @param  {Function} [cb]  Optional: The callback function to call with each story. When this function returns false the loop stops. Passed arguments: story, loopCount;
 * @return {Stories[]} Array of Stories.
 */
pub.stories = function(doc, cb) {
  if(arguments.length === 1 && doc instanceof Document) {
    return doc.stories;
  } else if (cb instanceof Function) {
    return forEach(doc.stories, cb);
  } else {
    error("b.stories(), incorrect call. Wrong parameters!");
  }
};

/**
 * 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.
 *
 * @cat Document
 * @subcat Multi-Getters
 * @method paragraphs
 * @param  {Document|Story|TextFrame} item The story or text frame instance to iterate the paragraphs in
 * @param  {Function} [cb]  Optional: The callback function to call with each paragraph. When this function returns false the loop stops. Passed arguments: para, loopCount
 * @return {Paragraphs[]} Array of Paragraphs.   
 */
pub.paragraphs = function(item, cb) {

  if(!item.hasOwnProperty('contents')) error("b.paragraphs(), Wrong object type.");

  if(arguments.length === 1) {
    return item.paragraphs;
  } else if (cb instanceof Function) {
    if (item instanceof Document) {
      return forEachStoryProperty(item, 'paragraphs', cb);
    } else {
      return forEach(item.paragraphs, cb);
    }
  }
};

// /**
//  * If no callback function is given it returns a Collection of strings otherwise calls the given callback function with each sentences of the given document, story or text frame.
//  *
//  * cat Document
//  * subcat Multi-Getters
//  * method sentences
//  * param  {Document|Story|TextFrame} item The story or text frame instance to iterate the sentences in
//  * param  {Function} cb  Optional: The callback function to call with each sentence. When this function returns false the loop stops. Passed arguments: sentence, loopCount
//  * return {Array} An array of strings
//  * 
//  */
//  // FIXME
// pub.sentences = function(item, cb) {

//   var err = false;
//   try{
//     item[0]; // check if list
//     err = true; // access ok -> error
//   } catch (expected) {};
//   if(err) error("b.sentences(), Array/Collection has been passed to b.sentences(). Single object expected.");

//   if(arguments.length >= 1 ) {
//     var arr;
//     try{
//       str = item.contents;  
//       arr = str.match( /[^\.!\?]+[\.!\?]+/g );
//     } catch (e){
//       error("b.sentences(), Object passed to b.sentences() does not have text or is incompatible.");
//     }

//     if(arguments.length === 1) {
//       return arr;
//     } else if (cb instanceof Function) {
//       forEach(arr,cb);
//     } else {
//       error("b.sentences(), the callback parameter is not a Function.");
//     }

//   }

// };

/**
 * 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.
 *
 * @cat Document
 * @subcat Multi-Getters
 * @method lines
 * @param  {Document|Story|TextFrame|Paragraph} item The document, story, text frame or paragraph instance to
 *                                                   iterate the lines in
 * @param  {Function} [cb] Optional: The callback function to call with each line. When this function returns false the loop stops. Passed arguments: line, loopCount
 * @return {Lines[]} Array of lines.
 */
pub.lines = function(item, cb) {

  if(!item.hasOwnProperty('contents')) error("b.lines(), Wrong object type.");

  if(arguments.length === 1) {
    return item.lines;
  } else if (cb instanceof Function) {
    if (item instanceof Document) {
      return forEachStoryProperty(item, 'lines', cb);
    } else {
      return forEach(item.lines, 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.
 *
 * @cat Document
 * @subcat Multi-Getters
 * @method words
 * @param  {Document|Story|TextFrame|Paragraph|Line} item The document, story, text frame, paragraph or line instance
 *                                                        to iterate the words in
 * @param  {Function} [cb] Optional: The callback function to call with each word. When this function returns false the loop stops. Passed arguments: word, loopCount
 * @return {Words[]} Array of Words.
 */
pub.words = function(item, cb) {

  if(!item.hasOwnProperty('contents')) error("b.words(), Wrong object type.");
  
  if(arguments.length === 1){
    return item.words;
  } else if (cb instanceof Function) {
    if (item instanceof Document) {
      return forEachStoryProperty(item, 'words', cb);
    } else {
      return forEach(item.words, 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.
 *
 * @cat Document
 * @subcat Multi-Getters
 * @method characters
 * @param  {Document|Story|TextFrame|Paragraph|Line|Word} item The document, story, text frame, paragraph, line or word instance to
 *                                                    iterate the characters in
 * @param  {Function} [cb] Optional: The callback function to call with each character. When this function returns false the loop stops. Passed arguments: character, loopCount
 * @return {Characters} You can use it like an array.
 */
pub.characters = function(item, cb) {

  if(!item.hasOwnProperty('contents')) error("b.characters(), Wrong object type.");

  if(arguments.length === 1) {
    return item.characters;
  } else if ( cb instanceof Function) {
    if (item instanceof Document) {
      return forEachStoryProperty(item, 'characters', cb);
    } else {
      return forEach(item.characters, cb);
    }
  }
};

var forEachStoryProperty = function(doc, property, cb) {
  var loopCount = 0;
  pub.stories(doc, function(story) {
    var properties = story[property];
    for (var i = 0, len = properties.length; i < len; i++) {
      if(cb(properties[i], loopCount++) === false) {
        return false;
      }
    }
    return true;
  });
};

/**
 * 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.
 *
 * @cat Document
 * @subcat Multi-Getters
 * @method items
 * @param  {Document|Page|Layer|Group} container The container where the PageItems sit in
 * @param  {Function|Boolean} [cb] Optional: The callback function to call for each PageItem. When this function returns false the loop stops. Passed arguments: item, loopCount. 
 * @return {PageItems[]} array or PageItems.
 */
pub.items = function(container, cb) {

  if (container instanceof Document 
    || container instanceof Page 
    || container instanceof Layer 
    || container instanceof Group) {

    if(arguments.length === 1 || cb === false){
      return container.allPageItems;
    } else if(cb instanceof Function ) {
      return forEach(container.allPageItems, cb);
    }
  } else {
    error("b.items(), Not a valid PageItem container, should be Document, Page, Layer or Group");
  }
};


/**
 * Removes all PageItems in the given Document, Page, Layer or Group.
 *
 * @cat Document
 * @method clear
 * @param  {Document|Page|Layer|Group} container The container where the PageItems sit in
 */
pub.clear = function(container) {

  if (container instanceof Document 
    || container instanceof Page 
    || container instanceof Layer 
    || container instanceof Group) {

      return forEach(container.allPageItems, function(item,n){
        // Groups have to be avoided for deletion
        // otherwise deletion process is confused
        if(item !== null && ! (item instanceof Group) ) {
          if(item.locked) error("b.clear(), some items are locked. Please unlock them first and sue then b.clear().");
          item.remove();
        }
      });

    } else {
      return false;
    }
};

/**
 * Removes the provided Page, Layer, PageItem, Swatch, etc.
 *
 * @cat Document
 * @method remove
 * @param  {PageItem} obj The object to be removed
 */
pub.remove = function(obj) {

  if(obj.hasOwnProperty("remove")) {
    obj.remove();
  } else {
    throw new Error("Provided object cannot be removed in b.remove().");
  }
}