spyder.api.widgets.main_widget

Main plugin widget.

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

Functions

run_test()

Classes

PluginMainWidget(name, plugin[, parent])

Spyder plugin main widget class.

class spyder.api.widgets.main_widget.PluginMainWidget(name, plugin, parent=None)

Bases: QWidget, SpyderWidgetMixin

Spyder plugin main widget class.

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

Notes

All Spyder dockable plugins define a main widget that must subclass this.

This widget is a subclass of QMainWindow that consists of a single, central widget and a set of toolbars that are stacked above or below that widget.

The toolbars are not moveable 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 = False

This attribute enables/disables showing a spinner on the top right to the left of the corner menu widget (Hamburguer menu).

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

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

Parameters:

ENABLE_SPINNER (bool) – 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. Default is False.

CONTEXT_NAME = None

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

If actions, toolbars, toolbuttons or menus belong to the global scope of the plugin, then this attribute should have a None value.

MARGIN_TOP = 0

Use this attribute to adjust the widget’s top margin in pixels.

SHOW_MESSAGE_WHEN_EMPTY = False

This attribute enables/disables showing a message when the widget is empty.

Notes

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

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

MESSAGE_WHEN_EMPTY = None

This is the main message that will be shown when the widget is empty.

Notes

• This must be a string

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

IMAGE_WHEN_EMPTY = None

Name of or path to the svg image to show when the widget is empty (optional).

Notes

• This needs to be an svg file so that it can be rendered correctly in high resolution screens.

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

DESCRIPTION_WHEN_EMPTY = None

This is the description (i.e. additional text) that will be shown when the widget is empty (optional).

Notes

• This must be a string.

• The Find in files plugin is an example of a core plugin that uses this.

SET_LAYOUT_WHEN_EMPTY = True

Whether to automatically set a vertical layout for the stacked widget that holds the empty message widget and the content one.

Notes

• You need to set this to False if you need to set a more complex layout in your widget.

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

sig_free_memory_requested

This signal can be emitted to request the main application to garbage collect deleted objects.

sig_quit_requested

This signal can be emitted to request the main application to quit.

sig_restart_requested

This signal can be emitted to request the main application to restart.

sig_redirect_stdio_requested

This signal can be emitted to request the main application to redirect standard output/error when using Open/Save/Browse dialogs within widgets.

Parameters:

enable (bool) – Enable/Disable standard input/output redirection.

sig_exception_occurred

This signal can be emitted to report an exception handled by this widget.

Parameters:

• methods (# --- Optional overridable)

• error_data (dict) –

  The dictionary containing error data. The expected keys are:

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

Notes

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

This signal is emitted to inform the 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) – New visibility of the dockwidget.

sig_update_ancestor_requested

This signal is emitted to inform the main window that a child widget needs its ancestor to be updated.

sig_unmaximize_plugin_requested

This signal is emitted to inform the main window that it needs to unmaximize the currently maximized plugin, if any.

Parameters:

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

sig_focus_status_changed

This signal is emitted to inform the focus status of the widget.

Parameters:

status (bool) – True if the widget is focused. False otherwise.

setLayout(layout)

Set layout of the main widget of this plugin.

closeEvent(self, a0: QCloseEvent | None)

focusInEvent(self, a0: QFocusEvent | None)

focusOutEvent(self, a0: QFocusEvent | None)

get_plugin()

Return the parent plugin.

get_action(name, context: str | None = None, plugin: str | None = None)

Return action by name.

add_corner_widget(action_or_widget, before=None)

Add widget to corner, that is to the left of the last added widget.

Parameters:

• action_or_widget (QAction or QWidget) – Any action or widget to add to the corner widget.

• before (QAction or QWidget) – Insert action_or_widget before this one.

Notes

By default widgets are added to the left of the last corner widget.

The central widget provides an options menu button and a spinner so any additional widgets will be placed by default to the left of the spinner, if visible.

get_corner_widget(name)

Return the a widget inside the corner widget by name.

Parameters:

name (str) – Unique name of the widget.

start_spinner()

Start default status spinner.

stop_spinner()

Stop default status spinner.

create_toolbar(toolbar_id)

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

Parameters:

toolbar_id (str) – Unique toolbar string identifier.

Returns:

The auxiliary toolbar that was created and added to the plugin interface.

Return type:

SpyderPluginToolbar

get_options_menu()

Return the main options menu of the widget.

get_options_menu_button()

Return the main options menu button of the widget.

get_main_toolbar()

Return the main toolbar of the plugin.

Returns:

The main toolbar of the widget that contains the options button.

Return type:

QToolBar

get_auxiliary_toolbars()

Return the auxiliary toolbars of the plugin.

Returns:

A dictionary of wirh toolbar IDs as keys and auxiliary toolbars as values.

Return type:

OrderedDict

set_icon_size(icon_size)

Set the icon size of the plugin’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, timeout)

Show a status message in the Spyder widget.

get_focus_widget()

Get the widget to give focus to.

Returns:

QWidget to give focus to.

Return type:

QWidget

Notes

This is applied when the plugin’s dockwidget is raised to the top.

update_margins(margin=None)

Update central widget margins.

update_title()

Update title of dockwidget or plugin window.

set_name(name)

Set widget name (plugin.NAME).

get_name()

Return widget name (plugin.NAME).

set_icon(icon)

Set widget icon.

get_icon()

Return widget icon.

render_toolbars()

Render all the toolbars of the widget.

Notes

This action can only be performed once.

set_content_widget(widget, add_to_stack=True)

Set the widget that actually displays content when there is an empty message.

Parameters:

• widget (QWidget) – Widget to set as the widget with content.

• add_to_stack (bool) – Whether to add this widget to stacked widget that holds the empty message.

show_content_widget()

Show the widget that actually displays content when there is an empty message.

show_empty_message()

Show the empty message widget.

create_window()

Create an undocked window containing this widget.

dock_window()

Dock undocked window back to the main window.

close_window()

Close undocked window when clicking on the close window button.

Notes

• 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 plugin’s Options 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 plugins without docking/undocking them first.

change_visibility(enable, force_focus=None)

Dock widget visibility has changed.

toggle_view(checked)

Toggle dockwidget’s visibility when its entry is selected in the menu Window > Panes.

Parameters:

checked (bool) – Is the entry in Window > Panes checked or not?

Notes

If you need to attach some functionality when this changes, use sig_toggle_view_changed. For an example, please see spyder/plugins/ipythonconsole/plugin.py

create_dockwidget(mainwindow)

Add to parent QMainWindow as a dock widget.

close_dock()

Close the dockwidget.

lock_unlock_position()

Show/hide title bar to move/lock position.

get_maximized_state()

Get dockwidget’s maximized state.

set_maximized_state(state)

Set internal attribute that holds dockwidget’s maximized state.

Parameters:

state (bool) – True if the plugin is maximized, False otherwise.

get_title()

Return the title that will be displayed on dockwidget or window title.

set_ancestor(ancestor)

Needed to update the ancestor/parent of child widgets when undocking.

setup()

Create widget actions, add to menu and other setup requirements.

update_actions()

Update the state of exposed actions.

Exposed actions are actions created by the self.create_action method.

on_close()

Perform actions before the widget is closed.

This method must only operate on local attributes.

on_focus_in()

Perform actions when the widget receives focus.

on_focus_out()

Perform actions when the widget loses focus.