/* This file contains proprietary software owned by Motorola Mobility, Inc.
No rights, expressed or implied, whatsoever to this software are provided by Motorola Mobility, Inc. hereunder.
(c) Copyright 2011 Motorola Mobility, Inc. All Rights Reserved.
*/ /** @module montage/ui/controller/array-controller @requires montage/core/core @requires montage/ui/controller/object-controller @requires montage/core/event/mutable-event */ var Montage = require("montage").Montage, ObjectController = require("ui/controller/object-controller").ObjectController, MutableEvent = require("core/event/mutable-event").MutableEvent; /** The ArrayController helps with organizing a collection of objects, and managing user selection within that collection. TYou can assign an ArrayController instance as the contentProvider property for a Montage List or Repetition object. @class module:montage/ui/controller/array-controller.ArrayController @classdesc @extends module:montage/ui/controller/object-controller.ObjectController */ var ArrayController = exports.ArrayController = Montage.create(ObjectController, /** @lends module:montage/ui/controller/array-controller.ArrayController# */ { /** @private */ _content: { enumerable: false, value: null }, /** The content managed by the ArrayController. @type {Function} @default {String} null */ content: { get: function() { return this._content; }, set: function(value) { if (this._content === value) { return; } this._content = value; //TODO for right now assume that any content change invalidates the selection completely; we'll need to address this of course this.selectedObjects = null; this.organizeObjects(); this._initSelections(); } }, /** The user-defined delegate object for the ArrayController.
If a delegate object exists, the ArrayController will notify the delegate of changes to the collection, or the selection.
Currently, the only supported delegate method is shouldChangeSelection, which passes the new and old selected objects.
If the function returns false the selection action is canceled. @type {Object} @default null @example var ArrayController = require("ui/controller/array-controller").ArrayController; var controller = ArrayController.create(); controller.delegate = Montage.create(Object.prototype, { shouldChangeSelection: function(newObj, oldObj) { console.log("New object is", newObj, "Old object is", oldObj); } }) */ delegate: { value: null }, /** @private */ _organizedObjects: { enumerable: false, value: null }, /** The filtered and sorted content of the ArrayCollection. @type {Function} @default null */ organizedObjects: { enumerable: false, get: function() { if (this._organizedObjects) { return this._organizedObjects; } this.organizeObjects(); return this._organizedObjects; } }, /** Specifies whether the ArrayCollection's content is automatically organized (false, by default). @type {Property} @default {Boolean} false */ automaticallyOrganizeObjects: { value: false }, /** @private */ _sortFunction: { enumerable: false, value: null }, /** The sort function used to organize the array collection. @type {Function} @default null @version 1.0 */ sortFunction: { get: function() { return this._sortFunction; }, set: function(value) { if (this._sortFunction === value) { return; } this._sortFunction = value; if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } }, /** @private */ _filterFunction: { enumerable: false, value: null }, /** The filter function used to organize the array collection. @type {Function} @default null @version 1.0 */ filterFunction: { get: function() { return this._filterFunction; }, set: function(value) { if (this._filterFunction === value) { return; } this._filterFunction = value; if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } }, /** @private */ _startIndex: { enumerable: false, value: null }, /** The start index of the organized objects. @type {Function} @default null @version 1.0 */ startIndex: { enumerable: false, get: function() { return this._startIndex; }, set: function(value) { if (this._startIndex === value) { return; } this._startIndex = value; if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } }, /** @private */ _endIndex: { enumerable: false, value: null }, /** The start index of the organized objects. @type {Function} @default null @version 1.0 */ endIndex: { enumerable: false, get: function() { return this._endIndex; }, set: function(value) { if (this._endIndex === value) { return; } this._endIndex = value; if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } }, /* @private */ _organizedObjectsIndexes: { value: null, enumerable: false }, /* @private */ _rangedOrganizedObjectsIndexes: { value: null, enumerable: false }, /** @private */ _selectedIndexes: { value: null, enumerable: false }, /** Description TODO @type {Function} @default null */ selectedIndexes: { get: function() { if (this._selectedIndexes) { return this._selectedIndexes; } if (!this._selectedContentIndexes) { return null; } return this._selectedIndexes = this._convertIndexesFromContentToOrganized(this.selectedContentIndexes); }, set: function(value) { if (this._selectedIndexes !== value) { var newIndexes = value ? this._convertIndexesFromOrganizedToContent(value) : null, newSelection = null; if (this.delegate && typeof this.delegate.shouldChangeSelection === "function") { if (newIndexes) { newSelection = this.content.filter(function(value, i) { return newIndexes.indexOf(i) >= 0; }, this); } if (this.delegate.shouldChangeSelection(this, newSelection, this._selectedObjects) === false) { return; } } this._selectedIndexes = value; var selectedContentIndexesChangeEvent,selectedObjectsChangeEvent; selectedContentIndexesChangeEvent = MutableEvent.changeEventForKeyAndValue("selectedContentIndexes" , this.selectedContentIndexes); selectedObjectsChangeEvent = MutableEvent.changeEventForKeyAndValue("selectedObjects" , this._selectedObjects); this._selectedContentIndexes = newIndexes; this._selectedObjects = null; this.dispatchEvent(selectedContentIndexesChangeEvent.withPlusValue(this.selectedContentIndexes)); this.dispatchEvent(selectedObjectsChangeEvent.withPlusValue(this.selectedObjects)); } } }, /** @private */ _convertIndexesFromOrganizedToContent: { value: function(indexes) { var index, selectedContentIndexes = [], lookup, valueLength = indexes.length, selectedIndex, lookupLength; // if _rangedOrganizedObjectsIndexes != null we have applied a range lookup = this._rangedOrganizedObjectsIndexes ? this._rangedOrganizedObjectsIndexes : this._organizedObjectsIndexes; if (lookup) { lookupLength = lookup.length; for (index = 0; index < valueLength ; index++) { selectedIndex = indexes[index]; if(selectedIndex < lookupLength && selectedIndex >= 0) { selectedContentIndexes[selectedContentIndexes.length] = lookup[selectedIndex]; } } } else { // then it's just a range with not filter or sort for (index = 0; index < valueLength ; index++) { selectedContentIndexes[selectedContentIndexes.length] = indexes[index] + this.startIndex; } } return selectedContentIndexes.sort(); } }, /** @private */ _convertIndexesFromContentToOrganized: { value: function(indexes) { var index, selectedOrganizedIndexes = [], lookup, valueLength = indexes.length, selectedIndex; // if _rangedOrganizedObjectsIndexes != null we have applied a range lookup = this._rangedOrganizedObjectsIndexes ? this._rangedOrganizedObjectsIndexes : this._organizedObjectsIndexes; if (lookup) { for (index = 0; index < valueLength ; index++) { selectedIndex = indexes[index]; if (selectedIndex >= 0) { selectedIndex = lookup.indexOf(selectedIndex); if (selectedIndex !== -1) { selectedOrganizedIndexes[selectedOrganizedIndexes.length] = selectedIndex; } } } } else { // then it's just a range with not filter or sort for (index = 0; index < valueLength ; index++) { selectedIndex = indexes[index] - this.startIndex; // Check if we are within the range of the current organizedObjects if(selectedIndex > -1 && (this.endIndex == null || selectedIndex < this.endIndex)) { selectedOrganizedIndexes[selectedOrganizedIndexes.length] = selectedIndex; } } } return selectedOrganizedIndexes.sort(); } }, /** Organizes the array collection using the filter and sort functions, if defined.
Dispatches a change event. @function @fires change@organizeObjects */ organizeObjects: { value: function() { var organizedObjects = this.content, funktion = this.filterFunction, index = 0, newIndex = 0, filteredIndexes, sortedIndexes, startIndex = this.startIndex, endIndex = this.endIndex, tmpArray, item; if (organizedObjects && typeof funktion === "function") { filteredIndexes = []; organizedObjects = organizedObjects.filter(function filterFunctionWrapper(item) { var filterValue = funktion.call(this, item); if (filterValue) { // we are going to keep the item in the new array filteredIndexes[newIndex] = index; newIndex++; } index++; return filterValue; }, this); } if (typeof (funktion = this._sortFunction) === "function") { // need to attach index information so that we can pick it up after the sort // this has the added side effect of creating a clone of the array so that if it wasn't filtered, // we are not editing the content directly sortedIndexes = []; tmpArray = []; index = 0; for (index = 0; (item = organizedObjects[index]); index++) { if (item !== null && typeof item === "object") { // attach the index item._montage_array_controller_index = index; tmpArray[index] = item; } else { // wrap in a host object tmpArray[index] = { _montage_array_controller_index : index, _montage_array_controller_value : item }; } } // Do the sort tmpArray = tmpArray.sort(function sortFunctionWrapper(a, b) { if (a._montage_array_controller_value) { a = a._montage_array_controller_value; } if (b._montage_array_controller_value) { b = b._montage_array_controller_value; } return funktion.call(this, a, b); }); // get all the new indexes organizedObjects = []; for (index = 0; (item = tmpArray[index]); index++) { newIndex = item._montage_array_controller_index; sortedIndexes[index] = filteredIndexes ? filteredIndexes[newIndex] : newIndex; if (item._montage_array_controller_value) { organizedObjects[index] = item._montage_array_controller_value; } else { organizedObjects[index] = item; delete item._montage_array_controller_index; } } // store it for later use this._organizedObjectsIndexes = sortedIndexes; } else { // store it for later use this._organizedObjectsIndexes = filteredIndexes; } this._applyRangeIfNeeded(organizedObjects); } }, /** @private */ _applyRangeIfNeeded: { value: function(organizedObjects) { var startIndex = this.startIndex, endIndex = this.endIndex, changeEvent; // We apply the range after the content is filtered and sorted if (organizedObjects && (typeof startIndex === "number" || typeof endIndex === "number")) { startIndex = typeof startIndex === "number" && startIndex >= 0 ? startIndex : 0; endIndex = typeof endIndex === "number" && endIndex < organizedObjects.length ? endIndex : organizedObjects.length; // apply the range organizedObjects = organizedObjects.slice(startIndex, endIndex); // store the index lookup change if(this._organizedObjectsIndexes) { this._rangedOrganizedObjectsIndexes = this._organizedObjectsIndexes.slice(startIndex, endIndex); } else { this._rangedOrganizedObjectsIndexes = null; } } // I don't want to provide a setter for organizedObjects, so update the cached value and notify observers that // the organizedObjects property changed changeEvent = MutableEvent.changeEventForKeyAndValue("organizedObjects" , this._organizedObjects ? this._organizedObjects.slice(0) : this._organizedObjects); this._organizedObjects = organizedObjects ? organizedObjects : []; this.dispatchEvent(changeEvent.withPlusValue(this._organizedObjects)); } }, /** @private */ _selectedObjects: { enumerable: false, value: null }, /** Gets or sets the selected objects in the collection.
Setting the selected objects to a new value fires an event of type change@selectedObjects. @type {Function} @default null @fires change@selectedContentIndexes */ selectedObjects: { enumerable: false, get: function() { if (this._selectedObjects) { return this._selectedObjects; } if (!this._selectedContentIndexes) { return null; } if(this.content) { this._selectedObjects = this.content.filter(function(value, i) { return this._selectedContentIndexes.indexOf(i) >= 0; }, this); } return this._selectedObjects; }, set: function(value) { // Normalizing the value before the difference check prevents false-positive "changes" for things like [x]=>x if (value === null || typeof value === "undefined") { // undefined => null value = null; } else if (!Array.isArray(value)) { // any single object, including false and zero value = [value]; } // TODO validate the array content maybe? if (this._selectedObjects === value) { return; } if (this.delegate && typeof this.delegate.shouldChangeSelection === "function") { if (this.delegate.shouldChangeSelection(this, value, this._selectedObjects) === false) { return; } } this._selectedObjects = value; var selectedContentIndexesChangeEvent, selectedIndexesChangeEvent; selectedContentIndexesChangeEvent = MutableEvent.changeEventForKeyAndValue("selectedContentIndexes" , this._selectedContentIndexes); selectedIndexesChangeEvent = MutableEvent.changeEventForKeyAndValue("selectedIndexes" , this._selectedIndexes); this._selectedContentIndexes = null; this._selectedIndexes = null; this.dispatchEvent(selectedContentIndexesChangeEvent.withPlusValue(this.selectedContentIndexes)); this.dispatchEvent(selectedIndexesChangeEvent.withPlusValue(this.selectedIndexes)); } }, /** @private */ _selectedContentIndexes: { enumerable: false, value: null }, /** Gets or sets the indexes of the currently selected items in the collection.
When set to a new set of indexes, generates a event of type "change@selectedObjects". @type {Function} @default null */ selectedContentIndexes: { enumerable: false, get: function() { if (this._selectedContentIndexes) { return this._selectedContentIndexes; } if (!this._selectedObjects) { return null; } this._selectedContentIndexes = []; var selectedIndex; this._selectedObjects.forEach(function(value) { if((selectedIndex = this.content.indexOf(value)) !== -1) { this._selectedContentIndexes.push(selectedIndex); } }, this); return this._selectedContentIndexes; }, set: function(value, internalSet) { var selectedIndexesChangeEvent, selectedObjectsChangeEvent; // Normalizing the value before the difference check prevents false-positive "changes" for things like [x]=>x if (value === null || value === false || typeof value === "undefined") { // undefined, false => null value = null; } else if (!Array.isArray(value)) { // any single index, including zero value = [value]; } // TODO validate the array content maybe? if (this._selectedContentIndexes === value) { return; } if (this.delegate && typeof this.delegate.shouldChangeSelection === "function") { var newIndexes = value, newSelection = null; if (newIndexes) { newSelection = this.content.filter(function(value, i) { return newIndexes.indexOf(i) >= 0; }, this); } if (this.delegate.shouldChangeSelection(this, newSelection, this._selectedObjects) === false) { return; } } this._selectedContentIndexes = value; selectedIndexesChangeEvent = MutableEvent.changeEventForKeyAndValue("selectedIndexes" , this._selectedIndexes); selectedObjectsChangeEvent = MutableEvent.changeEventForKeyAndValue("selectedObjects" , this._selectedObjects); this._selectedIndexes = null; this._selectedObjects = null; this.dispatchEvent(selectedIndexesChangeEvent.withPlusValue(this.selectedIndexes)); this.dispatchEvent(selectedObjectsChangeEvent.withPlusValue(this.selectedObjects)); if(!internalSet) { // update the selections only if the selectedContentIndexes is set directly this._updateSelections(); } } }, _initSelections: { value: function() { // create an array with null values with same // length as organizedObjects var len = this._organizedObjects.length; var arr = []; arr[0] = null; arr[len-1] = null; this._selections = arr; //Object.getPropertyDescriptor(this, "selections").set.call(this, arr, true); } }, _updateSelections: { value: function() { if(this.selectedIndexes) { this._initSelections(); var arr = this._selections; var selectedIndexes = this.selectedIndexes || []; var len = selectedIndexes.length, i=0, index; for(i=0; i< len; i++) { index = selectedIndexes[i]; if(index < arr.length-1) { arr[index] = true; } } } Object.getPropertyDescriptor(this, "selections").set.call(this, arr, true); } }, // parse array with same length as objects but contains true / false(falsy) _selections: {value: null}, selections: { get: function() { return this._selections; }, set: function(v, internalSet) { this._selections = v; if(this._selections) { if(!internalSet) { var arr = []; this._selections.forEach(function(item, i) { if(item) { arr.push(i); } }); // use the internalSet flag to prevent setting the selections again, Object.getPropertyDescriptor(this, "selectedIndexes").set.call(this, arr, true); } } } }, /** Initalizes the ArrayController with the specified content. @function @param {Object} content The collection of objects for the ArrayController to manage. @returns {ArrayController} */ initWithContent: { value: function(content) { this.content = content; return this; } }, /** A Boolean that specifies whether new objects that are added to the array collection are automatically selected. @type {Property} @default {Boolean} false */ selectObjectsOnAddition: { enumerable: false, value: false }, /** A Boolean that specifies whether the filter function is set to null when new objects that are added to the content. @type {Property} @default {Boolean} true */ clearFilterFunctionOnAddition: { enumerable: false, value: true }, /** Adds an item to the array collection's content property. @function @example var ArrayCollection = require("ui/controller/array-controller").ArrayCollection; var ac = ArrayCollection.create(); ac.add({name: "John"}); */ add: { value: function() { var newObject = this.newObject(); this.content.push(newObject); //TODO fdf what do we do with the filterFunction if the newObject wouldn't show? if (this.selectObjectsOnAddition) { this.selectedContentIndexes = [this.content.length-1]; } if (this.clearFilterFunctionOnAddition) { this.filterFunction = null; } else { } if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } }, /** Adds one or more items to the array controller's content property. @function @example var ArrayCollection = require("ui/controller/array-controller").ArrayCollection; var ac = ArrayCollection.create(); ac.addObjects( {label: "News"}, {label: "Sports"}, {label: "Weather"} ); */ addObjects: { value: function() { var objects = Array.prototype.slice.call(arguments), i, objectCount = objects.length, selectedContentIndexes, firstIndex; for (i = 0; i < objectCount; i++) { this.content.push(objects[i]); } if (this.selectObjectsOnAddition) { selectedContentIndexes = []; firstIndex = this.content.length-objectCount; for (i = 0; i < objectCount; i++) { selectedContentIndexes[i] = firstIndex++; } this.selectedContentIndexes = selectedContentIndexes; this.selectedObjects = objects; } if (this.clearFilterFunctionOnAddition) { this.filterFunction = null; } if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } }, /** Removes the currently selected item or items in the collection. @function */ remove: { value: function() { if (this.selectedObjects && this.selectedObjects.length > 0) { this.removeObjects.apply(this, this.selectedObjects); if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } // TODO what do we want to do otherwise? } }, /** Removes the specified object or objects from the collection. @function */ removeObjects: { value: function() { var objectsToRemove = Array.prototype.slice.call(arguments), remainingObjects; // TODO what do we do if there are no arguments? (should this be where we solve the problem of calling remove with no selection?) remainingObjects = this.content.filter(function(value) { return objectsToRemove.indexOf(value) < 0; }); this.content = remainingObjects; //TODO abandon selection? preserve what we can of the selection? if (this.automaticallyOrganizeObjects) { this.organizeObjects(); } } } });