{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``MenuButton`` widget allows specifying a list of menu items to select from, triggering events when a menu item is clicked. Unlike other widgets, it does not have a ``value`` parameter. Instead it has a ``clicked`` parameter that can be watched to trigger events and which reports the last clicked menu item.\n",
    "\n",
    "Discover more on using widgets to add interactivity to your applications in the [how-to guides on interactivity](../how_to/interactivity/index.md). Alternatively, learn [how to set up callbacks and (JS-)links between parameters](../../how_to/links/index.md) or [how to use them as part of declarative UIs with Param](../../how_to/param/index.html).\n",
    "\n",
    "#### Parameters:\n",
    "\n",
    "For details on other options for customizing the component see the [layout](../../how_to/layout/index.md) and [styling](../../how_to/styling/index.md) how-to guides.\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **``clicked``** (str): The last clicked menu item\n",
    "* **``items``** (list(tuple or str or None):  Menu items in the dropdown. Allows strings, tuples of the form (title, value) or Nones to separate groups of items.\n",
    "* **``split``** (boolean): Whether to add separate dropdown area to button.\n",
    "\n",
    "##### Display\n",
    "\n",
    "* **`button_style`** (str): The button style, either ``'solid'`` or ``'outline'``.\n",
    "* **``button_type``** (str): A button theme; should be one of ``'default'`` (white), ``'primary'`` (blue), ``'success'`` (green), ``'info'`` (yellow), ``'light'`` (light), or ``'danger'`` (red)\n",
    "* **`icon`** (str): An icon to render to the left of the button label. Either an SVG or an icon name which is loaded from [tabler-icons.io](https://tabler-icons.io)/.\n",
    "* **`icon_size`** (str): Size of the icon as a string, e.g. 12px or 1em.\n",
    "* **``disabled``** (boolean): Whether the widget is editable\n",
    "* **``name``** (str): The title of the widget\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `MenuButton` is defined by the name of the button and a *list of items* corresponding to the menu items.\n",
    "\n",
    "The items can be single string values or as below tuples of string values. By separating items by `None` we can group them into sections:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "menu_items = [('Option A', 'a'), ('Option B', 'b'), ('Option C', 'c'), None, ('Help', 'help')]\n",
    "\n",
    "menu_button = pn.widgets.MenuButton(name='Dropdown', items=menu_items, button_type='primary')\n",
    "\n",
    "pn.Column(menu_button, height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``clicked`` parameter will report the last menu item that was clicked:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "menu_button.clicked"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can `bind` to the `clicked` parameter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def handle_selection(clicked):\n",
    "    return f'You clicked menu item: \"{clicked}\"'\n",
    "\n",
    "pn.Column(\n",
    "    menu_button,\n",
    "    pn.bind(handle_selection, menu_button.param.clicked),\n",
    "    height=200\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``on_click`` method can trigger a function when a menu item is clicked:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "text = pn.widgets.TextInput(value='Ready')\n",
    "\n",
    "def b(event):\n",
    "    text.value = f'You clicked menu item: \"{event.new}\"'\n",
    "    \n",
    "menu_button.on_click(b)\n",
    "\n",
    "pn.Row(menu_button, text, height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Button Type\n",
    "\n",
    "The color of the button can be set by selecting one of the available button types:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.Column(*(pn.widgets.MenuButton(name=p, button_type=p, items=menu_items) for p in pn.widgets.MenuButton.param.button_type.objects))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Split Menu\n",
    "\n",
    "Additionally we can move the dropdown indicator into a separate area using the split option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "split_menu_button = pn.widgets.MenuButton(name='Split Menu', split=True, items=menu_items, button_type=\"primary\")\n",
    "pn.Column(split_menu_button, pn.bind(handle_selection, split_menu_button.param.clicked), height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the button itself is clicked in `split` mode, the `clicked` property will report the value of the `name` parameter, i.e. in this case clicking it will set the `clicked` parameter to `'Split Menu'`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Icons\n",
    "\n",
    "The ``MenuButton`` name and its `items` may contain Unicode characters and emojis, providing a convenient way to define common graphical buttons.\n",
    "\n",
    "For the button it self, you can use more advanced icons by providing an svg `icon` value or a named `icon` loaded from [tabler-icons.io](https://tabler-icons.io):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "file_items = [\"\\U0001F4BE Save\", \"🚪 Exit\"]\n",
    "help_items = [\"⚖️ License\", None, \"\\U0001F6C8 About\"]\n",
    "pn.Column(pn.Row(\n",
    "    pn.widgets.MenuButton(name=\"File\", icon=\"file\", items=file_items, width=75, button_type=\"light\"),\n",
    "    pn.widgets.MenuButton(name=\"🧏🏻‍♂️ Help\", items=help_items, width=100, button_type=\"light\"),\n",
    "    styles={\"border-bottom\": \"1px solid black\"}\n",
    "    ), height=200, \n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Controls\n",
    "\n",
    "The `MenuButton` widget exposes a number of options which can be changed from both Python and Javascript. Try out the effect of these parameters interactively:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pn.Row(menu_button.controls, menu_button)"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}