Context (class)
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
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
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
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)
- setTimeline(value)
- setLayer(value)
- setFrame(value)
- setKeyframe(keyframeIndex, layer)
- update(dom, timeline, layer, frame, element)
setDOM(value)
Set the DOM of the Context object
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
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
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
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
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
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
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
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
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
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
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();
Comments are closed.