26.5 Auditory Cues

SDK 1.4 introduced a framework for providing auditory cues in response to user interface actions without the complexity of adding an auxiliary L&F. Core support is provided by BasicLookAndFeel through an audio action map (see Table B-45 in Appendix B) that is available for use by subclasses.

It should be noted that, although the framework is in place, none of the standard L&Fs activate any sounds, at least as of SDK 1.4.1. Comments in the source code indicate that the activation has been temporarily disabled due to bugs in sound playback. So although this is an interesting area to watch, and you should feel free to experiment with customizations to activate various sounds, until Sun decides auditory cues are ready to be unleashed, it's probably best not to rely on them.

With that caveat, here's how the mechanism is set up. When getAudioActionMap( ) is called for the first time in BasicLookAndFeel, a series of initialization steps occur, with many opportunities for customization of the sort described in the next section:

1. The UI defaults are consulted to look up the list of sounds to be loaded, under the key "auditoryCues.cueList". This is how Table B-45 gets its values.

2. For each cue, createAudioAction( ) is called to create the actual Action object that plays the sound. BasicLookAndFeel uses Java Sound to load and play named audio files, and the Metal L&F takes advantage of this mechanism, as shown in Table 26-5 (the files are in the javax.swing.plaf.metal.sounds package within the runtime JAR). The Windows L&F takes a different approach and maps the cues in the list to appropriate Windows desktop properties so they reflect the choices made in the user's native desktop themes. This mapping is shown in Table 26-6.

   Table 26-5. Auditory cues mapped to sound files in MetalLookAndFeel

   Auditory cue	File
   CheckBoxMenuItem.commandSound	MenuItemCommand.wav
   InternalFrame.closeSound	FrameClose.wav
   InternalFrame.maximizeSound	FrameMaximize.wav
   InternalFrame.minimizeSound	FrameMinimize.wav
   InternalFrame.restoreDownSound	FrameRestoreDown.wav
   InternalFrame.restoreUpSound	FrameRestoreUp.wav
   MenuItem.commandSound	MenuItemCommand.wav
   OptionPane.errorSound	OptionPaneError.wav
   OptionPane.informationSound	OptionPaneInformation.wav
   OptionPane.questionSound	OptionPaneQuestion.wav
   OptionPane.warningSound	OptionPaneWarning.wav
   PopupMenu.popupSound	PopupMenuPopup.wav
   RadioButtonMenuItem.commandSound	MenuItemCommand.wav

   Table 26-6. Auditory cues mapped to desktop properties in WindowsLookAndFeel

   Auditory cue	Desktop property
   CheckBoxMenuItem.commandSound	win.sound.menuCommand
   InternalFrame.closeSound	win.sound.close
   InternalFrame.maximizeSound	win.sound.maximize
   InternalFrame.minimizeSound	win.sound.minimize
   InternalFrame.restoreDownSound	win.sound.restoreDown
   InternalFrame.restoreUpSound	win.sound.restoreUp
   MenuItem.commandSound	win.sound.menuCommand
   OptionPane.errorSound	win.sound.hand
   OptionPane.informationSound	win.sound.asterisk
   OptionPane.questionSound	win.sound.question
   OptionPane.warningSound	win.sound.exclamation
   PopupMenu.popupSound	win.sound.menuPopup
   RadioButtonMenuItem.commandSound	win.sound.menuCommand

3. Once the audio actions are created, BasicLookAndFeel associates each action with a sound file to be played when the action is performed. A protected method and inner AudioAction class provide support for this approach, and it's used by the Metal L&F, as shown in Table 26-5. Other L&Fs can override this and use different mechanisms to produce appropriate sounds; the Windows L&F does this to provide a link between the Java auditory cues and the sounds defined by the user's native desktop sound themes, which may change even while the Java application is running.

The UI delegates within the Basic L&F have been enhanced to trigger sounds at appropriate times. When one of these classes wishes to play a sound, it calls BasicLookAndFeel.playSound( ), passing in the corresponding Action. The playSound( ) method doesn't always play the sound. It first checks to see if the action is present in the list contained in the UI defaults entry "AuditoryCues.playList". This list gives applications a chance to turn particular cues on and off, and it's here that the current implementation has blocked sounds from actually playing. If there were no sound bugs, the Metal L&F would include the sounds for the four kinds of OptionPane cues, and the Windows L&F would include all sound cues, in this list. At press time, the play list is always left empty. When playSound( ) finds the action in the play list, it invokes the action's actionPerformed( ) method to produce the sound.

There are a variety of ways to customize the sounds produced for the auditory cues. The discussion of the Windows L&F approach illustrates the most complex: you can create a custom L&F that overrides the mechanisms in BasicLookAndFeel that load and produce sounds. Without going nearly that far you can still achieve a great deal. By taking advantage of the UI defaults mechanism you can alter the sound used by default for a particular cue simply by setting up a link to your own audio file. For example:

UIManager.put("PopupMenu.popupSound", "myGreatBloop.au");

Finally, you can assign specific cues to a particular component by storing values in its own ActionMap. In this case you need to create the Action that plays the sound and assign it to the map. Suppose you have a menuItem that you want to play a special sound, which you encapsulated as myMenuSoundAction. Here's the code you'd use:

ActionMap menuMap = menuItem.getActionMap( ); menuMap.put("MenuItem.commandSound", myMenuSoundAction);

We hope this auditory cue mechanism will soon be reliable enough to be active in the shipping SDK so that we can all start taking advantage of it. In the meantime, this discussion of customization has been a good setup for the next topic.