Learn Adobe AIR, Part I: Build A Note Storage App

Working with the Clipboard

When creating notes, a user may have content stored in their operating system’s clipboard that they want to insert into our application as a note. AIR provides access to the clipboard quite easily, so let’s check it when we display the New Note form. Replace your ShowNewNote function with the following lines:

function ShowNewNote() {    
 if (air.Clipboard.generalClipboard.hasFormat(    
   air.ClipboardFormats.TEXT_FORMAT)){    
     $("#data").val(air.Clipboard.generalClipboard.getData(    
       air.ClipboardFormats.TEXT_FORMAT));    
 }    
 $("#new_note_form").show();    
}

In the above code snippet, lines 2–4, check whether there is any plaintext data on the clipboard. If there is, we copy that data into the main content area of our New Note form. It would be possible to extend this functionality to include other data formats as well, including rich text and HTML—check out the clipboard data formats in the AIR documentation if you’d like to experiment some more.

If we wanted to take this application even further, we could offer a simple “copy” function for each individual note. This functionality is already supported by most major browsers, but AIR goes one step further by allowing us to directly manipulate the contents of the general clipboard. If you’re interested in exploring this functionality, the official AIR documentation does a good job of explaining how to read from and write to the system clipboard, and includes some great code examples.

Closing an Application

Chances are we’ll want to let our user close our note storage application easily. Let’s create a File > Exit menu item, to give our application a touch of desktop familiarity. First, open up notes_menus.xml and add the line in bold below:

<?xml version="1.0" encoding="utf-8"?>    
<root>    
 <menuitem label="File">    
   <menuitem label="_New Note" onSelect="ShowNewNote" />    
   <menuitem label="E_xit" onSelect="QuitNotes" />    
 </menuitem>    
</root>

We’ve set the mnemonic on the x of “Exit”—common practice in Windows desktop apps.

We can close the application by calling the method air.NativeApplication.nativeApplication.exit. However, AIR provides a sophisticated event system designed to deal with more complex operations that applications may need to perform. One of these operations is to prevent default actions. Given that we may want to temporarily disable the capacity of our user to exit the application—for example, during an asynchronous delete-all-notes database operation—we’ll use this approach instead.

There’s a preventDefault method in air.Event that will, not surprisingly, prevent AIR from executing an event’s default action. In our case, this event is called air.Event.EXITING, and the routines throughout our application should all take this approach. We can check if the default exit action is being prevented by another area of the application using a simple procedure:

function QuitNotes() {    
 var event = new air.Event(air.Event.EXITING, false, true);    
 air.NativeApplication.nativeApplication.dispatchEvent(event);    
 if (!event.isDefaultPrevented()) {    
   air.NativeApplication.nativeApplication.exit();    
 }    
}

Place this function at the end of your notes.js file, and your user will no longer be able to terminate the application when it’s in the middle of something important. The AIR docs provide more information about handling application termination.

Finishing up

That’s it for our note storage application! If you hit any hurdles along the way, you can download the final project files to compare with your own. To use these files, simply import them into a new AIR project in Aptana (select File > Import > Archive File). Aptana also allows you to easily package the application as an AIR file for deployment. Click the air button on your Aptana toolbar. In the Adobe AIR Package Exporter dialog that appears, just confirm that the right project is selected, and that the application descriptor is called application.xml. To minimize file size, feel free to remove the AIR localizer and the excess jQuery files, then click Finish and an AIR package will be created for you. Here’s what your completed package should look like.

Further reading

AIR is a very powerful platform, and by using familiar web technologies, it has an extremely low barrier of entry. In this tutorial, we used our existing JavaScript skills and the powerful jQuery library to create a practical AIR application. Along the way, we looked at how AIR implements menu items, writes to a database, manages events, and more.

If this article has excited you enough to develop more with Adobe AIR, you’re in luck—next week we’ll be publishing a follow-up article, which builds on the principles we learned here.. If you can’t wait, however, be sure to visit the official AIR guide on adobe.com, Developing HTML/AJAX applications on Adobe AIR. This resource contains a number of comprehensive guides covering all the major areas of AIR development, as well as links to other great tutorials. And once you’ve exhausted the documentation, head to the Adobe AIR Developer Center for HTML and Ajax for some terrific, focused tutorials. So what are you waiting for? Get running on AIR!

Quiz Yourself

Test your understanding of this article with a short quiz, and receive a FREE copy of the pocket guide, Adobe AIR For JavaScript Developers, delivered to your door for FREE, thanks to Adobe Systems. This offer is only available to the first 100 people, so get in quick (if you miss out, you can also download the book in PDF format for free).

Take the quiz!