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

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");
  },
));

Overview

Getting Started

Call Session

Features

Advanced

Migration Guide

Resources

Prerequisites

Get CallSession Instance

Set Layout

LayoutType Enum

Set Call Layout Type

Picture-in-Picture Mode

Enable PiP

Disable PiP

Enter PiP Mode

Set Chat Button Unread Count

Listen for Layout Events

Initial Layout Settings

Hide UI Elements

Button Click Listeners

Next Steps

Session Control

Layout Listener

​Prerequisites

​Get CallSession Instance

​Set Layout

​LayoutType Enum

​Set Call Layout Type

​Picture-in-Picture Mode

​Enable PiP

​Disable PiP

​Enter PiP Mode

​Set Chat Button Unread Count

​Listen for Layout Events

​Initial Layout Settings

​Hide UI Elements

​Button Click Listeners

​Next Steps

Session Control

Layout Listener

Prerequisites

Get CallSession Instance

Set Layout

LayoutType Enum

Set Call Layout Type

Picture-in-Picture Mode

Enable PiP

Disable PiP

Enter PiP Mode

Set Chat Button Unread Count

Listen for Layout Events

Initial Layout Settings

Hide UI Elements

Button Click Listeners

Next Steps