{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import panel_material_ui as pmui\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Player` widget provides media-player like controls to step through a range of integer frames. It is built on the [Material UI Slider](https://mui.com/material-ui/react-slider/), [IconButton](https://mui.com/material-ui/react-button/#icon-button) and [ToggleButtonGroup](https://mui.com/material-ui/react-toggle-button/) components.\n",
    "\n",
    "The speed at which the widget plays is defined by the `interval` (in milliseconds) and it is possible to advance more than one frame per update using the `step` parameter. The animation itself runs in the browser, so a `Player` keeps working in a static HTML export.\n",
    "\n",
    "It falls into the broad category of single-value, bounded, numeric widgets that provide a compatible API and include the [`IntSlider`](IntSlider.ipynb) and [`DiscretePlayer`](DiscretePlayer.ipynb) widgets.\n",
    "\n",
    "Discover more on using widgets to add interactivity to your applications in the [how-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html). Alternatively, learn [how to set up callbacks and (JS-)links between parameters](https://panel.holoviz.org/how_to/links/index.html) or [how to use them as part of declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html).\n",
    "\n",
    "#### Parameters:\n",
    "\n",
    "For details on other options for customizing the component see the [customization guides](https://panel-material-ui.holoviz.org/customization/index.html).\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **`direction`** (`int`): The current play direction: `-1` plays in reverse, `0` is paused and `1` plays forward.\n",
    "* **`disabled`** (`boolean`): Whether the widget is editable.\n",
    "* **`interval`** (`int`): The interval between updates in milliseconds. Default is 500, i.e. two updates per second.\n",
    "* **`loop_policy`** (`Literal[\"once\", \"loop\", \"reflect\"]`): What to do when the player reaches the last frame. `'once'` stops, `'loop'` wraps around and `'reflect'` reverses the direction.\n",
    "* **`step`** (`int`): The number of frames to advance on each update or button press.\n",
    "* **`start`** (`int`): The lower bound of the frame range.\n",
    "* **`end`** (`int`): The upper bound of the frame range.\n",
    "* **`value`** (`int`): The current frame. Updated on every frame while playing and while the slider is dragged.\n",
    "* **`value_throttled`** (`int`): The current frame. Updated on every frame while playing but only once the slider handle is released.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`color`** (`str`): The color of the slider and of the active transport button.\n",
    "* **`label`** (`str`): The title of the widget.\n",
    "* **`preview_duration`** (`int`): How long (in milliseconds) the slower/faster buttons display the resulting frame rate before reverting to their icon.\n",
    "* **`scale_buttons`** (`float`): A scaling factor applied to the transport buttons.\n",
    "* **`show_loop_controls`** (`boolean`): Whether the loop policy controls are shown.\n",
    "* **`show_value`** (`boolean`): Whether to display the current value.\n",
    "* **`size`** (`Literal[\"small\", \"medium\", \"large\"]`): The size of the slider and the transport buttons.\n",
    "* **`value_align`** (`Literal[\"start\", \"center\", \"end\"]`): The alignment of the label and value row.\n",
    "* **`variant`** (`Literal[\"full\", \"minimal\"]`): Whether to render the stacked `'full'` player or the single-row `'minimal'` player.\n",
    "* **`visible_buttons`** (`list[str]`): The transport buttons to display. One or more of `'slower'`, `'first'`, `'previous'`, `'reverse'`, `'pause'`, `'play'`, `'next'`, `'last'` and `'faster'`.\n",
    "* **`visible_loop_options`** (`list[str]`): The loop policies to offer.\n",
    "\n",
    "##### Styling\n",
    "\n",
    "- **`sx`** (`dict`): Component level styling API.\n",
    "- **`theme_config`** (`dict`): Theming API.\n",
    "\n",
    "##### Aliases\n",
    "\n",
    "For compatibility with Panel certain parameters are allowed as aliases:\n",
    "\n",
    "- **`name`**: Alias for `label`\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Usage\n",
    "\n",
    "The `Player` steps through the frames between `start` and `end`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "player = pmui.Player(label='Frame', start=0, end=10, value=3)\n",
    "\n",
    "player"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like most other widgets, `Player` has a `value` parameter that can be accessed or set:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "player.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead of `start` and `end` you may declare the number of frames with the `length` keyword, which expands to `start=0, end=length-1`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Player(label='Frame', length=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variants\n",
    "\n",
    "The `variant` parameter controls the layout. The default `'full'` player stacks the label, the slider, the transport buttons and the loop controls, while the `'minimal'` player collapses everything into a single row consisting of a play/pause toggle, the slider and (if `show_value`) the value. Use it when the player has to fit into a toolbar or sit directly below a plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Column(\n",
    "    pmui.Player(label='Full', length=10, show_value=True),\n",
    "    pmui.Player(label='Minimal', length=10, show_value=True, variant='minimal'),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Loop Policy\n",
    "\n",
    "The `loop_policy` determines what happens when the player reaches the end of the range. `'once'` stops, `'loop'` wraps back to the first frame and `'reflect'` reverses the direction. The policy can also be changed from the toggle group below the buttons, which can be restricted with `visible_loop_options` or hidden entirely with `show_loop_controls=False`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Column(\n",
    "    pmui.Player(label='Once', length=10, loop_policy='once'),\n",
    "    pmui.Player(label='Loop', length=10, loop_policy='loop'),\n",
    "    pmui.Player(label='Reflect', length=10, loop_policy='reflect'),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Controlling Playback from Python\n",
    "\n",
    "The `play`, `pause` and `reverse` methods (and the `direction` parameter they set) drive the player from Python:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "controlled = pmui.Player(label='Frame', length=20, interval=200)\n",
    "\n",
    "pmui.Column(\n",
    "    controlled,\n",
    "    pmui.Row(\n",
    "        pmui.Button(label='Play', on_click=lambda _: controlled.play()),\n",
    "        pmui.Button(label='Pause', on_click=lambda _: controlled.pause()),\n",
    "        pmui.Button(label='Reverse', on_click=lambda _: controlled.reverse()),\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visible Buttons\n",
    "\n",
    "Use `visible_buttons` to render a subset of the nine transport buttons."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Player(label='Frame', length=10, visible_buttons=['previous', 'play', 'pause', 'next'], show_loop_controls=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Show Value\n",
    "\n",
    "Set `show_value=True` to display the current frame next to the label. Its placement is controlled by `value_align`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Column(\n",
    "    pmui.Player(label='Start', length=10, show_value=True, value_align='start'),\n",
    "    pmui.Player(label='Center', length=10, show_value=True, value_align='center'),\n",
    "    pmui.Player(label='End', length=10, show_value=True, value_align='end'),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Color\n",
    "\n",
    "You can specify a `color`, which is applied to the slider and to the button matching the current `direction`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Player(label='Frame', length=10, color='secondary')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sizes\n",
    "\n",
    "Use `size` to scale the slider and the buttons and `scale_buttons` to scale the buttons on their own."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Column(\n",
    "    pmui.Player(label='Small', length=10, size='small'),\n",
    "    pmui.Player(label='Medium', length=10, size='medium'),\n",
    "    pmui.Player(label='Scaled buttons', length=10, scale_buttons=1.5),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disabled\n",
    "\n",
    "The widget can be disabled with `disabled=True`, which also stops playback."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Player(label='Frame', length=10, disabled=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Reference\n",
    "\n",
    "#### Basic Usage"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pmui.Player(label='Frame', length=10).api(jslink=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### References\n",
    "\n",
    "**Panel Documentation:**\n",
    "\n",
    "- [How-to guides on interactivity](https://panel.holoviz.org/how_to/interactivity/index.html) - Learn how to add interactivity to your applications using widgets\n",
    "- [Setting up callbacks and links](https://panel.holoviz.org/how_to/links/index.html) - Connect parameters between components and create reactive interfaces\n",
    "- [Declarative UIs with Param](https://panel.holoviz.org/how_to/param/index.html) - Build parameter-driven applications\n",
    "\n",
    "**Material UI Slider:**\n",
    "\n",
    "- [Material UI Slider Reference](https://mui.com/material-ui/react-slider/) - Complete documentation for the underlying Material UI component\n",
    "- [Material UI Slider API](https://mui.com/material-ui/api/slider/) - Detailed API reference and configuration options"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.14.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}