How To Save Commands In Adobe Animate

This is a legacy article. I no longer create or back up Breathing/Wink extensions, just these articles are preserved hither as a reference for anyone to employ.

The ability to create extensions is one of my favorite features in Wink Pro. You tin extend Flash to include new features and automation in the form of Commands, Panels, and Tools. This series of tutorials will show you how to create your ain extensions for Flash. At that place is a special scripting linguistic communication that allows y'all to control Wink, and it is known as JSFL.

Table of Contents

• Creating Wink Extensions — Pt. 1: Introduction
• Creating Flash Extensions — Pt. ii: The DOM
• Creating Flash Extensions — Pt. 3: Manipulating the Library
• Creating Wink Extensions — Pt. 4: User Interaction
• Creating Flash Extensions — Pt. 5: SWF Panels
• Creating Flash Extensions — Pt. vi: Custom Tools
• Creating Wink Extensions — Pt. vii: Distributing to Others

Lesson 1: Introduction

JSFL (JS[JavaScript]FL[Flash])

JSFL is a variant of JavaScript specifically written to interact with the Wink authoring environs. Like Actionscript, JavaScript is based on the ECMAScript standard. And so, if you have any familiarity with JavaScript, or ActionScript, you volition notice this knowledge useful in writing JSFL. It should be noted that JSFL and ActionScript are distinct languages with singled-out purposes. The latter is compiled into a SWF, and that SWF tin play in the ubiquitous Wink Actor. Conversely, JSFL code is executed on the spot and is used to control Flash Professional itself. Thus, JSFL tin achieve nearly everything that a user tin inside Flash, such every bit create layers, create objects, select frames, manipulate Library items, open files, and salvage files. Additionally, JSFL allows you to script a few tasks that users cannot normally perform (at to the lowest degree not easily or quickly).

Yous create a new JSFL script past choosing File > New and selecting Wink JavaScript File in the New Certificate dialog box. The file extension for a JSFL script is always .jsfl. In this tutorial, you lot'll start visually by copying user actions from the History Panel.

The History Panel

The History Panel functions as an advanced undo/redo. This panel besides has the capacity to show the JSFL code necessary to duplicate each (enabled) user activeness.  Follow the steps below to create a JSFL control using the History Panel.

1. Open a new Flash file.
2. Open the History Panel: Window > Other Panels > History.
3. Select the Rectangle Tool and describe a rectangle on the stage.  Find that this activity is recorded in the History Panel.
   
4. Click on the wing-out carte on the top-right of the History panel. Here you can alter the brandish format and tooltip display.
   
   Change the display to show JavaScript in Panel (if it's not selected already).
   
5. Change to the Option tool. Select the rectangle on stage and delete it.
6. Take hold of the slider on the left side of the History Panel and drag it upward then that it's parallel to the original rectangle command. Note that sliding the arrow undid the deletion of the rectangle. This slider functions like an disengage and redo.
   
7. Drag the slider downward to the deleteSelection command. Now select the original addNewRectangle command and hitting the Replay push button. This will create a rectangle with the same dimensions as the original rectangle.
   
8. With the addNewRectangle command still selected, hit Copy Steps button in the bottom right of the History Panel.
9. Elevate the disengage/redo slider to the very tiptop of the History Console to revert the document to its opened state.
10. Open a new file: File > New. When the New Document dialog appears, choose Flash JavaScript File and click OK.
11. Paste the stored command into the newly opened script, Edit > Paste.
12. Hit the Run Script push within the script editor and render to the Wink document.
    
    Note that a rectangle has been fatigued on the stage in the aforementioned place and with the same dimensions equally the i that was drawn with the rectangle tool. This script can now be modified to practice something more useful, like get the document size and draw a rectangle to lucifer the dimensions of the document, or looped to create several rectangles at once.

Saving a Command

To save your JSFL script for after use in Wink, you'll desire to save your script to the Configuration/Commands directory. This will allow you to execute your script using the Commands bill of fare (and optionally, a keyboard shortcut). The beginning step is to locate the Configuration directory for your installation of Wink.

Locating your configuration directory

To locate your Configuration directory, you can check these common locations, or simply create and run a new JSFL script with the post-obit code:

fl.trace(fl.configURI);

This script volition impress the location of your Configuration directory in the Output panel. Note that each installation of Flash has its own Configuration directory.

The next tutorial in this series shows you how to use JSFL to manipulate other parts of your Flash document. If you're interested in learning more JSFL, you can also check out Chapter 4 of Animation with Scripting.

---

Lesson two: The DOM

This tutorial will focus on a couple of nuts for using JSFL (divers in the previous in a higher place) to change a Flash certificate. Everything that tin can be manipulated in JSFL is considered an object. The Document Object Model (DOM) is basically the bureaucracy or structure (model) of objects inside a particular document. If you lot've written JavaScript for a web browser, you're probably somewhat familiar with accessing the DOM of an HTML document.

At that place'south an order to everything you practise within a Flash document, whether y'all've realized earlier or not. The DOM makes this lodge explicit. Let'due south get-go past looking at the most basic Phase object in Wink, known as an element. All Phase objects (e.yard. bitmaps, groups, graphic symbols, and movieclip symbols) inherit the properties (things that describe the object) and methods (things that can be done to or by the object) of a basic element. The certificate object hierarchy for whatever element on Stage is as follows:

Wink > Document > Timeline > Layer > Frame > Chemical element

Each element is on a single frame, that frame is stationed on a single layer, so on, all the way upward to the level of the certificate, and so Flash itself at the very tiptop. So, to admission the 1st element, in the 1st frame, on the 1st layer, within the first Timeline (aka Scene), within the 1st open document in Flash, you could use the post-obit JSFL code:

fl.documents[0].timelines[0].layers[0].frames[0].elements[0];

The 0s (i.e. documents[0]) access the first detail in an Array (collection of objects). This is known as array note. Accept a expect at the documentation for the Document object. It has a number of methods and backdrop. I frequently return to the documentation when writing new scripts. I recommend downloading the PDF of the entire section for quick reference.

Follow the steps beneath to employ two of the Certificate properties to ameliorate the script from the first tutorial (above):

1. Create a new Wink Document (AS2 or AS3), using File > New.
2. Create a new Flash JavaScript file (JSFL), using File > New.
3. Add the following code to your JSFL script and click the Run Script button:

var dom = fl.getDocumentDOM();
dom.addNewRectangle({left:0, top:0,correct:dom.width, bottom:dom.height}, 0);

Switch back to the new document that you lot created. You should see a rectangle (with the fill up and stroke colors from your Toolbar) that fills the Stage.

Let's have a closer wait at the code that you added to accomplish this. The first line creates a new variable with the name dom. This line as well uses the Flash object (fl) to shop a reference to the current document. That will save some typing in the next line and keep the script a little bit easier to read.

In the 2d line, you've replaced the acme and left positions of the new rectangle to represent with the x and y coordinates at the tiptop-left corner of the Stage (0, 0). Additionally, you access the width and elevation properties from the dom variable to match the rectangle's dimensions with those of the Stage.  This new rectangle is much more useful than the i created previously. For instance, this rectangle could now be used as a background, a mask, or (given a few more steps) to create a matte to hide the edges of the Stage. If y'all're interested in learning more about creating mattes and masks with JSFL, check out Affiliate 4 of Animation with Scripting.

Note from the structure listed above that you lot can also use the DOM to alter frames, layers, and timelines. For instance, the post-obit code will create a new layer named artwork:

var dom = fl.getDocumentDOM();
dom.getTimeline().addNewLayer("artwork");

Try experimenting with methods and properties establish in the documentation to make changes in Wink documents. I recommend using "test" documents, rather than actual work files, in example something unexpected happens.

A similar object structure exists in JSFL to manipulate Libary items. The next tutorial (below) dives deeper into the Library object.

---

Lesson 3: Manipulating the Library

Part of being a solid Wink user and a skillful collaborator is maintaining clean, navigable files. This means naming layers and library items conspicuously, deleting unused material, keeping folders organized, etc. Because these actions must be practical to all files and are quite repetitive, they're good candidates for automation. Yous tin use JSFL to script all of these actions into a single keystroke or mouse click. This tutorial will focus on creating a Command (saving a Control is explained in the showtime tutorial higher up) that volition clean up the items in the Library.

The image below shows a sampling from a typical Flash Library. With only fourteen items, this Library is non terribly hard to sort through, just as the document grows and new items are added, this Library will become unwieldy.

There are a number of unlike ways to organize a Library. Sometimes it makes sense to organize your Library items by purpose, such as collecting all the artwork for a single animated character into ane Library folder. Another common approach is to organize Library items into folders by blazon (i.due east. motion-picture show clips in i folder, sound clips in some other, and so on).

This tutorial will help you create a script to organize your Library past item blazon using methods and properties establish in the Library object and the Particular object. The Library object references the document Library itself, which contains a list Item objects. Those items will have unique methods and properties based on their types (such as the SymbolItem or the VideoItem), merely every item in the Library, regardless of blazon, volition inherit the methods and properties of the Detail object.

Organzing Bitmaps

You'll first create a script to organize a single detail blazon. Bitmaps can mess upwards a Library pretty quickly, so you'll begin past wrangling those.

1. Open up an existing certificate with an unorganized Library, or create a new document and add some Library items to exam the script on.

ii. Create a new JSFL script (File > New > Flash JavaScript File).

3. Add the post-obit variables to your script so that they tin can be easily reference in the residue of your code:

var dom = fl.getDocumentDOM();
var lib = dom.library;
var items = lib.items;

4. Add a folderName variable subsequently the previous variables :

var folderName = "bitmaps";

5. Add the following line to cheque for the existence of the binder, and to create the folder if it doesn't exist later the lawmaking in the previous steps:

if( ! lib.itemExists(folderName) ) lib.newFolder(folderName);

The assertion point (!) inverts the truth value (i.e. to see that the detail does non exist). Technically, the if statement is unnecessary, since the new folder will only be created if the path doesn't already exist, but information technology's a good do to have the check, in case the functionality changes in a time to come version of Flash, or yous want to update the script later to deed differently if the binder has already been created.

6. Add together the following code to loop through the library items and move merely the bitmaps to the "bitmaps" folder:

for(var i=0; i<lib.items.length; i++){
var o = lib.items[i];
if(o.itemType=="bitmap") lib.moveToFolder(folderName, o.proper noun);
}

When run on the Library shown higher up, the results appear every bit follows:

You can apply the same logic to create and organize folders for any of the available item types.

Organizing Multiple Detail Types

Now that the bitmaps are under control, why non take care of some other items? Follow the steps below to create and organize several folders.

i. Add a new assortment to the existing set of variables and create several new items based the folder names you want to appear in your Library:

var dom = fl.getDocumentDOM();
var lib = dom.library;
var items = lib.items;
var folderTypes = new Array();
folderTypes['bitmaps'] = "bitmap";
folderTypes['mcs'] = "movie clip";
folderTypes['graphics'] = "graphic";
folderTypes['audio'] = "sound";
folderTypes['fonts'] = "font";

Each new type should be assigned a value that matches the name of an itemType.

2. Then start a for in loop that encompasses the previous for loop the folderTypes that you've created:

for(var type in folderTypes) {
if(!lib.itemExists(folderName)) lib.newFolder(folderName);
for(var i=0; i<lib.items.length; i++){
var o = lib.items[i];
if(o.itemType=="bitmap") lib.moveToFolder(folderName, o.name);
}
}

iii. Add together folderName and itemType variables inside the for in loop to store data from the folderTypes assortment:

for(var type in folderTypes) {
var folderName = type;
var itemType = folderTypes[folderName];


iv. Alter the hard-coded "bitmap" itemType to reference the itemType variable, then that it will update as the for in loop runs:

if(o.itemType==itemType) lib.moveToFolder(folderName, o.name);


Voilà! An organized Library:

Yous tin customize the script to suit your individual or projection-based needs.

---

Lesson 4: User Interaction

The ability to include user interaction into a JSFL script can provide a significant level of flexibility and feedback. Flexibility and feedback are especially useful when you plan to distribute your extension to others. Flexibility allows the script to run differently depending on current conditions. Is there a certificate open? Are items selected in the Library? Etc. If then, yous tin can ask the user how to go along. Feedback lets the user know that the script has run properly (or non), so that he/she can keep with confidence. This tutorial will encompass the primary types of user interaction bachelor in JSFL.

Basic Interaction

At that place are three types of basic interaction: alerts, confirms, and prompts.

Alarm

The alert method displays a modal message (i.e., cypher else can take place while the message box is open) with an OK button.

Sample code:

alarm('this is an alarm');

The alarm box serves every bit a simple grade of advice to signal to the user that a process succeeded, failed, or somewhere in between. Since at that place is only one push in the prompt, and the prompt must exist closed earlier the user can continue working in Flash, in that location is no new information that is retrieved from the user after the message is closed. This 1-way advice is unique to the alert prompt.

Ostend

The confirm method displays a modal box with an OK button and a Abolish button.

Sample lawmaking:

var success = ostend('Are you sure y'all want to exercise this?');

Because the confirm dialog box includes two buttons, a boolean (true/imitation) value is returned to betoken which push has been pressed. This allows the script to behave differently depending on the user's choice:

if (success) {
//do something
} else {
//practise something else
}

The confirm dialog can be used for any "fork in the road" where information technology might be beneficial for the user to take input earlier proceeding.

Prompt

The prompt method includes an OK button, a Cancel button, and a textfield in which a user can type a response.

var result = prompt('Enter your text:');

If the user clicks OK, then the value entered in returned. If the user clicks abolish, a value of nil is returned. This allows you lot to apply the entered value to determine what occurs in the script:

if (result == null) {
//do nothing
} else {
//apply the value of result to proceed with the script
}

The prompt dialog is useful for allowing the user to name items and instances. You can likewise catechumen entered values to numbers using the parseInt and parseFloat JavaScript methods.

Advanced Interaction

In add-on to the basic user interaction methods, you tin too display a completely custom XMLUI panel, using the document.xmlPanel method. These panels can incorporate any number of interactive items, including: buttons, checkboxes, color selectors, drop-down lists, sliders, radio buttons, text boxes, text inputs, and even SWFs.

The content of the panel is divers past an XML file, using specific tags. The tags command the layout of the panel also as the items that announced in the panel. The panel is then launched past accessing the stored XML file:

var dom = fl.getDocumentDOM();
var xpanel = dom.xmlPanel(absoluteFileLocation);

Hither's the content of the XML file that renders the Combine TextFields dialog with radio buttons to a higher place:

<?xml version="i.0" encoding="UTF-8"?>
<dialog id="combineTF" championship="Combine TextFields" buttons="accept,cancel">
<vbox>
<label value="Sort from:" />
<radiogroup id="sortby" tabindex="5">
<radio label="top" accesskey="t" selected="true"/>
<radio label="left" accesskey="l" />
<radio label="lesser" accesskey="b" />
<radio label="right" accesskey="r" />
</radiogroup>
</vbox>
<spacer />
<hbox>
<label value="Separator:" />
<textbox id="separator" maxlength="20" multiline="simulated"
value="" tabindex="ane" size="12" literal="false" />
</hbox>
</dialog>

Merely similar the prompt method, the xmlPanel method will render null if the user clicks Cancel. If the user clicks OK, an object is returned containing all of the values gear up in the XMLUI dialog box. Y'all can and so loop through the object's properties every bit shown in the document.xmlPanel reference, or access them direct by name, for example:

var separator = xpanel["separator"];

The merely total reference for the tags and syntax used to create XMLUI dialogs can exist institute in Extending Flash MX 2004, an excellent and important desk reference for anyone interested in Flash extensions. Even though the book is quite dated (in software years), much of the JSFL API remains the same, and the book is still useful, even if you lot just utilize it for the XMLUI reference (which I'thousand constantly using).

---

Lesson v: SWF Panels

If yous've been post-obit this tutorial series thus far, this might exist the tutorial you've been waiting for. The ability to load a SWF into the Flash Professional person interface is definitely 1 of the coolest aspects of Flash extensibility. At that place are 2 distinct advantages to building a Flash console:

1. Endless visual possibilities
2. The power of ActionScript

The 1st advantage should exist fairly obvious to anyone familiar with Flash'due south blueprint and animation capabilities. The 2nd advantage may exist slightly less obvious, since ActionScript and JSFL can appear and then similar, simply ActionScript (3, specifically) has a whole host of capabilities that JSFL does not (network connectivity, timed events, and the ability to interface with nearly any file type using ByteArray, to proper name a few). The topic of exploiting ActionScript capabilities in a panel actually deserves its ain weblog post, but for at present it's sufficient to say that SWF panels make cool stuff possible.

This tutorial will serve equally a primer, getting you lot started on the basics of how to load your console into the Flash interface and how to communicate with JSFL through your SWF.

A Elementary Panel

A Flash panel is merely a published SWF that can exist loaded into the Wink Professional person interface via Window > Other Panels. You can design custom panels to look like the panels that come installed with Wink, or yous can make them entirely unique.

Setting up the Flash file

Follow the steps below to create a uncomplicated panel.

1. Create a new Flash file (AS3), File > New… > ActionScript three.0.
2. Save the file (File > Save As…) as myPanel.
3. In the Properties console, update the certificate size to 200 x 300 px. The default width for a panel is generally 200 pixels.
4. If you like, update the Stage Color. When you click on the colour selector, you can apply the centre dropper to select the greyness color within part of the Wink interface, so that your panel color matches the rest of Flash.
5. Open the Components panel, Window > Components.
6. Twirl open up the User Interface binder and drag a Button component onto the Stage.
   
7. Give the Button case a name of btn in the Properties console. An instance name volition permit you to reference the push from ActionScript.
8. Change the width of the push button to 180 and adjust its position on Stage as needed.
9. Add a label to the button of Create Rectangle.
   

For simplicity sake, you volition use the script created in Role 2 of this series, merely once you go the hang of this, you'll exist able to add as much complexity equally yous similar.

Calculation the Code

From a SWF, your ActionScript needs a way to talk with JSFL: enter the MMExecute function. This function will pass a string to exist interpreted as JSFL. The JSFL code volition only exist executed when yous've properly loaded your console. Your JSFL code volition not execute when yous run Test Pic. More than on how to install your panel in a moment.

When you pass JSFL code equally a string, be careful to escape any characters such equally quotation marks (using a backslash, east.g. /") that volition disrupt the string in ActionScript. Alternatively, if you use double-quotes for JSFL, you can use single-quotes to wrap your string, or vice versa. For case, to trigger a JSFL alert from ActionScript, yous could employ the following code:
MMExecute("alert('howdy');");

Follow these steps to add together the functional code to your panel:

1. Create a new layer named actions and lock the layer.
2. Select the beginning frame of the actions layer and open up the Deportment panel (Window > Deportment).
3. Add together the following code inside your actions panel:

btn.addEventListener(MouseEvent.CLICK, onBtnClick);
office onBtnClick(east:MouseEvent):void {
var jsfl:String = new String();
jsfl += "var dom = fl.getDocumentDOM();";
jsfl += "dom.addNewRectangle({left:0, acme:0,right:dom.width, lesser:dom.height}, 0);";
MMExecute(jsfl);
}

1. Publish your SWF (Command > Exam Picture).

The first line of the ActionScript adds a listener to the push button component that volition burn when the button is clicked. The next line begins the definition of the onBtnClick office that executes when the button instance is clicked. Inside the role, a string is created to house the JSFL code. That string is then passed to be executed equally JSFL by the MMExecute role. Mostly, I like to concatenate my strings on carve up lines using the += operator, because it keeps my JSFL somewhat readable inside the ActionScript. You'll learn how to store the JSFL lawmaking externally later in the tutorial (a technique that I much prefer).

Make sure you have no errors in your Compiler Errors panel. If yous press the button right at present in the Examination Movie window, nil will happen, only you'll set that in the next pace.

Loading your panel into Flash Professional

In gild to have your SWF prove up equally a panel, you will need to place it in the Configuration/WindowSWF folder. See the 1st tutorial for how to locate your Configuration directory. Follow the steps below to launch and run your console.

1. Identify a copy of the myPanel.swf file inside the Configuraton/WindowSWF folder.
2. Restart Flash.
3. Create a new document, File > New > ActionScript 3.0.
4. Open up your new console under Window > Other Panels > myPanel (the panel name volition e'er exist the file proper noun minus the .swf extension).
5. Click the Create Rectangle push button inside the panel.

You should now see a rectangle matching the Phase dimensions with the stroke and fill colors from your toolbar.

Success!

Accessing an External Script

So far, you lot've run JSFL code as a string inside ActionScript. This works fine for simple panels like the one you built in the steps above, but what about more complex deportment? I recommend using the fl.runScript function.

Running an entire Script

If you want to run an unabridged script, all you need to do is pass the consummate path of your script. Suppose you wanted to include a myPanelActions.jsfl file in the WindowSWF directory with you SWF file, you could utilize the post-obit ActionScript:
MMExecute("fl.runScript(fl.configURI + 'WindowSWF/myPanelActions.jsfl') ; ");

That bit of code would execute the unabridged myPanelActions.jsfl script.

Running a single office

At present suppose you wanted to include several deportment in a single JSFL script. So, now y'all have a createRectangle function inside your myPanelActions.jsfl file, along with several other functions. You could modify the onBtnClick part from above equally follows:

function onBtnClick(e:MouseEvent):void {
MMExecute("fl.runScript(fl.configURI + 'WindowSWF/myPanelActions.jsfl', 'createRectangle';)");
}

That would let yous add together several other buttons (and actions) to your panel, while keeping your ActionScript nice and clean. This technique as well reduces the need to keep rails of so many double- and single-quotes. Additionally, it's much easier to debug (find and fix errors) by testing a separate JSFL script.

SWF Console Examples

At present that you've got the hang of the basics, you tin create all kinds of neat Flash panels. Here are some examples of publicly available Wink panels that I've created. Maybe they'll provide some inspiration as to what you tin can create.

Queasy Tools

Queasy Tools is a macro-style console that I created to clean upwards my Commands menu. It allows me to quickly tween and perform mutual actions that normally require several steps.

EaseCaddy

EaseCaddy is a panel that stores custom eases for animation. Note the advantages of making such a tool equally a Wink console (displaying the listing, a visible graph of the ease, graphical buttons, etc).

FrameSync

FrameSync is a panel to speed up lip-syncing. It can pull frame labels from a symbol and display them in the panel. The labels tin can so be clicked to update the content on the Timeline. Because of ActionScript'due south timing mechanisms, the console can also refresh automatically to capture changes in user selections.

Hopefully these examples provide you with some ideas for your own SWF panels. Delight feel gratuitous to mail links to your Flash panel creations in the comments.

Bonus: Productivity Script

One time you've loaded your console into the Flash interface, you don't need to restart Flash each time yous make an update to your panel. You lot just need to shut your panel and re-open it inside Flash.

Instead of running Test Movie, then copying my SWF to the config directory with each update, I created the post-obit script that I utilise equally a Control to publish my SWF directly to the WindowSWF folder:

var dom = fl.getDocumentDOM();
var fileName = dom.name.split(".fla").join(".swf");
var swfFile = fl.configURI + "WindowSWF/" + fileName;
dom.exportSWF(swfFile, true);

So y'all can even use JSFL to speed up extension production!

---

Lesson vi: Custom Tools

Flash offers the ability to create your own tools and store them in the Flash Toolbar. Tools are probably the near underutilized type of Flash extension. This tutorial volition walk through the basics of creating a  tool.

Edifice a Tool

This tutorial will demonstrate how to create a line tool. Wink already has a line tool, but this will serve as a jumping off signal that can be easily expanded into a more complex tool.

File setup

Similar to Commands and SWF Panels, Tools have their own folder in the Configuration directory (run into the 1st tutorial for how to locate your Configuration directory). The Polystar tool (found with the Rectangle tool in the Toolbar) is a custom tool that comes installed with Wink. You can employ the Polystar tool files in the Configuration/Tools directory as a guide when building new tools. Follow the steps below to create a tool from scratch.

1. In Flash, create a new JSFL script (File > New > Flash JavaScript File).
2. Relieve the script as TestTool.jsfl in your Configuration/Tools directory.
3. Create a 16 x 15 pixel PNG paradigm (using Flash, Photoshop, Fireworks, or your favorite image editor) and save information technology in the Tools directory every bit TestTool.png. This will serve equally the icon in the Toolbar. I just created a diagonal line.
   
   You tin also correct-click and cull Save Image As… to save the epitome on this page.
4. Optionally (pun intended), you tin can create a TestTool.xml file in the Tools directory. This file tin exist used to establish options for the tool that can be adjusted past the user. This tutorial will not embrace creating options, merely yous can look at the Tools/PolyStar.xml options for inspiration.

Now that yous files are fix upwards, you'll start adding code to your JSFL script.

Predefined Functions

One concept that is unique to creating a tool involves prescribed functions that Wink volition call as your tool is put to use: configureTool, notifySettingsChanged, setCursor, actuate, deactivate, mouseDown, mouseMove, and mouseUp. Most of these functions have to be present (and contain no errors) when Wink is started for your tool to load properly.

Add the following code to the height of your script:

role configureTool() {
theTool = fl.tools.activeTool;
theTool.setToolName( "testtool" );
theTool.setIcon( "TestTool.png" );
theTool.setMenuString( "Test Tool" );
theTool.setToolTip( "Test Tool" );
theTool.setOptionsFile( "TestTool.xml" );
theTool.setPI( "shape" );
}

The configureTool role is triggered past Wink on starting time-up.  The offset line grabs the active tool, which happens to exist your tool while your configureTool part is executing. The stored variable is and then used to constitute all of the basic setup options for the tool. The name Wink uses internally is assigned using setToolName. The file name called in setIcon should match the PNG that you saved to your Tools directory. The setMenuString and setToolTip methods make up one's mind how the tool proper name is displayed in the Wink interface and Toolbar (on rollover).  The setOptionsFile points to the options file that you (optionally) saved. Lastly, the setPI method determines which settings are shown in the Backdrop panel ("PI" used to stand for Properties Inspector, the previous name of the Properties panel). In this instance, the shape (stroke, fill, and color) options will be displayed, since the end goal is to depict a line on Phase.

Add this function to the end of your script:

function notifySettingsChanged() {
theTool = fl.tools.activeTool;
}

The notifySettingsChanged role will be triggered later on the user has changed any of the tool settings (those established in the XML options file). This function allows you to update any variables before taking further action. For instance, suppose you wanted to use you own stroke width setting, separate from the Properties console. You would shop the default stroke width in a variable, and update the variable to match any new settings once the notifySettingsChanged function is called. Since y'all're non adding any options for this tutorial, this function is essentially empty, merely it'southward good to have it available in case yous want to add together this functionality later on.

Add the post-obit code to your script:

function setCursor() {
fl.tools.setCursor( 0 );
}

The setCursor function is too automatically triggered past Flash. Y'all then use the fl.tools.setCursor method to decide what blazon of cursor is displayed when you tool is in employ. The options are as follows:

• 0 = Plus cursor (+)
• 1 = black pointer
• 2 = white arrow
• three = four-way arrow
• four = two-way horizontal pointer
• 5 = ii-way vertical arrow
• 6 = X
• vii = hand cursor

Add the actuate role to be called when the user selects your tool:

part actuate() {
var theTool = fl.tools.activeTool;
}

Consequently, y'all'll also desire to add the following deactivate office for after use:

role deactivate() {
}

This office is generally called when the user selects a different tool. You can employ this part to shut off whatever event listeners or end any processes that do need to execute while the tool is inactive.

Add the post-obit to the end of your script:

part mouseDown() {
fl.drawingLayer.beginDraw();
startPt = fl.tools.snapPoint( fl.tools.penDownLoc );
}

The mouseDown function will exist triggered by, you guessed it, the user pressing the mouse button (while over the Stage area). The start line inside this role will activate the drawingLayer using the beginDraw method. The drawing layer is a temporary visual feedback system for the user. It helps to indicate what the tool volition attain before the user releases the mouse button and commits to an action.

When you lot tool is consummate, information technology will display a preview using the cartoon layer, every bit shown in the image above. Additionally, the starting signal is stored for later using in the mouseDown function. The snapPoint method is used to snap the location to the nearest geometric object, but this snapping can be omitted.

Add the following part to your script:

part mouseMove(mouseLoc) {
if (fl.tools.mouseIsDown) {
var pt1 = startPt;
var pt2 = fl.tools.snapPoint( mouseLoc );
fl.drawingLayer.beginFrame();
path = fl.drawingLayer.newPath();
path.addPoint(pt1.x, pt1.y);
path.addPoint(pt2.x, pt2.y);
fl.drawingLayer.drawPath(path);
fl.drawingLayer.endFrame();
}
}

The mouseMove function is also congenital-in, and rather self-explanatory. It receives an statement with the current location of the mouse. The adjacent line checks if the mouse push button is downwardly (pressed), if not, yous won't want to draw anything for this tool. Inside that if check, the starting point is stored equally a new variable, in case you want to manipulate information technology without altering the startPt variable, and the current location of the mouse is stored. The beginFrame method clears out and initializes the cartoon layer for new data. A path is then created, and the two stored points are mapped to the path. The drawPath method renders that path onto the cartoon layer (so that the user can see it). The endFrame method signals the end of any temporary drawing for the moment.

The mouseMove role is then called repeatedly as the user moves the mouse.

As an alternative to creating a path and adding points, yous could use the moveTo and lineTo methods to generate the temporary line:

fl.drawingLayer.moveTo( pt1.x, pt1.y );
fl.drawingLayer.lineTo( pt2.ten, pt2.y );

While these methods may be more familiar to you from using ActionScript, you lot'll come across in the next bit of code why y'all've created a Path object instead for this scenario.

Add this final function to your script:

function mouseUp() {
fl.drawingLayer.endDraw();
path.makeShape();
}

The endDraw method exits the cartoon mode completely. Since you've created a path object already, you simply return the path (using the default stroke and fill settings) via the makeShape method.

You lot script is now complete!

Loading the New Tool

Make sure the files you've created are all in the Configuration/Tools directory and follow the steps below to access and use your tool in Flash.

1. Restart Flash.
2. Access the Customize Tools Panel dialog box, via Edit > Customize Tools console (Windows), or Wink > Customize Tools panel (Mac).
   
3. Locate Test Tool in the Available Tools carte du jour at the left. The Electric current Selection carte at the correct indicates the tools currently assigned to the selected location in the Tools panel at the far left. If you tin't detect your tool in the list, y'all likely accept an error in your script. Attempt debugging your script and restarting Flash.
4. Browse through the tools to specify the a location, click on the tool in the prototype of the Tools panel, and then click the >> Add together >> push. I chose to add the new tool with the Line Tool.
5. Click OK to save the tool settings.
6. Create a new document, File > New… > ActionScript three.0. Note: your tool with work the same regardless of which version of ActionScript you lot're using.
7. Select the Examination Tool (from underneath the Line Tool, or wherever you added the Test Tool).
   
8. Draw a line on Phase by pressing the mouse button in one location, dragging to another location, so releasing.
   

And at that place you have it!

Boosted Tips

So far, you've run through the bare-bones of creating a simple tool, only in that location are many bells and whistles that you can add. In addition to creating a settings XML file, you might consider adding some of the functionality covered in this section.

For example, within y'all mouseMove function, you might want to constrain you line to 45-degree (or 30-degree) angles when the shift push is pressed (the way many other pattern tools do):

if (fl.tools.shiftIsDown){
//code constrain angle
}

You may also want to check for a minimum distance when drawing on Stage, so that it'southward more difficult for the user to accidentally draw a one-pixel long line (run across the PolyStar tool for an case of this).

If yous play around with the tool as is, information technology will work pretty well on the main Timeline, but it might produce some funny results inside of nested symbols. That's a symbol instance oft has a registration betoken that doesn't friction match the registration point of the Stage. In guild to gear up this, employ a function to transform your coordinates to the current viewMatrix, like so:

function transformPoint( pt,  mat ) {
var x = pt.x*mat.a + pt.y*mat.c + mat.tx;
var y = pt.x*mat.b + pt.y*mat.d + mat.ty;
pt.ten = 10;
pt.y = y;
return pt;
}

A sample phone call to the office might look like this:

var pt1 = transformPoint( startPt, fl.getDocumentDOM().viewMatrix);

Lastly, debugging. If you're having problem with your tool loading, endeavour running the script by double-clicking on the JSFL file (or clicking the Run Script push button in the Flash Script Editor). In most cases, if you lot take a syntax error in your script, it will be displayed in the Output panel, along with a line number.

Instead of restarting Flash every time you brand a code update to your tool, you can simply run the following JSFL lawmaking in a new script:
fl.reloadTools();

I accept this script saved every bit a command, and I add together the following line to clear out any old errors in the Output panel:

fl.outputPanel.clear();

That does it for this tutorial. If you lot desire to know more about building tools, bank check out Extending Flash MX 2004.

Deco tools

Deco tools were added in Wink CS4 and CS5. Y'all can as well create your ain Deco tool by placing a JSX file in the Configuration/ProcScripts directory. Annotation that a JSX file is the type of JavaScript used for other Creative Suite applications (non JSFL). There is very little documentation on creating a Deco tool. Here are some links with more than info (i, 2, three). The best way to kickoff is to re-create one of the existing JSX files and change the code. This may be a topic in a hereafter postal service.

---

Lesson seven: Distributing to Others

One of the absolute coolest things about Flash extensions is that you lot can easily share them with others. This tutorial will show you how to create package that can be emailed or posted to a website. That parcel tin so exist downloaded by others and installed using Extension Manager.

Extension Manager

Extension Manager (EM) is a free application that is automatically installed when yous install any of the Adobe Creative Suite applications, including Flash Professional. If you accept Flash installed, you accept EM installed, whether y'all knew it or not. You lot can install extensions using EM, as well as package them.

Packaging an Extension

When you package an extension with EM, all of your extension files are collected into a unmarried file or package. That package can then exist distributed. Double-clicking on the package will automatically launch EM and begin the (cursory) installation process. Before packaging your extension, you'll need to create an MXI descriptor file.

The MXI file

An MXI file is a special XML file that contains information about the extension (title, author, version, copyright, license agreement, which files it includes, where to install the files, etc.). Here's sample text from an MXI file:

<?xml version="i.0" encoding="UTF-viii"?>
<macromedia-extension
proper name="Sample Extension"
version="one.0.0"
blazon="command">
<author proper name="Your Name" />
<products>
<product name="Flash" version="vii" primary="true" />
</products>
<description>
<![CDATA[
This extension does A and B.
]]>
</clarification>
<ui-access>
<![CDATA[
The command tin can be found in 'Commands > Sample Extension'
]]>
</ui-access>
<license-agreement>
<![CDATA[
]]>
</license-agreement>
<files>
<file source="Sample Extension.jsfl" destination="$flash/Commands" />
</files>
</macromedia-extension>

I generally start from an existing MXI, and make any necessary changes. In the sample text to a higher place, you'll (minimally) want to alter the following items: the proper noun and version attributes in the root tag, the name attribute in the author tag, the files tag(s) (and attributes), too equally the description and ui-access tag content. The version attribute in the product tag determines the oldest version of Wink in which your extension can be installed (7 = MX 2004, 8 = Flash 8, nine = CS3, 10 = CS4, and so on).

The version yous choose will depend heavily on which JSFL commands your extension uses. Note the Version heading at the top of the each page inside the Extending Flash documentation; that will tell you the primeval version in which a detail object, method, or property is bachelor. The ui-access tag is an expanse where you tin provide instructions to the user on how to launch your extension. Both the ui-access and description volition appear in EM once the extension has been installed (meet the image at the acme of this page). Note that both tags likewise contain CDATA wrappers. The CDATA tags permit the content inside to be interpreted as plain text instead of XML content.

The MXI file can be edited in a simple text editor similar Notepad (Windows) or TextEdit (Mac). You should take a file tag (inside the files tags) for each file used in your extension. For instance, a bones tool, similar the one in the previous tutorial (above), would require at least 3 file tags:

<files>
<file source="TestTool.jsfl" destination="$flash/Tools" />
<file source="TestTool.png" destination="$flash/Tools" />
<file source="TestTool.xml" destination="$wink/Tools" />
</files>

The source aspect should reference the location of the source file relative to the location of the MXI file, and then that EM knows where to look for the files when packaging. For this reason, it'southward easiest to keep the MXI file in the same directory as your source files. Note the utilize of $flash in the destination aspect. This is a handy-great way to reference the location of the user's Wink Configuration directory, regardless of their version or linguistic communication. The version of EM that the user (or their arrangement) opens will decide which version of Flash that receives your extension.

Generating the packet

Later on y'all've edited your MXI file in a text editor, open up it in EM. It will ask where you want to save your packaged file (commonly I opt to keep information technology with my MXI and source files). One time y'all've given your file a proper noun and location, EM will packet all the files referenced in the files tag of the MXI file and include them in a single MXP (or ZXP for CS5-specific extensions) file. Y'all tin at present post this extension to your website or the Adobe Exchange and share information technology with others. All potential users of your extension have to practice (afterward downloading ) is double-click your MXP file and they're off and running.

Where to Become From Hither

That wraps upwardly this series on creating Flash extensions. Thank you for reading!

You lot tin can always learn from comparing your JSFL to that of others on the spider web. If you're interested in learning more JSFL, don't forget about the excellent Extending Flash MX 2004 volume.

✕

Go updates from Ajar Productions

Sign upwardly today and go the InDesign Split Text premium extension for free!

Success! Check your email to confirm your subscription and go your reward.

Source: https://ajarproductions.com/blog/2011/02/08/creating-flash-extensions-pt1/

Posted by: maserneash1938.blogspot.com

Share this post