Skip to content

Commit 1441f3e

Browse files
niels9001niels9001
committed
Fix
1 parent 38accad commit 1441f3e

3 files changed

Lines changed: 377 additions & 10 deletions

File tree

‎.openpublishing.redirection.json‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,5 @@
11
{
22
"redirections": [
3-
{
4-
"source_path": "hub/apps/design/widgets/widgets-create-a-template.md",
5-
"redirect_url": "/windows/apps/develop/widgets/widgets-create-a-template",
6-
"redirect_document_id": false
7-
},
8-
{
9-
"source_path": "hub/apps/design/style/sound.md",
10-
"redirect_url": "/windows/apps/develop/ui/sound",
11-
"redirect_document_id": false
12-
},
133
{
144
"source_path": "hub/apps/design/app-settings/store-and-retrieve-app-data.md",
155
"redirect_url": "/windows/apps/develop/data/store-and-retrieve-app-data",

‎hub/apps/design/style/sound.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
description: Sound helps complete an application's user experience, and gives them that extra audio edge they need to match the feel of Windows across all platforms.
3+
label: Sound
4+
title: Sound
5+
template: detail.hbs
6+
ms.assetid: 9fa77494-2525-4491-8f26-dc733b6a18f6
7+
ms.date: 05/19/2017
8+
ms.topic: how-to
9+
keywords: windows 10, winui
10+
pm-contact: kisai
11+
design-contact: mattben
12+
dev-contact: joyate
13+
doc-status: Published
14+
ms.localizationpriority: medium
15+
---
16+
# Sound
17+
18+
![hero image](images/header-sound.svg)
19+
20+
There are many ways to use sound to enhance your app. You can use to sound to supplement other UI elements, enabling users to recognize events audibly. Sound can be an effective user interface element for people with visual disabilities. You can use sound to create an atmosphere that immerses the user; for example, you might play a whimsical soundtrack in the background of puzzle game, or use ominous sound effects for a horror/survival game.
21+
22+
## Examples
23+
24+
> [!div class="nextstepaction"]
25+
26+
> [Open the WinUI 3 Gallery app and see Sound in action](winui3gallery://item/Sound)
27+
28+
29+
[!INCLUDE [winui-3-gallery](../../../includes/winui-3-gallery.md)]
30+
31+
32+
## Sound Global API
33+
34+
UWP provides an easily accessible sound system that allows you to simply "flip a switch" and get an immersive audio experience across your entire app.
35+
36+
The [**ElementSoundPlayer**](/uwp/api/windows.ui.xaml.elementsoundplayer) is an integrated sound system within XAML, and when turned on all default controls will play sounds automatically.
37+
```C#
38+
ElementSoundPlayer.State = ElementSoundPlayerState.On;
39+
```
40+
The **ElementSoundPlayer** has three different states: **On** **Off** and **Auto**.
41+
42+
If set to **Off**, no matter where your app is run, sound will never play. If set to **On** sounds for your app will play on every platform.
43+
44+
Enabling ElementSoundPlayer will automatically enable spatial audio (3D sound) as well. To disable 3D sound (while still keeping the sound on), disable the **SpatialAudioMode** of the ElementSoundPlayer:
45+
46+
```C#
47+
ElementSoundPlayer.SpatialAudioMode = ElementSpatialAudioMode.Off
48+
```
49+
50+
The **SpatialAudioMode** property can takes these values:
51+
- **Auto**: Spatial audio will turn on when sound is on.
52+
- **Off**: Spatial audio is always off, even if sound is on.
53+
- **On**: Spatial audio will always play.
54+
55+
To learn more about spatial audio and how XAML handles it see [AudioGraph - Spatial Audio](/windows/uwp/audio-video-camera/audio-graphs#spatial-audio).
56+
57+
## Sound Volume Override
58+
59+
All sounds within the app can be dimmed with the **Volume** control. However, sounds within the app cannot get *louder than the system volume*.
60+
61+
To set the app volume level, call:
62+
```C#
63+
ElementSoundPlayer.Volume = 0.5;
64+
```
65+
Where maximum volume (relative to system volume) is 1.0, and minimum is 0.0 (essentially silent).
66+
67+
## Control Level State
68+
69+
If a control's default sound is not desired, it can be disabled. This is done through the **ElementSoundMode** on the control.
70+
71+
The **ElementSoundMode** has two states: **Off** and **Default**. When not set, it is **Default**. If set to **Off**, every sound that control plays will be muted *except for focus*.
72+
73+
```XAML
74+
<Button Name="ButtonName" Content="More Info" ElementSoundMode="Off"/>
75+
```
76+
77+
```C#
78+
ButtonName.ElementSoundState = ElementSoundMode.Off;
79+
```
80+
81+
## Is this the right sound?
82+
83+
When creating a custom control, or changing an existing control's sound, it is important to understand the usages of all the sounds the system provides.
84+
85+
Each sound relates to a certain basic user interaction, and although sounds can be customized to play on any interaction, this section serves to illustrate the scenarios where sounds should be used to maintain a consistent experience across all WinUI apps.
86+
87+
### Invoking an Element
88+
89+
The most common control-triggered sound in our system today is the **Invoke** sound. This sound plays when a user invokes a control through a tap/click/enter/space or press of the 'A' button on a gamepad.
90+
91+
Typically, this sound is only played when a user explicitly targets a simple control or control part through an [input device](../input/index.md).
92+
93+
94+
To play this sound from any control event, simply call the Play method from **ElementSoundPlayer** and pass in **ElementSound.Invoke**:
95+
```C#
96+
ElementSoundPlayer.Play(ElementSoundKind.Invoke);
97+
```
98+
99+
### Showing & Hiding Content
100+
101+
There are many flyouts, dialogs and dismissible UIs in XAML, and any action that triggers one of these overlays should call a **Show** or **Hide** sound.
102+
103+
When an overlay content window is brought into view, the **Show** sound should be called:
104+
105+
```C#
106+
ElementSoundPlayer.Play(ElementSoundKind.Show);
107+
```
108+
Conversely when an overlay content window is closed (or is light dismissed), the **Hide** sound should be called:
109+
110+
```C#
111+
ElementSoundPlayer.Play(ElementSoundKind.Hide);
112+
```
113+
### Navigation Within a Page
114+
115+
When navigating between panels or views within an app's page (see [NavigationView](../controls/navigationview.md)), there is typically bidirectional movement. Meaning you can move to the next view/panel or the previous one, without leaving the current app page you're on.
116+
117+
The audio experience around this navigation concept is encompassed by the **MovePrevious** and **MoveNext** sounds.
118+
119+
When moving to a view/panel that is considered the *next item* in a list, call:
120+
121+
```C#
122+
ElementSoundPlayer.Play(ElementSoundKind.MoveNext);
123+
```
124+
And when moving to a previous view/panel in a list considered the *previous item*, call:
125+
126+
```C#
127+
ElementSoundPlayer.Play(ElementSoundKind.MovePrevious);
128+
```
129+
### Back Navigation
130+
131+
When navigating from the current page to the previous page within an app the **GoBack** sound should be called:
132+
133+
```C#
134+
ElementSoundPlayer.Play(ElementSoundKind.GoBack);
135+
```
136+
### Focusing on an Element
137+
138+
The **Focus** sound is the only implicit sound in our system. Meaning a user isn't directly interacting with anything, but is still hearing a sound.
139+
140+
Focusing happens when a user navigates through an app, this can be with the gamepad/keyboard/remote or kinect. Typically the **Focus** sound *does not play on PointerEntered or mouse hover events*.
141+
142+
To set up a control to play the **Focus** sound when your control receives focus, call:
143+
144+
```C#
145+
ElementSoundPlayer.Play(ElementSoundKind.Focus);
146+
```
147+
### Cycling Focus Sounds
148+
149+
As an added feature to calling **ElementSound.Focus**, the sound system will, by default, cycle through 4 different sounds on each navigation trigger. Meaning that no two exact focus sounds will play right after the other.
150+
151+
The purpose behind this cycling feature is to keep the focus sounds from becoming monotonous and from being noticeable by the user; focus sounds will be played most often and therefore should be the most subtle.
152+
153+
## Related articles
154+
155+
* [Designing for Xbox and TV](../devices/designing-for-tv.md)
156+
* [ElementSoundPlayer class documentation](/uwp/api/windows.ui.xaml.elementsoundplayer)

0 commit comments

Comments
 (0)