diff --git a/nicegui/ui_run.py b/nicegui/ui_run.py index 708fd87ba7..467d60536c 100644 --- a/nicegui/ui_run.py +++ b/nicegui/ui_run.py @@ -88,7 +88,7 @@ def run(*, :param binding_refresh_interval: time between binding updates (default: `0.1` seconds, bigger is more CPU friendly) :param reconnect_timeout: maximum time the server waits for the browser to reconnect (default: 3.0 seconds) :param message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable) - :param fastapi_docs: enable FastAPI's automatic documentation with Swagger UI, ReDoc, and OpenAPI JSON (bool or dictionary as described `here`_, default: `False`) + :param fastapi_docs: enable FastAPI's automatic documentation with Swagger UI, ReDoc, and OpenAPI JSON (bool or dictionary as described `here `_, default: `False`) :param show: automatically open the UI in a browser tab (default: `True`) :param on_air: tech preview: `allows temporary remote access `_ if set to `True` (default: disabled) :param native: open the UI in a native window of size 800x600 (default: `False`, deactivates `show`, automatically finds an open port) diff --git a/website/documentation/content/overview.py b/website/documentation/content/overview.py index 656d5df3bc..1ca72a6a8a 100644 --- a/website/documentation/content/overview.py +++ b/website/documentation/content/overview.py @@ -14,6 +14,7 @@ section_testing, section_text_elements, ) +from ...style import subheading doc.title('*NiceGUI* Documentation', 'Reference, Demos and more') @@ -151,3 +152,318 @@ def create_tiles(): if page.title: ui.label(page.title.replace('*', '')).classes(replace='text-2xl') ui.markdown(description).classes(replace='bold-links arrow-links') + + +@doc.ui +def map_of_nicegui(): + ui.separator().classes('mt-6') + subheading('Map of NiceGUI', anchor_name='map-of-nicegui') + ui.add_css(''' + .map-of-nicegui a code { + font-weight: bold; + } + ''') + ui.markdown(''' + This overview shows the structure of NiceGUI. + It is a map of the NiceGUI namespace and its contents. + It is not exhaustive, but it gives you a good idea of what is available. + An ongoing goal is to make this map more complete and to add missing links to the documentation. + + #### `ui` + + UI elements and other essentials to run a NiceGUI app. + + - [`ui.element`](/documentation/element): base class for all UI elements + - customization: + - `.props()` and [`.default_props()`](/documentation/element#default_props): add Quasar props and regular HTML attributes + - `.classes()` and [`.default_classes()`](/documentation/element#default_classes): add Quasar, Tailwind and custom HTML classes + - [`.tailwind`](/documentation/section_styling_appearance#tailwind_css): convenience API for adding Tailwind classes + - `.style()` and [`.default_style()`](/documentation/element#default_style): add CSS style definitions + - [`.tooltip()`](/documentation/tooltip): add a tooltip to an element + - [`.mark()`](/documentation/element_filter#markers): mark an element for querying with an [ElementFilter](/documentation/element_filter) + - interaction: + - [`.on()`](/documentation/generic_events): add Python and JavaScript event handlers + - `.update()`: send an update to the client (mostly done automatically) + - `.run_method()`: run a method on the client side + - `.get_computed_prop()`: get the value of a property that is computed on the client side + - hierarchy: + - `with ...:` nesting elements in a declarative way + - `__iter__`: an iterator over all child elements + - `ancestors`: an iterator over the element's parent, grandparent, etc. + - `descendants`: an iterator over all child elements, grandchildren, etc. + - `slots`: a dictionary of named slots + - `add_slot`: fill a new slot with NiceGUI elements or a scoped slot with template strings + - [`clear`](/documentation/section_page_layout#clear_containers): remove all child elements + - [`move`](/documentation/element#move_elements): move an element to a new parent + - `remove`: remove a child element + - `delete`: delete an element and all its children + - `is_deleted`: whether an element has been deleted + - elements: + - [`ui.aggrid`](/documentation/aggrid) + - [`ui.audio`](/documentation/audio) + - [`ui.avatar`](/documentation/avatar) + - [`ui.badge`](/documentation/badge) + - [`ui.button`](/documentation/button) + - [`ui.button_group`](/documentation/button_group) + - [`ui.card`](/documentation/card), `ui.card_actions`, `ui.card_section` + - [`ui.carousel`](/documentation/carousel), `ui.carousel_slide` + - [`ui.chat_message`](/documentation/chat_message) + - [`ui.checkbox`](/documentation/checkbox) + - [`ui.chip`](/documentation/chip) + - [`ui.circular_progress`](/documentation/circular_progress) + - [`ui.code`](/documentation/code) + - [`ui.codemirror`](/documentation/codemirror) + - [`ui.color_input`](/documentation/color_input) + - [`ui.color_picker`](/documentation/color_picker) + - [`ui.column`](/documentation/column) + - [`ui.context_menu`](/documentation/context_menu) + - [`ui.date`](/documentation/date) + - [`ui.dialog`](/documentation/dialog) + - [`ui.dropdown_button`](/documentation/button_dropdown) + - [`ui.echart`](/documentation/echart) + - [`ui.editor`](/documentation/editor) + - [`ui.expansion`](/documentation/expansion) + - [`ui.grid`](/documentation/grid) + - [`ui.highchart`](/documentation/highchart) + - [`ui.html`](/documentation/html) + - [`ui.icon`](/documentation/icon) + - [`ui.image`](/documentation/image) + - [`ui.input`](/documentation/input) + - [`ui.interactive_image`](/documentation/interactive_image) + - `ui.item`, `ui.item_label`, `ui.item_section` + - [`ui.joystick`](/documentation/joystick) + - [`ui.json_editor`](/documentation/json_editor) + - [`ui.knob`](/documentation/knob) + - [`ui.label`](/documentation/label) + - [`ui.leaflet`](/documentation/leaflet) + - [`ui.line_plot`](/documentation/line_plot) + - [`ui.linear_progress`](/documentation/linear_progress) + - [`ui.link`](/documentation/link), `ui.link_target` + - [`ui.list`](/documentation/list) + - [`ui.log`](/documentation/log) + - [`ui.markdown`](/documentation/markdown) + - [`ui.matplotlib`](/documentation/matplotlib) + - [`ui.menu`](/documentation/menu), `ui.menu_item` + - [`ui.mermaid`](/documentation/mermaid) + - [`ui.notification`](/documentation/notification) + - [`ui.number`](/documentation/number) + - [`ui.pagination`](/documentation/pagination) + - [`ui.plotly`](/documentation/plotly) + - [`ui.pyplot`](/documentation/pyplot) + - [`ui.radio`](/documentation/radio) + - [`ui.range`](/documentation/range) + - [`ui.restructured_text`](/documentation/restructured_text) + - [`ui.row`](/documentation/row) + - [`ui.scene`](/documentation/scene), [`ui.scene_view`](/documentation/scene#scene_view) + - [`ui.scroll_area`](/documentation/scroll_area) + - [`ui.select`](/documentation/select) + - [`ui.separator`](/documentation/separator) + - [`ui.skeleton`](/documentation/skeleton) + - [`ui.slider`](/documentation/slider) + - [`ui.space`](/documentation/space) + - [`ui.spinner`](/documentation/spinner) + - [`ui.splitter`](/documentation/splitter) + - [`ui.stepper`](/documentation/stepper), `ui.step`, `ui.stepper_navigation` + - [`ui.switch`](/documentation/switch) + - [`ui.tabs`](/documentation/tabs), `ui.tab`, `ui.tab_panels`, `ui.tab_panel` + - [`ui.table`](/documentation/table) + - [`ui.textarea`](/documentation/textarea) + - [`ui.time`](/documentation/time) + - [`ui.timeline`](/documentation/timeline), `ui.timeline_entry` + - [`ui.toggle`](/documentation/toggle) + - [`ui.tooltip`](/documentation/tooltip) + - [`ui.tree`](/documentation/tree) + - [`ui.upload`](/documentation/upload) + - [`ui.video`](/documentation/video) + - special layout [elements](/documentation/page_layout): + - `ui.header` + - `ui.footer` + - `ui.drawer`, `ui.left_drawer`, `ui.right_drawer` + - `ui.page_sticky` + - special functions and objects: + - [`ui.add_body_html`](/documentation/section_pages_routing#add_html_to_the_page) and + [`ui.add_head_html`](/documentation/section_pages_routing#add_html_to_the_page): add HTML to the body and head of the page + - [`ui.add_css`](/documentation/add_style#add_css_style_definitions_to_the_page), + [`ui.add_sass`](/documentation/add_style#add_sass_style_definitions_to_the_page) and + [`ui.add_scss`](/documentation/add_style#add_scss_style_definitions_to_the_page): add CSS, SASS and SCSS to the page + - [`ui.clipboard`](/documentation/clipboard): interact with the browser's clipboard + - [`ui.colors`](/documentation/colors): define the main color theme for a page + - `ui.context`: get the current UI context including the `client` and `request` objects + - [`ui.dark_mode`](/documentation/dark_mode): get and set the dark mode on a page + - [`ui.download`](/documentation/download): download a file to the client + - [`ui.keyboard`](/documentation/keyboard): define keyboard event handlers + - [`ui.navigate`](/documentation/navigate): let the browser navigate to another location + - [`ui.notify`](/documentation/notification): show a notification + - [`ui.on`](/documentation/generic_events#custom_events): register an event handler + - [`ui.page_title`](/documentation/page_title): change the current page title + - [`ui.query`](/documentation/query): query HTML elements on the client side to modify props, classes and style definitions + - [`ui.run`](/documentation/run) and `ui.run_with`: run the app (standalone or attached to a FastAPI app) + - [`ui.run_javascript`](/documentation/run#run_custom_javascript_on_the_client_side): run custom JavaScript on the client side (can use `getElement()`, `getHtmlElement()`, and `emitEvent()`) + - [`ui.teleport`](/documentation/teleport): teleport an element to a different location in the HTML DOM + - [`ui.timer`](/documentation/timer): run a function periodically or once after a delay + - `ui.update`: send updates of multiple elements to the client + - decorators: + - [`ui.page`](/documentation/page): define a page (in contrast to the automatically generated "auto-index page") + - [`ui.refreshable`](/documentation/refreshable), `ui.refreshable_method`: define refreshable UI containers + (can use [`ui.state`](/documentation/refreshable#refreshable_ui_with_reactive_state)) + + #### `app` + + App-wide storage, mount points and lifecycle hooks. + + - [`app.storage`](/documentation/storage): + - `app.storage.tab`: stored in memory on the server, unique per tab + - `app.storage.client`: stored in memory on the server, unique per client connected to a page + - `app.storage.user`: stored in a file on the server, unique per browser + - `app.storage.general`: stored in a file on the server, shared across the entire app + - `app.storage.browser`: stored in the browser's local storage, unique per browser + - [lifecycle hooks](/documentation/section_action_events#events): + - `app.on_connect()`: called when a client connects + - `app.on_disconnect()`: called when a client disconnects + - `app.on_startup()`: called when the app starts + - `app.on_shutdown()`: called when the app shuts down + - `app.on_exception()`: called when an exception occurs + - [`app.shutdown()`](/documentation/section_action_events#shut_down_nicegui): shut down the app + - static files: + - [`app.add_static_files()`](/documentation/section_pages_routing#add_a_directory_of_static_files), + `app.add_static_file()`: serve static files + - [`app.add_media_files()`](/documentation/section_pages_routing#add_directory_of_media_files), + `app.add_media_file()`: serve media files (supports streaming) + - [`app.native`](/documentation/section_configuration_deployment#native_mode): configure the app when running in native mode + + #### `html` + + [Pure HTML elements](/documentation/html#other_html_elements): + + `a`, + `abbr`, + `acronym`, + `address`, + `area`, + `article`, + `aside`, + `audio`, + `b`, + `basefont`, + `bdi`, + `bdo`, + `big`, + `blockquote`, + `br`, + `button`, + `canvas`, + `caption`, + `cite`, + `code`, + `col`, + `colgroup`, + `data`, + `datalist`, + `dd`, + `del_`, + `details`, + `dfn`, + `dialog`, + `div`, + `dl`, + `dt`, + `em`, + `embed`, + `fieldset`, + `figcaption`, + `figure`, + `footer`, + `form`, + `h1`, + `header`, + `hgroup`, + `hr`, + `i`, + `iframe`, + `img`, + `input_`, + `ins`, + `kbd`, + `label`, + `legend`, + `li`, + `main`, + `map_`, + `mark`, + `menu`, + `meter`, + `nav`, + `object_`, + `ol`, + `optgroup`, + `option`, + `output`, + `p`, + `param`, + `picture`, + `pre`, + `progress`, + `q`, + `rp`, + `rt`, + `ruby`, + `s`, + `samp`, + `search`, + `section`, + `select`, + `small`, + `source`, + `span`, + `strong`, + `sub`, + `summary`, + `sup`, + `svg`, + `table`, + `tbody`, + `td`, + `template`, + `textarea`, + `tfoot`, + `th`, + `thead`, + `time`, + `tr`, + `track`, + `u`, + `ul`, + `var`, + `video`, + `wbr` + + #### `background_tasks` + + Run async functions in the background. + + - `create()`: create a background task + - `create_lazy()`: prevent two tasks with the same name from running at the same time + + #### `run` + + Run IO and CPU bound functions in separate threads and processes. + + - [`run.cpu_bound()`](/documentation/section_action_events#running_cpu-bound_tasks): run a CPU-bound function in a separate process + - [`run.io_bound()`](/documentation/section_action_events#running_i_o-bound_tasks): run an IO-bound function in a separate thread + + #### `observables` + + Observable collections that notify observers when their contents change. + + - `ObservableCollection`: base class + - `ObservableDict`: an observable dictionary + - `ObservableList`: an observable list + - `ObservableSet`: an observable set + + #### `testing` + + Write automated UI tests which run in a headless browser (slow) or fully simulated in Python (fast). + + - [`Screen`](/documentation/section_testing#screen_fixture) fixture: start a real (headless) browser to interact with your application + - [`User`](/documentation/section_testing#user_fixture) fixture: simulate user interaction on a Python level (fast) + ''').classes('map-of-nicegui arrow-links bold-links')