Introduction to the Apple Classes

Starting with Mac OS X 10.4.3, Apple provides you with a set of JavaScript classes that make it easy to incorporate common controls and utilities into your widget. These classes, called Apple Classes, include:

• A scroll area and scroll bars

• Sliders

• Animation timers

• Buttons, including the standard glass-style button

• The Info button

The Apple Classes are found in /System/Library/WidgetResources/AppleClasses/ and can be used from there or from within your widget, depending on whether backward compatibility is a concern.

Including an Apple Class

There are two ways to use any Apple Class in your widget: so that your widget is backward compatible with Mac OS X versions 10.4 to 10.4.2, or so your widget runs on Mac OS X 10.4.3 and later.

Backwards Compatible Usage

Since the Apple Classes are included with Mac OS X starting with version 10.4.3, you may want to use a class yet deploy the widget on Mac OS X versions 10.4 to 10.4.2. To do this, follow these steps:

1. Copy the needed Apple Classes out of /System/Library/WidgetResources/ into a folder, named AppleClasses, at the top level of your widget's bundle.

2. In your main HTML file, include the needed classes using a local file path, like this:

   <script type='text/javascript' src='AppleClasses/AppleInfoButton.js' charset='utf-8'/>

3. In your Info.plist information property list file, include the key BackwardsCompatibleClassLookup and set its value to the boolean value YES.

By copying the needed Apple Classes inside in your widget and including the local copy in your main HTML file, your widget uses the local copies, ensuring that the classes are available to your widget no matter what version of Mac OS X v.10.4 the widget is running on.

Note that the Info.plist key BackwardsCompatibleClassLookup has special meaning on Mac OS X v.10.4.3 and later. When Dashboard sees this key and any <script> tag that includes a file with AppleClasses/ as the first part of its path, it automatically provides your widget with the corresponding version located in /System/Library/WidgetResources/ instead of the local copy. This allows you to use the most up-to-date version of an Apple Class in future versions of Mac OS X while retaining backward compatibility with earlier versions of Mac OS X v.10.4.

For Widgets on Mac OS X v.10.4.3 and Later

If you intend for your widget to only work on Mac OS X version 10.4.3 and later, you can omit any backward compatibility steps and just include the JavaScript files for the needed classes at the their location in /System/Library/WidgetResources/, like this:

<script type='text/javascript' src='/System/Library/WidgetResources/AppleClasses/AppleInfoButton.js' charset='utf-8'/>

Using an Apple Class

Read these articles to learn more about the Apple Classes and how to use them: