Layout & UI

Control the call layout and UI elements during an active session. These methods allow you to change the call layout, enable Picture-in-Picture mode, and update UI badges.

Prerequisites

• An active call session
• Access to the CallSession instance

Get CallSession Instance

Layout and UI methods are called on the CallSession singleton:

CallSession? callSession = CallSession.getInstance();

CallSession.getInstance() returns null if no active session exists. Always use the null-aware ?. operator when calling methods.

---

Set Layout

Change the call layout during an active session.

// Switch to tile layout (grid view)
await CallSession.getInstance()?.setLayout(LayoutType.tile);

// Switch to spotlight layout (active speaker focus)
await CallSession.getInstance()?.setLayout(LayoutType.spotlight);

// Switch to sidebar layout
await CallSession.getInstance()?.setLayout(LayoutType.sidebar);

LayoutType Enum

Value	Description
LayoutType.tile	Grid layout showing all participants equally sized
LayoutType.spotlight	Focus on the active speaker with others in smaller tiles
LayoutType.sidebar	Main speaker with participants in a sidebar

When the layout changes, the onCallLayoutChanged(LayoutType) callback is triggered on your LayoutListener.

---

Set Call Layout Type

Alias for setLayout(). Changes the call layout.

await CallSession.getInstance()?.setCallLayoutType(LayoutType.tile);

---

Picture-in-Picture Mode

Enable Picture-in-Picture (PiP) mode to allow users to continue viewing the call while using other apps.

Enable PiP

await CallSession.getInstance()?.enablePictureInPictureLayout();

Disable PiP

await CallSession.getInstance()?.disablePictureInPictureLayout();

Enter PiP Mode

Enter the system Picture-in-Picture mode directly.

await CallSession.getInstance()?.enterPipMode();

PiP behavior differs between platforms. Android uses the system PiP window, while iOS uses a custom overlay. Use isPipSupported() to check availability before calling this method.

---

Set Chat Button Unread Count

Update the badge count on the chat button to show unread messages.

// Set unread count
await CallSession.getInstance()?.setChatButtonUnreadCount(5);

// Clear unread count
await CallSession.getInstance()?.setChatButtonUnreadCount(0);

Parameter	Type	Description
count	int	Number of unread messages to display on the badge

The chat button must be visible (hideChatButton(false)) for the badge to appear.

---

Listen for Layout Events

Register a LayoutListener to receive callbacks when layout changes occur:

CallSession.getInstance()?.layoutListener = LayoutListeners(
  onCallLayoutChanged: (LayoutType layoutType) {
    debugPrint("Layout changed to: $layoutType");
  },
  onParticipantListVisible: () {
    debugPrint("Participant list is now visible");
  },
  onParticipantListHidden: () {
    debugPrint("Participant list is now hidden");
  },
  onPictureInPictureLayoutEnabled: () {
    debugPrint("PiP mode enabled");
  },
  onPictureInPictureLayoutDisabled: () {
    debugPrint("PiP mode disabled");
  },
);

Flutter listeners are not lifecycle-aware. You must manually remove listeners in your widget’s dispose() method to prevent memory leaks.

---

Initial Layout Settings

Configure the initial layout when joining a session:

SessionSettings sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .setLayout(LayoutType.tile)  // Start with tile layout
    .build();

---

Hide UI Elements

Control the visibility of various UI elements:

SessionSettings sessionSettings = CometChatCalls.SessionSettingsBuilder()
    // Panels
    .hideControlPanel(false)         // Show bottom control bar
    .hideHeaderPanel(false)          // Show top header bar
    .hideSessionTimer(false)         // Show session duration timer

    // Buttons
    .hideChangeLayoutButton(false)   // Show layout toggle button
    .hideChatButton(false)           // Show chat button
    .hideParticipantListButton(false) // Show participant list button
    .build();

---

Button Click Listeners

Listen for UI button clicks to implement custom behavior:

CallSession.getInstance()?.addButtonClickListener(ButtonClickListeners(
  onChangeLayoutButtonClicked: () {
    debugPrint("Layout button clicked");
  },
  onChatButtonClicked: () {
    debugPrint("Chat button clicked");
    // Open your chat UI
  },
  onParticipantListButtonClicked: () {
    debugPrint("Participant list button clicked");
  },
));

Next Steps

Session Control

Leave session and hand raise controls

Layout Listener

Handle all layout events