Designing Widgets

Now that you know how to assemble a basic widget, you can start thinking about which higher-level features you want to add to your own widget. Before going any further, you should consider how your widget presents itself to the user.

Generally speaking, widget interface design isn't as constrained to Apple Human Interface Guidelines as Cocoa or Carbon applications are. Despite this freedom, there are basic software design principles that should be followed. This chapter presents some guidelines that you should consider when creating your widget.

Main Interface Design Guidelines

The main face of your widget is the front side (your widget displays preferences on its back). This is the side users recognize and interact with the most.

Follow these guidelines as you design your widget’s front side:

Figure 8  A cluttered widget is a jack of all trades, master of none
A cluttered widget is a jack of all trades, master of none
Figure 9  Three simple widgets, each focused on a single task
Three simple widgets, each focused on a single taskThree simple widgets, each focused on a single task
Figure 10  A large widget monopolizes valuable screen space
A large widget monopolizes valuable screen space
Figure 11  A small widget provides information and leaves room for other widgets
A small widget provides information and leaves room for other widgets
Figure 12  Color makes your widget stand out—can you spot the Calendar?
Color makes your widget stand out—can you spot the Calendar?
Figure 13  An offensive widget–be careful with color!
An offensive widget–be careful with color!
Figure 14  Aqua controls don’t belong on the face of your widget
Aqua controls don’t belong on the face of your widget
Figure 15  A widget with custom controls
A widget with custom controls
Figure 16  Don’t waste valuable space in your widget with advertising
Don’t waste valuable space in your widget with advertising
Figure 17  Put information not vital to the widget on the back
Put information not vital to the widget on the back

Widget Back Side Design Guidelines

If your widget requires configuration, you can display preferences on the back of your widget. Here are some tips for designing your widget’s back:

Figure 18  A non-standard control for showing your widget’s back
A non-standard control for showing your widget’s back
Figure 19  The standard info button—users know what this means
The standard info button—users know what this means
Figure 20  Proper info button placement
Proper info button placement
Figure 21  Aqua controls on a widget’s back
Aqua controls on a widget’s back
Figure 22  Different backgrounds distinguish between front and back
Different backgrounds distinguish between front and back
Figure 23  Branding is appropriate on a widget’s back
Branding is appropriate on a widget’s back

Widget Bar Icons

Widgets are represented by an icon in the widget bar. The dimensions below define the standard icon size and shadow for a widget bar icon:

Other Tips

Follow these tips when designing and implementing your widget.

Widget Programming

  • Use JavaScript whenever possible. Animation and widget logic is possible using JavaScript and results in faster execution and a smaller memory footprint.

  • Use custom Widget and WebKit plug-ins sparingly. Plug-ins add significant complexity to your widget and should only be used whenever a task isn’t possible using JavaScript.

  • Avoid using Java applets, Flash animations, and QuickTime movies. They are heavyweight and take up a considerable amount of memory.

Drop Shadows

Widget backgrounds tend to feature drop shadows. The dimensions below define the standard drop shadow for a widget:

  • 50% opacity

  • 90 degree angle from horizontal

  • 4 pixel offset (distance from source)

  • 10 pixel size, using Gaussian blur

Integrated Menus

As previously noted, you should design unique, custom controls that integrate well into your widget’s overall design instead of using standard Aqua controls. Displaying a menu in this context is common and features an implementation that is a little unusual but not difficult to make work.

First, you need to design a custom control that resembles a popup menu, like the Voices sample code does:

Figure 24  Voice’s popup menu fits in with its design
Voice’s popup menu fits in with its design

Note the characteristics shared between an Aqua popup menu and the custom control used here: the arrow icons, the left aligned text, and a defining outline that specifies the bounds of the control. Also, note the differing color versus the widget’s background. These are all things to take into account when making your own custom menu control.

Three elements, one of which is unseen here, make this menu work: an image that represents the popup menu, a line of text that shows the current menu option, and, unseen here, a hidden <select> popup menu element that provides the actual menu used to select an option.

Implementing Your Custom Menu Control

After designing your popup menu, you need to set up three elements in HTML: the popup image you designed, a text element that reflects the currently selected menu option, and a <select> element that holds your actual menu:

<img class="popupMenuImage" src="Images/Menu.png" />
<div id="popupMenuText">Available Voices</div>
<select id='popupMenu' onchange='popupChanged(this);'>
        <option value="One">One</option>
        <option value="Two">Two</option>
</select>

Now that the elements are in place, position them using CSS. The menu image is placed first, with the text over it. The linchpin is the <select> element, which provides the menu when clicked; it’s placed over the text and image, but its opacity is set to zero.

.popupMenuImage {
    position: absolute;
    left: 28px;
    top: 169px;
    z-index: 18;
}
 
#popupMenuText {
    font: 13px "Helvetica Neue";
    font-weight: Bold;
    color: white;
    text-shadow: black 0px 1px 0px;
    position: absolute;
    left: 44px;
    top: 176px;
    z-index: 19;
}
 
#popupMenu {
    position:absolute;
    top: 169px;
    left: 28px;
    width: 163px;
    height: 30px;
    opacity: 0.0;
    z-index: 20;
}

Doing this makes your custom image look like the control being clicked, but in reality, the <select> receives the click and displays its menu. Rest assured that while the popup menu itself is transparent, the menu shown is opaque.

The final piece is changing the custom popup menu text when a user chooses an option in the menu. In the HTML, a function is set that’s called when the popup’s selection changes. This function changes the menu text to reflect the new selection:

function popupChanged(elem)
{
    var chosenOption = elem.options[elem.selectedIndex].value;
    document.getElementById("popupMenuText").innerText = chosenOption;
 
    // Other code that handles the menu selection change
}

Search Fields

Many widgets feature a search field that allows users to find content that your widget displays. WebKit offers a new type of <input> type, called search that provides the look and behavior of a standard search field for a widget:

<input type="search">

In addition to the search type of the <input> element, these attributes are available when this type is used:

placeholder

Allows you to specify placeholder text for the search field; this text is shown inside the field when it does not have key focus and should be a label indication what type of input it expects.

results

Allows you to specify how many results are saved. Saved search terms are displayed in a menu that’s displayed when the search field’s magnifying glass is clicked upon.

onsearch

Allows you to specify a handler that is called when the enter or return keys are pressed.

incremental

Including this attribute means that the onsearch handler is called every time a character is entered into the search field.

onkeypress

Allows you to specify a handler that is called when any key is pressed.

Help Tags

Many applications feature help tags that appear to users as they hold their cursor over an element. Your widget should display help tags for controls and any other elements that would benefit from further explanation. To provide a help tag for an element, use the title attribute:

<div id="helloText" title="This is a helpful explanation of this element">Hello, World!</div>

Universal Access

OS X v.10.4 "Tiger" includes a new feature named VoiceOver. VoiceOver is a system-wide screen reader that benefits visually impaired users by audibly describing the current window.

To ensure that VoiceOver properly describes your widget, you need to take two things into account when creating it:

  • In your HTML, structure your elements logically. If your widget has a top-down orientation, make sure the corresponding HTML elements are in an order that reflects their orientation. Likewise, if your widget displays its information from the left to the right, make sure that the left-most element is the first in your HTML and that each subsequent section follows in the file’s structure.

  • Use alt attributes to describe images. VoiceOver reads these aloud when it comes to an image in your widget:

<img src="sun.png" alt="Sunny">