SubAspectComponentOptions class

Configuration options for the SubAspectComponent widget.

Defines styling, sizing, and builder hooks for a responsive sub-video area (e.g., screenshare preview, secondary video, controls overlay) typically positioned at the bottom-left of the screen. Supports dynamic height calculation based on viewport dimensions and control visibility state.

Properties:

• backgroundColor: Default background color when containerDecoration is null
• children: List of widgets to render in Stack (e.g., video stream, audio cards, controls)
• showControls: Visibility flag (true = container visible with computed dimensions; false = height collapses to 0)
• containerWidthFraction: Optional width as fraction of screen width (0.0-1.0). Defaults to 1.0 (full width)
• containerHeightFraction: Optional height as fraction of screen height (0.0-1.0). Takes precedence over defaultFractionSub
• defaultFractionSub: Height calculation fallback. If ≤1: fraction of screen height (e.g., 0.3 = 30%); if >1: fixed pixel height (e.g., 40.0 = 40px). Defaults to 40.0 pixels
• padding: Inner padding for container content area
• margin: Outer margin around container
• alignment: Child alignment within container (defaults to Alignment.centerLeft)
• containerDecoration: Optional BoxDecoration for borders, gradients, shadows (overrides backgroundColor)
• clipBehavior: Clipping behavior for Stack children (defaults to Clip.hardEdge)
• contentBuilder: Hook to wrap Stack of children (receives defaultContent = Stack with all children)
• containerBuilder: Hook to wrap Container with dimensions/styling (receives child = processed content, computed width/height)
• wrapperBuilder: Hook to wrap Positioned widget (receives container = styled container, defaultWrapper = Positioned at bottom-left)

Dimension Calculation Logic:

Width:
  = (containerWidthFraction ?? 1.0) * screenWidth
  Clamped to [0.0, 1.0] range before multiplication

Height (when showControls = true):
  If containerHeightFraction provided:
    = containerHeightFraction * screenHeight (clamped to [0.0, 1.0])
  Else if 0 < defaultFractionSub ≤ 1:
    = defaultFractionSub * screenHeight (fractional mode)
  Else if defaultFractionSub > 1:
    = defaultFractionSub (fixed pixel mode)
  Else:
    = 40 pixels (minimum fallback)

Height (when showControls = false):
  = 0 (collapses container)

Builder Hook Flow:

1. Create Stack with children → defaultContent
2. contentBuilder?(defaultContent) → content
3. Wrap content in Container with dimensions → defaultContainer
4. containerBuilder?(content, width, height) → container
5. Wrap container in Positioned(bottom: 0, left: 0) → defaultWrapper
6. wrapperBuilder?(container) → wrapper
7. Wrap wrapper in Visibility(showControls)

Common Configurations:

// 1. Fixed pixel height (e.g., 150px control bar at bottom)
SubAspectComponentOptions(
  backgroundColor: Colors.black87,
  children: [controlButtonsWidget],
  defaultFractionSub: 150.0, // pixels
)

// 2. Fractional height (e.g., 30% of screen for screenshare preview)
SubAspectComponentOptions(
  backgroundColor: Colors.grey[900]!,
  children: [screensharePreview],
  containerHeightFraction: 0.3, // 30% of screen height
  containerWidthFraction: 0.5,   // 50% of screen width
)

// 3. Custom positioning (e.g., top-right instead of bottom-left)
SubAspectComponentOptions(
  backgroundColor: Colors.transparent,
  children: [miniVideoPreview],
  defaultFractionSub: 0.25,
  wrapperBuilder: (context) {
    return Positioned(
      top: 16,
      right: 16,
      child: context.container,
    );
  },
)

// 4. Rounded container with shadow
SubAspectComponentOptions(
  backgroundColor: Colors.white,
  children: [videoStreamWidget],
  defaultFractionSub: 200.0,
  containerDecoration: BoxDecoration(
    borderRadius: BorderRadius.circular(12),
    boxShadow: [BoxShadow(color: Colors.black38, blurRadius: 8)],
  ),
  padding: EdgeInsets.all(8),
  margin: EdgeInsets.all(16),
)

Typical Use Cases:

• Screenshare preview area (fractional sizing, positioned at bottom)
• Control button overlay (fixed pixel height, full width)
• Secondary video stream (mini player in corner)
• Audio-only participant grid (compact list at bottom)
• Meeting timer/status bar (fixed height, left-aligned)