#424 review and API improvements

nicegui/elements/icon.py

@@ -1,16 +1,31 @@
+from typing import Optional
+
 from ..element import Element
 
 
 class Icon(Element):
 
-    def __init__(self, name: str) -> None:
+    def __init__(self,
+                 name: str,
+                 *,
+                 size: Optional[str] = None,
+                 color: Optional[str] = None,
+                 ) -> None:
         """Icon
 
-        Displays an icon.
+        This element is based on Quasar's `QIcon <https://quasar.dev/vue-components/icon>`_ component.
 
         `Here <https://material.io/icons/>`_ is a reference of possible names.
 
-        :param name: the name of the icon
+        :param name: name of the icon
+        :param size: size in CSS units, including unit name or standard size name (xs|sm|md|lg|xl), examples: 16px, 2rem
+        :param color: color name for component, examples: primary, teal-10
         """
         super().__init__('q-icon')
         self._props['name'] = name
+
+        if size:
+            self._props['size'] = size
+
+        if color:
+            self._props['color'] = color

nicegui/elements/knob.py

@@ -1,54 +1,56 @@
-from typing import Union
+from typing import Optional
 
-from ..dependencies import register_component
-from .icon import Icon
 from .label import Label
 from .mixins.value_element import ValueElement
 
 
 class Knob(ValueElement):
 
-    def __init__(
-        self,
-        value: float = 100.0,
-        color: str = 'primary',
-        center_color: str = 'white',
-        track_color: str = 'secondary',
-        size: str = '',
-        show_value: Union[bool, None] = False,
-        icon_name: Union[str, None] = None,
-        icon_color: str = 'black',
-        icon_size: str = '1rem',
-    ) -> None:
+    def __init__(self,
+                 value: float = 0.0,
+                 *,
+                 min: float = 0.0,
+                 max: float = 1.0,
+                 step: float = 0.01,
+                 color: Optional[str] = 'primary',
+                 center_color: Optional[str] = None,
+                 track_color: Optional[str] = None,
+                 size: Optional[str] = None,
+                 show_value: bool = False,
+                 ) -> None:
         """Knob
 
         This element is based on Quasar's `QKnob <https://quasar.dev/vue-components/knob>`_ component.
         The element is used to take a number input from the user through mouse/touch panning.
 
-        :param value: the initial value of the field (from 0.0 to 100.0)
-        :param color: color name for component, examples: primary, teal-10.
-        :param center_color: color name for the center part of the component, examples: primary, teal-10.
-        :param track_color: color name for the track of the component, examples: primary, teal-10.
-        :param size: size in CSS units, including unit name or standard size name (xs|sm|md|lg|xl), examples: 16px, 2rem.
-        :param icon: name for the icon in the center of thecomponent, examples: volume_up, volume_down.
-        :param icon_color: color name for the icon in the center of the component, examples: primary, teal-10.
-        :param icon_size: size in CSS units, including unit name or standard size name (xs|sm|md|lg|xl), examples: 16px, 2rem.
+        :param value: the initial value (default: 0.0)
+        :param min: the minimum value (default: 0.0)
+        :param max: the maximum value (default: 1.0)
+        :param step: the step size (default: 0.01)
+        :param color: color name for component, examples: primary, teal-10 (default: "primary")
+        :param center_color: color name for the center part of the component, examples: primary, teal-10
+        :param track_color: color name for the track of the component, examples: primary, teal-10
+        :param size: size in CSS units, including unit name or standard size name (xs|sm|md|lg|xl), examples: 16px, 2rem
+        :param show_value: whether to show the value as text
         """
-        super().__init__(tag='q-knob', value=value, on_value_change=None)
+        super().__init__(tag='q-knob', value=value, on_value_change=None, throttle=0.05)
 
+        self._props['min'] = min
+        self._props['max'] = max
+        self._props['step'] = step
         self._props['color'] = color
-        self._props['center-color'] = center_color
-        self._props['track-color'] = track_color
-        self._props['size'] = size
+        self._props['show-value'] = True  # NOTE: enable default slot, e.g. for nested icon
 
-        if show_value:
-            self._props['show-value'] = True
-            with self:
-                self.label = Label('0').bind_text_from(self, 'value')
+        if center_color:
+            self._props['center-color'] = center_color
+
+        if track_color:
+            self._props['track-color'] = track_color
 
-        if icon_name:
-            self._props['show-value'] = True
+        if size:
+            self._props['size'] = size
+
+        self.label: Optional[Label] = None
+        if show_value:
             with self:
-                self.icon = Icon(icon_name)
-                self.icon._props['size'] = icon_size
-                self.icon._props['color'] = icon_color
+                self.label = Label().bind_text_from(self, 'value')

website/reference.py

@@ -148,15 +148,10 @@ def create_full(menu: ui.element) -> None:
 
     @example(ui.knob, menu)
     def knob_example():
-        primary = ui.knob(value=50)
+        knob = ui.knob(0.3, show_value=True)
 
-        (
-            ui.knob(show_value=True)
-            .bind_value(primary, 'value')
-            .label.classes('text-teal')
-        )
-
-        ui.knob(icon_name="volume_up").bind_value(primary, 'value')
+        with ui.knob(color='orange', track_color='grey-2').bind_value(knob, 'value'):
+            ui.icon('volume_up')
 
     @example(ui.color_input, menu)
     def color_input_example():