I’ve been working on Dwarf little by little and finally built one of the most requested features—unit types. The five available unit types are pixels, picas, centimeters, inches, and percent. Inches have dotted lines for quarter inches and percent always displays 100% on the ruler, but scales its grid to show ten columns and ten rows. At the moment, the units are based on a 72 dpi screen, but I’ll be adding an option to change the dpi, since most screens aren’t 72. If anyone has suggestions for that other than using a list, let me know.

The unit type is selected by clicking the menu at the right of the toolbar. It prompts a context menu with the options. Dwarf remembers which unit type you used last, so it’ll remain the same next time you startup. Along with unit types, I included positions and dimensions in the toolbar. This is mostly for the position, but I thought dimensions look nice up there too. At the moment, the position is in relation to the main screen, but the next build improves multi-screen support. You will be able to specify which screen to relate the position to. This also comes in handy for moving guides from screen to screen.

If you’re already a Dwarf user, start up for the update, or download it from GitHub. And, as always, let me know what you think in the comments.

I’ve been working on Dwarf over the past few days and decided it’s time to give a little introduction on its key features. Be sure to view fullscreen with no scaling to see it at 100%. The prerelease of Dwarf available to download on GitHub and the source code is hosted there as well. I’ll be rolling out the official 1.0 build pretty soon—I just need to add a few more key features.

A recent AIR prerelease drop broke Dwarf. I’m actually not surprised, since it uses a pretty ghetto hack—displaying a transparent window fullscreen and using ‘virtual’ windows. Because Dwarf is such an integral part of my everyday workflow and it’s such a small app, I figured I could easily rewrite it within a day or two. I’ve been on such a code-sharing high, that I started a new Git repository for it where you can find my work in progress. So far, I have a single ruler working with a semi-functional Mac toolbar. Everything should be complete either tonight or tomorrow, so keep an eye out.

On a legal note, the source code is provided under the GNU General Public License (GPL), so you can reuse and modify the code all you want as long as it’s still free. If you’d like to use it for commercial purposes, let’s talk.

A couple months ago, I started working on a Twitter component for my current project at Adobe. I went into this knowing I’d have to finally face the beast… OAuth. Just about every well-known Twitter client out there uses Basic Auth—and for a reason. It’s easy, what the user expects, and gives your app more credibility—there’s no requirement to leave to authenticate through the browser like with OAuth.

About five or six months ago, Twitter decided to enforce the transition. From then on, any application that uses the API must use OAuth in order to see “via [your app]” on tweets published with it—otherwise, it would display “via API.” Since “via” is where apps get probably 90% of their referrals, this was a big deal. Luckily for me, DestroyTwitter existed before that time and Twitter decided not to push the change on the veteran apps. Recently, however, the bad news spread that Basic Auth would be deprecated in June. This means every Twitter app must transition to the pain that is OAuth.

After developing the MAX Companion this past fall and now the more generalized version, I found myself rewriting the Twitter component each time. After a while, the Twitter API code I wrote for DestroyTwitter began to merge with the actual implementation, so it was no longer a standalone library that could easily be used by other projects. These past few months, I’ve been learning a great deal about framework architecture and design patterns. It has led me to realize I need to start fresh.

With all that being said, I’d like introduce a library I started working on two days ago. I call it TwitterAspirin. It’s an AS3 Twitter API library that eases the pain, providing developers with a very powerful tool for communicating with Twitter. Though it’s still a newborn at the moment, I see potential already. The library is built on RobotLegs and uses AS3 Signals instead of events. It’s hosted on GitHub, so the source code will always be available to the public. And, after last night’s commit, its OAuth functionality is complete. Here’s how to use it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

package {
	import com.destroytoday.twitteraspirin.Twitter;
 
	import flash.display.Sprite;
 
	public class Test extends Sprite {
		// set application consumer key and secret
		public var twitter:Twitter = new Twitter(consumerKey, consumerSecret);
 
		public function Test() {
			// add signal listeners
			twitter.oauth.requestTokenSignal.add(requestTokenHandler);
			twitter.oauth.accessTokenSignal.add(accessTokenHandler);
			twitter.oauth.verifyAccessTokenSignal.add(verifyAccessTokenHandler);
		}
 
		// click the 'Authorize' button to get the request token
		protected function authorizeClickHandler():void {
			twitter.oauth.getRequestToken();
		}
 
		// upon receiving the request token, open Twitter in the browser to authorize
		protected function requestTokenHandler(oauth:OAuth, token:OAuthToken):void {
			navigateToURL(new URLRequest(oauth.getAuthorizeURL()));
		}
 
		// return with the provided pin and click the 'Activate' button to get the access token
		protected function activateClickHandler():void {
			twitter.oauth.getAccessToken(pin);
		}
 
		// upon receiving the access token, verify it
		protected function accessTokenHandler(oauth:OAuth, token:OAuthToken):void {
			oauth.verifyAccessToken(token);
		}
 
		// done
		protected function verifyAccessTokenHandler(oauth:OAuth, token:OAuthToken):void {
		}
	}
}

As you can see, it’s extremely easy to use. Not only that, it provides great flexibility. Many libraries are simple to implement, but don’t allow the developer access to certain aspects of the process. With TwitterAspirin, each method returns the loader involved with the operation, giving developers the ability to listen for errors, cancel the operation, or attain the raw API data. The library also uses loader pools to recycle instances, so you can submit a tweet and, while it’s loading, submit another—you don’t have to wait for the first operation to finish. Then, once the operation is complete, the loader is disposed and returned to the pool, which optimizes performance and memory usage.

I’m really excited to see where TwitterAspirin goes and I have nothing but great expectations. Be sure to follow along with development and fork whenever you like.

I started the XMLLoader class a few months back, but didn’t post right away because it needed a lot of cleanup. Not cleanup in the sense of performance improvement or refactoring—it simply used my old programming style, full of dollar signs and underscores. If anyone remembers seeing my code in that form, I deeply apologize for the pain it must have caused your eyes.

So why an XMLLoader class?—because 99% of the data I load with AS3/AIR is in XML format. I stay far from JSON when possible because in AS3 it’s slower than a slug on its day off. XML is native and uses E4X, which lets developers navigate its information just like you would an AS3 tree. I load XML so often, I found myself copying and pasting the same code each time I’d need it—this is the clearest indicator that a class must be written.

Parsing String data to XML poses an issue that many don’t know about. I only discovered it because of the Twitter API. The API is so janked, it sometimes returns the HTML error page instead of the XML response. It wouldn’t be so bad if it weren’t for an image tag in the HTML that isn’t closed. This immediately throws an “XML parser failure: element is malformed” error. Using try/catch is the only way to avoid this. That’s why I wrote it into XMLLoader. It automatically handles the data, attempts to parse it, and, if there are any errors, the load stops and dispatches an error signal.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

package {
	import com.destroytoday.net.XMLLoader;
 
	import flash.display.Sprite;
 
	public class Test extends Sprite {
		public var loader:XMLLoader;
 
		public function Test() {
			loader = new XMLLoader();
 
			loader.retryCount = 2;
			loader.includeResponseInfo = true;
 
			loader.openSignal.add(loaderOpenHandler);
			loader.completeSignal.add(loaderCompleteHandler);
			loader.errorSignal.add(loaderErrorHandler);
 
			loader.load("http://search.twitter.com/search.atom?q=destroytoday");
		}
 
		protected function loaderOpenHandler(loader:XMLLoader):void {
			trace(loader);
		}
 
		protected function loaderCompleteHandler(loader:XMLLoader, data:XML):void {
			trace(loader, data);
		}
 
		protected function loaderErrorHandler(loader:XMLLoader, error:String, message:String):void {
			trace(loader, error, message);
			trace(loader.responseStatus);
		}
	}
}

Speaking of signals, XMLLoader is the first class in DestroyFramework to use Robert Penner’s AS3 Signals instead of events. If you have to ask why, you haven’t been programming in AS3 long enough. Each XMLLoader instance has signals for open, complete, error, and cancel. The class also includes a retryCount property that indicates how many times to attempt to load a URL before calling it quits. Since some APIs can be down one second, then up the next, this feature really comes in handy. It’s mainly intended for handling the beloved fail whale.

The last two features include a cancel method and an includeResponseInfo property. Sure, URLLoader has a cancel method, close, but an exception is thrown if you call close when no operation is in progress. This makes sense, but the runtime shouldn’t close down shop when it happens. XMLLoader instead cancels and dispatches the cancel signal when the cancel method is called, and if no operations are in progress, it simply does nothing.

The includeResponseInfo property is an incredibly easy way to tell the loader to return the response status code and headers upon success or fail. Without XMLLoader, you could get this information with an event listener and the appropriate handler, but it’s far easier to flick a switch. In all honesty, I’ve neglected to retrieve this info using URLLoader in the past simply because it’s such a verbose process. Now that it only requires setting the property to true, I know I’ll use it more often than not.

As always, the source code is available on GitHub. Be sure to keep watch—my account will be pretty active these next few weeks.

Yesterday, during my weekly football “service”, I spent a few minutes starting the ApplicationUtil class. So far, it consists of only two methods, getVersion and closeOpenWindows. The first accesses the application descriptor and returns the application’s version. closeOpenWindows is a necessity I learned in the Apollo days from Christian Cantrell. I had issues with my first AIR app, DestroyFlickr, where it wouldn’t quit, even if all of the visible windows were closed. I commonly use window visibility to show/hide utility windows, so the invisible ones were hanging around, keeping the app open. This method runs a quick loop to close all open windows, visible or not. It also includes an andQuit argument that, when true, sets autoExit to true, which quits the app upon close of the windows. Here’s some unnecessary example code to give this post more character:

1
2
3
4
5
6
7
8
9
10

var version:String = ApplicationUtil.getVersion();
trace(version); // v1
 
trace(NativeApplication.nativeApplication.openedWindows.length); // 3
ApplicationUtil.closeOpenWindows();
trace(NativeApplication.nativeApplication.openedWindows.length); // 0
 
// suppose three windows are open again
ApplicationUtil.closeOpenWindows(true); // closes windows and quits before trace is called
trace(NativeApplication.nativeApplication.openedWindows.length);

I realized I need a more…official…way of debugging my apps, so I wrote the Console class. It’s primary function is to record activity to a specified log file. So far, I have a few methods that write entries—success, error, cancel, and print. I definitely plan to add more, but these are the main ones I intend to use in the near future. Since the name “trace” is off limits in AS3, I referenced my PHP background and named the trace method, “print”.

The class also includes the ability to automatically trace entries to Eclipse’s console along with writing them to a file. Files are written asynchronously, but I also added a delay property that combines entries, so the writing process is less likely to slow down the app. Taking advantage of AIR 2.0’s UncaughtErrors feature, the Console automatically logs fatal errors and their stack traces, if possible. Here’s an example of its usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

var path:String = File.applicationStorageDirectory.nativePath;
 
// params: log file path, LoaderInfo
// automatically writes a session start entry to the log
Console.init(path, loaderInfo);
 
Console.delay = 1000;
Console.traceError = true;
 
// params: id, message
Console.success("wp post", "wrote blog post");
 
// params: id, message
Console.error("wp post", "previous post was depressing");
 
// params: id, message
Console.cancel("Christmas", "why would you want to do that?");
 
// params: message
Console.print("this is a test");

[Fri Dec 18 00:31:31 GMT-0500 2009] Session Start
[Fri Dec 18 00:31:31 GMT-0500 2009] [success] [wp post] wrote blog post
[Fri Dec 18 00:31:31 GMT-0500 2009] [error] [wp post] previous post was depressing
[Fri Dec 18 00:31:31 GMT-0500 2009] [cancel] [Christmas] why would you want to do that?
[Fri Dec 18 00:31:31 GMT-0500 2009] [print] this is a test

I do expect to build the class over time, eventually adding TextField support. In the meantime, the source code is available on GitHub.

I felt like working on something new this past weekend, so I devoted a few hours to the new AIR 2.0 Beta. One feature that really caught my eye is the NativeProcess class, which allows developers to communicate with the system through an executable. This is a game-changer in the AIR world, opening more doors than you or I can ever imagine. I’ve always wanted screen capture support in AIR, so with this new class, I developed it myself.

Surprisingly, my efforts proved successful!—I had a working class, ScreenCapture, and application, ScreenCaptureDemo, up and running within a few hours. Tired of staring at the Spark components, I decided to add a touch of DT to the app by designing my own skin. This took far longer than the core of the app, but made a world of difference. Now that I think of it, this could be considered my first Flex app.

The downside of the NativeProcess class is it nulls the cross-platform benefit of AIR. The developer must compile a .dmg for Mac, a .exe for Windows, and the choice between a few for Linux. Since I only spent this weekend on the ScreenCapture class and I’m only familiar with the Mac command line, both the class and demo app are Mac-only. Also, the demo won’t work just yet for most of you. It requires a prerelease build of AIR 2.0, but things should be okay once the Beta 2 is out.

Download ScreenCaptureDemo (Mac-only, requires AIR 2.0 prerelease)

Along with adding the ScreenCapture class to DestroyFramework, I created a repository for the ScreenCaptureDemo source and installer on GitHub as well. Check them both out and enjoy!

[note] I’m not quite sure why Vimeo decided to cut out the right audio channel in the screencast…

In DestroyTwitter, I make use of the NativeApplication.nativeApplication.startAtLogin property. It allows the app to automatically open whenever the user turns on his computer. It’s a great feature that’s as easy as setting the property to true, though it has a downside. When using ADL (AIR Debug Launcher), if you try to change this property, an error is thrown:

Error: Error #2014: Feature is not available at this time.
	at flash.desktop::NativeApplication/set startAtLogin()

This wouldn’t be a big deal if the developer only experienced the error, but some Linux users run builds that requires AIR apps to launch with ADL. Even though this pertains to only one DestroyTwitter user that I know of, every user deserves the same experience—especially if they do all that fancy command line code. Prior to today, I used the following code to avoid the error:

1
2
3
4
5
6
7
8
9
10
11
12
13

protected var adl:Boolean;
 
public function set openAtStartup(value:Boolean):void {
	if (adl) return;
 
	try {
		adl = false;
 
		NativeApplication.nativeApplication.startAtLogin = value;
	} catch (error:*) {
		adl = true;
	}
}

This works, but I cringe every time I need to use try/catch. While searching the depths of the flash package, looking for a solution, I came across the Capabilities.isDebugger property. It’s exactly what I was looking for, but for some reason, I never knew about it. Here’s the new implementation:

1
2
3
4
5

public function set openAtStartup(value:Boolean):void {
	if (!Capabilities.isDebugger) {
		NativeApplication.nativeApplication.startAtLogin = value;
	}
}

It’s as easy as pie and enables me to remove one more try/catch from my code and another angel gets his wings.

I came across this freakish bug yesterday in DestroyTwitter. As mentioned in a previous post, the next release takes great advantage of ContextMenus. In doing so, I managed to crash ADL without any report to the console or debug views. The problem lies in the data property of the NativeMenuItem class. Setting it to a particular Number will shutdown the app, as if you forgot to press 4 8 15 16 23 42 (LOST reference).

It gets weirder. When I set the property to the Twitter ID of my @destroytwitter account, it busts, which is how I found the issue. BUT! If I set the property to the Twitter ID of either my @destroytoday or @jonniehallman accounts, it works as expected. On top of that, if you convert the Number to a String, it works. If you place the Number within an Object like {id: $id}, it works. Below is the source code, give it a shot. I’m running Flash Builder 4 on Mac OS X 10.6.1. The bug has been submitted to Adobe—I’m dying to find out what causes it.

[note] @jonniehallman is my private test account, not my private personal account. It consists of thousands of tweets like “test”, “test test test”, “yet another test”, and so on.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

package app.test {
	import flash.display.NativeMenu;
	import flash.display.NativeMenuItem;
	import flash.display.Sprite;
	import flash.utils.setTimeout;
 
	public class Test extends Sprite {
		public var _menu:NativeMenu;
 
		public function Test () {
			_menu = new NativeMenu ();
 
			_menu.addItem (new NativeMenuItem ("Open Link"));
 
			setTimeout (__init, 1000);;
		}
 
		private function __init ():void {
			// 14837781 works
			// 14839458 works
			// 2389723 doesn't work
			// 75443589 doesn't work
			_menu.getItemAt (0).data = 75443589;
 
			_menu.display (stage, mouseX, mouseY);
		}
	}
}