Context (class)

Categories:Flash

Overview

Summary

The Context class provides convenient access to the major DOM elements, and serves to replace cumbersome fl.getDocumentDOM() calls, as well as all related code regarding timelines, layers, frames, etc.

Contents

Note that Context is currently in flux, and some of the intended functionality is (unfortunately) still buggy

Usage

Context objects hold the following properties by default:

  • document
  • timeline
  • layer
  • keyframes
  • frame

Thus in xJSFL terms, "context" will always refer a location in the Flash IDE with regards to these properties.

The simplest usage of context is via Context.create(),a static method which returns a Context instance referring to the user's current location in the document:

var context = Context.create();
trace(context);
[object Context dom="Untitled-1" timeline="Symbol 1" layer[2]="Layer 1" keyframe[1]=2]	

This is in direct contrast to writing JSFL boilerplate code, such as:

var doc = fl.getDocumentDOM();
if(doc)
{
    var timeline  = dom.getTimeline();
    var layer     = timeline.layers[timeline.currentLayer];
    var frame     = layer.frames[timeline.currentFrame];
    // code for getting layer keyframes not included
}

As you can see, the Context instance is fully inspectable, gathering all the major DOM elements in one place:

Output.inspect(context, {'function':false, 'string':false, 'number':false}, 1);	
Inspect: Context (depth:1, objects:6, values:5, time:0.0 seconds)
--------------------------------------------------------------------------------
object => Context
    [dom] => Document
    [timeline] => Timeline
    [item] => SymbolItem
    [layer] => Layer
    [keyframes] => Array
    [frame] => Frame

The properties on the Context instance can then be accessed directly, or manipulated using Context-specific methods as needed:

context.dom.path
context.frame.elements;
context.selectFrames();
context.goto();

Context instances can also be passed around, updated, cloned, set, got, navigated-to, (and soon, serialized and deserialized) making them an extremely powerful tool for manipulating and traversing the Flash IDE.

Note that for reasons of simplicity, Context objects do not yet support multiple layer or frame selections. For multiple selections, you can simply use the standard Flash methods:

var layers = context.timeline.getSelectedLayers();
var frames = context.timeline.getSelectedFrames();

Instantiation

Context(dom, timeline, layer, frame, element)

Context object provides convenient access to the major DOM elements

Parameters:

  • dom Context A Context object with a valid dom property
  • dom Boolean Pass true to grab the current Document DOM
  • dom Number The 0-based index of the Document
  • dom String The name of the Document
  • dom File A valid .fla file
  • dom Document A Document
  • timeline Context A Context object with a valid timeline property
  • timeline Boolean Pass true to grab the current timeline
  • timeline String The name of (path to) an item in the library
  • timeline Number The 0-based index of an item in the library
  • timeline SymbolInstance A Symbol Instance
  • timeline SymbolItem A SymbolItem
  • timeline Timeline A Symbol Item's timeline reference
  • layer Context A Context object with a valid layer property
  • layer Boolean Pass true to grab the current layer
  • layer String The name of the layer
  • layer Number The 0-based index of the layer
  • layer Layer A Layer
  • frame Context A Context object with a valid frame property
  • frame Boolean Pass true to grab the current frame
  • frame String The name of the frame
  • frame Number The 0-based index of the frame
  • frame RegExp The keyframe index of the frame, i.e. /2/
  • frame Frame A Frame

The first thing you'll notice about the Context constructor is that it can take a huge variety of instantiation parameters. All Context methods are extremely flexible, allowing you to pass in Booleans, indices, names, objects or even other Context instances from which to grab related properties.

Also, all constructor parameters are optional, the default being to snapshot the current state of the Flash IDE, as the following example shows:

var context = new Context();
trace(context);
[object Context dom="Untitled-1" timeline="Scene 1" layer[0]="Layer 1" keyframe[0]=0]

The following example creates a new Context instance, but with a saved document, in a movieclip with multiple layers and frames. Note the layer index/layer name and keyframe index/frame index:

var context = new Context();
trace(context);
[object Context dom="Measurements 09.fla" timeline="instructions" layer[13]="controls" keyframe[2]=5]

The following example creates a new Context instance, but explicitly specifies the parameters, in this case, another open document:

var context = new Context('game level 01', 'bridge', 0, 0);
[object Context dom="game level 01" timeline="bridge" layer[0]="Layer 1" keyframe[0]=0]

create(dom, timeline, layer, frame)

Factory method provides the quickest way to get the current context

Parameters:

  • dom Boolean An optional flag to not create a dom context
  • timeline Boolean An optional flag to not create a timeline context
  • layer Boolean An optional flag to not create a layer context
  • frame Boolean An optional flag to not create a frame context

Returns:

  •   Context A new Context instance

Context.create() is a static method on the Context class that allows for chaining, and is the easiest way to create a Context in everyday development. The following example creates a Context instance the immediately selects the current layer:

var context = Context
    .create()
    .selectLayer();

Properties

The properties in this section are available on any Context instance, assuming that they have been set.

The following examples assume the existence of a context instance like so:

var context = Context.create();

dom

A Document object

The dom property of a Context instance is an actual Document object, on which you can access properties and methods:

context.dom.frameRate = 25;
context.dom.arrange('forward');
context.dom.convertLinesToFills();

item

A Library Item instance

The item property of a Context instance is the Library Item object associated with the Context's timeline, on which you can access properties and methods:

context.item.name;
context.item.itemType = 'graphic';
context.item.item.addData('data', 'string', 'Some data...')

timeline

A Timeline object

The timeline property of a Context instance is an actual Timeline object, on which you can access properties and methods:

context.timeline.frameCount;
context.timeline.copyMotion();
context.timeline.pasteMotion(); 

layer

A Layer object

The layer property of a Context instance is a single Layer object, on which you can access properties and methods:

context.layer.frameCount;
context.layer.name = 'Animation';
context.layer.locked = false;

layerIndex

The current layer's index

The layerIndex property of a Context instance is the index of the Context's current Layer in its parent timeline:

trace(context.layerIndex);
3

frame

A Frame object

The frame property of a Context instance is a single Frame object on the Context's current layer, on which you can access properties and methods:

context.frame.actionScript;
context.frame.soundName = "assets/sounds/laser.mp3";
context.frame.getCustomEase("position");

keyframes

An Array of Frame objects

The keyframes property of a Context instance is a special getter property, that returns an Array of the Context's current layer's keyframe objects:

trace('frames: ' + context.layer.frames.length);
trace('keyframes: ' + context.keyframes);
frames: 50
keyframes: [object Frame],[object Frame],[object Frame],[object Frame],[object Frame]

context

A String representing the internal context of the Context object

When creating a Context instance, or updating the existing properties of a Context instance, a property called context keeps track of the last operation:

context.setFrame(0);
trace(context.context);
frame

Set / update methods

The following methods update the current state of the Context object without needing to create a new one.

setDOM(value)

Set the DOM of the Context object

Parameters:

  • value Context A Context object with a valid dom property
  • value Boolean Pass true to grab the current Document DOM
  • value Number The 0-based index of an open Document
  • value String The name of an open Document, or path or URI to an existing .fla
  • value File An existing .fla file
  • value Document A Document

The following example updates the dom of the current Context object using another open document's name:

context.setDOM('some other document');

setTimeline(value)

Set the Timeline of the Context object

Parameters:

  • value Context A Context object with a valid timeline property
  • value Boolean Pass true to grab the current timeline
  • value String The name of (path to) an item in the library
  • value Number The 0-based Scene index
  • value SymbolItem A SymbolItem
  • value SymbolInstance A Symbol Instance
  • value Timeline A Symbol's timeline reference
  • value null The document root

The following example updates the timeline of the current Context object using the current timeline:

context.setTimeline(true);	

setLayer(value)

Set the Layer of the Context object

Parameters:

  • value Context A Context object with a valid layer property
  • value Boolean Pass true to grab the current layer
  • value String The name of the layer
  • value Number The 0-based index of the layer
  • value Layer A Layer

The following example updates the layer of the current Context object using a layer index:

context.setLayer(2);	

setFrame(value)

Set the Frame of the Context object

Parameters:

  • value Context A Context object with a valid frame property
  • value Boolean Pass true to grab the current frame
  • value String The name of the frame
  • value Number The 0-based index of the frame
  • value RegExp A numeric RegExp indicating the keyframe index, i.e. /2/
  • value Frame A Frame

The following example updates the frame and layer of the current Context object using a frame label:

context.setFrame('end');		

The following example updates the frame of the current Context object by indicating the 2nd keyframe on the current layer, using a numeric Regular Expression:

context.setFrame(/2/);

setKeyframe(keyframeIndex, layer)

Set the Keyframe of the Context object

Parameters:

  • keyframeIndex Number The 0-based index of the keyframe you want to target (i.e. passing 1 would select the 2nd keyframe, which might be on frame 12)
  • layer Context A Context object with a valid layer property
  • layer Boolean Pass true to grab the current layer
  • layer String The name of the layer
  • layer Number The 0-based index of the layer
  • layer Layer A Layer

The following example updates the frame of the current Context object using a keyframe index (note that the layer parameter is optional):

setKeyframe(4);	

update(dom, timeline, layer, frame, element)

Updates all parameters of the Context Object with the current IDE state

Parameters:

  • dom Boolean An optional flag to not update the dom context
  • timeline Boolean An optional flag to not update the timeline context
  • layer Boolean An optional flag to not update the layer context
  • frame Boolean An optional flag to not update the frame context
  • element Boolean An optional flag to not update the element context

Returns:

  •   Context Itself

The following example updates the dom, timeline and layer only, of the current Context object:

context.update(true, true, true, false, false);
trace(context);
[object Context dom="Measurements 09.fla" timeline="instructions" layer[12]="text" keyframe[3]=5]	

Manipulation methods

The following methods provide ways to interact with the Contexts you'll create.

goto()

Updates the document focus, timeline, layer, frame and playhead to the current context

Returns:

  •   Context Itself

The following example sets a context then goes to it:

// create a context
    var context = Context.create();
    var item = context.dom.library.addNewItem('movie clip');
    context.dom.library.editItem();

// swap documents
    fl.createDocument();

// go back to old context
	alert('Swapping back to original context...');
    context.goto();		

select()

Select the current context of the Context object

Returns:

  •   Context Itself

Whenever you call a set or update operation, the Context instance makes a reference internally as to what was updated, i.e. document, timeline, layer, or frame. Subsequently calling a select() will attempt to select (using the Flash UI) at least the layer, frame or keyframe that was just updated:

The following example creates a Context, sets the keyframe, and selects it in one line of code:

Context.create()
    .setKeyframe(4, 'Animation')
    .select();		

selectLayer(addToSelection)

Explicitly select the current Layer of the Context object

Parameters:

  • addToSelection Boolean An optional Boolean to add to, rather than replace the current layer selection

Returns:

  •   Context Itself

The following example sets 2 layers and explicitly selects them in the Flash UI:

Context
    .create()
    .selectLayer()
    .setLayer(0)
    .selectLayer(true);		

selectFrame(addToSelection)

Select the current Frame of the Context object

Parameters:

  • addToSelection Boolean An optional Boolean to add to, rather than replace the current frame selection

Returns:

  •   Context Itself

The following example selects two keyframes on the timeline, then reverses them using standard JSFL:

var context = Context
    .create()
    .setKeyframe(0)
    .selectFrame()
    .setKeyframe(1)
    .selectFrame(true);
	
context.timeline.reverseFrames();

Utility methods

clone()

Returns a copy of the Context object

Returns:

  •   Context A new Context instance

There are times when you might want to work on a copy of a Context, rather than the original Context; perhaps you want to pass separate instances into different functions.

The following example demonstrates cloning an original Context instance, then selecting the frames of each one independently:

var context1 = Context
    .create()
    .setKeyframe(0);
	
var context2 = context1
	.clone()
    .setKeyframe(1);
	
dom.selectNone();

alert("Selecting Context 1's frame...");
context1.selectFrame();
	
alert("Selecting Context 2's frame...");
context2.selectFrame();		

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>