Skip to content

compas_threejs.viewer.plugin.Plugin ¤

Plugin()

A viewer plugin: toolbar buttons in the frontend, and their Python half.

A subclass sets name and static, the folder holding the plugin's built frontend, plugin.js (and plugin.css, if it has one). plugin.js default-exports definePlugin({ name, groups }) from @compas-dev/compas-threejs-ts, with the same name. A plugin without static is Python only: the page loads nothing for it. Methods marked with @action("...") handle what the frontend sends, and are told which workspace (browser tab) sent it; send answers that tab, send_all talks to every tab.

The plugin is one object for all workspaces: a workspace shows the plugins in Workspace.plugins, by default all of App.plugins - but the main workspace leaves out a plugin whose in_main is False, one made for other tabs (an element's editor).

hide, show, disable and enable take the ids of button groups, single buttons or panels, as the frontend names them in groups and panels. A subclass may list them in ids, so that a misspelled id raises instead of doing nothing.

Examples:

>>> app = App()
>>> standard = Standard()
>>> app.plugins = [standard, Camera()]
>>> standard.hide("display")  # a whole group
>>> standard.disable("scale")  # one button
>>> app.start()

Attributes¤

disabled property ¤

disabled

The ids of the disabled groups and buttons.

hidden property ¤

hidden

The ids of the hidden groups and buttons.

Methods:¤

attached ¤

attached()

Called once the plugin is added to an App: sends the state set before that.

A subclass with state of its own extends it, calling super().attached().

disable ¤

disable(*ids)

Greys out these groups or buttons; their clicks and shortcuts do nothing.

enable ¤

enable(*ids)

Enables these groups or buttons again.

handle ¤

handle(action_name, data, workspace)

Calls the handlers of action_name with data and the Workspace it came from.

A handler that raises is logged and shown to the asking tab as an error notice; the other handlers still run, and the tab stays connected.

hide ¤

hide(*ids)

Hides these groups or buttons.

manifest ¤

manifest()

The entry plugins.json lists for this plugin; paths are relative to the page.

Each path carries the file's modification time (?v=...), so a browser loads a rebuilt plugin instead of the copy it cached.

new_workspace ¤

new_workspace(workspace)

Called when a browser tab asks for a workspace that doesn't exist yet, before it loads its plugins.

A plugin that opens tabs (viewer.workspaceUrl(id) in the frontend) overrides it to set up the workspace: its Workspace.plugins, and its content. See App.on_new_workspace.

notify ¤

notify(message, kind='info', *, workspace=None, key=None, progress=None)

Shows message to the user for a moment, at the bottom of the view.

kind is "info", "success", "warning" or "error". It goes to one workspace, chosen like send's; workspace="all" shows it in every tab.

With a key, it takes the place of the notice with the same key still shown. With a progress (0 to 1) it shows a progress bar, and stays until a notice with its key takes its place - so a long handler can show how far along it is, then how it ended, in one notice::

for i, wall in enumerate(walls):
    self.notify(f"Computing ({i + 1} of {len(walls)})", key="walls", progress=i / len(walls))
    ...
self.notify(f"Computed {len(walls)} walls", "success", key="walls")

A notice with a progress is sent at once, not when the handler is done (see Outbox.batch).

on ¤

on(action_name)

Adds a handler for action_name from outside the plugin, as a decorator.

@camera.on("save") ... def saved(data, workspace): ... print(data, workspace.workspace_id)

send ¤

send(action_name, data=None, *, workspace=None, key=None)

Sends data to the frontend's channel.on(action_name, ...) handlers in one workspace.

That is workspace (a Workspace or its id) if given; otherwise, inside an action handler, the workspace the handled message came from, and elsewhere "main".

With a key, the message is also kept (replacing the last one with that key) and replayed to browsers that connect later - for state, like a list of saved views.

send_all ¤

send_all(action_name, data=None, *, key=None)

Like send, to every workspace - for state the plugin shares between browser tabs.

A keyed message is also replayed to tabs opened later, in any workspace.

send_buttons ¤

send_buttons()

Sends every workspace which groups and buttons are hidden or disabled; kept for browsers that connect later.

show ¤

show(*ids)

Shows these groups or buttons again.

compas_threejs.viewer.plugin.action ¤

action(name)

Marks a Plugin method as the handler of the frontend's channel.send(name, data).

The method is called as method(data, workspace) on the server thread, with the Workspace of the browser tab the message came from.