Base Component#

class ngapp.components.basecomponent.AppContext(
app: object,
capture_events: bool = False,
capture_call_stack: bool = False,
environment: ngapp.utils.Environment = None,
components_by_id: dict[str,
object]=<factory>,
_cached_app_id: int | None = None,
)#

Bases: object

Parameters:

  • app (object)

  • capture_events (bool)

  • capture_call_stack (bool)

  • environment (Environment)

  • components_by_id (dict[str, object])

  • _cached_app_id (int | None)

class ngapp.components.basecomponent.Component(
component: str,
*ui_children: T | str,
ui_slots: dict[str, list] | None = None,
namespace: bool = False,
ui_style: str | dict | None = None,
ui_class: str | list[str] | None = None,
ui_hidden: bool | None = None,
id: str = '',
)#

Bases: object

Base component class, the component name is passed as argument

Parameters:

  • component (str)

  • ui_children (T | str)

  • ui_slots (dict[str, list] | None)

  • namespace (bool)

  • ui_style (str | dict | None)

  • ui_class (str | list[str] | None)

  • ui_hidden (bool | None)

  • id (str)

add_keybinding(
key: str,
callback: Callable,
local: bool = False,
keyup: bool = False,
keydown: bool = True,
split_key: str = '+',
capture: bool = False,
single: bool = False,
prevent_default: bool = False,
match: str | None = None,
allow_typing: bool = False,
)#

Add key binding to component.

callback(ev) gets the key event with attributes combo, type, key, code, ctrlKey, shiftKey, altKey, metaKey, repeat, timeStamp, target (tag name) and isContentEditable.

Args:
prevent_default: call preventDefault() on the event in the

browser listener (e.g. "ctrl+s", "tab").

match: "code" matches with hotkeys-js (key codes, symbols on

US layout only), "key" matches KeyboardEvent.key (any layout, "?", "[", "+"; shift / alt producing a symbol are ignored unless listed). None picks "key" for symbols hotkeys-js does not know ("?", "+", …). single has no effect with "key".

allow_typing: also fire while an input, textarea or select has the

focus (filtered by default so shortcuts do not fire while typing). Uses "key" matching.

Parameters:

  • key (str)

  • callback (Callable)

  • local (bool)

  • keyup (bool)

  • keydown (bool)

  • split_key (str)

  • capture (bool)

  • single (bool)

  • prevent_default (bool)

  • match (str | None)

  • allow_typing (bool)

call_js(func: Callable, *args, **kwargs)#

This method ensures safe JavaScript execution by automatically deferring the function call until the JavaScript environment is ready. If JavaScript is already available, the function executes immediately.

Args:

func (callable): A Python function *args: Positional arguments to pass to the function when called. **kwargs: Keyword arguments to pass to the function when called.

Note:

  • Safe to call in app __init__ method (when .js is not yet available)

Example:
>>> def my_method(js):
...     return js.console.log("Hi from JS when app is initialized")
>>> self.call_js(my_method)
Parameters:

func (Callable)

create_event_handler(
function,
prevent_default: bool = True,
stop_propagation: bool = False,
stop_immediate_propagation: bool = False,
return_value: object | None = None,
)#

Create an event handler for the component.

Args:

function (Callable): The function to call when the event is triggered. prevent_default (bool): Whether to prevent the default action of the event. stop_propagation (bool): Whether to stop the propagation of the event. stop_immediate_propagation (bool): Whether to stop immediate propagation of the event. return_value (object, optional): The value to return from the event handler.

Parameters:

  • prevent_default (bool)

  • stop_propagation (bool)

  • stop_immediate_propagation (bool)

  • return_value (object | None)

property js#

Direct access to the JavaScript environment for immediate execution.

This property provides direct access to the JavaScript runtime environment, allowing you to run any JavaScript function or access any JavaScript object immediately.

Note:

  • Cannot be used in __init__ methods - use call_js() instead for deferred execution

  • Only available after the JavaScript environment is fully loaded

Example:

self.js.console.log(“Hello from Python!”)

on(
events: str | list,
func: Callable[[Event], None] | Callable[[], None],
arg: object = None,
clear_existing: bool = False,
)#

Add event listener

Parameters:

  • events (str | list)

  • func (Callable[[Event], None] | Callable[[], None])

  • arg (object)

  • clear_existing (bool)

property quasar#

Access to the Quasar framework’s $q object and utilities.

Provides access to all Quasar framework functionality through a Python interface. The returned proxy object allows calling any method available on Quasar’s $q object as documented at: https://quasar.dev/options/the-q-object

Note:

  • Cannot be used in __init__ methods

Example:
>>> # Show a notification
>>> self.quasar.notify({
...     'message': 'Operation completed successfully!',
...     'color': 'positive',
... })
remove_keybinding(key: str)#

Remove the key bindings of this component for key.

Parameters:

key (str)

property ui_hidden#

Set display to none. Compare with below - the class hidden means the element will not show and will not take up space in the layout.

property ui_invisible#

Set visibility to hidden. Compare with above - the class invisible means the element will not show, but it will still take up space in the layout.

class ngapp.components.basecomponent.Event(
name: str,
component: 'Component',
arg: object | None = None,
value: object | None = None,
)#

Bases: object

Parameters:

  • name (str)

  • component (Component)

  • arg (object | None)

  • value (object | None)

class ngapp.components.basecomponent.FileData(app_id: str, name: str = '', id: int | None = None)#

Bases: object

Parameters:

  • app_id (str)

  • name (str)

  • id (int | None)

class ngapp.components.basecomponent.Storage(component: T | ngapp.App)#

Bases: object

Storage class for components, use it to store large chunks of data on the backend

Parameters:

component (T | ngapp.App)

append(key: str, value, use_pickle=False)#

Append value to the list stored under key.

Parameters:

key (str)

delete(key: str)#

Delete data from storage

Parameters:

key (str)

get(key: str, default=None, cache=True)#

Get data from storage. With cache=False a value that is not in memory yet is downloaded without being kept (for large entries that are only needed once).

Parameters:

key (str)

get_list(
key: str,
start: int = 0,
stop: int | None = None,
cache=True,
) → list#

Items start:stop of the list stored under key.

Parameters:

  • key (str)

  • start (int)

  • stop (int | None)

Return type:

list

static list_keys(changed) → set[str]#

The list names among the changed keys of an on_change callback.

Return type:

set[str]

list_len(key: str) → int#

Number of items in the list stored under key.

Parameters:

key (str)

Return type:

int

on_change(callback)#

Call callback(changed_keys) when published changes arrive.

In a local app this happens on publish() itself; when the changes come from a compute node, once the client received them (the data of changed entries is fetched lazily on get). A full load of the app does not trigger it, use the app’s load event for that. Returns a function that removes the callback.

publish()#

Make the changes since the last publish visible to the on_change callbacks: directly in a local app, on a compute node by uploading them and pushing the metadata through the backend, which also stores it in the file (a later load of the file sees the same state).

set(
key: str,
value: str | dict | list | bytes | object,
use_pickle=False,
)#

Set data in storage

Parameters:

  • key (str)

  • value (str | dict | list | bytes | object)