Layout Listener

Monitor layout changes with LayoutListeners. This listener provides callbacks for call layout changes, participant list visibility, and Picture-in-Picture (PiP) mode state changes.

Prerequisites

An active call session
Access to the CallSession instance

Register Listener

Set the layoutListener on the CallSession to receive layout event callbacks:

final callSession = CallSession.getInstance();

callSession?.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 the layout listener in your widget’s dispose() method to prevent memory leaks.

Callbacks

onCallLayoutChanged

Triggered when the call layout changes between Tile and Spotlight modes.

onCallLayoutChanged: (LayoutType layoutType) {
  debugPrint("Layout changed to: $layoutType");

  switch (layoutType) {
    case LayoutType.tile:
      // Update UI for tile layout
      setState(() => _currentLayout = LayoutType.tile);
      break;
    case LayoutType.spotlight:
      // Update UI for spotlight layout
      setState(() => _currentLayout = LayoutType.spotlight);
      break;
  }
}

LayoutType Values:

Value	Description
`LayoutType.tile`	Grid layout showing all participants equally
`LayoutType.spotlight`	Focus on active speaker with others in sidebar

Use Cases:

Update layout toggle button icon
Adjust custom UI overlays
Log layout preference analytics

onParticipantListVisible

Triggered when the participant list panel becomes visible.

onParticipantListVisible: () {
  debugPrint("Participant list opened");
  // Track analytics
  // Adjust UI if needed
  setState(() => _isParticipantListVisible = true);
}

Use Cases:

Log analytics events
Adjust custom UI elements
Pause other UI animations

onParticipantListHidden

Triggered when the participant list panel is hidden.

onParticipantListHidden: () {
  debugPrint("Participant list closed");
  // Restore UI
  setState(() => _isParticipantListVisible = false);
}

Use Cases:

Restore UI elements
Resume animations
Update button states

onPictureInPictureLayoutEnabled

Triggered when Picture-in-Picture (PiP) mode is enabled.

onPictureInPictureLayoutEnabled: () {
  debugPrint("PiP mode enabled");
  // Hide non-essential UI elements
  setState(() => _isPipEnabled = true);
}

Use Cases:

Hide call control buttons
Simplify UI for small window
Track PiP feature usage

onPictureInPictureLayoutDisabled

Triggered when Picture-in-Picture (PiP) mode is disabled.

onPictureInPictureLayoutDisabled: () {
  debugPrint("PiP mode disabled");
  // Restore full UI
  setState(() => _isPipEnabled = false);
}

Use Cases:

Restore call control buttons
Show full call UI
Resume normal layout

Complete Example

Here’s a complete example handling all layout events:

import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
import 'package:flutter/material.dart';

class CallScreen extends StatefulWidget {
  const CallScreen({super.key});

  @override
  State<CallScreen> createState() => _CallScreenState();
}

class _CallScreenState extends State<CallScreen> {
  CallSession? _callSession;
  LayoutType _currentLayout = LayoutType.tile;
  bool _isParticipantListVisible = false;
  bool _isPipEnabled = false;

  @override
  void initState() {
    super.initState();
    _callSession = CallSession.getInstance();
    _setupLayoutListener();
  }

  void _setupLayoutListener() {
    _callSession?.layoutListener = LayoutListeners(
      onCallLayoutChanged: (LayoutType layoutType) {
        if (mounted) {
          setState(() => _currentLayout = layoutType);
        }
      },
      onParticipantListVisible: () {
        if (mounted) {
          setState(() => _isParticipantListVisible = true);
          debugPrint("Participant list visible");
        }
      },
      onParticipantListHidden: () {
        if (mounted) {
          setState(() => _isParticipantListVisible = false);
          debugPrint("Participant list hidden");
        }
      },
      onPictureInPictureLayoutEnabled: () {
        if (mounted) {
          setState(() => _isPipEnabled = true);
          debugPrint("PiP enabled");
        }
      },
      onPictureInPictureLayoutDisabled: () {
        if (mounted) {
          setState(() => _isPipEnabled = false);
          debugPrint("PiP disabled");
        }
      },
    );
  }

  @override
  void dispose() {
    // Must manually remove listener to prevent memory leaks
    _callSession?.layoutListener = null;
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // Call UI content here
          if (!_isPipEnabled)
            Positioned(
              bottom: 16,
              left: 0,
              right: 0,
              child: Row(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  // Layout toggle button
                  IconButton(
                    icon: Icon(
                      _currentLayout == LayoutType.tile
                          ? Icons.grid_view
                          : Icons.person,
                    ),
                    tooltip: _currentLayout == LayoutType.tile
                        ? "Switch to spotlight"
                        : "Switch to tile",
                    onPressed: () async {
                      final newLayout = _currentLayout == LayoutType.tile
                          ? LayoutType.spotlight
                          : LayoutType.tile;
                      await _callSession?.setLayout(newLayout);
                    },
                  ),
                  // PiP button
                  IconButton(
                    icon: const Icon(Icons.picture_in_picture),
                    tooltip: "Enter PiP mode",
                    onPressed: () async {
                      await _callSession?.enterPipMode();
                    },
                  ),
                ],
              ),
            ),
        ],
      ),
    );
  }
}

Remove Listener

Remove the layout listener in your widget’s dispose() method to prevent memory leaks:

@override
void dispose() {
  _callSession?.layoutListener = null;
  super.dispose();
}

Controlling Layout Programmatically

You can change the layout and PiP state programmatically:

Change Layout

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

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

Enable/Disable PiP

// Enable Picture-in-Picture
await CallSession.getInstance()?.enablePictureInPictureLayout();

// Disable Picture-in-Picture
await CallSession.getInstance()?.disablePictureInPictureLayout();

Initial Layout Configuration

Set the initial layout when joining a session:

final sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .setLayout(LayoutType.tile)  // or LayoutType.spotlight
    .hideChangeLayoutButton(false)  // Allow users to change layout
    .build();

Callbacks Summary

Callback	Parameter	Description
`onCallLayoutChanged`	`LayoutType`	Call layout changed (tile/spotlight)
`onParticipantListVisible`	-	Participant list panel opened
`onParticipantListHidden`	-	Participant list panel closed
`onPictureInPictureLayoutEnabled`	-	PiP mode was enabled
`onPictureInPictureLayoutDisabled`	-	PiP mode was disabled

Overview

Getting Started

Call Session

Features

Advanced

Migration Guide

Resources

Prerequisites

Register Listener

Callbacks

onCallLayoutChanged

onParticipantListVisible

onParticipantListHidden

onPictureInPictureLayoutEnabled

onPictureInPictureLayoutDisabled

Complete Example

Remove Listener

Controlling Layout Programmatically

Change Layout

Enable/Disable PiP

Initial Layout Configuration

Callbacks Summary

Next Steps

Layout & UI

Session Settings

​Prerequisites

​Register Listener

​Callbacks

​onCallLayoutChanged

​onParticipantListVisible

​onParticipantListHidden

​onPictureInPictureLayoutEnabled

​onPictureInPictureLayoutDisabled

​Complete Example

​Remove Listener

​Controlling Layout Programmatically

​Change Layout

​Enable/Disable PiP

​Initial Layout Configuration

​Callbacks Summary

​Next Steps

Layout & UI

Session Settings

Prerequisites

Register Listener

Callbacks

onCallLayoutChanged

onParticipantListVisible

onParticipantListHidden

onPictureInPictureLayoutEnabled

onPictureInPictureLayoutDisabled

Complete Example

Remove Listener

Controlling Layout Programmatically

Change Layout

Enable/Disable PiP

Initial Layout Configuration

Callbacks Summary

Next Steps