You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docusaurus/docs/Android/04-ui-components/05-participants/02-participants-grid.mdx
+24-21Lines changed: 24 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,44 +1,47 @@
1
-
# ParticipantsGrid
1
+
# ParticipantsLayout
2
2
3
-
The `ParticipantsGrid` component is one of our most versatile and complex UI components, designed to render a list of participants in a call. It handles different UI layouts based on the number of participants and different screen orientations. Additionally, it can also render screen sharing content when there is an active session.
3
+
The `ParticipantsLayout` component is one of our most versatile and complex UI components, designed to render a list of participants in a call. It handles different UI layouts based on the number of participants and different screen orientations. Additionally, it can also render screen sharing content when there is an active session.
4
4
5
5
Before jumping into how to use the component and how to customize it, let's review what some of these features mean.
6
6
7
-
What you can do with the `ParticipantsGrid` are:
7
+
What you can do with the `ParticipantsLayout` are:
8
8
9
-
- Displays a grid list of the remote/local participants.
- Displays a list of the remote/local participants.
10
+
- There are two available layouts, Grid and [Spotlight](04-participants-spotlight.mdx)
11
+
- There is also a dynamic option where the layout will switch automatically based on any pinned participants.
12
+
- All the layout variants are supported in portrait and in landscape mode
13
+
- Renders [Screensharing](../04-call/05-screen-share-content.mdx) on demand, regardless of selected layout.
12
14
13
15
### Flexible Layout
14
16
15
-
The `ParticipantsGrid` changes the UI layout based on the number of participants. In calls with fewer than four people, the local participant video is rendered in a floating item, using the [FloatingParticipantVideo](03-floating-participant-video.mdx). In calls with four or more people, it's rendered with other participants in a grid.
17
+
The `ParticipantsLayout` changes the UI layout based on the number of participants. In calls with fewer than four people, the local participant video is rendered in a floating item, using the [FloatingParticipantVideo](03-floating-participant-video.mdx). In calls with six or more people, it's rendered with other participants in a grid.
16
18
17
19
Additionally, the participants are rendered in the following way:
18
20
19
-
***One participant**: Rendered as the only single item in the "grid", taking up the full component space.
21
+
***One participant**: Rendered as the only single item in the layout, taking up the full component space.
20
22
***Two participants** (1 remote + local): The remote participant is rendered within the full component space while the local participant is a floating item.
21
-
***Three participants** (2 remote + local): Remote participants are in a vertical split-screen, while the local participant is a floating item.
22
-
***Four or more participants**: (4 or more remote): Participants are rendered as a grid of items, in a paginated way. Up to 6 participants per page, with the sorted participant.
23
+
***Three to four participants** (2-3 remote + local): Remote participants are in a vertical split-screen, while the local participant is a floating item.
24
+
***Five or more** (4 remote + local): Participants are rendered as a grid of items, in a paginated way. Up to 6 participants per page, with the sorted participant.
23
25
24
26
Sorted participants gives you the list of participants sorted by:
25
-
26
27
* anyone who is pinned
27
-
* dominant speaker
28
28
* if you are screensharing
29
-
* last speaking at
29
+
30
+
If the participants are not visible on the screen they are also sorted by:
31
+
* is dominant speaker
32
+
* has video enabled
33
+
* has audio enabled
30
34
* all other video participants by when they joined
31
-
* audio only participants by when they joined
32
35
33
36
### Orientation
34
37
35
38
The component handles both Landscape and Portrait orientations by rendering different UI. In Portrait mode, the video layout is optimized for standard mobile device rendering, while the landscape mode offers more screen real estate to render video by adding a transparent app bar and pushing the call controls to the side. This is helpful when you need to pay attention to details of the video content of other participants.
36
39
37
40
Additionally, both of these orientations work for screen sharing and adjust the UI accordingly.
The `ParticipantsSpotlight` is a Composable component that allows you to highlight one participant and this one participant takes much of the screen, while the rest are rendered
4
+
either as a horizontal or vertical list depending on orientation.
5
+
6
+
Let's see how to use the `ParticipantsSpotlight`.
7
+
8
+
## Usage
9
+
10
+
To use the `ParticipantsSpotlight` component in your app you can use it direcyly as a component or you can configure the [ParticipantsLayout](02-participants-grid.mdx) to display the spotlight.
11
+
12
+
### Use it directly
13
+
```kotlin
14
+
ParticipantsSpotlight(call = call)
15
+
```
16
+
The only mandatory parameter is `call` which represents the call for which the participants are being displayed.
17
+
18
+
### Use it via [ParticipantsLayout](02-participants-grid.mdx)
19
+
20
+
If you are using the `ParticipantsLayout` you can use an enum value `LayoutType` with one of three options.
21
+
22
+
Those are:
23
+
```kotlin
24
+
//Automatically choose between Grid and Spotlight based on pinned participants and dominant speaker.
25
+
DYNAMIC
26
+
27
+
//Force a spotlight view, showing the dominant speaker or the first speaker in the list.
28
+
SPOTLIGHT
29
+
30
+
//Always show a grid layout, regardless of pinned participants.
31
+
GRID
32
+
```
33
+
34
+
Here is how it looks in action:
35
+
```kotlin
36
+
ParticipantsLayout(
37
+
layoutType =LayoutType.SPOTLIGHT,
38
+
call = call
39
+
)
40
+
```
41
+
42
+
The [ParticipantsLayout](02-participants-grid.mdx) internally displays the `ParticipantSpotlight` in two cases.
43
+
1. You have set the `layoutType` to `LayoutType.SPOTLIGHT` in which case a participant is always spotlighted. The participant shown in the spotlight is chosen based on the following order:
44
+
1. is pinned
45
+
2. is dominantSpeaker
46
+
3. is first in the participants list
47
+
2. You have set the `LayoutType` to `LayoutType.DYNAMIC` in which case if there is a "pinned" participant, the spotlight view will be chosen in favor of grid.
48
+
49
+
*Note*: `ParticipantLayout` will always prioritize screensharing regardless of the `LayoutType` if there is a [screensharing session](../04-call/05-screen-share-content.mdx).s
50
+
51
+
52
+
Using this component, you'll likely see something similar to the following UI:
This is a very simple component so it doesn't have replaceable slots, but it still offers ways to customize its appearance.
64
+
65
+
-`modifier`: Modifier for styling.
66
+
-`isZoomable`: Decide if this spotlight video renderer is zoomable or not.
67
+
-`style`: Defined properties for styling a single video call track.
68
+
-`videoRenderer`: A single video renderer renders each individual participant.
69
+
70
+
If you're looking for guides on how to override and customize this UI, we have various [UI Cookbook](../../05-ui-cookbook/01-overview.mdx) recipes for you and we cover a portion of customization within the [Video Android SDK Tutorial](../../02-tutorials/01-video-calling.mdx).
0 commit comments