ElementCollection (class)

04Jul2011 0 Comments Categories:Elements

Overview

Summary

The ElementCollection class is designed to group and manipulate elements on the Flash stage.

It is a subclass of the Collection class, background information about which can be found in the Introduction to Collections article.

Contents

Usage

The ElementCollection class expects an array of stage elements as its only parameter, so is nearly always used in conjunction with the Element Selector function (although you can of course pass in elements manually). This allows you to abstract fairly complex selections into an easy-to-manage expressions.

The following example creates an ElementCollection using standard dom properties:

var collection = new ElementCollection(dom.selection);
collection.list();
[object ElementCollection length=5]: Array (depth:1, objects:0, values:12, time:0.0 seconds)
--------------------------------------------------------------------------------------------
array => Array
	 0: "Item_12"
	 1: "Item_13"
	 2: "Item_14"
	 3: "Item_15"
	 4: "Item_16"

The following example uses the Element Selector function to grab the current stage selection:

var collection = $(':selection');
collection.list();
[object ElementCollection length=5]: Array (depth:1, objects:0, values:12, time:0.0 seconds)
--------------------------------------------------------------------------------------------
array => Array
	 0: "Item_12"
	 1: "Item_13"
	 2: "Item_14"
	 3: "Item_15"
	 4: "Item_16"

Note that a collection does not select the items on the stage - it merely holds a reference to them. To physically select items on the stage, see the select() method.

ElementCollection extends Collection

One last note - remember that ElementCollection extends Collection, so you still get to use all the methods on the Collection class, including each(), which is a very powerful method for applying custom manipulation to collection elements:

See the example in Working with Elements for more infomation.

Running the example code

If you want some elements to to quickly test the example code on this page, run the following code which will create some transparent red squares on the Flash stage:

function makeSquares(num, cols)
{
	// variables
		num = num || 9;
		cols = cols || 3;
		var dom = window.dom;
		var lib = dom.library;
		var context = Context.create();
		
	// make square
		if( ! lib.itemExists('square'))
		{
			lib.addNewItem('movie clip', 'square');
			lib.editItem('square');
			dom.addNewRectangle({left:-25, top:-25, right:25, bottom:25}, 0);
			dom.selectAll();
			dom.setFillColor('#FF000066');
			dom.setStroke('#000000', 0.5, 'solid')
			context.goto();
		}
		
	// add items to scene
		var collection = $('*');
		for(var i = 0; i < num; i++)
		{
			var x = i % cols;
			var y = (i - x) / cols;
			var name = 'Item_' + xjsfl.utils.pad(i + 1, '0', 2);
			if( ! collection.find(name))
			{
				lib.addItemToDocument({x:(x * 50) + 50, y:(y * 50) + 50}, 'square');
				dom.selection[0].name = name;
			}
		}
		dom.selectNone();
}

makeSquares();

API

ElementCollection(elements)

ElementCollection class enacpsulates and modifies Arrays of stage Elements

Parameters:

  • name String The property name
  • value Object The property value. Can be any valid value, or a callback of = function the form fn(e,i){} that returns a value

Returns:

  •   Collection The original ElementCollection object

The following example grabs all items on the stage:

var collection = $('*');
collection.list();
[object ElementCollection length=10]: Array (depth:1, objects:0, values:10, time:0.0 seconds)
---------------------------------------------------------------------------------------------
array => Array
	 0: "Item_01"
	 1: "Item_02"
	 2: "Item_03"
	 3: "Item_04"
	 4: "Item_05"
	 5: "Item_06"
	 6: "Item_07"
	 7: "Item_08"
	 8: "Item_09"
	 9: "Item_10"

find(element)

Finds a single element or groups of elements within the collection

Parameters:

  • element Number The index of the element to find
  • element String The name of the element to find
  • element RegExp A RegExp to match against the names of the elements (plural) to find

Returns:

  •   Element A single element
  •   Array An array of elements (only if a RegExp is supplied)

Sometimes when writing new collection methods, or even in your own callbacks, you need to reference a particular item in the collection. The find() method allows you to enter a variety of parameters to return either a single, or an Array of elements

The following example :

var collection = $('*');
var element = collection find('Item_05');

dom.selection = [element];

select(element)

Select one or all of the elements within the collection

Parameters:

  • element Boolean An optional true flag to select all elements (the default)
  • element Number An optional index of the element to select
  • element String An optional name of the element to select
  • element Element An optional reference to the element to select

Returns:

  •   ElementCollection The original ElementCollection object

The following example selects all (unlocked) items on the stage:

$('*').select();

The following example selects the item named "Item_03" in the collection:

$('*').select('Item_05');

The following example selects each of the items in turn, and alerts its progress:

function select(element, index)
{
	this.select(index);
	alert('Selected ' + element.name)
}
$('*').each(select);

move(x, y, relative)

Move the collection on stage by, or to, x and y values

Parameters:

  • x Number The x pixel value to move to, or by
  • y Number The y pixel value to move to, or by
  • relative Boolean An optional flag to move the elements relative to their current position, defaults to false

Returns:

  •   ElementCollection The original ElementCollection object

The following example moves all elements of the collection, as a whole unit, to the top-left hand corner of the stage, with the bounding box of the collection aligned to the [0,0] point:

$('*').move(0, 0);

duplicate(add)

Duplicates and updates the current collection

Parameters:

  • add Boolean An optional flag to add (rather then replace) the duplicated items to the current collection, defaults to false

Returns:

  •   ElementCollection The original ElementCollection object

The following example creates some squares, then chains up duplicate and move commands to create an array of elements:

makeSquares(5, 5);

$('*')
	.space('horizontal', 10)
	.move(10, 10)
	.duplicate()
	.move(0, 60, true)
	.duplicate()
	.move(0, 60, true)

Note that new items are automatically renamed from their existing names and numbers. In the above example, the newly-duplicated items were labeled based on from the highest-numbered item in the previous element, Item_05, creating Item_06 through to Item_15.

deleteElements()

Removes all elements from the collection and the stage

Returns:

  •   ElementCollection The original ElementCollection object

The following example deletes the selected elements:

$(':selected').deleteElements();

attr(name, value)

Sets a single property on each element in the collection

Parameters:

  • prop Object A hash of valid name:value properties
  • prop String The name of the property to modify
  • value Value A valid property value
  • value Array An array of property values
  • value Object An Object of x, y property values
  • value Function A callback function of the format function(element, index, elements), that returns a value

Returns:

  •   ElementCollection The original ElementCollection object

The attr() method is identical to the Collection attr() method with the subtle difference that it supports the following compound pseudo-properties:

  • position [x, y] x and y in stage coordinatesy
  • scale [scaleX, scaleY] Pass in a single number to set scale for both axis
  • size [width, height] Sets the width and height in stage (not element) space, so will skew the object if rotated

You can supply either a single Number to copy the value to both components (ie, scaleX and scaleY), and Array of 2 values, or an object with x and y properties.

Note that attr() does not yet handle alpha, tint, or brightness, but will do at some point.

The following example sets the rotation property of all objects:

$('*').attr('rotation', 30);

The following example sets the x and y scale of all the objects:

$('*').attr('scale', [1, 0.5]);

The following 2 examples update 2 properties at the same time, as well as using a callback, to set a random position on the collection's elements:

function rand(){ return Math.random() * 200 - 100; } // function is called twice
$('*').attr({x:rand, y:rand});	
function rand(){ return [Math.random() * 200, Math.random() * 200]; } // function passes back a 2-element array
$('*').attr('position', rand);

This example sets the scale of an object using a compound property name (scale) but passes back only a single value, which is set for both components (scaleX & scaleY):

function rand(){ return Math.random() + 0.5; }

$('*').attr('scale', rand);


rename(baseName, startIndex, padding, separator)

Numerically renames elements in order

Parameters:

  • baseName Function A callback of the format function(item, index, items, originalName) which should return a String name

  • baseName String A single "name_###" name/number pattern string

  • baseName String The basename for your objects
  • padding Number An optional padding length for the numeric part of the name
  • padding Boolean An optional flag to automatically pad the numeric part of the name to the correct length
  • startIndex Number An optional number to start renaming from. Defaults to 1
  • separator String An optional separator between the numeric part of the name. Defaults to '_'

Returns:

  •   ItemCollection The original ItemCollection

The following example performs a default rename, renaming all items on the stage from the starting index "1" padding as necessary:

$('*')
	.rename()
	.list();
[object ElementCollection length=10]: Array (depth:1, objects:0, values:10, time:0.0 seconds)
---------------------------------------------------------------------------------------------
array => Array
	 0: "Item_01"
	 1: "Item_02"
	 2: "Item_03"
	 3: "Item_04"
	 4: "Item_05"
	 5: "Item_06"
	 6: "Item_07"
	 7: "Item_08"
	 8: "Item_09"
	 9: "Item_10"

The following examples demonstrate various renaming techniques:

var items = $(':selection');

items.rename();              // rename using defaults, "clip_1", "clip_2", "clip_3" ...
items.rename('clip_##');     // rename, starting from 1, padding to 2 characters, "clip_01", "clip_02", "clip_03" ...
items.rename('clip_025');    // rename, starting from 25, padding to 3 characters, "clip_025", "clip_026", "clip_027" ...
items.rename('clip', 4, 25); // rename, starting from 25, padding to 4 characters, "clip_0025", "clip_0026", "clip_0027" ...

The following example uses a callback to rename any symbols on stage with their class name: 

$$(':symbol').rename( function(element){ return element.libraryItem.linkageClassName.split('.').pop(); } );

orderBy(prop, reverseOrder)

Reorder the elements on the stage (front-to-back) by an arbitrary property

Parameters:

  • prop String The property to compare
  • reverseOrder Boolean Optionally arrange in reverse order

Returns:

  •   ElementCollection The original ElementCollection object

The following example positions, scales, then orders elements in reverse order by size, a pseudo-property derived from width x height (note that orderBy() also reorders the elements within the internal Array, which will affect subsequent operations):

$('*')
	.resetTransform()
	.attr('pos', 125)
	.attr('scale', function(element, index, elements){ return index / elements.length * 5; })
    .orderBy('size', true);

align(props)

Align elements to one another

Parameters:

  • props String The specific arguments for the arrange type. Acceptable values are 'left,right,top,bottom,top left,top right,bottom left,bottom right,vertical,horizontal,center'

Returns:

  •   ElementCollection The original ElementCollection object

The align() method repackages the native Flash align functionaliity, with a slightly different parameter syntax. Note that align() will soon support aligning to objects, similar to match();

The following example creates and scales some :

$('*')
	.resetTransform()
	.randomize({'pos':300, scale:2, rotation:360})
	.align('top')


distribute(props, toStage)

Distribute elements relative to one another

Parameters:

  • props String 1 or 2 of 'left,horizontal,right,top,vertical,bottom'
  • toStage Boolean Use the stage bounding box

Returns:

  •   ElementCollection The original ElementCollection object

The distribute() method repackages the native Flash distribute functionaliity, with a slightly different parameter syntax.

The following example positions, randomizes, then distributes elements horizontally:

$('*')
	.attr('pos', 30)
	.randomize({x:400, width:[5, 40]})
	.attr('height', function(e){return e.width})
	.distribute('horizontal')


space(direction, type)

Space elements relative to one another

Parameters:

  • direction String The direction in which to space. Acceptable values are 'vertical,horizontal'
  • type Number An optional amount of space to add or subtract between items
  • type Boolean An optional flag to use the stage bounding box (only has an effect on the root)

Returns:

  •   ElementCollection The original ElementCollection object

The distribute() method repackages the native Flash space functionaliity, with a slightly different parameter syntax.

The following example positions, randomizes, then distributes elements horizontally in a few different ways:

$('*')
	.attr('pos', 30)
	.randomize({x:400, width:[5, 40]})
	.attr('height', function(e){return e.width})

	.space('horizontal')        // spaces according to the current collection bounds
	.space('horizontal', 0)     // spaces left-to-right, with a 0px gutter
	.space('horizontal', true); // spaces to the document bounds (only effective on the root)


match(prop, element)

match elements' dimensions relative to one another

Parameters:

  • props String The dimension in which to match. Acceptable values are'width,height,size'
  • element Boolean An optional flag (true=biggest, false=smallest) of the element whose dimension(s) you want to match. Defaults to true
  • element Number An optional index of the element whose dimension(s) you want to match
  • element String An optional name of the element whose dimension(s) you want to match
  • element Element An optional reference to an element (which doesn't need to be in the collection) whose dimension(s) you want to match

Returns:

  •   ElementCollection The original ElementCollection object

The match() method adds to JSFL's native match functionality by allowing you to choose how element sizes are matched, with a slightly different syntax from the native method.

The following example applies the default match (equivilent to passing true as the 2nd parameter) which is to match to the largest size:

$('*')
	.randomize('rotation', 360)
	.match('size', 0)

The following example chooses another element within the collection to match the height to:

$(squares)
	.randomize({size:50, y:'20'})
	.match('height', circle);


toGrid(precision, rounding)

Repositions element positions to round multiples of numbers

Parameters:

  • precision Number The pixel-precision to reposition to, e.g. 0
  • precision Array The pixel-precision to reposition to, e.g. [10, 20]
  • rounding Number Round down(-1), nearest(0), or up(1). Defaults to nearest(0)

Returns:

  •   ElementCollection The original ElementCollection object

The following example aligns all elements to the grid:

$('*').toGrid(0);

The following example creates some squares, randomizes them, then snaps them to the nearest 25 pixels:

makeSquares(3 * 6, 6);
$('*')
	.randomize({pos:25})
	.toGrid(25);

The following example uses the Iterators class to align all elements in all library items, across all layers and frames, to the closest pixel:

function alignElements(frame, index, frames, context)
{
	trace('Aliging elements in: ' + context);
	$('*').toGrid(0);
}
Iterators.items(true, null, null, alignElements);
Aliging elements in: [object Context dom="library items 02.fla" timeline="Button 2" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="Button 3" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="MovieClip 1" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="MovieClip 1" layer[0]="Layer 1" keyframe[1]=3]
Aliging elements in: [object Context dom="library items 02.fla" timeline="MovieClip 1" layer[0]="Layer 1" keyframe[2]=8]
Aliging elements in: [object Context dom="library items 02.fla" timeline="MovieClip 1" layer[1]="Layer 2" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="MovieClip 1" layer[2]="Layer 3" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="MovieClip 1" layer[2]="Layer 3" keyframe[1]=3]
Aliging elements in: [object Context dom="library items 02.fla" timeline="Sprite 1" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="Button 1" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="Graphic 1" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="Graphic 2" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="Sprite 2" layer[0]="Layer 1" keyframe[0]=0]
Aliging elements in: [object Context dom="library items 02.fla" timeline="MovieClip 3" layer[0]="Layer 1" keyframe[0]=0]

randomize(prop, value)

Randomizes properties of the elements

Parameters:

  • prop Object An object containing property name:value pairs
  • prop String A valid String property. Acceptable values are: x, y, width, height, rotation, scaleX, scaleY, transformX, transformY, skewX, skewY, position, scale, size. Note that position, scale and size should be arrays
  • value Number A multiplier value, i.e. 10
  • value String A valid modifier property, i.e. "+20%"
  • value Array A valid modifier range, i.e. [100, 200]

Returns:

  •   ElementCollection The original ElementCollection object

The randomize() method allows you to randomize the properies of elements by passing numbers, expressions, and ranges as the methods's 2nd argument (see xjsfl.utils.randomizeValue() for more information):

  • Numeric 25 0 - 25 more than the original value
  • Expression "25" 0 - 25 on either side of the original value
  • Percentage "+25%" 100% - 125% of the original value
  • Range [25, 50] Anywhere between 25 - 50
You may also pass in a single Object of property:value pairs, to update multiple properties at once. Note that randomize() does not yet support pseudo properties such as tint, brightness and color.

The following example creates some elements, then randomizes various properties using a variety of techniques:

makeSquares(3 * 6, 6);
$('*')
	.attr('x', function(e){ return e.x * 2; })
	.randomize({
		pos:100,
		size:[60, 10],
		rotation:'180',
		scale:'150%'
	});

resetTransform()

Resets the transform of the elements

Returns:

  •   ElementCollection The original ElementCollection object

The following example rotates the stage elements, then after the alert, clears the transformation:

$('*')
	.attr('rotation', 45)
	.call(alert, 'Click OK to reset transform')
	.resetTransform();

refresh()

Forces the a refreshes of the display after a series of operations

Returns:

  •   ElementCollection The original ElementCollection object

Sometimes after a series of element updates, the stage doesn't update. The refresh() method forces an update.

The following example refreshes the stage after a hypothetical operation that leaves the stage in an invalid state:

$('*')
	.each(someOperation)
	.refresh();

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

© Copyright - xJSFL - Theme Design by Kriesi.at