Before we get started diving into custom chrome you should ask yourself if you really need to use it.  There is a performance cost associated with creating your own custom chrome.  It also takes longer to create custom chrome, so not only will your app be slower, it will take longer to develop.  Additionally (man, I’m really making custom chrome sound like a bad idea, huh?) making a custom skin for your app may decrease usability as you’ll be forcing your users to become accustomed to an interfaces that differs from the standard one their OSes present.

So custom chrome may not be a good idea.  Then again, it can really set your app apart and to I’ve yet to see an AIR app resource-intense enough that the performance penalty for using custom chrome would really matter.  Since you’re reading this you’ve probably already decided to go ahead and use a custom skin for you application so let’s get to it.

The first thing to do is open up your application’s XML descriptor file.  In this file there are two items of interest so far as chrome is concerned:

1. systemChrome and
2. transparent

SystemChrome is a flag that tells your application to either use the “standard” chrome (i.e., the OS’s chrome) or “none”.  Since we want to use custom chrome set this to “none”.

Transparent is a flag that sets your application window to be transparent.  It takes a value of “true” or “false”.  You can only use this when systemChrome is set to none.  If you are going to use an unusual shape for you application, like a beer glass, set this to “true” so you won’t have a square application window floating around.

If you were to run your app at this point you’d see you still have a title bar with maximize, minimize and close buttons.  If you’re going custom you probably want to go all out and make your own title bar, or not as you may not even want a traditional title bar.  The chrome you are seeing now is called “FlexChrome” and to get rid of it you need to make an edit to your application’s MXML file.  In the WindowedApplication tag add an attribute, “showFlexChrome” and set it to “false”:

<WindowedApplication
showFlexChrome="false"/>

When you run your app now you’ll no longer have a title bar or any maximize, minimize or close buttons.  You also can no longer drag your application.  Using system or Flex chrome offers a lot of functionality for free so we’ve got some work to do to get it back.  Beer Near Here Desktop does not support maximizing or minimizing so I’ll only be adding a close button and some drag functionality.  Adding maximize and minimize should work in a similar manner to closing.  But first, we’ll throw in a background so we have something to look at.

The Beer Near Here Desktop application window is exactly 550 pixels wide and 830 pixels tall.  The background beer glass you see when the app loads is 532 pixels wide and 800 pixels tall.  Why the difference?  When you do a search another image is laid on top of the application, dimming it and effectively disabling most of the buttons.  This overlay image is 550×830 pixels.

So the first thing I did was set the width and height for the entire application in the WindowedApplication tag:

<WindowedApplication
showFlexChrome="false"
width="550" height="830"/>

I then added an mx:Image control inside WindowedApplication:

<mx:Image
top="0" left="0"
id="background"
width="532" height="800"
source="images/loading-anim/00.png"/>

Running the app now shows a nice glass of beer.  In fact, get a beer now, it’ll make this more fun.

Okay, I’m back with my beer

So we now have our app running with a custom background image but we can’t move it or close it.  Well, we can close it, but we have to rely on the OS for that rather than the application itself.  For now you can close the app by either right-clicking the application in the Windows start bar or the Mac OS dock and choosing the close command.  Since the background is in place and it’s easy to do we’ll implement some dragging next.

// This drags your application
NativeApplication.nativeApplication.activeWindow.stage.nativeWindow.stage.nativeWindow.startMove();

The above is a nice, long line of Actionscript that will drag your application.  To make use of it you’ll have to import the flash.desktop.NativeApplication package into your application.  To drag the application we are going to listen for the mouse down event on the background image we added earlier.  To handle this we’ll need an event listener:

private function _dragStart(event:MouseEvent):void
{
NativeApplication.nativeApplication.activeWindow.stage.nativeWindow.stage.nativeWindow.startMove();
}

Now that we have our event listener we can wire it up to the background image:

// Add the drag event listener
background.addEventListeners(MouseEvent.MOUSE_DOWN, _dragStart);

This wires the mouse down event to call the _dragStart method thus our app will be dragged so long as the mouse button is held down over the app.  Easy enough, right?  There is one slight catch: this only works if the background image is clicked.  This means that if you place another image on top of the background image like I did with the Beer Near Here logo, clicking in the logo area will not initiate a drag — you’ll have to add a mouse down event listener to this other image (or whatever you added) as well.  There is a nice part to this as well as transparent areas of the background image do not register clicks.  So, while the application window and background image for BNHD are actually rectangular if you click in the transparent part of the application you’ll actually click through to whatever is beneath the application.

Taking stock of the situation we have an application with a custom background image that can be dragged by clicking the background and dragging the mouse.  In the final part of this post we’ll add a close button so we can close the app without relying on the user’s operating system.  To accomplish this with BNHD I created an ImageButton component which can be found in my Flex Library (there is some documentation on this component, hopefully I’ll have a demo soon-ish).

The ImageButton component is very straightforward: you give it an image for the button, an image for the button’s hover state and a function to call when it is clicked.  If you don’t want to use ImageButton you can use any clickable control.  So code for the ImageButton looks like this:

<smorg:ImageButton
id="closeBtn"
image="@Embed('images/close-btn.png')"
hoverImage="@Embed('images/close-hover-btn.png')"
click="_closeApp();"
right="85" top="19"
width="42" height="42"/>

Of interest here is the _closeApp function.  Here’s the function:

private function _closeApp()
{
var exitingEvent:Event = new Event(Event.EXITING, false, true);
NativeApplication.nativeApplication.dispatchEvent(exitingEvent);
if (!exitingEvent.isDefaultPrevented())
{
NativeApplication.nativeApplication.exit();
}
}

This function creates and dispatches an Event.EXITING event.  This announces our intent to close the application.  The function then checks if the event’s default behavior is being prevent, that is, is there something else going on with the app that is preventing us from exiting?  BNHD is simple and this case never comes up, but it’s good to be prepared.  Assuming the default event behavior is not prevented, and it never is, we exit the application.

That’s the basic rundown of how I setup Beer Near Here Desktop.  Now it is a bit more involved but most of the details are rather specific to BNHD so I don’t really think they deserve much attention here with two exceptions.  The first is the loading/searching animation that drains the beer glass.  This was a lot of work and I think it turned out awesome.  This will probably be the topic of the next AIR post.

The second is the loading overlay image I mentioned above.  This overlay ended up serving a purpose beyond my initial intent quite nicely.  Originally I planned simply to use it to dim the background while the app was doing any “thinking” type operations (loading, searching, et cetera) to draw attention to any pop ups.  It does this well enough but by placing well within the app’s MXML file I was also able to use it to effectively disable all the controls in the main app window during any thinking operations.

If you load up BNHD and do a search you’ll see that all of the controls in the main app window become unclickable except for the close button (and, of course, any controls in the popup).  Rather than write a method that enables and disables all these controls I just ordered them within the MXML document such that all of them would be beneath the overlay image except the close button (and popups).  This allows users to exit at any time but not to click buttons they shouldn’t and cause havoc.  Perhaps a useful trick if you plan to do any custom loading overlays or animations with your application.

Until next time.

Read Part 5.