Main window#
The datalab.gui.main module provides the main window of the
DataLab project.
- class datalab.gui.main.DLMainWindow(console=None, hide_on_close=False)[source]#
DataLab main window
- Parameters:
console – enable internal console
hide_on_close – True to hide window on close
- static xmlrpc_server_started(port)[source]#
XML-RPC server has started, writing comm port in configuration file
- get_group_titles_with_object_info() tuple[list[str], list[list[str]], list[list[str]]][source]#
Return groups titles and lists of inner objects uuids and titles.
- Returns:
Groups titles, lists of inner objects uuids and titles
- get_object_titles(panel: Literal['signal', 'image', 'macro'] | None = None) list[str][source]#
Get object (signal/image) list for current panel. Objects are sorted by group number and object index in group.
- Parameters:
panel – panel name. If None, current data panel is used (i.e. signal or image panel).
- Returns:
List of object titles
- Raises:
ValueError – if panel is unknown
- get_object(nb_id_title: int | str | None = None, panel: Literal['signal', 'image'] | None = None) SignalObj | ImageObj[source]#
Get object (signal/image) from index.
- Parameters:
nb_id_title – Object number, or object id, or object title. Defaults to None (current object).
panel – Panel name. Defaults to None (current panel).
- Returns:
Object
- Raises:
KeyError – if object not found
ValueError – if multiple objects have the same title
TypeError – if index_id_title type is invalid
- find_object_by_uuid(uuid: str) SignalObj | ImageObj | ObjectGroup | None[source]#
Find an object by UUID, searching across all panels.
This method searches for an object in both signal and image panels, making it suitable for cross-panel operations (e.g., radial profile that takes an ImageObj and produces a SignalObj).
Difference from get_object(): - get_object() requires specifying a panel and accepts number/id/title - find_object_by_uuid() searches all panels automatically using only UUID
- Parameters:
uuid – UUID of the object to find
- Returns:
The object if found in any panel, None otherwise
- resolve_title_reference(reference: str) tuple[str, SignalObj | ImageObj | ObjectGroup] | None[source]#
Resolve a title reference to
(panel_str, object or group).- Parameters:
reference –
<UUID8>(object) org<UUID8>(group) reference- Returns:
The unique match across signal and image panels, or None if the reference matches nothing or is ambiguous.
- get_object_uuids(panel: Literal['signal', 'image'] | None = None, group: int | str | None = None) list[str][source]#
Get object (signal/image) uuid list for current panel. Objects are sorted by group number and object index in group.
- Parameters:
panel – panel name. If None, current panel is used.
group – Group number, or group id, or group title. Defaults to None (all groups).
- Returns:
List of object uuids
- Raises:
ValueError – if panel is unknown
- get_sel_object_uuids(include_groups: bool = False) list[str][source]#
Return selected objects uuids.
- Parameters:
include_groups – If True, also return objects from selected groups.
- Returns:
List of selected objects uuids.
- get_current_object_uuid() str | None[source]#
Return current object uuid in current panel.
- Returns:
UUID of the current object, or None if no object is current.
- add_group(title: str, panel: Literal['signal', 'image'] | None = None, select: bool = False) str[source]#
Add group to DataLab.
- Parameters:
title – Group title
panel – Panel name. Defaults to None.
select – Select the group after creation. Defaults to False.
- Returns:
UUID of the created group
- select_objects(selection: list[int | str], panel: Literal['signal', 'image'] | None = None) None[source]#
Select objects in current panel.
- Parameters:
selection – List of object numbers (1 to N) or uuids to select
panel – panel name. If None, current panel is used. Defaults to None.
- select_groups(selection: list[int | str] | None = None, panel: Literal['signal', 'image'] | None = None) None[source]#
Select groups in current panel.
- Parameters:
selection – List of group numbers (1 to N), or list of group uuids, or None to select all groups. Defaults to None.
panel – panel name. If None, current panel is used. Defaults to None.
- delete_metadata(refresh_plot: bool = True, keep_roi: bool = False) None[source]#
Delete metadata of selected objects
- Parameters:
refresh_plot – Refresh plot. Defaults to True.
keep_roi – Keep ROI. Defaults to False.
- call_method(method_name: str, *args, panel: Literal['signal', 'image'] | None = None, **kwargs)[source]#
Call a public method on a panel or main window.
This generic method allows calling any public method that is not explicitly exposed in the proxy API. The method resolution follows this order:
If panel is specified: call method on that specific panel
If panel is None: a. Try to call method on main window (DLMainWindow) b. If not found, try to call method on current panel (BaseDataPanel)
This makes it convenient to call panel methods without specifying the panel parameter when working on the current panel.
- Parameters:
method_name – Name of the method to call
*args – Positional arguments to pass to the method
panel – Panel name (“signal”, “image”, or None for auto-detection). Defaults to None.
**kwargs – Keyword arguments to pass to the method
- Returns:
The return value of the called method
- Raises:
AttributeError – If the method does not exist or is not public
ValueError – If the panel name is invalid
Examples
>>> # Call remove_object on current panel (auto-detected) >>> win.call_method("remove_object", force=True) >>> # Call a signal panel method specifically >>> win.call_method("delete_all_objects", panel="signal") >>> # Call main window method >>> win.call_method("get_current_panel")
- remote_request_context() Iterator[None][source]#
Context in which a request of a remote client runs (XML-RPC, Web API).
Errors are propagated to the caller, which reports them to the client, instead of being shown in a message box: no user waits for it, and showing a message box crashes DataLab when it runs without display. The error is also shown in the status bar.
- call_method_slot(method_name: str, args: list, panel: Literal['signal', 'image'] | None, kwargs: dict) None[source]#
Slot to call a method from RemoteServer thread in GUI thread.
This slot receives signals from RemoteServer and executes the method in the GUI thread, avoiding thread-safety issues with Qt widgets and dialogs.
- Parameters:
method_name – Name of the method to call
args – Positional arguments as a list
panel – Panel name or None for auto-detection
kwargs – Keyword arguments as a dict
- run_remote_command(command: Callable[..., object], *args, return_result: bool = False) None[source]#
Slot to run a command requested by a remote client in GUI thread.
The exception raised by the command, if any, is stored in RemoteServer to be re-raised to the client. Being remote controlled, this slot signals that DataLab is ready only once the command is done and its exception stored.
- Parameters:
command – Main window method running the command
args – Command arguments
return_result – If True, store the command result in RemoteServer, to be returned to the client (it must be XML-RPC serializable)
- get_object_shapes(nb_id_title: int | str | None = None, panel: Literal['signal', 'image'] | None = None) list[source]#
Get plot item shapes associated to object (signal/image).
- Parameters:
nb_id_title – Object number, or object id, or object title. Defaults to None (current object).
panel – Panel name. Defaults to None (current panel).
- Returns:
List of plot item shapes
- add_annotations_from_items(items: list, refresh_plot: bool = True, panel: Literal['signal', 'image'] | None = None) None[source]#
Add object annotations (annotation plot items).
- Parameters:
items – annotation plot items
refresh_plot – refresh plot. Defaults to True.
panel – panel name. If None, current panel is used.
- add_label_with_title(title: str | None = None, panel: Literal['signal', 'image'] | None = None) None[source]#
Add a label with object title on the associated plot
- Parameters:
title – Label title. Defaults to None. If None, the title is the object title.
panel – panel name. If None, current panel is used.
- run_macro(number_or_title: int | str | None = None) None[source]#
Run macro.
- Parameters:
number – Number of the macro (starting at 1). Defaults to None (run current macro, or does nothing if there is no macro).
- stop_macro(number_or_title: int | str | None = None) None[source]#
Stop macro.
- Parameters:
number – Number of the macro (starting at 1). Defaults to None (stop current macro, or does nothing if there is no macro).
- import_macro_from_file(filename: str) None[source]#
Import macro from file
- Parameters:
filename – Filename.
- start_webapi_server(host: str | None = None, port: int | None = None) dict[source]#
Start the Web API server.
- Parameters:
host – Host address to bind to. Defaults to “127.0.0.1”.
port – Port number. Defaults to auto-detect available port.
- Returns:
Dictionary with “url” and “token” keys.
- Raises:
RuntimeError – If Web API imports are unavailable or the server is running.
- get_webapi_status() dict[source]#
Get Web API server status.
- Returns:
Dictionary with “running”, “url”, “token” and “available” keys.
- property panels: tuple[AbstractPanel, ...]#
Return the tuple of implemented panels (signal, image, macro, history)
- Returns:
Tuple of panels
Take menu screenshots
- open_plugin_instrument(plugin: PluginBase, tool: PluginTool) InstrumentWindow[source]#
Show the instrument window of a plugin tool, creating it if needed.
The successive windows of an instrument share its worker: a window opened again calls the instrument once the closed one has closed it.
- close_plugin_instruments() None[source]#
Close all plugin instrument windows, and wait for their instruments, including those of windows closed before, within a common time limit.
- show_applications(plugin_id: str | None = None) None[source]#
Show the Applications panel
The first time, the panel floats beside the main window; afterwards, it is shown where the user left it (docked, tabified or floating). When it is already shown with the requested application, it flashes to draw attention to it; switching to another application needs no flashing.
- Parameters:
plugin_id – ID of the application plugin to show (default: the one already shown)
- reload_plugins() None[source]#
Reload third-party plugins at runtime.
This unregisters active plugins, clears plugin actions from both panels, re-discovers plugin modules (reloading code changes from disk), re-registers enabled plugins, then recreates plugin actions and refreshes menus.
- show_command_palette() None[source]#
Show the command palette (searchable list of menu commands).
Lists every command available for the current panel by its menu path and triggers the one chosen by the user.
- set_process_isolation_enabled(state: bool) None[source]#
Enable/disable process isolation
- Parameters:
state – True to enable process isolation
- get_current_panel() str[source]#
Return current panel name
- Returns:
“signal”, “image”, “macro”)
- Return type:
Panel name (valid values
- current_panel_name() str[source]#
Return current panel name, without processing pending events
Unlike
get_current_panel(), this may be called while Qt is handling an event, e.g. from a show event (see issue #527).- Returns:
“signal”, “image”, “macro”)
- Return type:
Panel name (valid values
- set_current_panel(panel: Literal['signal', 'image', 'macro'] | BaseDataPanel) None[source]#
Switch to panel.
- Parameters:
panel – panel name or panel instance
- Raises:
ValueError – unknown panel
- calc(name: str, param: DataSet | None = None, edit: bool = True) None[source]#
Call computation feature
nameNote
This calls either the processor’s
compute_<name>method (if it exists), or the processor’s<name>computation feature (if it is registered, using therun_featuremethod). It looks for the function in all panels, starting with the current one.- Parameters:
name – Compute function name
param – Compute function parameter. Defaults to None.
edit – Whether to show parameter edit dialog. Defaults to True. Set to False when calling from remote/API to avoid blocking dialogs.
- Raises:
FeatureNotFoundError – unknown function (a
ValueError)
- toggle_show_titles(state: bool) None[source]#
Toggle show annotations option
- Parameters:
state – state
- handle_autorefresh_action(state: bool) None[source]#
Handle auto-refresh action from UI (with confirmation dialog)
- Parameters:
state – desired state
- toggle_show_first_only(state: bool) None[source]#
Toggle show first only option
- Parameters:
state – state
- verify_provenance_activity(activity_id: str) dict[source]#
Recompute a recorded activity as a separate candidate and compare it.
Nothing is inserted in the workspace and the ledger is not modified.
- Parameters:
activity_id – Identifier of the recorded activity.
- Returns:
Verification report (JSON-compatible).
- show_capsule_dialog() None[source]#
Show the workspace capsule dialog (export, inspect, replay, compare).
- export_capsule(filename: str, name: str | None = None, description: str | None = None, as_revision: bool = True, workspace_ref: str | None = None, workspace_filename: str | None = None, attachments: list[str] | None = None) str[source]#
Export the workspace as a capsule (workspace and its provenance).
- Parameters:
filename – Capsule file name (
.dlcapsule).name – Capsule name.
description – Capsule description.
as_revision – When the workspace was opened from a capsule, name that capsule as the parent revision. Defaults to True.
workspace_ref – Absolute IRI where the workspace will be published: the capsule then references the workspace instead of including it, and the workspace is saved apart, to workspace_filename.
workspace_filename – File name of the workspace published at workspace_ref (default: last segment of the IRI, next to the capsule).
attachments – Light files (protocol, notes, small tables, 16 MiB at most each) declared in the capsule, never opened or executed.
- Returns:
Manifest fingerprint of the capsule.
- open_capsule(filename: str, workspace: str | None = None) None[source]#
Open a capsule as the workspace, replacing the current one.
The capsule is checked first (archive, manifest, workspace SHA-256 and size): the workspace is left unchanged if it is invalid. A revision exported later names this capsule as its parent.
- Parameters:
filename – Capsule file name (
.dlcapsule).workspace – Workspace file of a capsule that references its workspace instead of including it.
- remove_object(force: bool = False) None[source]#
Remove current object from current panel.
- Parameters:
force – if True, remove object without confirmation. Defaults to False.
- save_to_h5_file(filename: str | None = None) None[source]#
Save to a DataLab HDF5 file
- Parameters:
filename – HDF5 filename. If None, a file dialog is opened.
- Raises:
IOError – if filename is invalid or file cannot be saved.
- open_h5_files(h5files: list[str] | None = None, import_all: bool | None = None, reset_all: bool | None = None) None[source]#
Open a DataLab HDF5 file or import from any other HDF5 file.
When the question about clearing the workspace will be asked, the files are chosen first: if a workspace file holds provenance, the question says that appending it ignores that provenance (no further warning).
- Parameters:
h5files – HDF5 filenames (optionally with dataset name, separated by “,”)
import_all – Import all datasets from HDF5 files
reset_all – Reset all application data before importing
- import_dataset_from_file(filename: str, dsetname: str | None, import_all: bool | None, reset_all: bool) None[source]#
Open a DataLab workspace file, or import a single dataset from it
- Parameters:
filename – Path to the HDF5 file (already validated)
dsetname – Dataset name to import, or
Noneto import allimport_all – If
True, import all datasets without browsingreset_all – If
True, clear workspace before importing
- import_all_from_h5_file(filename: str, reset_all: bool | None = None) None[source]#
Import an HDF5 file through the DataLab HDF5 browser
- Parameters:
filename – HDF5 filename
reset_all – Delete all DataLab signals/images before importing data
- browse_h5_files(filenames: list[str], reset_all: bool | None = None) None[source]#
Browse HDF5 files
- Parameters:
filenames – HDF5 filenames
reset_all – Reset all application data before importing
- load_h5_workspace(h5files: list[str], reset_all: bool = False) None[source]#
Load native DataLab HDF5 workspace files programmatically.
This method does not create file-selection widgets or progress bars. When history recording is active and the new-session policy is
"ask", a history-session question may still be shown before loading.When a file holding provenance is appended (
reset_all=False), its provenance is not imported: no question is asked, and the noticedatalab_capsule.recorder.APPEND_NOTICEis added toprovenance.notices(and logged).Warning
This method only supports native DataLab HDF5 files. For importing arbitrary HDF5 files (non-native), use the GUI menu or macros with
datalab.control.proxy.RemoteProxy.- Parameters:
h5files – List of native DataLab HDF5 filenames
reset_all – Reset all application data before importing. Defaults to False.
- Raises:
ValueError – If a file is not a valid native DataLab HDF5 file
- save_h5_workspace(filename: str) None[source]#
Save current workspace to a native DataLab HDF5 file without GUI elements.
This method can be safely called from the internal console as it does not create any Qt widgets, dialogs, or progress bars. It is designed for programmatic use when saving DataLab workspace files.
- Parameters:
filename – HDF5 filename to save to
- Raises:
IOError – If file cannot be saved
- import_h5_file(filename: str, reset_all: bool | None = None) None[source]#
Import HDF5 file into DataLab
- Parameters:
filename – HDF5 filename (optionally with dataset name,
" (separated by)
")
reset_all – Delete all DataLab signals/images before importing data
- add_object(obj: SignalObj | ImageObj, group_id: str = '', set_current=True, new_session_behavior: SessionBehavior | None = None) bool[source]#
Add object - signal or image
- Parameters:
obj – object to add (signal or image)
group_id – group ID (optional)
set_current – True to set the object as current object
new_session_behavior – Optional history session creation policy
- Returns:
True if the object was added successfully, False otherwise
- set_object(obj: SignalObj | ImageObj) None[source]#
Set object data - update an existing signal or image in-place.
The existing object is identified by UUID carried by
obj(from a previousget_object()call).
- load_from_files(filenames: list[str], param: DataSet | None = None) None[source]#
Open objects from files in current panel (signals/images)
- Parameters:
filenames – list of filenames
param – Optional format-specific import parameters applied to every file requiring them, without showing any dialog. Defaults to None.
- load_from_directory(path: str, param: DataSet | None = None) None[source]#
Open objects from directory in current panel (signals/images).
- Parameters:
path – directory path
param – Optional format-specific import parameters applied to every file requiring them, without showing any dialog. Defaults to None.
- add_signal(title: str, xdata: np.ndarray, ydata: np.ndarray, xunit: str = '', yunit: str = '', xlabel: str = '', ylabel: str = '', group_id: str = '', set_current: bool = True, new_session_behavior: SessionBehavior | None = None) bool[source]#
Add signal data to DataLab.
- Parameters:
title – Signal title
xdata – X data
ydata – Y data
xunit – X unit. Defaults to “”
yunit – Y unit. Defaults to “”
xlabel – X label. Defaults to “”
ylabel – Y label. Defaults to “”
group_id – group id in which to add the signal. Defaults to “”
set_current – if True, set the added signal as current
new_session_behavior – Optional history session creation policy
- Returns:
True if signal was added successfully, False otherwise
- Raises:
ValueError – Invalid xdata dtype
ValueError – Invalid ydata dtype
- add_image(title: str, data: np.ndarray, xunit: str = '', yunit: str = '', zunit: str = '', xlabel: str = '', ylabel: str = '', zlabel: str = '', group_id: str = '', set_current: bool = True, *, new_session_behavior: SessionBehavior | None = None) bool[source]#
Add image data to DataLab.
- Parameters:
title – Image title
data – Image data
xunit – X unit. Defaults to “”
yunit – Y unit. Defaults to “”
zunit – Z unit. Defaults to “”
xlabel – X label. Defaults to “”
ylabel – Y label. Defaults to “”
zlabel – Z label. Defaults to “”
group_id – group id in which to add the image. Defaults to “”
set_current – if True, set the added image as current
new_session_behavior – Optional history session creation policy
- Returns:
True if image was added successfully, False otherwise
- Raises:
ValueError – Invalid data dtype