diff --git a/panel/widgets/button.py b/panel/widgets/button.py index 5b9681cadb..e84b7fe7b1 100644 --- a/panel/widgets/button.py +++ b/panel/widgets/button.py @@ -1,5 +1,5 @@ """ -Defines Button and button-like widgets which allow triggering events +Defines the Button and button-like widgets which allow triggering events or merely toggling between on-off states. """ from functools import partial @@ -19,7 +19,9 @@ class _ButtonBase(Widget): - button_type = param.ObjectSelector(default='default', objects=BUTTON_TYPES) + button_type = param.ObjectSelector(default='default', objects=BUTTON_TYPES, doc=""" + A button theme; should be one of 'default' (white), 'primary' (blue), 'success' (green), + 'info' (yellow), 'light' (light), or 'danger' (red).""") _rename = {'name': 'label'} @@ -89,10 +91,26 @@ def jscallback(self, args={}, **callbacks): class Button(_ClickButton): + """The `Button` widget allows triggering events when the button is clicked. + + The Button provides a `value` parameter, which will toggle from `False` to `True` + while the click event is being processed + + It also provides an additional `clicks` parameter, that can be watched to subscribe to click + events. - clicks = param.Integer(default=0) + Reference: https://panel.holoviz.org/reference/widgets/Button.html#widgets-gallery-button - value = param.Event() + :Example: + + >>> pn.widgets.Button(name='Click me', button_type='primary') + """ + + clicks = param.Integer(default=0, doc=""" + Number of clicks (can be listened to)""") + + value = param.Event(doc=""" + Toggles from False to True while the event is being processed.""") _rename = {'clicks': None, 'name': 'label', 'value': None} @@ -115,11 +133,31 @@ def _process_event(self, event): self.clicks += 1 def on_click(self, callback): + """ + Register a callback to be executed when the `Button` is clicked. + + The callback is given an `Event` argument declaring the number of clicks + + Arguments + --------- + callback: (callable) + The function to run on click events. Must accept a positional `Event` argument + """ self.param.watch(callback, 'clicks', onlychanged=False) class Toggle(_ButtonBase): + """The `Toggle` widget allows toggling a single condition between `True`/`False` states. + + This widget is interchangeable with the `Checkbox` widget. + + Reference: https://panel.holoviz.org/reference/widgets/Toggle.html + :Example: + + >>> Toggle(name='Toggle', button_type='success') + """ + value = param.Boolean(default=False, doc=""" Whether the button is currently toggled.""") @@ -135,6 +173,19 @@ def _get_embed_state(self, root, values=None, max_opts=3): class MenuButton(_ClickButton): + """The `MenuButton` widget allows specifying a list of menu items to select from triggering + events when the button 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. + + Reference: https://panel.holoviz.org/reference/widgets/MenuButton.html + + :Example: + + >>> menu_items = [('Option A', 'a'), ('Option B', 'b'), None, ('Option C', 'c')] + >>> MenuButton(name='Dropdown', items=menu_items, button_type='primary') + """ clicked = param.String(default=None, doc=""" Last menu item that was clicked.""") @@ -160,4 +211,14 @@ def _process_event(self, event): self.clicked = item def on_click(self, callback): + """ + Register a callback to be executed when the button is clicked. + + The callback is given an `Event` argument declaring the number of clicks + + Arguments + --------- + callback: (callable) + The function to run on click events. Must accept a positional `Event` argument + """ self.param.watch(callback, 'clicked', onlychanged=False)