Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 7 - Sound / Using Sound

PlaySound Errata

The *PlaySound function was inadvertently omitted from the Sound chapter in Newton Programmer's Guide for Newton 2.0 and Newton Programmer's Reference. This function was documented for the 1.x system, still works the same under the 2.1 OS, and is documented again in this chapter for completeness.

Note however, it is not the recommended way to play sounds due to interactions with the user preference settings related to sound. *PlaySound honors user preference settings for pen, alarm, and action sound effects by comparing the sound frame passed as its argument to the "typical" sound effects; for example, *PlaySound(ROM_click) is silent when pen sound effects are turned off. This behavior can produce unfortunate side-effects, the most notable being that GetRoot():SysBeep() does nothing when the alert sound is the same as the alarm sound and alarm sound effects are disabled.

Rather than *PlaySound, it is recommended that you use a sound channel or the functions *PlaySoundEffect, PlaySoundIrregardless, or PlaySoundIrregardlessAtVolume. The function *PlaySoundEffect is preferred to all other versions of *PlaySound for playing pen, alarm, and action sound effects.

The function PlaySoundAtVolume is not recommended, since it calls *PlaySound and thus is subject to the same limitations.

All of these functions (besides *PlaySound) are documented in Newton Programmer's Reference.