Voices: Betsie Bush and Peter Yearsley (librivox.org)
Music: Baby, Please Don’t Go by Big Bill Broonzy

We don’t have an exact release date available. I’m hoping it will be in the next 1-3 months. The SmartMouthRT SDK (Software Developer’s Kit) will be priced to reflect its greater flexibility beyond that of the Flash Extension. The first release will analyze essentially any (and all) sound playing within the Flash Player. Future releases will likely include the ability to target specific sound objects (i.e., for multiple simultaneous characters) as well as microphone objects.

Want an email when SmartMouthRT is available? Subscribe to our newsletter.

What differentiates a feature from a bandage? Here are some characteristics of a feature:

1. Can be turned on or off, usually with a single variable.
2. Does not interfere with existing functionality (i.e., when the feature is turned off, the application should function just as it did before adding the feature).
3. Easy to read code (i.e., dependent code can simply check to see if the feature is on, rather than testing several ambiguous conditions).

Bandages have almost the exact opposite characteristics: can’t be easily reversed, interfere with existing functionality, and usually very difficult to read. Features also have the added advantage of being useful later. Even if you do not using the exact same code base, when your code is written as features, rather than cobbled together to serve a micro-specific purpose, it’s much easier to copy code from one project to another.

There are several techniques that differentiate feature-building. Consider the simple example that follows into in order to examine some of those techniques. Suppose your application includes the following 3 functions: navigateTo, nextPage, and prevPage. Your application plays start-to-finish automatically triggering the 3 aforementioned functions, but your client has indicated that they would like the application to pause when it reaches the end of a section. Additionally, the client wants the backward (e.g. when the user presses the back button) navigation to stop when the beginning of a section is reached.

Bandage Approach

First, have a look at a bandage approach. Since you know the page number that corresponds with each section, you could quickly hard-code these values into the respective functions.

function navigateTo(page) {
//no change in functionality
}

function nextPage(){
if(currentPage == 11 || currentPage == 18 || currentPage == 24 || currentPage == 30) pause();
else navigateTo(currentPage+1);
}

function prevPage(){
if(currentPage != 12 || currentPage != 19 || currentPage != 25 || currentPage != 31) navigateTo(currentPage-1);
else /*do nothing*/;
}

While this solution will work from the client’s point of view, it will get messy for you if a page needs to be added anywhere (lengthening a section and changing all of the relevant page numbers) or client decides that this feature is not needed after all. Even worse, what if the client loves it and wants more new functionality…now you’ll have to add bandages on top of bandages.

Feature Approach

One way to improve upon the bandage approach is to move the logic to a central location. This can be done in the example above by moving logic from the nextPage and prevPage functions to the single navigateTo function.

function navigateTo(page) {
var sectionStart = (currentPage == 11 || currentPage == 18 || currentPage == 24 || currentPage == 30);
var sectionEnd = (currentPage == 12 || currentPage == 19 || currentPage == 25 || currentPage == 31);
if(sectionStart) {
disableBackNav();
} else if (sectionEnd) {
pause();
} else {
//run normally
}
}

function nextPage(){
navigateTo(currentPage+1);
}

function prevPage(){
navigateTo(currentPage-1);
}

The purpose of this code is already slightly clearer than the bandage approach. The logic has moved out of multiple functions and into a single function that is called by the other two. Two variables are then created, sectionStart and sectionEnd, to test the location of the current page. The conditions that determine these values are adjusted based on the currentPage location, which will have already been altered by nextPage or prevPage (unlike the bandage example above). Additionally, the navigation will function properly even if it’s not triggered by the nextPage or prevPage functions, because all navigation is routed through navigateTo.

While jumping in with a bandage approach can seem quicker in the short run, you can see that difference in the amount of code required between these two examples is negligible. Additional improvements can be made to the code by moving the section start and end numbers out of the navigateTo function and to a location that is easy to find and edit (like the top of the code). Ideally, these numbers would not have to be present at all. If the data that contains page information, often stored in XML, clearly groups sections, section starts and ends can be determined dynamically, rather than hard-coding actual numbers that are likely to change.

A sample bit of XML might look something like this:
<root>
<section name='Introduction'>
<page name='Welcome' id='010101' />
<page name='Course Navigation' id='010102' />
<page name='Initial Questions' id='010103' />
</section>
<section name='Tools'>
<page name='Toolbar' id='010201' />
<page name='Calculator' id='010202' />
<page name='Navigation' id='01020' />
<page name='Selection' id='010204' />
</section>
<section name='Course Review'>
<page name='Review Screen' id='010301' />
<page name='Close Course' id='010302' />
<page name='Submit Results' id='010303' />
</section>
</root>

As sections are added to the application structure, the application dynamically reads the section breaks from the clearly-defined XML data.

Further refinement would involve creation of variables like pauseAtSectionEnd and lockBackNavAtSectionStart that are set at the top of the code. Thus, each feature can easily be enabled or disabled without diving down into functions that contain other purposes. This has the additional benefit of reducing the chances that you might break something that was already working in the code, which can happen from deleting even 1 character accidentally.

In short, bandaging assumes on some level that you’ll never have to look at the code again…so what does it matter how organized it is, right? In my experience, this is almost never the case, bandaging will always come back to haunt the developer. Building features rather than applying bandages has made my life a lot easier as developer. Furthermore, it’s made me popular among my colleagues, because this type of code construction has facilitated easy updates and fixes when they’ve needed them in a hurry. I hope this post helps you to think about your projects in a new and helpful way.

var nm:NativeMenu = NativeApplication.nativeApplication.menu;
var nm0:NativeMenuItem = nm.getItemByName('File');
var mi:NativeMenuItem = new NativeMenuItem("Export...");
mi.addEventListener(Event.SELECT, exportSelected);
nm0.submenu.addItem(mi);

Unfortunately, the menu item resolves to null in the above code and subsequently generates an error. Instead, I’m using the following code (that works):

var nm:NativeMenu = NativeApplication.nativeApplication.menu;
var nm0:NativeMenuItem = getMenuItemByLabel(nm, 'File');
var mi:NativeMenuItem = new NativeMenuItem("Export...");
mi.addEventListener(Event.SELECT, exportSelected);
nm0.submenu.addItem(mi);

The getMenuItemByLabel function is as follows:

function getMenuItemByLabel(menu:NativeMenu, labelName:String):NativeMenuItem {
var count:uint = menu.items.length;
for(var i:uint=0; i < count; i++){
var item:NativeMenuItem = menu.getItemAt(i);
if(item.label === labelName) return item;
}
return null;
}

That way I can get the menu by name and rest assured that I’ve added to the File menu (or any other existing menu) without having to guess its index.

Download
MotionBrush.zip

I’m pretty happy with this new software, so I’ll try to post more videos. Still working on getting better resolution out of the video host though…

stage.width will return the width of the content on the stage and ignore any empty pixels around the edges. So if you only have a 100 px wide rectangle on stage, your stage.width will be 100.

stage.stageWidth will give you the size of the stage, more like Stage.width in Actionscript 2. Use stage.stageWidth if you’re trying to position elements relative to the stage.

Same goes for stage.height and stage.stageHeight.

The short answer: Instance Names.

For the detailed answer check out this video tutorial using Actionscript 3.

The Actionscript has to know “who” you’re wanting to talk to. Just as we know human beings by name, and talk about them and to them by name, Actionscript references objects by name. A teacher might tell “Timmy” to sit down. Accordingly, your script might tell “circle” to move 10 pixels to the left. If no symbol with the name, “circle” exists, nothing happens; just as no one sits down if there’s no “Timmy” in the classroom.

Referencing nested MovieClips works the same way, just add a dot inbetween:
var clipReference = grandparentClip.parentClip.childClip;

Remember that a symbol name is different than an instance name. You can have multiple instances of a symbol on stage, but each instance name has to be unique. Instance names are set in the Property Inspector, symbol names are set in the Library.

Keep this idea in mind when working with Actionscript and it will make your life a whole lot easier.

I’m a big believer in the open-source movement and many times I’ve been able to find an open source solution that does the trick as well or better than a packaged piece of software can. So I started searching under the assumption that I would eventually settle on an open-source solution. In the case of Actionscript documentation, I found my ideal solution in VisDoc. It was one of the few solutions that had a Graphical User Interface rather than using a command line. It produces a beautiful set of documentation files. It works for both AS2 and AS3 (and Java). The one downside is that it’s Mac only. It’s not open-source, but with a sticker price of $40, it’s well worth the time saved. If you’re still looking for open-source or you need an app for your Windows machine, OSFlash has a comprehensive list of open-source documentations tools for Actionscript.