Icon Badge Library for Air
Introduction
Adobe Air is often used to build feed readers or social media clients. This kind of applications can retrieve new data while they are running in the background. In that case it would be great to inform the user about the amount of new items. With OS X you can use the dock icon for that purpose. The Cocoa Framework allows to display a user defined text consistently on top of the application dock tile (icon). E.g. the screenshot at the right shows 2 unread mails in the inbox.
Native and emulated badge
Unfortunately the Air runtime allows no access to this native functionality. Thats why the idea for this library came up. It tries to emulate the native badge with the possibilities Air provides (see left image). Until now only the OS X badge is supported but a Windows implementation is possible, too. I will demonstrate the extensibility in one of the following blog posts.
Demo
If you have a Mac, you can download this Air application where the badge shows up on the real application icon. Running this application on windows will have no visual effect.
None Mac users can use the following demo that shows a preview of the dock icon:
You can browse the sources for this example on the google code repository.
Usage
To show the badge label you can use the static facade AirIconBadge. Internally it will create an IconBadge appropriate for the current operating system. Note: only one implementation for OS X is provided until now! Windows or Linux users won’t see a badge label.
With the static property label you can assign any string that should be displayed. Thats it.
1 | AirIconBadge.label = "1"; |
If you assign an empty string or null, no badge will be displayed. To remove the current badge label you can also call the method clearLabel().
By default the biggest icon defined within the application descriptor will be loaded and shown. If no icon has been defined or the path is incorrect you must assign a customIcon in order to see the label. You can also assign a customIcon if you want to replace the default icon temporarily. Removing the customIcon will show up the default icon again.
1 | AirIconBadge.customIcon = new CustomIconBitmap(); |
If neither of the icons could be loaded, no badge will be displayed. In this case an error event will be dispatched (UpdateErrorEvent). To get status information about the internals you can register for the InformationEvent. Both events will be dispatched by the IconBadge witch is statically stored within the AirIconBadge.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | var iconBadge : IconBadge = AirIconBadge.iconBadge; iconBadge.addEventListener(UpdateErrorEvent.UPDATE_ERROR, handleError); iconBadge.addEventListener(InformationEvent.INFORMATION, handleInformation); function handleError(event : UpdateErrorEvent) : void { // do some error handling } function handleInformation(event : InformationEvent) : void { trace(event.information.toString()); } |
Download
All sources, binaries and examples are available for download under the MIT license.
Whats next
The documentation (especially the ASDocs) will be improved as well as the sources. If you have questions or feature requests, please let my know. The next blog posts will give you a deeper insight in the architecture and extensibility of this library.
Great Idea and exactly what I need for my current application
Unfortunately I´m getting an osx exception while changing the label at runtime. Only happens outside the debugger.
”
Process: AirBadgeExample [10716]
Path: /Applications/Example/AirBadgeExample.app/Contents/MacOS/AirBadgeExample
Identifier: AirBadgeExample.BE4FC688BE28993DE1D05E6AB4B9871A369A8FB5.1
Version: 1.0 (???)
Code Type: X86 (Native)
Parent Process: launchd [951]
Date/Time: 2010-03-28 03:07:28.670 +0200
OS Version: Mac OS X 10.6.2 (10C540)
[..]
Exception Type: EXC_BAD_ACCESS (SIGBUS)
Exception Codes: KERN_PROTECTION_FAILURE at 0×0000000000000170
Crashed Thread: 0 Dispatch queue: com.apple.main-thread
[..]
”
Using latest AIR release.
Any idea?
Haven´t tried swapping dock icons without your lib yet. Probably an AIR bug?!
Thanks for your feedback. I just tested it with the latest Air beta release myself and had no problems updating the badge (same OS X version as you have).
Maybe you are not using the latest Air version? I tested with 2.0.0.11670. You can find your exact version number in /Library/Frameworks/Adobe AIR.framework/Versions/1.0/Resources/Info.plist.
But anyway, this seems to be an Air bug as it crashes with an OS X exception. Please let me know if you find out what causes this bug.
Mattes,
I tested the lib in my application and I get the same crash every time around 20 seconds after startup.
I tracked the error down to the DropShadowFilter on the DockBagdgeBackground (no exception without filters… which is strange enough)… could be a garbage collector issue or something?!
I´m using AIR 2.0.0.10760.
One more thing: The AIR badge using a different color than the original osx badge? The osx badge uses something like 205,60,30.
No matter how long I ran the example, I didn’t get this exception. Could you please update your Air runtime to be sure it is not an issue of an older beta version?
Regarding the color. I picked it from the original badge. But it is not exactly the same color. On my uncalibrated monitor it looks pretty much the same. The current color is a gradient from 254,2,2 to 240,0,0. Compared with yours (205,60,30) I can’t see a difference on my monitor.
Anyway, I compiled a new library version with your color, you can download it here: http://blog.mattes-groeger.de/uploads/air-icon-badge-0.1.swc
By the way, do you know what the exact font type of the OS X badge is? I was not able to find the right one. Thanks in advance.
You are right, my fault. Always forget I´m working with beta code
. Works with the latest AIR release.
Thanks for the change on the badge color.
What about an optional parameter “badgeColor” for future releases? Would be cool to have it even more flexible than the orignal badge.
Anyway, great Lib!
Glad to here that it now works with the latest beta release!
The reason I built this library was to provide a consistent way for Air applications to use the icon badge on OS X. Allowing to customize the color would break this consistency. Maybe I change my mind in the future but for now you have to implement your custom badge if you want to change the appearance (or compile your own swc version).