From 36cb88de4d6408fea3084a82b0cdbada60ced1d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrg=20Lehni?= Date: Sat, 16 Jan 2016 16:51:47 +0100 Subject: [PATCH] Write documentation for Project#addLayer() and #insertLayer() Closes #903 --- src/basic/Rectangle.js | 12 +++--- src/item/Item.js | 6 +-- src/project/Project.js | 93 +++++++++++++++++++++++++----------------- 3 files changed, 64 insertions(+), 47 deletions(-) diff --git a/src/basic/Rectangle.js b/src/basic/Rectangle.js index 9339e4fb..ca126f6e 100644 --- a/src/basic/Rectangle.js +++ b/src/basic/Rectangle.js @@ -799,10 +799,10 @@ var Rectangle = Base.extend(/** @lends Rectangle# */{ ['Right', 'Center'], ['Bottom', 'Center'] ], function(parts, index) { - var part = parts.join(''); - // find out if the first of the pair is an x or y property, - // by checking the first character for [R]ight or [L]eft; - var xFirst = /^[RL]/.test(part); + var part = parts.join(''), + // find out if the first of the pair is an x or y property, + // by checking the first character for [R]ight or [L]eft; + xFirst = /^[RL]/.test(part); // Rename Center to CenterX or CenterY: if (index >= 4) parts[1] += xFirst ? 'Y' : 'X'; @@ -861,8 +861,8 @@ new function() { var proto = Rectangle.prototype; return Base.each(['x', 'y', 'width', 'height'], function(key) { - var part = Base.capitalize(key); - var internal = '_' + key; + var part = Base.capitalize(key), + internal = '_' + key; this['get' + part] = function() { return this[internal]; }; diff --git a/src/item/Item.js b/src/item/Item.js index 103d8e7c..0b509fbf 100644 --- a/src/item/Item.js +++ b/src/item/Item.js @@ -2114,8 +2114,8 @@ var Item = Base.extend(Emitter, /** @lends Item# */{ * {@grouptitle Hierarchy Operations} * * Adds the specified item as a child of this item at the end of the its - * children list. You can use this function for groups, compound paths and - * layers. + * {@link #children} list. You can use this function for groups, compound + * paths and layers. * * @param {Item} item the item to be added as a child * @return {Item} the added item, or `null` if adding was not possible @@ -2129,7 +2129,7 @@ var Item = Base.extend(Emitter, /** @lends Item# */{ * in its {@link #children} list. You can use this function for groups, * compound paths and layers. * - * @param {Number} index + * @param {Number} index the index at which to insert the item * @param {Item} item the item to be inserted as a child * @return {Item} the inserted item, or `null` if inserting was not possible */ diff --git a/src/project/Project.js b/src/project/Project.js index af185b56..324ceb1f 100644 --- a/src/project/Project.js +++ b/src/project/Project.js @@ -269,44 +269,6 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{ }, // TODO: Implement setSelectedItems? - insertLayer: function(index, item) { - if (item instanceof Layer) { - item._remove(false, true); - Base.splice(this._children, [item], index, 0); - item._setProject(this, true); - // See Item#_remove() for an explanation of this: - if (this._changes) - item._changed(/*#=*/Change.INSERTION); - // TODO: this._changed(/*#=*/Change.LAYERS); - // Also activate this layer if there was none before - if (!this._activeLayer) - this._activeLayer = item; - } else { - item = null; - } - return item; - }, - - addLayer: function(item) { - return this.insertLayer(undefined, item); - }, - - // Project#_insertItem() and Item#_insertItem() are helper functions called - // in Item#copyTo(), and through _getOwner() in the various Item#insert*() - // methods. They are called the same to facilitate so duck-typing. - _insertItem: function(index, item, _preserve, _created) { - item = this.insertLayer(index, item) - // Anything else than layers needs to be added to a layer first. - // If none exists yet, create one now, then add the item to it. - || (this._activeLayer || this._insertItem(undefined, - new Layer(Item.NO_INSERT), true, true)) - .insertChild(index, item, _preserve); - // If a layer was newly created, also activate it. - if (_created && item.activate) - item.activate(); - return item; - }, - _updateSelection: function(item) { var id = item._id, selectedItems = this._selectedItems; @@ -390,6 +352,61 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{ return null; }, + /** + * {@grouptitle Hierarchy Operations} + * + * Adds the specified layer at the end of the this project's {@link #layers} + * list. + * + * @param {Layer} layer the layer to be added to the project + * @return {Layer} the added layer, or `null` if adding was not possible + */ + addLayer: function(layer) { + return this.insertLayer(undefined, layer); + }, + + /** + * Inserts the specified layer at the specified index in this project's + * {@link #layers} list. + * + * @param {Number} index the index at which to insert the layer + * @param {Item} item the item to be inserted in the project + * @return {Layer} the added layer, or `null` if adding was not possible + */ + insertLayer: function(index, layer) { + if (layer instanceof Layer) { + layer._remove(false, true); + Base.splice(this._children, [layer], index, 0); + layer._setProject(this, true); + // See Item#_remove() for an explanation of this: + if (this._changes) + layer._changed(/*#=*/Change.INSERTION); + // TODO: this._changed(/*#=*/Change.LAYERS); + // Also activate this layer if there was none before + if (!this._activeLayer) + this._activeLayer = layer; + } else { + layer = null; + } + return layer; + }, + + // Project#_insertItem() and Item#_insertItem() are helper functions called + // in Item#copyTo(), and through _getOwner() in the various Item#insert*() + // methods. They are called the same to facilitate so duck-typing. + _insertItem: function(index, item, _preserve, _created) { + item = this.insertLayer(index, item) + // Anything else than layers needs to be added to a layer first. + // If none exists yet, create one now, then add the item to it. + || (this._activeLayer || this._insertItem(undefined, + new Layer(Item.NO_INSERT), true, true)) + .insertChild(index, item, _preserve); + // If a layer was newly created, also activate it. + if (_created && item.activate) + item.activate(); + return item; + }, + /** * {@grouptitle Fetching and matching items} *