spyder.api.widgets.main_widget

spyder.api.widgets.main_widget#

Main plugin widget.

SpyderDockablePlugin plugins must provide a WIDGET_CLASS attribute that is a subclass of PluginMainWidget.

Classes

PluginMainWidget(name, plugin[, parent])

Spyder plugin main widget class.

class spyder.api.widgets.main_widget.PluginMainWidget( name: str, plugin: SpyderPluginV2, parent: spyder.app.mainwindow.MainWindow | None = None, )[source]#

Bases: QWidget, SpyderWidgetMixin

Spyder plugin main widget class.

This class handles both a dockwidget pane and a floating window widget (undocked pane).

Note

All SpyderDockablePlugins define a main widget that must be a subclass of this class.

Notes

This widget is a subclass of QWidget that consists of a single central widget and a set of toolbars stacked above it.

The toolbars are not movable nor floatable and must occupy the entire horizontal space available for the plugin. This mean that toolbars must be stacked vertically and cannot be placed horizontally next to each other.

ENABLE_SPINNER: bool = False#

Enable/disable showing a progress spinner on the top right of the toolbar.

If True, an extra space will be added to the toolbar (even if the spinner is not moving) to avoid items jumping to the left/right when the spinner appears. If False no extra space will be added.

The spinner is shown to the left of the Options (hamburger) menu.

Plugins that provide actions that take time should make this True and use the start_spinner()/stop_spinner() methods accordingly.

Examples

The Find in Files plugin (spyder.plugins.findinfiles is an example of a core plugin that uses it.

CONTEXT_NAME: str | None = None#

The name under which to store actions, toolbars, toolbuttons and menus.

This optional attribute defines the context name under which actions, toolbars, toolbuttons and menus should be registered in the Spyder global registry.

If those elements belong to the global scope of the plugin, then this attribute should have a None value, which will use the plugin’s name as the context scope.

MARGIN_TOP: int = 0#: Adjust the widget’s top margin in integer pixels.

SHOW_MESSAGE_WHEN_EMPTY: bool = False#

Enable or (by default) disable showing a message when the widget is empty.

Note

If True, you need to set at least the MESSAGE_WHEN_EMPTY attribute as well.

Examples

The Find in Files plugin is an example of a core plugin that uses it.

MESSAGE_WHEN_EMPTY: str | None = None#

The main message, as a string, that will be shown when the widget is empty.

Must be set to a string when SHOW_MESSAGE_WHEN_EMPTY is True, and has no effect if that attribute is False.

Examples

The Find in Files plugin is an example of a core plugin that uses it.

IMAGE_WHEN_EMPTY: str | None = None#

Name of or path to an SVG image to show when the widget is empty.

If None (the default), no image is shown.

Only shown when SHOW_MESSAGE_WHEN_EMPTY is set to True.

Note

This needs to be an SVG file so that it can be rendered correctly on high-resolution screens.

Examples

The Find in Files plugin is an example of a core plugin that uses it.

DESCRIPTION_WHEN_EMPTY: str | None = None#

Additional text shown below the main message when the widget is empty.

If None (the default), no additional text is shown.

Only shown when SHOW_MESSAGE_WHEN_EMPTY is set to True, and shown below MESSAGE_WHEN_EMPTY.

Examples

The Find in Files plugin is an example of a core plugin that uses it.

SET_LAYOUT_WHEN_EMPTY: bool = True#

Use a vertical layout for the stack holding the empty and content widgets.

Set this to False if you need to use a more complex layout in your widget; True is the default behavior.

Examples

The Debugger plugin is an example of a core plugin that uses it.

sig_free_memory_requested: Signal#: Signal to request the main application garbage-collect deleted objects.

sig_quit_requested: Signal#: Signal to request the main Spyder application quit.

sig_restart_requested: Signal#: Signal to request the main Spyder application quit and restart itself.

sig_redirect_stdio_requested(bool): Signal#

Request the main app redirect standard out/error within file pickers.

This will redirect stdin, stdout, and stderr when using Open, Save, and Browse dialogs within a plugin’s widgets.

Parameters:: enable (bool) – Enable (True) or disable (False) standard input/output redirection.

sig_exception_occurred(PyQt_PyObject): Signal#

Signal to report an exception from a plugin.

Parameters:

error_data (dict[str, str | bool]) –

The dictionary containing error data. The expected keys are:

error_data = {
    "text": str,
    "is_traceback": bool,
    "repo": str,
    "title": str,
    "label": str,
    "steps": str,
}

The is_traceback key indicates if text contains plain text or a Python error traceback.

The title and repo keys indicate how the error data should customize the report dialog and GitHub error submission.

The label and steps keys allow customizing the content of the error dialog.

sig_toggle_view_changed(bool): Signal#

Signal to report that visibility of a dockable plugin has changed.

This is triggered by checking/unchecking the entry for a pane in the Window ‣ Panes menu.

Parameters:: visible (bool) – Whether the widget has been shown (True) or hidden (False).

sig_update_ancestor_requested: Signal#: Notify the main window that a child widget needs its ancestor updated.

sig_unmaximize_plugin_requested(), (PyQt_PyObject): Signal#

Request the main window unmaximize the currently maximized plugin, if any.

If emitted without arguments, it’ll unmaximize any plugin.

Parameters:: plugin_instance (spyder.api.plugins.SpyderDockablePlugin) – Unmaximize current plugin only if it is not plugin_instance.

sig_focus_status_changed(bool): Signal#

Signal to report a change in the focus state of this widget.

Parameters:: status (bool) – True if the widget is now focused; False if it is not.

__init__( name: str, plugin: SpyderPluginV2, parent: spyder.app.mainwindow.MainWindow | None = None, ) → None[source]#

Create a new main widget for a plugin.

The widget is created automatically by Spyder, and is not intended to be instantiated manually.

Parameters:

name (str) – The name of the plugin, i.e. the SpyderPluginV2.NAME.
plugin (SpyderPluginV2) – The plugin object this is to be the container class of.
parent (spyder.app.mainwindow.MainWindow | None, optional) – The container’s parent widget, normally the Spyder main window. By default (None), no parent widget (used for testing).

Return type:

None

Raises:

SpyderAPIError – If SHOW_MESSAGE_WHEN_EMPTY is set to True but MESSAGE_WHEN_EMPTY is not set to a non-empty string.

setLayout(layout: QLayout) → None[source]#: Set layout for the widget.

closeEvent(event: QCloseEvent) → None[source]#

Handle closing the widget.

Parameters:: event (QCloseEvent) – The event object closing this widget.
Return type:: None

focusInEvent(event: QFocusEvent) → None[source]#

Handle the widget gaining focus.

Parameters:: event (QFocusEvent) – The focus event object.
Return type:: None

focusOutEvent(event: QFocusEvent) → None[source]#

Handle the widget losing focus.

Parameters:: event (QFocusEvent) – The focus event object.
Return type:: None

get_plugin() → SpyderPluginV2[source]#

Return the parent plugin of this widget.

Returns:: The parent plugin of this widget.
Return type:: SpyderPluginV2

get_action( name: str, context: str | None = None, plugin: str | None = None, ) → spyder.utils.qthelpers.SpyderAction[source]#

Return an action by name, context and plugin.

Parameters:

name (str) – Identifier of the action to retrieve.
context (str | None, optional) – Context identifier under which the action was stored. If None, the default, then the CONTEXT_NAME attribute is used instead.
plugin (str | None, optional) – Identifier of the plugin in which the action was defined. If None, the default, then the PLUGIN_NAME attribute is used instead.

Returns:

The corresponding action stored under the given name,: context and plugin.

Return type:

spyder.utils.qthelpers.SpyderAction

Raises:

KeyError – If the combination of name, context and plugin keys does not exist in the action registry.

add_corner_widget( action_or_widget: spyder.utils.qthelpers.SpyderAction | QWidget, before: spyder.utils.qthelpers.SpyderAction | QWidget | None = None, ) → None[source]#

Add a widget to the corner toolbar.

By default, widgets are added to the left of the last toolbar item. Corner widgets provide an options menu button and a spinner so any additional widgets will be placed the left of the spinner, if visible (unless before is set).

Parameters:

widget (spyder.utils.qthelpers.SpyderAction | QWidget) – The action or widget to add to the toolbar.
before (spyder.utils.qthelpers.SpyderAction | QWidget | None, optional) – The action or widget to add widget before (to the right of). If None (the default), the widget will be added to the left of the left-most widget.

Return type:

None

Raises:

SpyderAPIError – If either widget or before lacks a name attribute; a widget with the same name as widget was already added; a widget with before.name has not been added previously; or the first widget added is not the options (hamburger) menu widget.

get_corner_widget( name: str, ) → spyder.utils.qthelpers.SpyderAction | QWidget | None[source]#

Return a widget by its unique ID (i.e. its name attribute).

Parameters:: name (str) – The name attribute of the widget to return.
Returns:: The widget object corresponding to name, or None if a widget with that name does not exist.
Return type:: QWidget | None

start_spinner() → None[source]#

Start the default status spinner.

Return type:: None

stop_spinner() → None[source]#

Stop the default status spinner.

Return type:: None

create_toolbar( toolbar_id: str, ) → MainWidgetToolbar[source]#

Create and add an auxiliary toolbar to the top of the plugin.

Parameters:: toolbar_id (str) – The unique identifier name of this toolbar.
Returns:: The auxiliary toolbar object that was created.
Return type:: MainWidgetToolbar

get_options_menu() → PluginMainWidgetOptionsMenu[source]#

Return the options (“hamburger”) menu for this widget.

Returns:: The options (“hamburger”) menu widget.
Return type:: PluginMainWidgetOptionsMenu

get_options_menu_button() → QToolButton[source]#

Return the options menu button for this widget.

Returns:: The button widget for the plugin options (“hamburger”) menu.
Return type:: QToolButton

get_main_toolbar() → MainWidgetToolbar[source]#

Return the main toolbar of this widget.

Returns:: The main toolbar of the widget that contains the options button.
Return type:: MainWidgetToolbar

get_auxiliary_toolbars() → OrderedDict[MainWidgetToolbar][source]#

Return the auxiliary toolbars of this widget.

Returns:: A dictionary with toolbar IDs as keys and their corresponding auxiliary toolbar widgets as values.
Return type:: OrderedDict[MainWidgetToolbar]

set_icon_size(icon_size: int) → None[source]#

Set the icon size of this widget’s toolbars.

Parameters:: iconsize (int) – An integer corresponding to the size in pixels to which the icons of the plugin’s toolbars need to be set.

show_status_message(message: str, timeout: int) → None[source]#

Show a message in the Spyder status bar.

Parameters:

message (str) – The message to display in the status bar.
timeout (int) – The amount of time, in milliseconds, to display the message. If 0, the default, the message will be shown until a plugin calls show_status_message() again.

Return type:

None

get_focus_widget() → PluginMainWidget[source]#

Get the widget to give focus to.

This is called when this widget’s dockwidget is raised to the top.

Returns:: The widget to give focus to.
Return type:: QWidget

update_margins(margin=None)[source]#

Update the margins of this widget’s central widget.

Parameters:: margin (int | None) – The margins to use for the central widget, or None for the default margins.
Return type:: None

update_title() → None[source]#

Update this widget’s dockwidget title.

Return type:: None

set_name(name: str) → None[source]#

Set this widget’s name.

Note

Normally, this is set to the same as the plugin’s name, SpyderPluginV2.NAME.

Parameters:: name (str) – The name to set.
Return type:: None

get_name() → str[source]#

Return this widget’s name.

By default, the same as the plugin’s name, SpyderPluginV2.NAME.

Returns:: The name of the widget, and normally the plugin as well.
Return type:: str

set_icon(icon: QIcon) → None[source]#

Set this widget’s icon.

Parameters:: icon (QIcon) – The icon object to set as the widget’s icon.
Return type:: None

get_icon() → QIcon[source]#

Get this widget’s icon.

Returns:: The widget’s icon object.
Return type:: QIcon

render_toolbars() → None[source]#

Render all toolbars of this widget.

Caution

This action can only be performed once.

Return type:: None

set_content_widget( widget: QWidget, add_to_stack: bool = True, ) → None[source]#

When there is an empty message, set the widget for actual content,

Parameters:

widget (QWidget) – Widget to set as the widget with actual (non-empty) content.
add_to_stack (bool, optional) – Whether to add this widget to stacked widget that holds the empty message.

Return type:

None

show_content_widget() → None[source]#

Show the widget that displays actual content instead of the empty one.

Return type:: None

show_empty_message() → None[source]#

Show the empty message widget.

Return type:: None

create_window() → None[source]#

Create an undocked window containing this widget.

Return type:: None

dock_window() → None[source]#

Dock an undocked window with this widget back to the main window.

Return type:: None

close_window() → None[source]#

Close undocked window when clicking on the close window button.

This can either dock or hide the window, depending on whether the user hid the window before:

The default behavior is to dock the window, so that new users can experiment with the dock/undock functionality without surprises.
If the user closes the window by clicking on the Close action in the widget’s options (“hamburger”) menu or by going to the Window ‣ Panes menu, then we will hide it when they click on the close button again. That gives users the ability to show/hide panes without docking/undocking them first.

Return type:: None

change_visibility( enable: bool, force_focus: bool | None = None, ) → None[source]#

Raise this widget to the foreground, and/or grab its focus.

Parameters:

state (bool) – Whether the widget is being raised to the foreground (True) or set as not in the foreground (False). The latter does not actually send it to the background, but does configure it for not being actively shown (e.g. it disables its empty pane widget, if any).
force_focus (bool | None, optional) – If True, always give the widget keyboard focus when raising or un-raising it with this method. If None, only give it focus when showing, not hiding (setting state to True), and only if SpyderDockablePlugin.RAISE_AND_FOCUS is True. If False, the default, don’t give it focus regardless.

Return type:

None

toggle_view(checked: bool) → None[source]#

Show or hide this widget in the Spyder interface.

Used to show or hide it from the from the Window ‣ Panes menu.

Parameters:: value (bool) – Whether to show (True) or hide (False) this widget.
Return type:: None

Notes

If you need to attach some functionality when this changes, use sig_toggle_view_changed. For an example, please see spyder.plugins.onlinehelp.widgets.

create_dockwidget( mainwindow: spyder.app.mainwindow.MainWindow, ) → tuple[spyder.widgets.dock.SpyderDockWidget, DockWidgetArea][source]#

Add this widget to the parent Spyder main window as a dock widget.

Parameters:

mainwindow (spyder.app.mainwindow.MainWindow) – The main window to set as the dockwidget’s parent.

Returns:

spyder.widgets.dock.SpyderDockWidget – The newly created dock widget.
Qt.DockWidgetArea – The area of the window the dockwidget is placed in.

close_dock() → None[source]#

Close the dockwidget.

Return type:: None

lock_unlock_position() → None[source]#

Show/hide title bar to move/lock this widget’s position.

Return type:: None

get_maximized_state() → bool[source]#

Get this widget’s maximized state.

Returns:: True if the widget is maximized, False otherwise.
Return type:: bool

set_maximized_state(state: bool) → None[source]#

Set the attribute that holds this widget’s maximized state.

Parameters:: state (bool) – True to set the widget as maximized, False set it as not maximized.
Return type:: None

get_title() → str[source]#

Return the title that will be displayed on dockwidgets or windows.

Returns:: This dockwidget’s tab/window title.
Return type:: str
Raises:: NotImplementedError – If the main widget subclass doesn’t define a get_title method.

set_ancestor(ancestor: QWidget) → None[source]#

Update the ancestor/parent of child widgets when undocking.

Parameters:: ancestor (QWidget) – The window widget to set as a parent of this one.
Return type:: None

setup() → None[source]#

Create widget actions, add to menus and perform other setup steps.

Return type:: None
Raises:: NotImplementedError – If the main widget subclass doesn’t define a setup method.

update_actions() → None[source]#

Update the state of exposed actions.

Exposed actions are actions created by the create_action() method.

Return type:: None
Raises:: NotImplementedError – If the subclass doesn’t define an update_actions method.

on_close() → None[source]#

Perform actions before the widget is closed.

Does nothing by default; intended to be overridden for widgets that need to perform actions on close.

Warning

This method must only operate on local attributes.

Return type:: None

on_focus_in() → None[source]#

Perform actions when the widget receives focus.

Does nothing by default; intended to be overridden for widgets that need to perform actions on gaining focus.

Return type:: None

on_focus_out() → None[source]#

Perform actions when the widget loses focus.

Does nothing by default; intended to be overridden for widgets that need to perform actions on loosing focus.

Return type:: None

spyder.api.widgets.main_widget

Contents

spyder.api.widgets.main_widget#