Merge branch 'main' of github.com:zauberzeug/nicegui into main

README.md

@@ -2,7 +2,7 @@
 
 <img src="https://raw.githubusercontent.com/zauberzeug/nicegui/main/sceenshots/ui-elements.png" width="300" align="right">
 
-We like [Streamlit](https://streamlit.io/) but find it does to much magic when it comes to state handling. In search for an alernative nice library to write simple graphical user interfaces in Python we discovered [justpy](https://justpy.io/). While too "low-level-html" for our daily usage it provides a great basis for "NiceGUI".
+We like [Streamlit](https://streamlit.io/) but find it does too much magic when it comes to state handling. In search for an alernative nice library to write simple graphical user interfaces in Python we discovered [justpy](https://justpy.io/). While too "low-level HTML" for our daily usage it provides a great basis for "NiceGUI".
 
 ## Purpose
 
@@ -10,14 +10,14 @@ NiceGUI is intended to be used for small scripts and single-page user interfaces
 
 ## Features
 
-- browser-based Graphical User Interface
+- browser-based graphical user interface
 - shared state between multiple browser windows
 - implicit reload on code change
 - clean set of GUI elements (label, button, checkbox, switch, slider, input, ...)
 - simple grouping with rows, columns and cards
-- genral-purpose html and markdown elements
+- general-purpose HTML and markdown elements
 - built-in timer to refresh data in intervals (even every 10 ms)
-- straight-forward data bindings to write even less code
+- straight-forward data binding to write even less code
 
 ## Install
 
@@ -42,7 +42,7 @@ Launch it with:
 python3 main.py
 ```
 
-The GUI is now avaliable thorugh http://localhost/ in your browser. Note: The script will automatically reload the page if you modify the code.
+The GUI is now avaliable through http://localhost/ in your browser. Note: The script will automatically reload the page when you modify the code.
 
 ## API
 

main.py

@@ -75,8 +75,8 @@ with ui.row(classes='flex w-full'):
 
 design = '''### Styling & Design
 
-NiceGUI use the [Quasar Framework](https://quasar.dev/) and hence has their full design power. Each NiceGUI element provides a `design` property which content is passed [as props the Quasar component](https://justpy.io/quasar_tutorial/introduction/#props-of-quasar-components):
-Have a look at [the Quasar documentation](https://quasar.dev/vue-components/button#design) for all styling "props".
+NiceGUI uses the [Quasar Framework](https://quasar.dev/) and hence has its full design power. Each NiceGUI element provides a `design` property whose content is passed [as "props" to the Quasar component](https://justpy.io/quasar_tutorial/introduction/#props-of-quasar-components):
+Have a look at [the Quasar documentation](https://quasar.dev/vue-components/button#design) for all styling props.
 
 You can also apply [Tailwind](https://tailwindcss.com/) utility classes with the `classes` property or `add_classes` method.
 '''
@@ -85,15 +85,16 @@ with (example(design)):
     ui.radio(['x', 'y', 'z'], design='inline color=green')
     ui.button(icon='touch_app', design='outline round', classes='shadow-lg ml-14')
 
-design = '''### Bindings
+binding = '''### Bindings
 
-With help of the [binding](https://pypi.org/project/binding/) package NiceGUI is able to directly bind UI elements to models (dict, class, ...).
+With help of the [binding](https://pypi.org/project/binding/) package NiceGUI is able to directly bind UI elements to models.
+Binding is possible for UI element properties like text, value or visibility and for model properties that are (nested) class attributes.
 
-Eeach element provides methods `bind_value` and `bind_visibility` to create a two-way binding with the corresponding property. 
-To define a one-way binding use the `_from` and `_to` variants of these methods. 
+Each element provides methods like `bind_value` and `bind_visibility` to create a two-way binding with the corresponding property.
+To define a one-way binding use the `_from` and `_to` variants of these methods.
 Just pass a property of the model as parameter to these methods to create the binding.
 '''
-with (example(design)):
+with (example(binding)):
 
     class Demo:
 

nicegui/elements/checkbox.py

@@ -13,8 +13,8 @@ class Checkbox(BoolElement):
                  ):
         """Checkbox Element
 
-        :param text: the label to display beside the checkbox
-        :param value: set to True if initally it should be checked; default is False
+        :param text: the label to display next to the checkbox
+        :param value: set to `True` if it should be checked initally; default is `False`
         :param design: Quasar props to alter the appearance (see `their reference <https://quasar.dev/vue-components/checkbox>`_)
         :param on_change: callback to execute when value changes
         """

nicegui/elements/html.py

@@ -4,11 +4,11 @@ from .element import Element
 class Html(Element):
 
     def __init__(self, content: str = '', design='', classes: str = ''):
-        """Html Element
+        """HTML Element
 
-        Renders arbitrary html onto the page. `Tailwind <https://tailwindcss.com/>`_ can be used for styling.
+        Renders arbitrary HTML onto the page. `Tailwind <https://tailwindcss.com/>`_ can be used for styling.
 
-        :param content: the html code to be displayed
+        :param content: the HTML code to be displayed
         """
 
         view = jp.QDiv()

nicegui/elements/input.py

@@ -14,11 +14,11 @@ class Input(StringElement):
                  on_change: Callable = None):
         """Text Input Element
 
-        :param label: display name for the text input
+        :param label: displayed label for the text input
         :param placeholder: text to show if no value is entered
-        :param value: the current value of the field
+        :param value: the current value of the text input
         :param design: Quasar props to alter the appearance (see `their reference <https://quasar.dev/vue-components/input>`_)
-        :param on_change: callback when the input is confirmed via leaving the focus
+        :param on_change: callback to execute when the input is confirmed by leaving the focus
         """
         view = jp.QInput(
             label=label,

nicegui/elements/line_plot.py

@@ -4,14 +4,14 @@ from .plot import Plot
 class LinePlot(Plot):
 
     def __init__(self, n: int = 1, limit: int = 100, update_every=1, close: bool = True, **kwargs):
-        """Plot Element
+        """Line Plot
 
-        Create a line plot. The  `push` method provides live updating when utilized in combination with ui.timer.
+        Create a line plot. The `push` method provides live updating when utilized in combination with `ui.timer`.
 
-        :param n: number of data points to begin with
-        :param limit: maximum number of datapoints (new ones will push out the oldest)
+        :param n: number of lines
+        :param limit: maximum number of datapoints per line (new points will displace the oldest)
         :param update_every: update plot only after pushing new data multiple times to save CPU and bandwidth
-        :param close: whether the figure should be closed after exiting the context; set to False if you want to update it later, default is True
+        :param close: whether the figure should be closed after exiting the context; set to `False` if you want to update it later, default is `True`
         :param kwargs: arguments like `figsize` which should be passed to `pyplot.figure <https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.figure.html>`_
         """
 

nicegui/elements/markdown.py

@@ -9,7 +9,7 @@ class Markdown(Html):
 
         Renders markdown onto the page.
 
-        :param content: the markdown to be displayed
+        :param content: the markdown content to be displayed
         """
 
         super().__init__(content, classes=classes)

nicegui/elements/number.py

@@ -16,11 +16,11 @@ class Number(FloatElement):
                  ):
         """Number Input Element
 
-        :param label: display name for the input
+        :param label: displayed name for the number input
         :param placeholder: text to show if no value is entered
         :param value: the inital value of the field
-        :param format: a string like '%.2f' to format the entered number before displaying
-        :param on_change: callback when the input is confirmed via leaving the focus
+        :param format: a string like '%.2f' to format the displayed value
+        :param on_change: callback to execute when the input is confirmed by leaving the focus
         :param design: Quasar props to alter the appearance (see `their reference <https://quasar.dev/vue-components/input>`_)
         """
 

nicegui/elements/plot.py

@@ -10,7 +10,7 @@ class Plot(Element):
 
         Create a context to configure a `Matplotlib <https://matplotlib.org/>`_ plot.
 
-        :param close: whether the figure should be closed after exiting the context; set to False if you want to update it later, default is True
+        :param close: whether the figure should be closed after exiting the context; set to `False` if you want to update it later, default is `True`
         :param kwargs: arguments like `figsize` which should be passed to `pyplot.figure <https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.figure.html>`_
         """
 

nicegui/elements/radio.py

@@ -13,9 +13,9 @@ class Radio(ChoiceElement):
                  ):
         """Radio Selection Element
 
-        :param options: a list or dict specifying the options
+        :param options: a list ['value1', ...] or dictionary `{'value1':'label1', ...}` specifying the options
         :param value: the inital value
-        :param on_change: callback when selection changes
+        :param on_change: callback to execute when selection changes
         :param design: Quasar props to alter the appearance (see `their reference <https://quasar.dev/vue-components/radio>`_)
         """
 

nicegui/elements/select.py

@@ -13,9 +13,9 @@ class Select(ChoiceElement):
                  ):
         """Dropdown Selection Element
 
-        :param options: a list or dict specifying the options
+        :param options: a list ['value1', ...] or dictionary `{'value1':'label1', ...}` specifying the options
         :param value: the inital value
-        :param on_change: callback when selection changes
+        :param on_change: callback to execute when selection changes
         :param design: Quasar props to alter the appearance (see `their reference <https://quasar.dev/vue-components/select>`_)
         """
 

nicegui/elements/switch.py

@@ -13,8 +13,8 @@ class Switch(BoolElement):
                  ):
         """Switch Element
 
-        :param text: the label of the button
-        :param value: set to True if initally it should be active; default is False
+        :param text: the label to display next to the switch
+        :param value: set to `True` if initally it should be active; default is `False`
         :param design: Quasar props to alter the appearance (see `their reference <https://quasar.dev/vue-components/switch>`_)
         :param on_click: callback which is invoked when state is changed by the user
         """

nicegui/elements/toggle.py

@@ -13,9 +13,9 @@ class Toggle(ChoiceElement):
                  ):
         """Toggle Element
 
-        :param options: a list or dict specifying the options
+        :param options: a list ['value1', ...] or dictionary `{'value1':'label1', ...}` specifying the options
         :param value: the inital value
-        :param on_change: callback when selection changes
+        :param on_change: callback to execute when selection changes
         :param design: Quasar props to alter the appearance (see `their reference <https://quasar.dev/vue-components/toggle>`_)
         """
 

nicegui/timer.py

@@ -14,12 +14,12 @@ class Timer:
     def __init__(self, interval, callback, *, active=True, once=False):
         """Timer
 
-        One major drive behind the creation of NiceGUI was the necessity to have an simple approach to update the interface in regular intervals. For example to show a graph with incomming measurements.
+        One major drive behind the creation of NiceGUI was the necessity to have a simple approach to update the interface in regular intervals, for example to show a graph with incomming measurements.
 
-        :param interval: the interval in which the timer is been called
+        :param interval: the interval in which the timer is called
         :param callback: function to execute when interval elapses
-        :param active: whether timer should run or be paused
-        :param once: whether the callback is only executed once after an delay specified by `interval`; default is False
+        :param active: whether the callback should be executed or not
+        :param once: whether the callback is only executed once after a delay specified by `interval`; default is `False`
         """
 
         parent = Element.view_stack[-1]