MovieClipHelper.js

define(
    [
        'easeljs',
        'CatLab/Easelbone/EaselJS/DisplayObjects/Placeholder',
        'CatLab/Easelbone/Utilities/Deferred'
    ],
    function(
        createjs,
        Placeholder,
        Deferred
    ) {
        "use strict";

        var MovieClipHelper = function() {

        };

        var p = MovieClipHelper.prototype;

        /**
         * Find elements by name and turn them into placeholders.
         * Returns an array with all placeholders.
         * @param {string|array} name
         * @param container
         * @returns {Array}
         */
        p.findPlaceholders = function (name, container) {
            var out = [];
            var placeholders = this.findFromNames(name, container);

            placeholders.forEach(function (element) {
                out.push(new Placeholder(element));
            });
            return out;
        };

        /**
         * Find all named elements (generated by adobe animate) in the container
         * or its children (for named elements), with dot notation support and fallback
         * to deprecated/alternative names when providing an array.
         * @param {string|Array} names
         * @param containers
         * @param {{ all: boolean }} options
         * @returns {Array}
         */
		p.findFromNames = function (names, containers, options) {

			if (!Array.isArray(containers)) {
				containers = [containers];
			}

			if (!Array.isArray(names)) {
				names = [names];
			}

			var results = [];
			var name;
			var nameParts;
			var rootName;

			// Loop through the names and return the first resultset with matches
			for (var i = 0; i < names.length; i ++) {

				name = names[i];

				// Check for dot notation
				nameParts = name.split('.');
				rootName = nameParts.shift();

				// Go through all containers
				containers.forEach(function (container) {
					results = results.concat(this.findFromNameInContainer(container, rootName, options));

					// Do we need to go further down the rabbithole?
					if (nameParts.length > 0) {
						results = this.findFromNames(nameParts.join('.'), results);
					}
				}.bind(this));

				if (results.length > 0) {
					return results;
				}
			}

			return results;
		};

		p.buildNamedChildMap = function(container) {

			if (typeof(container._mh_named_children_map) !== 'undefined') {
				return;
			}

			// Create a map of named children.
			// This is a simple 1-dimensional map: name -> child.
			container._mh_named_children_map = {};

			// Create a deep map of all descendants by name for O(1) lookups.
			// This is a 1-dimensional map: name -> [child, child, ...]
			container._mh_deep_named_children_map = {};

			// Create a map of timeline labels.
			// This is a 2-dimensional map: label -> [child, child, ...]
			// A label can have multiple children; grandchildren are included as well
			container._mh_timeline_label_map = {};

			// Generate the timeline labels for this child.
			if (container.timeline) {
				var labels = container.timeline.getLabels();
				for (var i = 0; i < labels.length; i++) {
					if (typeof(container._mh_timeline_label_map[labels[i].label]) === 'undefined') {
						container._mh_timeline_label_map[labels[i].label] = [];
					}
					container._mh_timeline_label_map[labels[i].label].push(container);
				}
			}

			this.forEachNamedChild(container, function(child, name) {
				container._mh_named_children_map[name] = child;

				// Generate the map recursively.
				this.buildNamedChildMap(child);

				// Copy the timeline labels to the container.
				for (var k in child._mh_timeline_label_map) {
					if (child._mh_timeline_label_map.hasOwnProperty(k)) {
						if (typeof(container._mh_timeline_label_map[k]) === 'undefined') {
							container._mh_timeline_label_map[k] = [];
						}
						container._mh_timeline_label_map[k] = container._mh_timeline_label_map[k].concat(child._mh_timeline_label_map[k]);
					}
				}

				// Build the deep map: add this child under its own name
				if (typeof(container._mh_deep_named_children_map[name]) === 'undefined') {
					container._mh_deep_named_children_map[name] = [];
				}
				container._mh_deep_named_children_map[name].push(child);

				// Merge child's deep map into container's deep map
				for (var dk in child._mh_deep_named_children_map) {
					if (child._mh_deep_named_children_map.hasOwnProperty(dk)) {
						if (typeof(container._mh_deep_named_children_map[dk]) === 'undefined') {
							container._mh_deep_named_children_map[dk] = [];
						}
						container._mh_deep_named_children_map[dk] = container._mh_deep_named_children_map[dk].concat(child._mh_deep_named_children_map[dk]);
					}
				}

			}.bind(this));

		}

        /**
         * Find all named elements (generated by adobe animate) in the container
         * and all child named elements and return them.
         * @param container
         * @param name
         * @param {{ all: boolean }} options
         * @param results
         * @returns {Array}
         */
        p.findFromNameInContainer = function (container, name, options, results) {

            if (typeof (results) === 'undefined') {
                results = [];
            }

            if (typeof (options) === 'undefined') {
                options = {};
            }

			// Cache a container map for faster lookups.
			this.buildNamedChildMap(container);

			// Direct child lookup (O(1))
			if (typeof(container._mh_named_children_map[name]) !== 'undefined') {
				results.push(container._mh_named_children_map[name]);
			}

			// Deep lookup using pre-built map instead of recursive search
            if (results.length === 0 || options.all) {
				if (container._mh_deep_named_children_map && container._mh_deep_named_children_map[name]) {
					var deepResults = container._mh_deep_named_children_map[name];
					for (var i = 0; i < deepResults.length; i++) {
						// Avoid duplicates from direct child lookup
						if (results.indexOf(deepResults[i]) === -1) {
							results.push(deepResults[i]);
						}
					}
				}
            }

            return results;
        };

        /**
         * Loop through all named children
         * @param container
         * @param callback
         */
        p.forEachNamedChild = function(container, callback)
        {
            // Look for named properties (defined by adobe animate)
            for (var key in container) {

                if (!container.hasOwnProperty(key)) {
                    continue;
                }

                switch (key) {
                    case 'parent':
                    case 'mask':
                        continue;
                }

                if (
					container[key] instanceof createjs.DisplayObject &&
					!(container[key] instanceof createjs.Shape)
				) {
                    if (callback(container[key], key, container) === false) {
                        return;
                    }
                }
            }
        };

        p.forAllNamedChildren = function(container, callback, level)
        {
			if (typeof(level) === 'undefined') {
				level = 0;
			}

            this.forEachNamedChild(container, function(child, name) {

                callback(child, name, container, level);
                this.forAllNamedChildren(child, callback, level + 1);

            }.bind(this));
        };

        /**
         * Apply spritesheet filters and cache their result
         * @param filters
         * @param container
         */
        p.applySpriteFilters = function(filters, container)
        {
            this.forAllNamedChildren(container, function(child, name, parent) {

                if (!(child instanceof createjs.Sprite)) {
                    return;
                }

                var bounds = child.getBounds();
                child.filters = filters;
                child.cache(0, 0, bounds.width, bounds.height);

            }.bind(this));
        };

        /**
         * @param container
         * @param label
         * @returns {boolean}
         */
		p.hasLabeledFrame = function(label, container) {
			// Ensure the map is built
			this.buildNamedChildMap(container);

			// Fast lookup using the cached map
			if (
				container._mh_timeline_label_map &&
				container._mh_timeline_label_map[label] &&
				container._mh_timeline_label_map[label].length > 0
			) {
				return true;
			}

			return false;
		};

        p.pause  = function(container)
        {
            if (container.timeline) {
                container.timeline._was_paused = container.timeline.paused;
                container.timeline.paused = true;
            }

            this.forEachNamedChild(container, function(child) {
                this.pause(child);
            }.bind(this));
        };

        p.resume = function(container)
        {
            if (container.timeline) {
                container.timeline.paused = container.timeline._was_paused;
                delete container.timeline._was_paused;
            }

            this.forEachNamedChild(container, function(child) {
                this.resume(child);
            }.bind(this));
        }

		/**
		 * @param container
		 * @param label
		 * @returns {number}
		 */
		p.countLabeledFrames = function(label, container) {
			// Ensure the map is built
			this.buildNamedChildMap(container);

			var count = 0;
			if (container._mh_timeline_label_map && container._mh_timeline_label_map[label]) {
				count += container._mh_timeline_label_map[label].length;
			}

			return count;
		};

        /**
         * @param label
         * @param container
         */
        p.jumpToFrame = function(label, container)
        {
            var promises = [];

			if (
				container._mh_timeline_label_map &&
				container._mh_timeline_label_map[label]
			) {
				container._mh_timeline_label_map[label].forEach(function(child) {
					promises.push(this._jumpToFrameUntilFinished(label, child));
				}.bind(this));
			}

            return Deferred.when.apply(this, promises);
        };

        /**
         * @param label
         * @param container
         * @returns {*}
         * @private
         */
        p._jumpToFrameUntilFinished = function(label, container)
        {
            // Don't jump to elements that are not visible.
            var state = new Deferred();
            if (container.parent) {
                container.gotoAndPlay(label);
                container.timeline.on('complete', function() {
                    state.resolve();
                });
            } else {
                state.resolve();
            }

            return state.promise();
        }

        /**
         * Attach helper methods to the createjs MovieClip prototype
         */
        p.attach = function(createjs) {
            var helper = this;

            var p = createjs.MovieClip.prototype;

            p.forEachNamedChild = function(callback) {
                return helper.forEachNamedChild(this, callback);
            };

            p.findNamedChildren = function(names) {
                return helper.findFromNames(names, this);
            };

            p.findPlaceholders = function(names) {
                return helper.findPlaceholders(names, this);
            };

            p.applySpriteFilters = function(filters) {
                return helper.applySpriteFilters(filters, this);
            };

            p.hasLabeledFrame = function(label) {
                return helper.hasLabeledFrame(label, this);
            };

            p.jumpToFrame = function(label) {
                return helper.jumpToFrame(label, this);
            };
        };

        return new MovieClipHelper();

    }
);