diff --git a/Doc/lib/libwinsound.tex b/Doc/lib/libwinsound.tex index 53b7256ad75..a873b9e7c82 100644 --- a/Doc/lib/libwinsound.tex +++ b/Doc/lib/libwinsound.tex @@ -40,21 +40,49 @@ two functions and several constants. \begin{datadesc}{SND_FILENAME} The \var{sound} parameter is the name of a WAV file. + Do not use with \constant{SND_ALIAS}. \end{datadesc} \begin{datadesc}{SND_ALIAS} - The \var{sound} parameter should be interpreted as a control panel - sound association name. + The \var{sound} parameter is a sound association name from the registry. + If the registry contains no such name, play the system default sound + unless \constant{SND_NODEFAULT} is also specified. + If no default sound is registered, raise RuntimeError. + Do not use with \constant{SND_FILENAME). + + All Win32 systems support at least the following; most systems support + many more: + + \begin{verbatim} + PlaySound argument Corresponding Control Panel -> Sounds name + ------------------ ------------------------------------------ + 'SystemAsterisk' Asterisk + 'SystemExclamation' Exclamation + 'SystemExit' Exit Windows + 'SystemHand' Critical Stop + 'SystemQuestion' Question + \end{verbatim} + + For example, + + \begin{verbatim} + # Play Windows exit sound. + winsound.PlaySound("SystemExit", winsound.SND_ALIAS) + + # Probably play Windows default sound, if any is registered (because + # "*" probably isn't the registered name of any sound). + winsound.PlaySound("*", winsound.SND_ALIAS) + \end{verbatim} \end{datadesc} \begin{datadesc}{SND_LOOP} Play the sound repeatedly. The \constant{SND_ASYNC} flag must also - be used to avoid blocking. + be used to avoid blocking. Cannot be used with \constant{SND_MEMORY}. \end{datadesc} \begin{datadesc}{SND_MEMORY} The \var{sound} parameter to \function{PlaySound()} is a memory - image of a WAV file. + image of a WAV file, as a string. \strong{Note:} This module does not support playing from a memory image asynchronously, so a combination of this flag and @@ -70,7 +98,8 @@ two functions and several constants. \end{datadesc} \begin{datadesc}{SND_NODEFAULT} - If the specified sound cannot be found, do not play a default beep. + If the specified sound cannot be found, do not play the system default + sound. \end{datadesc} \begin{datadesc}{SND_NOSTOP} diff --git a/PC/winsound.c b/PC/winsound.c index b3b1baef5a6..e182db536b6 100644 --- a/PC/winsound.c +++ b/PC/winsound.c @@ -59,7 +59,7 @@ static char sound_beep_doc[] = static char sound_module_doc[] = "PlaySound(sound, flags) - play a sound\n" "SND_FILENAME - sound is a wav file name\n" -"SND_ALIAS - sound is a control panel sound association name\n" +"SND_ALIAS - sound is a registry sound association name\n" "SND_LOOP - Play the sound repeatedly; must also specify SND_ASYNC\n" "SND_MEMORY - sound is a memory image of a wav file\n" "SND_PURGE - stop all instances of the specified sound\n"