# StoryBlock Options

`StoryBlockOption` configures behavior specific to `FwStoryBlockView`. These options control autoplay, fullscreen functionality, appearance, and advanced features unique to the StoryBlock component.

## Overview

`StoryBlockOption` provides configuration for:

* Autoplay and autopause behavior
* Fullscreen icon visibility
* Compact mode sizing
* Jetpack Compose integration
* Vertical swipe gestures
* Immersive mode parameters

## Creating StoryBlockOption

### Using Builder

```kotlin
val storyBlockOption = StoryBlockOption.Builder()
    .enableAutoPlay(true)
    .showFullScreenIcon(true)
    .enableAutoPause(false)
    .build()
```

### Using DSL (Recommended)

```kotlin
val viewOptions = viewOptions {
    storyBlockOptions {
        enableAutoPlay(true)
        showFullScreenIcon(true)
        enableAutoPause(false)
        enableVerticalSwipe(false)
    }
}
```

## Properties

### enableAutoPlay

**Type:** `Boolean`\
**Default:** `true`

Enable or disable automatic video playback when StoryBlock is initialized.

```kotlin
storyBlockOptions {
    enableAutoPlay(true)
}
```

**When enabled:**

* Video starts playing automatically after initialization
* Ideal for story-like experiences

**When disabled:**

* User must tap to start playback
* Better for user-controlled experiences

### showFullScreenIcon

**Type:** `Boolean`\
**Default:** `true`

Show or hide the fullscreen expansion icon in compact mode.

```kotlin
storyBlockOptions {
    showFullScreenIcon(true)
}
```

The fullscreen icon allows users to expand the StoryBlock from compact mode to fullscreen mode.

### enableAutoPause

**Type:** `Boolean`\
**Default:** `false`

Automatically pause when StoryBlock finish playing a video.

```kotlin
storyBlockOptions {
    enableAutoPause(true)
}
```

**Note:** For most cases, use the `pauseWhenNotVisible` parameter in `FwStoryBlockView.init()` instead.

### usedOnJetpackCompose

**Type:** `Boolean`\
**Default:** `false`

Enable optimizations when using StoryBlock with Jetpack Compose.

```kotlin
storyBlockOptions {
    usedOnJetpackCompose(true)
}
```

Set to `true` when integrating StoryBlock in a Compose-based UI for better performance.

### enableSmallSizeInCompact

**Type:** `Boolean`\
**Default:** `false`

Use smaller UI elements in compact mode.

```kotlin
storyBlockOptions {
    enableSmallSizeInCompact(true)
}
```

Reduces the size of UI controls and elements when the StoryBlock is displayed in compact mode.

### handleAppearanceManually

**Type:** `Boolean`\
**Default:** `false`

Manually control appearance/disappearance callbacks.

```kotlin
storyBlockOptions {
    handleAppearanceManually(true)
}
```

When enabled, you're responsible for managing visibility state changes.

### setImmersiveParam

**Type:** `ImmersiveParam`\
**Default:** `ImmersiveParam(topControlsInset = 0)`

Configure top inset for immersive mode.

```kotlin
storyBlockOptions {
    setImmersiveParam(
        ImmersiveParam(topControlsInset = 24.dpToPx())
    )
}
```

Use this to adjust for system UI elements like status bars in immersive fullscreen mode.

### enableVerticalSwipe

**Type:** `Boolean`\
**Default:** `false`

Enable vertical swipe gestures to navigate between videos.

```kotlin
storyBlockOptions {
    enableVerticalSwipe(true)
}
```

When enabled, users can swipe up/down to navigate between videos in the StoryBlock.

### isArrowButtonVisible

**Type:** `Boolean`\
**Default:** `true`

Show or hide the arrow buttons used to navigate between videos in the StoryBlock inline view. When visible, users can tap the arrow buttons to switch to the previous or next video without swiping.

**Applies to:** `FwStoryBlockView` (inline/compact mode). This is distinct from [PlayerOption.isArrowButtonVisible](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/player-options#isarrowbuttonvisible), which controls the arrow buttons in the fullscreen player (`PlayerActivity`).

```kotlin
storyBlockOptions {
    isArrowButtonVisible(false)
}
```

**Behavior:**

* `true` - Arrow navigation buttons are visible in the StoryBlock view
* `false` - Arrow buttons are hidden; users must swipe to navigate between videos

## Default Values

| Property                   | Default Value       |
| -------------------------- | ------------------- |
| `enableAutoPlay`           | `true`              |
| `showFullScreenIcon`       | `true`              |
| `enableAutoPause`          | `false`             |
| `usedOnJetpackCompose`     | `false`             |
| `enableSmallSizeInCompact` | `false`             |
| `handleAppearanceManually` | `false`             |
| `immersiveParam`           | `ImmersiveParam(0)` |
| `enableVerticalSwipe`      | `false`             |
| `isArrowButtonVisible`     | `true`              |

## Complete Examples

### Standard StoryBlock Configuration

```kotlin
class StoryBlockActivity : AppCompatActivity() {
    private lateinit var storyBlock: FwStoryBlockView
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_story_block)
        
        storyBlock = findViewById(R.id.storyBlock)
        
        val viewOptions = viewOptions {
            baseOptions {
                feedResource(FeedResource.Discovery)
            }
            playerOptions {
                playerMode(PlayerMode.FIT_MODE)
            }
            storyBlockOptions {
                enableAutoPlay(true)
                showFullScreenIcon(true)
            }
        }
        
        storyBlock.init(
            fragmentManager = supportFragmentManager,
            lifecycle = lifecycle,
            viewOptions = viewOptions,
            pauseWhenNotVisible = true
        )
    }
    
    override fun onDestroy() {
        super.onDestroy()
        storyBlock.destroy()
    }
}
```

### Vertical Swipe Navigation

```kotlin
val viewOptions = viewOptions {
    baseOptions {
        feedResource(FeedResource.Discovery)
    }
    storyBlockOptions {
        enableAutoPlay(true)
        enableVerticalSwipe(true) // Swipe up/down to navigate
        showFullScreenIcon(true)
    }
}
```

### Compose Integration

```kotlin
val viewOptions = viewOptions {
    storyBlockOptions {
        usedOnJetpackCompose(true)
        enableAutoPlay(true)
        showFullScreenIcon(true)
    }
}
```

### Immersive Mode with Status Bar

```kotlin
val viewOptions = viewOptions {
    playerOptions {
        enableImmersiveMode(true)
    }
    storyBlockOptions {
        setImmersiveParam(
            ImmersiveParam(
                topControlsInset = getStatusBarHeight()
            )
        )
        enableAutoPlay(true)
    }
}

fun getStatusBarHeight(): Int {
    val resourceId = resources.getIdentifier("status_bar_height", "dimen", "android")
    return if (resourceId > 0) resources.getDimensionPixelSize(resourceId) else 0
}
```

## Important Notes

* `enableAutoPlay` affects initial playback only; users can always control playback after
* `showFullScreenIcon` is only visible in compact mode
* Fullscreen mode provides access to all features (shopping, chat, etc.)
* `usedOnJetpackCompose` should be enabled for Compose-based UIs
* `pauseWhenNotVisible` in `init()` is preferred over `enableAutoPause`
* `handleAppearanceManually` is for advanced use cases only
* Vertical swipe gestures may conflict with scroll views
* `ImmersiveParam` helps position content correctly under system UI
* StoryBlock options only apply to `FwStoryBlockView`, not other widgets

## See Also

* [ViewOptions Overview](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration) - Complete configuration system
* [FwStoryBlockView](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/storyblock) - StoryBlock widget guide
* [PlayerOption](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration/player-options) - Player configuration
* [BaseOption](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration/base-options) - Content source configuration