nicegui 1.4.2__tar.gz → 1.4.4__tar.gz

{nicegui-1.4.2 → nicegui-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nicegui
-Version: 1.4.2
+Version: 1.4.4
 Summary: Create web-based user interfaces with Python. The nice way.
 Home-page: https://github.com/zauberzeug/nicegui
 License: MIT
@@ -20,7 +20,6 @@ Provides-Extra: native
 Provides-Extra: plotly
 Requires-Dist: Pygments (>=2.15.1,<3.0.0)
 Requires-Dist: aiofiles (>=23.1.0,<24.0.0)
-Requires-Dist: aiohttp (>=3.8.5,<4.0.0)
 Requires-Dist: fastapi (>=0.93,<1.0.0)
 Requires-Dist: fastapi-socketio (>=0.0.10,<0.0.11)
 Requires-Dist: httpx (>=0.24.0,<1.0.0)
@@ -35,7 +34,7 @@ Requires-Dist: plotly (>=5.13.0,<6.0.0) ; extra == "plotly"
 Requires-Dist: python-multipart (>=0.0.6,<0.0.7)
 Requires-Dist: python-socketio (>=5.10.0)
 Requires-Dist: pywebview (>=4.4.0,<5.0.0) ; extra == "native"
-Requires-Dist: typing-extensions (>=3.10.0)
+Requires-Dist: typing-extensions (>=4.0.0)
 Requires-Dist: uvicorn[standard] (>=0.22.0,<0.23.0)
 Requires-Dist: vbuild (>=0.8.2)
 Requires-Dist: watchfiles (>=0.18.1,<1.0.0)

nicegui-1.4.4/nicegui/.syncignore

@@ -0,0 +1,3 @@
+__pycache__/
+.DS_Store
+*.tmp

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/air.py

@@ -1,5 +1,6 @@
 import asyncio
 import gzip
+import json
 import re
 from typing import Any, Dict, Optional
 
@@ -55,7 +56,8 @@ class Air:
         @self.relay.on('ready')
         def _handle_ready(data: Dict[str, Any]) -> None:
             core.app.urls.add(data['device_url'])
-            print(f'NiceGUI is on air at {data["device_url"]}', flush=True)
+            if core.app.config.show_welcome_message:
+                print(f'NiceGUI is on air at {data["device_url"]}', flush=True)
 
         @self.relay.on('error')
         def _handleerror(data: Dict[str, Any]) -> None:
@@ -85,8 +87,10 @@ class Air:
             if client_id not in Client.instances:
                 return
             client = Client.instances[client_id]
-            if isinstance(data['msg']['args'], dict) and 'socket_id' in data['msg']['args']:
-                data['msg']['args']['socket_id'] = client_id  # HACK: translate socket_id of ui.scene's init event
+            if data['msg']['args'] and data['msg']['args'][0].startswith('{"socket_id":'):
+                args = json.loads(data['msg']['args'][0])
+                args['socket_id'] = client_id  # HACK: translate socket_id of ui.scene's init event
+                data['msg']['args'][0] = json.dumps(args)
             client.handle_event(data['msg'])
 
         @self.relay.on('javascript_response')

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/app/app_config.py

@@ -34,6 +34,7 @@ class AppConfig:
     reconnect_timeout: float = field(init=False)
     tailwind: bool = field(init=False)
     prod_js: bool = field(init=False)
+    show_welcome_message: bool = field(init=False)
     _has_run_config: bool = False
 
     def add_run_config(self,
@@ -48,6 +49,7 @@ class AppConfig:
                        reconnect_timeout: float,
                        tailwind: bool,
                        prod_js: bool,
+                       show_welcome_message: bool,
                        ) -> None:
         """Add the run config to the app config."""
         self.reload = reload
@@ -60,6 +62,7 @@ class AppConfig:
         self.reconnect_timeout = reconnect_timeout
         self.tailwind = tailwind
         self.prod_js = prod_js
+        self.show_welcome_message = show_welcome_message
         self._has_run_config = True
 
     @property

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/client.py

@@ -105,7 +105,8 @@ class Client:
             'elements': elements.replace('&', '&')
                                 .replace('<', '&lt;')
                                 .replace('>', '&gt;')
-                                .replace('`', '&#96;'),
+                                .replace('`', '&#96;')
+                                .replace('$', '&#36;'),
             'head_html': self.head_html,
             'body_html': '<style>' + '\n'.join(vue_styles) + '</style>\n' + self.body_html + '\n' + '\n'.join(vue_html),
             'vue_scripts': '\n'.join(vue_scripts),
@@ -192,9 +193,9 @@ class Client:
         path = target if isinstance(target, str) else self.page_routes[target]
         outbox.enqueue_message('open', {'path': path, 'new_tab': new_tab}, self.id)
 
-    def download(self, url: str, filename: Optional[str] = None) -> None:
-        """Download a file from the given URL."""
-        outbox.enqueue_message('download', {'url': url, 'filename': filename}, self.id)
+    def download(self, src: Union[str, bytes], filename: Optional[str] = None) -> None:
+        """Download a file from a given URL or raw bytes."""
+        outbox.enqueue_message('download', {'src': src, 'filename': filename}, self.id)
 
     def on_connect(self, handler: Union[Callable[..., Any], Awaitable]) -> None:
         """Register a callback to be called when the client connects."""

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/element.py

@@ -410,7 +410,7 @@ class Element(Visibility):
         """Update the element on the client side."""
         outbox.enqueue_update(self)
 
-    def run_method(self, name: str, *args: Any) -> AwaitableResponse:
+    def run_method(self, name: str, *args: Any, timeout: float = 1, check_interval: float = 0.01) -> AwaitableResponse:
         """Run a method on the client side.
 
         If the function is awaited, the result of the method call is returned.
@@ -418,10 +418,13 @@ class Element(Visibility):
 
         :param name: name of the method
         :param args: arguments to pass to the method
+        :param timeout: maximum time to wait for a response (default: 1 second)
+        :param check_interval: time between checks for a response (default: 0.01 seconds)
         """
         if not core.loop:
             return NullResponse()
-        return self.client.run_javascript(f'return runMethod({self.id}, "{name}", {json.dumps(args)})')
+        return self.client.run_javascript(f'return runMethod({self.id}, "{name}", {json.dumps(args)})',
+                                          timeout=timeout, check_interval=check_interval)
 
     def _collect_descendants(self, *, include_self: bool = False) -> List[Element]:
         elements: List[Element] = [self] if include_self else []

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/aggrid.py

@@ -85,7 +85,7 @@ class AgGrid(Element, component='aggrid.js', libraries=['lib/aggrid/ag-grid-comm
         super().update()
         self.run_method('update_grid')
 
-    def call_api_method(self, name: str, *args) -> AwaitableResponse:
+    def call_api_method(self, name: str, *args, timeout: float = 1, check_interval: float = 0.01) -> AwaitableResponse:
         """Call an AG Grid API method.
 
         See `AG Grid API <https://www.ag-grid.com/javascript-data-grid/grid-api/>`_ for a list of methods.
@@ -95,12 +95,15 @@ class AgGrid(Element, component='aggrid.js', libraries=['lib/aggrid/ag-grid-comm
 
         :param name: name of the method
         :param args: arguments to pass to the method
+        :param timeout: timeout in seconds (default: 1 second)
+        :param check_interval: interval in seconds to check for a response (default: 0.01 seconds)
 
         :return: AwaitableResponse that can be awaited to get the result of the method call
         """
-        return self.run_method('call_api_method', name, *args)
+        return self.run_method('call_api_method', name, *args, timeout=timeout, check_interval=check_interval)
 
-    def call_column_api_method(self, name: str, *args) -> AwaitableResponse:
+    def call_column_api_method(self, name: str, *args,
+                               timeout: float = 1, check_interval: float = 0.01) -> AwaitableResponse:
         """Call an AG Grid Column API method.
 
         See `AG Grid Column API <https://www.ag-grid.com/javascript-data-grid/column-api/>`_ for a list of methods.
@@ -110,10 +113,12 @@ class AgGrid(Element, component='aggrid.js', libraries=['lib/aggrid/ag-grid-comm
 
         :param name: name of the method
         :param args: arguments to pass to the method
+        :param timeout: timeout in seconds (default: 1 second)
+        :param check_interval: interval in seconds to check for a response (default: 0.01 seconds)
 
         :return: AwaitableResponse that can be awaited to get the result of the method call
         """
-        return self.run_method('call_column_api_method', name, *args)
+        return self.run_method('call_column_api_method', name, *args, timeout=timeout, check_interval=check_interval)
 
     async def get_selected_rows(self) -> List[Dict]:
         """Get the currently selected rows.
@@ -137,7 +142,7 @@ class AgGrid(Element, component='aggrid.js', libraries=['lib/aggrid/ag-grid-comm
         rows = await self.get_selected_rows()
         return rows[0] if rows else None
 
-    async def get_client_data(self) -> List[Dict]:
+    async def get_client_data(self, *, timeout: float = 1, check_interval: float = 0.01) -> List[Dict]:
         """Get the data from the client including any edits made by the client.
 
         This method is especially useful when the grid is configured with ``'editable': True``.
@@ -147,13 +152,15 @@ class AgGrid(Element, component='aggrid.js', libraries=['lib/aggrid/ag-grid-comm
         Note that when editing a cell, the row data is not updated until the cell exits the edit mode.
         This does not happen when the cell loses focus, unless ``stopEditingWhenCellsLoseFocus: True`` is set.
 
+        :param timeout: timeout in seconds (default: 1 second)
+        :param check_interval: interval in seconds to check for a response (default: 0.01 seconds)
         :return: list of row data
         """
         result = await self.client.run_javascript(f'''
             const rowData = [];
             getElement({self.id}).gridOptions.api.forEachNode(node => rowData.push(node.data));
             return rowData;
-        ''')
+        ''', timeout=timeout, check_interval=check_interval)
         return cast(List[Dict], result)
 
     async def load_client_data(self) -> None:

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/chat_message.py

@@ -2,12 +2,13 @@ import html
 from typing import List, Optional, Union
 
 from ..element import Element
+from .html import Html
 
 
-class ChatMessage(Element, component='chat_message.js'):
+class ChatMessage(Element):
 
     def __init__(self,
-                 text: Union[str, List[str]], *,
+                 text: Union[str, List[str]] = ..., *,
                  name: Optional[str] = None,
                  label: Optional[str] = None,
                  stamp: Optional[str] = None,
@@ -27,15 +28,15 @@ class ChatMessage(Element, component='chat_message.js'):
         :param sent: render as a sent message (so from current user) (default: False)
         :param text_html: render text as HTML (default: False)
         """
-        super().__init__()
+        super().__init__('q-chat-message')
 
+        if text is ...:
+            text = []
         if isinstance(text, str):
             text = [text]
         if not text_html:
             text = [html.escape(part) for part in text]
             text = [part.replace('\n', '<br />') for part in text]
-        self._props['text'] = text
-        self._props['text-html'] = True
 
         if name is not None:
             self._props['name'] = name
@@ -46,3 +47,7 @@ class ChatMessage(Element, component='chat_message.js'):
         if avatar is not None:
             self._props['avatar'] = avatar
         self._props['sent'] = sent
+
+        with self:
+            for line in text:
+                Html(line)

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/echart.js

@@ -17,7 +17,7 @@ export default {
   methods: {
     update_chart() {
       convertDynamicProperties(this.options, true);
-      this.chart.setOption(this.options);
+      this.chart.setOption(this.options, { notMerge: this.chart.options?.series.length != this.options.series.length });
     },
   },
   props: {

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/image.js

@@ -12,6 +12,7 @@ export default {
   `,
   props: {
     src: String,
+    t: String,
   },
   data: function () {
     return {
@@ -26,7 +27,8 @@ export default {
   },
   methods: {
     compute_src() {
-      this.computed_src = (this.src.startsWith("/") ? window.path_prefix : "") + this.src;
+      const suffix = this.t ? (this.src.includes("?") ? "&" : "?") + "_nicegui_t=" + this.t : "";
+      this.computed_src = (this.src.startsWith("/") ? window.path_prefix : "") + this.src + suffix;
     },
   },
 };

nicegui-1.4.4/nicegui/elements/image.py

@@ -0,0 +1,47 @@
+import base64
+import io
+import time
+from pathlib import Path
+from typing import Union
+
+from PIL.Image import Image as PIL_Image
+
+from .mixins.source_element import SourceElement
+
+
+class Image(SourceElement, component='image.js'):
+    PIL_CONVERT_FORMAT = 'PNG'
+
+    def __init__(self, source: Union[str, Path, PIL_Image] = '') -> None:
+        """Image
+
+        Displays an image.
+        This element is based on Quasar's `QImg <https://quasar.dev/vue-components/img>`_ component.
+
+        :param source: the source of the image; can be a URL, local file path, a base64 string or a PIL image
+        """
+        super().__init__(source=source)
+
+    def _set_props(self, source: Union[str, Path]) -> None:
+        if isinstance(source, PIL_Image):
+            source = pil_to_base64(source, self.PIL_CONVERT_FORMAT)
+        super()._set_props(source)
+
+    def force_reload(self) -> None:
+        """Force the image to reload from the source."""
+        self._props['t'] = time.time()
+        self.update()
+
+
+def pil_to_base64(pil_image: PIL_Image, image_format: str) -> str:
+    """Convert a PIL image to a base64 string which can be used as image source.
+
+    :param pil_image: the PIL image
+    :param image_format: the image format
+    :return: the base64 string
+    """
+    buffer = io.BytesIO()
+    pil_image.save(buffer, image_format)
+    base64_encoded = base64.b64encode(buffer.getvalue())
+    base64_string = base64_encoded.decode('utf-8')
+    return f'data:image/{image_format.lower()};base64,{base64_string}'

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/interactive_image.js

@@ -49,7 +49,8 @@ export default {
   },
   methods: {
     compute_src() {
-      const new_src = (this.src.startsWith("/") ? window.path_prefix : "") + this.src;
+      const suffix = this.t ? (this.src.includes("?") ? "&" : "?") + "_nicegui_t=" + this.t : "";
+      const new_src = (this.src.startsWith("/") ? window.path_prefix : "") + this.src + suffix;
       if (new_src == this.computed_src) {
         return;
       }
@@ -103,5 +104,6 @@ export default {
     content: String,
     events: Array,
     cross: Boolean,
+    t: String,
   },
 };

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/interactive_image.py

@@ -1,15 +1,20 @@
 from __future__ import annotations
 
+import time
 from pathlib import Path
 from typing import Any, Callable, List, Optional, Union, cast
 
+from PIL.Image import Image as PIL_Image
+
 from ..events import GenericEventArguments, MouseEventArguments, handle_event
+from .image import pil_to_base64
 from .mixins.content_element import ContentElement
 from .mixins.source_element import SourceElement
 
 
 class InteractiveImage(SourceElement, ContentElement, component='interactive_image.js'):
     CONTENT_PROP = 'content'
+    PIL_CONVERT_FORMAT = 'PNG'
 
     def __init__(self,
                  source: Union[str, Path] = '', *,
@@ -55,3 +60,13 @@ class InteractiveImage(SourceElement, ContentElement, component='interactive_ima
             )
             handle_event(on_mouse, arguments)
         self.on('mouse', handle_mouse)
+
+    def _set_props(self, source: Union[str, Path]) -> None:
+        if isinstance(source, PIL_Image):
+            source = pil_to_base64(source, self.PIL_CONVERT_FORMAT)
+        super()._set_props(source)
+
+    def force_reload(self) -> None:
+        """Force the image to reload from the source."""
+        self._props['t'] = time.time()
+        self.update()

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/json_editor.js

@@ -28,7 +28,7 @@ export default {
     },
     destroyEditor() {
       if (this.editor) {
-        this.editor.dispose();
+        this.editor.destroy();
       }
     },
   },

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/mixins/content_element.py

@@ -1,6 +1,6 @@
-from typing import Any, Callable
+from typing import Any, Callable, cast
 
-from typing_extensions import Self, cast
+from typing_extensions import Self
 
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/mixins/disableable_element.py

@@ -1,6 +1,6 @@
-from typing import Any, Callable
+from typing import Any, Callable, cast
 
-from typing_extensions import Self, cast
+from typing_extensions import Self
 
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/mixins/filter_element.py

@@ -1,6 +1,6 @@
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Optional, cast
 
-from typing_extensions import Self, cast
+from typing_extensions import Self
 
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/mixins/name_element.py

@@ -1,6 +1,6 @@
-from typing import Any, Callable
+from typing import Any, Callable, cast
 
-from typing_extensions import Self, cast
+from typing_extensions import Self
 
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/mixins/source_element.py

@@ -1,7 +1,7 @@
 from pathlib import Path
-from typing import Any, Callable, Optional, Union
+from typing import Any, Callable, Optional, Union, cast
 
-from typing_extensions import Self, cast
+from typing_extensions import Self
 
 from ... import core
 from ...binding import BindableProperty, bind, bind_from, bind_to

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/mixins/text_element.py

@@ -1,6 +1,6 @@
-from typing import Any, Callable
+from typing import Any, Callable, cast
 
-from typing_extensions import Self, cast
+from typing_extensions import Self
 
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/mixins/value_element.py

@@ -1,6 +1,6 @@
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Optional, cast
 
-from typing_extensions import Self, cast
+from typing_extensions import Self
 
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/number.py

@@ -14,6 +14,7 @@ class Number(ValidationElement, DisableableElement):
                  value: Optional[float] = None,
                  min: Optional[float] = None,  # pylint: disable=redefined-builtin
                  max: Optional[float] = None,  # pylint: disable=redefined-builtin
+                 precision: Optional[int] = None,
                  step: Optional[float] = None,
                  prefix: Optional[str] = None,
                  suffix: Optional[str] = None,
@@ -33,6 +34,7 @@ class Number(ValidationElement, DisableableElement):
         :param value: the initial value of the field
         :param min: the minimum value allowed
         :param max: the maximum value allowed
+        :param precision: the number of decimal places allowed (default: no limit, negative: decimal places before the dot)
         :param step: the step size for the stepper buttons
         :param prefix: a prefix to prepend to the displayed value
         :param suffix: a suffix to append to the displayed value
@@ -51,6 +53,7 @@ class Number(ValidationElement, DisableableElement):
             self._props['min'] = min
         if max is not None:
             self._props['max'] = max
+        self._precision = precision
         if step is not None:
             self._props['step'] = step
         if prefix is not None:
@@ -79,6 +82,16 @@ class Number(ValidationElement, DisableableElement):
         self._props['max'] = value
         self.sanitize()
 
+    @property
+    def precision(self) -> Optional[int]:
+        """The number of decimal places allowed (default: no limit, negative: decimal places before the dot)."""
+        return self._precision
+
+    @precision.setter
+    def precision(self, value: Optional[int]) -> None:
+        self._precision = value
+        self.sanitize()
+
     @property
     def out_of_limits(self) -> bool:
         """Whether the current value is out of the allowed limits."""
@@ -86,9 +99,13 @@ class Number(ValidationElement, DisableableElement):
 
     def sanitize(self) -> None:
         """Sanitize the current value to be within the allowed limits."""
-        value = float(self.value or 0)
+        if self.value is None:
+            return
+        value = float(self.value)
         value = max(value, self.min)
         value = min(value, self.max)
+        if self.precision is not None:
+            value = float(round(value, self.precision))
         self.set_value(float(self.format % value) if self.format else value)
 
     def _event_args_to_value(self, e: GenericEventArguments) -> Any:

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/scene.js

@@ -326,14 +326,20 @@ export default {
     },
     draggable(object_id, value) {
       if (!this.objects.has(object_id)) return;
-      if (value) this.draggable_objects.push(this.objects.get(object_id));
-      else this.draggable_objects.pop(this.objects.get(object_id));
+      const object = this.objects.get(object_id);
+      if (value) this.draggable_objects.push(object);
+      else {
+        const index = this.draggable_objects.indexOf(object);
+        if (index != -1) this.draggable_objects.splice(index, 1);
+      }
     },
     delete(object_id) {
       if (!this.objects.has(object_id)) return;
-      this.objects.get(object_id).removeFromParent();
+      const object = this.objects.get(object_id);
+      object.removeFromParent();
       this.objects.delete(object_id);
-      this.draggable_objects.pop(this.objects.get(object_id));
+      const index = this.draggable_objects.indexOf(object);
+      if (index != -1) this.draggable_objects.splice(index, 1);
     },
     set_texture_url(object_id, url) {
       if (!this.objects.has(object_id)) return;

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/scene.py

@@ -117,7 +117,7 @@ class Scene(Element,
             for obj in self.objects.values():
                 obj.send()
 
-    def run_method(self, name: str, *args: Any) -> AwaitableResponse:
+    def run_method(self, name: str, *args: Any, timeout: float = 1, check_interval: float = 0.01) -> AwaitableResponse:
         """Run a method on the client.
 
         :param name: name of the method
@@ -125,7 +125,7 @@ class Scene(Element,
         """
         if not self.is_initialized:
             return NullResponse()
-        return super().run_method(name, *args)
+        return super().run_method(name, *args, timeout=timeout, check_interval=check_interval)
 
     def _handle_click(self, e: GenericEventArguments) -> None:
         arguments = SceneClickEventArguments(

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/select.js

@@ -20,13 +20,20 @@ export default {
   },
   methods: {
     filterFn(val, update, abort) {
-      update(() => {
-        const needle = val.toLocaleLowerCase();
-        this.filteredOptions = needle
-          ? this.initialOptions.filter((v) => String(v.label).toLocaleLowerCase().indexOf(needle) > -1)
-          : this.initialOptions;
-      });
+      update(() => (this.filteredOptions = this.findFilteredOptions()));
     },
+    findFilteredOptions() {
+      const needle = this.$el.querySelector("input[type=search]")?.value.toLocaleLowerCase();
+      return needle
+        ? this.initialOptions.filter((v) => String(v.label).toLocaleLowerCase().indexOf(needle) > -1)
+        : this.initialOptions;
+    },
+  },
+  updated() {
+    const newFilteredOptions = this.findFilteredOptions();
+    if (newFilteredOptions.length !== this.filteredOptions.length) {
+      this.filteredOptions = newFilteredOptions;
+    }
   },
   watch: {
     options: {

{nicegui-1.4.2 → nicegui-1.4.4}/nicegui/elements/select.py

@@ -29,6 +29,7 @@ class Select(ChoiceElement, DisableableElement, component='select.js'):
 
         If `new_value_mode` is not None, it implies `with_input=True` and the user can enter new values in the input field.
         See `Quasar's documentation <https://quasar.dev/vue-components/select#the-new-value-mode-prop>`_ for details.
+        Note that this mode is ineffective when setting the `value` property programmatically.
 
         :param options: a list ['value1', ...] or dictionary `{'value1':'label1', ...}` specifying the options
         :param label: the label to display above the selection