Intro to JSFL (JavaScript Flash)

[ LiB ]

JSFL is scripting language that runs only in the Flash authoring environment. Instead of addressing clips or buttons the way ActionScript does, JSFL can address the currently selected shape or timeline's layer. What's wild is that JSFL can then execute nearly any command that you would normally do while authoring. In this way, you can use JSFL to help you author an FLA.

It may seem daunting to jump into JSFL, but it's actually really easy to start. That's because nearly every move you make while authoring is being recorded in the History panel using JSFL! Check it out: Draw a few simple shapes in a movie, and then open your History panel, select a few rows, and then click the Copy to Clipboard button at the lower right of the panel (see Figure 13.6).

Figure 13.6. You can grab some killer JSFL by just copying it from the History panel.

Now, paste into the Actions panel. You'll see the exact steps you performed but written in pure JSFL. The way it records everything you do would be creepy if it weren't so cool. I should note there's no JSFL for complex bending operations like the pen tool.

So JSFL is cool. I find it interesting to study the data structures Macromedia developed to describe your moves. But just admiring JSFL only goes so far; you'll probably want to know how to make it run inside Flash. There are a few basic ways:

• As a command. The simplest way is to just run JSFL as a command accessible through the Commands menu (as we'll do next ).

• In a WindowSWF. You can write JSFL that gets executed by a SWF that runs as a custom panel (also called a WindowSWF).

• As a custom draw tool. Finally, you can also run JSFL as a drawing tool that you add via Edit, Customize Tool Panel.

• Externally. It's even possible to set up batch scripts to run on an unattended version of Flashalthough you need Flash Pro for that.

Before we go any further, I want to reiterate that JSFL does one thing: modifies Flash files. It can do anything you can do while authoring (such as open files, edit contents, import media, break apart images, export movies, and so on), but it only runs inside the Flash authoring environmentnot the browser.

Homemade Commands

You can take a few steps (that get recorded in the History panel), select them, and then save the steps as a command. Using the History panel's Save Selected Steps as a Command does the work of actually pasting the JSFL into a text file and saving it in your Configuration folder. From that point forward, you can select your homemade script from the Commands menu. Alternatively, you can just create a text file into which you paste the script and then select that file directly when selecting the menu Command, Run Command. That's the way it's done in the following exercise. It's just cleaner because while we're testing we don't want to manage a bunch of homemade commands.

The background for the following task is the fact that some artists don't like Flash's gray background. Often they'll draw a large fill with a rectangle removed in place of the stage. My script now does that automatically. The process I took to develop that script was as follows :

1. I cleared the History panel and drew a large shape.
   
   
2. Because I couldn't just select a rectangle in the middle of a shape, I clicked off the shape and dragged until I was on the shape, and then pressed Delete. Although this wasn't exactly what I was going to need, it was close enough to start making edits.
   
   
3. I selected the steps, clicked Copy Steps to Clipboard, and then pasted into a text file eventually saved as stageMask.jsfl (see Figure 13.7).
   
   

   Figure 13.7. Take the raw script for clearing a rectangle within a shape from the History panel into a text file.

   

   
   

All I needed to do was make sure the original rectangle was big enough to cover the stage and then the selection (to be cleared) had to be the exact size and location of the stage. Here is the next incarnation of my script:

 1 width=550; 2 height=400; 3 fl.getDocumentDOM().addNewRectangle({left:-500, top:-500, right:width+500, bottom:height+500}, 0); 4 fl.getDocumentDOM().selectNone(); 5 fl.getDocumentDOM().setSelectionRect({left:0, top:0, right:width, bottom:height}); 6 fl.getDocumentDOM().deleteSelection(); 

Notice how line 3 draws a rectangle that goes exactly 500 pixels past the edges of the stage by using a nice -500 as well as expressions such as width+500 . Then line 5 makes a selection the exact size of the stage (something, by the way, not possible to do manually). I tested it (by selecting Command, Run Command), and it worked pretty well!

To make it a bit more practical, I wanted the first two lines to dynamically adapt to whatever the current stage size was. It took about 30 seconds to find in the JSFL documentation that the stage has two properties ( width and height ). So lines 1 and 2 changed as follows:

 width=fl.getDocumentDOM().width; height=fl.getDocumentDOM().height; 

One last touch was another cool method I found in the JSFL docs setFillColor . So I added the following code to what I had:

 fl.getDocumentDOM().setFillColor("#000000"); 

At this point, you could keep improving on this command. For example, you can make it automatically insert a new layer and then lock it (whereas the current script just draws into the current layer). In addition, you could present the user with a dialog box where, perhaps, the user could select a color to use. Before you go that far, let me suggest that the easiest way to build a custom dialog box is to use Flash itself (as opposed to using XML to UI). The next section shows how you can use a SWF as the user interface to a commandjust as long as the SWF runs inside the Flash authoring environment.

WindowSWF Custom Panel

Making a custom SWF appear as in a panel (called a WindowSWF panel) is just a matter of publishing your movie to the configuration folder WindowSWF. Once installed, your SWF can be accessed from the menu Window, Other Panels.

These WindowSWFs have all kinds of uses (beyond triggering JSFL commands as we'll do in a minute). For example, the App Inspector used for maintaining Flash Communication Server apps in Chapter 8, "Foundation Communication Server," is just a WindowSWF. I've seen homemade WindowSWFs for anything from a tool to retrieve key codes ( Key.getCode()) to a color picker to help find nice color combinations. Anyway, to make your WindowSWF execute JSFL, you just trigger the function called MMExecute() .

To trigger some JSFL, you need to store the entire set of steps as a string and pass that string to MMExecute(theString) . For example, the following example flips upside down any item the user has selected. Just make a new movie ( somewhat small stage size, such as 200x200) put a button ( my_btn ) onstage and this code in the first frame:

 my_btn.onRelease = function() { var command="fl.getDocumentDOM().rotateSelection(180);"; MMExecute(command); }; 

Finally, publish this to your WindowSWF configuration folder. You won't even need to restart Flash if you chose the WindowSWF folder inside your user Configuration folder (as opposed to the First Run version). Pop open the SWF via Window, Other Panels, and test it out.

The only thing tricky about executing JSFL this way is that you need to format your code as a string. When you need quotation marks inside the string, remember how you can use single quotes or \" for literal quotes. Also, variables and expressions need to be concatenated to the string. To separate multiple lines of code in a more complex command, simply use semicolons. Just be sure you supply a single command for the MMExecute() method. These are the same sorts of issues encountered when building a getURL() string dynamically.

Other Uses for JSFL

Hopefully, you feel empowered rather than overwhelmed. In any event, I feel obligated to mention a couple other ways you can use JSFL. The biggie is as custom tools. If you haven't noticed, the menu Edit, Customize Tools Panel preference enables you to change and add additional tools (see Figure 13.8).

Figure 13.8. The new Customize Tool Panel dialog box supports tools written in JSFL.

It turns out that Flash ships with just one special tool: the PolyStar! The expectation is that developers will create and share more tools. I've seen a few cool ones already, such as a 3D cube maker and a variety of arrow heads that automatically apply to lines you draw. Well, you guessed it: Creating such tools is done using JSFL. The best way to learn how to write such a tool is to look at how the standard tools that do ship with Flash work. You can find their JSFL files (along with the .png icon) in the Tools folder.

Finally, you can take a JSFL file and drag it onto Flash, and it will run. This means you can execute Flash from the command line. If you want to run a script on an unattended copy of Flash, you need to add additional lines of code, such as a command to close Flash at the end. For example, take the file stageMask.jsfl (from earlier) and add this line of code above the first line you currently have:

 doc=fl.createDocument();//to make a new document 

Then put this code after the last line:

 doc.exportSWF("file:///c  /temp/test.swf"); fl.closeDocument(doc); fl.quit(true); 

Now you just have to make sure that you have a folder called temp. Save the JSFL file, quit Flash, and then just double-click stageMask.jsfl. You'll see the test.swf show up automatically. To see the mask, launch the SWF, go full screen (Ctrl+F), and then right-click and select 100%.

I believe extensibility through JSFL will surprise even Macromedia. Consider how simple that mask script was. Add to that the fact you can make an interface as a Flash SWF, and I think you're going to see some creative solutions. I know I'll be making a few utilities for my own use.

[ LiB ]