{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``Panel`` provides a wide range of widgets to provide precise control over parameter values. The widget classes use a consistent API that allows treating broad categories of widgets as interchangeable. For instance, to select a value from a list of options, you can interchangeably use a ``Select`` widget, a ``RadioButtonGroup``, or a range of other equivalent widgets.\n",
    "\n",
    "Like all other components in ``Panel``, ``Widget`` objects will render and sync their state both in the notebook and on Bokeh server:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widget = pn.widgets.TextInput(name='A widget', value='A string')\n",
    "widget"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Changing the text value will automatically update the corresponding parameter, if you have a live running Python process:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widget.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Updating the parameter value will also update the widget:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widget.value = 'ABCDEFG'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Callbacks and links\n",
    "\n",
    "To listen to a parameter change we can call ``widget.param.watch`` with the parameter to watch and a function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import print_function\n",
    "\n",
    "widget.param.watch(print, 'value')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we change the ``widget.value`` now, the resulting change event will be printed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "widget.value = 'A'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In combination with ``Panel`` objects, widgets make it possible to build interactive dashboards and visualizations very easily. For more detail on defining callbacks and links between widgets and other components see the [Links user guide](Links.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Laying out widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To compose multiple widgets they can be added to a ``Row``, ``Column`` or ``Tabs`` Panel. To learn more about laying out widgets and panels, see the [customization user guide](Customization.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "slider = pn.widgets.FloatSlider(name='Another widget', width=200)\n",
    "pn.Column(widget, slider, width=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Types of Widgets\n",
    "\n",
    "The supported widgets can be grouped into a number of distinct categories with compatible APIs.\n",
    "\n",
    "### Options selectors\n",
    "\n",
    "Option selector widgets allow selecting one or more values from a list or dictionary. All widgets of this type have ``options`` and ``value`` parameters.\n",
    "\n",
    "#### Single values\n",
    "\n",
    "These widgets allow selecting one value from a list or dictionary of options:\n",
    "\n",
    "* **[``AutocompleteInput``](../reference/widgets/AutocompleteInput.ipynb)**: Select a ``value`` by entering it into an auto-completing text field.\n",
    "* **[``DiscretePlayer``](../reference/widgets/DiscretePlayer.ipynb)**: Displays media-player-like controls which allow playing and stepping through the provided options.\n",
    "* **[``DiscreteSlider``](../reference/widgets/DiscreteSlider.ipynb)**: Select a value using a slider.\n",
    "* **[``RadioButtonGroup``](../reference/widgets/RadioButtonGroup.ipynb)**: Select a value from a set of mutually exclusive toggle buttons.\n",
    "* **[``RadioBoxGroup``](../reference/widgets/RadioBoxGroup.ipynb)**: Select a value from a set of mutually exclusive checkboxes.\n",
    "* **[``Select``](../reference/widgets/Select.ipynb)**: Select a value using a dropdown menu.\n",
    "\n",
    "#### Multiple values\n",
    "\n",
    "These widgets allow selecting _multiple_ values from a list or dictionary of options:\n",
    "\n",
    "* **[``CheckBoxGroup``](../reference/widgets/CheckBoxGroup.ipynb)**: Select values by ticking the corresponding checkboxes.\n",
    "* **[``CheckButtonGroup``](../reference/widgets/CheckButtonGroup.ipynb)**: Select values by toggling the corresponding buttons. \n",
    "* **[``CrossSelector``](../reference/widgets/CrossSelector.ipynb)**: Select values by moving items between two lists.\n",
    "* **[``MultiSelect``](../reference/widgets/MultiSelect.ipynb)**: Select values by highlighting in a list.\n",
    "\n",
    "### Type-based selectors\n",
    "\n",
    "Type-based selectors provide means to select a value according to its type, and all have a ``value``. The widgets in this category may also have other forms of validation beyond the type, e.g. the upper and lower bounds of sliders.\n",
    "\n",
    "#### Single value\n",
    "\n",
    "Allow selecting a single ``value`` of the appropriate type:\n",
    "\n",
    "##### Numeric\n",
    "\n",
    "Numeric selectors are bounded by a ``start`` and ``end`` value:\n",
    "\n",
    "* **[``IntSlider``](../reference/widgets/IntSlider.ipynb)**: Select an integer value within a set bounds using a slider.\n",
    "* **[``FloatSlider``](../reference/widgets/FloatSlider.ipynb)**: Select a float value within a set bounds using a slider.\n",
    "* **[``Player``](../reference/widgets/Player.ipynb)**: Displays media-player-like controls, which allow playing and stepping over a range of integer values.\n",
    "\n",
    "##### Boolean\n",
    "\n",
    "* **[``Checkbox``](../reference/widgets/Checkbox.ipynb)**: Toggle a single condition between ``True``/``False`` states by ticking a checkbox.\n",
    "* **[``Toggle``](../reference/widgets/Toggle.ipynb)**: Toggle a single condition between ``True``/``False`` states by clicking a button.\n",
    "\n",
    "##### Dates\n",
    "\n",
    "* **[``DatetimeInput``](../reference/widgets/DatetimeInput.ipynb)**: Enter a datetime value as text, parsing it using a pre-defined formatter. \n",
    "* **[``DatePicker``](../reference/widgets/DatePicker.ipynb)**: Select a date value using a text box and the browser's date-picking utility.\n",
    "* **[``DateSlider``](../reference/widgets/DateSlider.ipynb)**: Select a date value within a set bounds using a slider.\n",
    "\n",
    "##### Text\n",
    "\n",
    "* **[``PasswordInput``](../reference/widgets/PasswordInput.ipynb)**: Enter any string using a password input box.\n",
    "* **[``TextInput``](../reference/widgets/TextInput.ipynb)**: Enter any string using a text input box.\n",
    "* **[``TextAreaInput``](../reference/widgets/TextAreaInput.ipynb)**: Enter any string using a multi-line text input box.\n",
    "\n",
    "##### Other\n",
    "\n",
    "* **[``ColorPicker``](../reference/widgets/ColorPicker.ipynb)**: Select a color using the browser's color-picking utilities.\n",
    "* **[``FileInput``](../reference/widgets/FileInput.ipynb)**: Upload a file from the frontend, making the file data and MIME type available in Python.\n",
    "* **[``LiteralInput``](../reference/widgets/LiteralInput.ipynb)**: Enter any Python literal using a text entry box, which is then parsed in Python.\n",
    "\n",
    "#### Ranges\n",
    "\n",
    "Allow selecting a range of values of the appropriate type stored as a ``(lower, upper)`` tuple on the ``value`` parameter.\n",
    "\n",
    "##### Numeric\n",
    "\n",
    "* **[``IntRangeSlider``](../reference/widgets/IntRangeSlider.ipynb)**: Select an integer range using a slider with two handles.\n",
    "* **[``RangeSlider``](../reference/widgets/RangeSlider.ipynb)**: Select a floating-point range using a slider with two handles.\n",
    "\n",
    "##### Dates\n",
    "\n",
    "* **[``DateRangeSlider``](../reference/widgets/DateRangeSlider.ipynb)**: Select a date range using a slider with two handles.\n",
    "\n",
    "### Other\n",
    "\n",
    "* **[``Button``](../reference/widgets/Button.ipynb)**: Allows triggering events when the button is clicked.  Unlike other widgets, it does not have a ``value`` parameter.\n",
    "* **[``DataFrame``](../reference/widgets/DataFrame.ipynb)**: A widget that allows displaying and editing a Pandas DataFrame.\n",
    "* **[``FileDownload``](../reference/widgets/FileDownload.ipynb)**: A button that allows downloading a file on the frontend by sending the file data to the browser.\n",
    "* **[``Progress``](../reference/widgets/Progress.ipynb)**: A Progress bar which allows updating current the progress towards some goal or indicate an ongoing process."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}