spyder.api.widgets.mixins

spyder.api.widgets.mixins#

Mixin classes for the Spyder widget API.

Classes

`SpyderActionMixin`()	Provide methods to create, add and get actions in a unified way.
`SpyderMainWindowMixin`()	Mixin with additional functionality for Spyder's `QMainWindow`s.
`SpyderMenuMixin`()	Provide methods to create, add and get menus.
`SpyderToolButtonMixin`()	Provide methods to create, add and get toolbar buttons.
`SpyderToolbarMixin`()	Provide methods to create, add and get toolbars.
`SpyderWidgetMixin`([class_parent, parent])	Basic functionality for all Spyder widgets and Qt items.
`SvgToScaledPixmap`()	Mixin to transform an SVG to a QPixmap.

class spyder.api.widgets.mixins.SpyderToolButtonMixin[source]#

Bases: object

Provide methods to create, add and get toolbar buttons.

Create a new Spyder toolbar button.

Parameters:

name (str) – Unique identifier for the toolbutton.
text (str | None, optional) – Localized text for the toolbutton, displayed in the interface. If None, the default, no text is shown.
icon (QIcon | str | None, optional) – Icon name or object to use in the toolbutton. If None, the default, no icon is shown.
tip (str | None, optional) – Tooltip text for the toolbutton. If None (the default), no tooltip is shown.
toggled (Callable[[Any], None] | bool | None, optional) – If None (default) then the button doesn’t act like a checkbox. If True, then the button modifies the configuration option on the section specified (or the default CONF_SECTION if section is not set). Otherwise, must be a callable, called when toggling this button. One of toggled and triggered must not be None.
triggered (Callable[[], None] | None, optional) – If a callable, will be called when triggering this button. Otherwise, if None (the default), this will not be a triggered button and toggled must be non-None instead.
autoraise (bool, optional) – If True (the default), the button will only draw a 3D frame when hovered over. If False, will draw the button frame all the time.
text_beside_icon (bool, optional) – If True, the button text will be displayed beside the icon. If False (the default), will only show the icon.
section (str | None, optional) – Name of the configuration section whose option is going to be modified. If None (the default) and option is not None, then it defaults to the class’ CONF_SECTION attribute.
option (spyder.config.types.ConfigurationKey | None, optional) – Name of the configuration option whose value is reflected and affected by the button. If None (the default), no option is associated with this button, e.g. for buttons that are triggered rather than toggled.
register_action (bool, optional) – If True (default) the action will be registered and searchable. If False, the action will be created but not registered.

Returns:

The toolbar button object that was created.

Return type:

QToolButton

get_toolbutton( name: str, context: str | None = None, plugin: str | None = None, ) → QToolButton[source]#

Retrieve a toolbar button by name, context and plugin.

Parameters:

name (str) – Identifier of the toolbutton to retrieve.
context (str | None, optional) – Context identifier under which the toolbutton 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 toolbutton was defined. If None, the default, then the PLUGIN_NAME attribute is used instead.

Returns:

The corresponding toolbutton widget stored under the given name, context and plugin.

Return type:

QToolButton

Raises:

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

get_toolbuttons( context: str | None = None, plugin: str | None = None, ) → dict[str, QToolButton][source]#

Return all toolbar buttons defined by a context on a given plugin.

Parameters:

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

Returns:

A dictionary that maps identifier name keys to their corresponding toolbutton objects.

Return type:

dict[str, QToolButton]

class spyder.api.widgets.mixins.SpyderToolbarMixin[source]#

Bases: object

Provide methods to create, add and get toolbars.

add_item_to_toolbar( action_or_widget: spyder.utils.qthelpers.SpyderAction | QWidget, toolbar: SpyderToolbar, section: str | None = None, before: str | None = None, before_section: str | None = None, ) → None[source]#

Add the given action or widget to this toolbar.

Parameters:

action_or_widget (spyder.utils.qthelpers.SpyderAction | QWidget) – The action or widget to add to the toolbar.
toolbar (SpyderToolbar) – The toolbar object to add action_or_widget to.
section (str | None, optional) – The section id in which to insert the action_or_widget, or None (default) for no section.
before (str | None, optional) – Make the action_or_widget appear before the action with the identifier before. If None (default), add it to the end. If before is not None, before_section will be ignored.
before_section (str | None, optional) – Make the section appear prior to before_section. If None (the default), add the section to the end. If you provide a before action, the new action will be placed before this one, so the section option will be ignored, since the action will now be placed in the same section as the before action.

Return type:

None

create_stretcher( id_: str | None = None, ) → QWidget[source]#

Create a stretcher widget to be used in a Spyder toolbar.

Parameters:: id (str | None, optional) – The identifier for the stretcher widget. If None (the default), no id will be set.
Returns:: The created stretcher widget.
Return type:: QWidget

create_toolbar( name: str, register: bool = True, ) → SpyderToolbar[source]#

Create a Spyder toolbar.

Parameters:

name (str) – Unique string identifier name of the toolbar to create.
register (bool, optional) – If True (default), register the toolbar in the global registry. If False, don’t register it.

Returns:

The created toolbar object.

Return type:

SpyderToolbar

get_toolbar( name: str, context: str | None = None, plugin: str | None = None, ) → SpyderToolbar[source]#

Return toolbar by name, context and plugin.

Parameters:

name (str) – Identifier of the toolbar to retrieve.
context (str | None, optional) – Context identifier under which the toolbar 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 toolbar was defined. If None, the default, then the PLUGIN_NAME attribute is used instead.

Returns:

The corresponding toolbar widget stored under the given name, context and plugin.

Return type:

SpyderToolbar

Raises:

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

get_toolbars( context: str | None = None, plugin: str | None = None, ) → dict[str, SpyderToolbar][source]#

Return all toolbars defined by a context on a given plugin.

Parameters:

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

Returns:

A dictionary that maps identifier name keys to their corresponding toolbar objects.

Return type:

dict[str, SpyderToolbar]

class spyder.api.widgets.mixins.SpyderMenuMixin[source]#

Bases: object

Provide methods to create, add and get menus.

This mixin uses a custom menu object that allows for the creation of sections in a simple way.

add_item_to_menu( action_or_menu: spyder.utils.qthelpers.SpyderAction | SpyderMenu, menu: SpyderMenu, section: str | None = None, before: str | None = None, before_section: str | None = None, ) → None[source]#

Add the given action or widget to the menu.

Parameters:

action_or_menu (spyder.utils.qthelpers.SpyderAction | SpyderMenu) – The action or submenu to add to the menu.
menu (SpyderMenu) – The menu object to add action_or_menu to.
section (str | None, optional) – The section id in which to insert the action_or_menu, or None (default) for no section.
before (str | None, optional) – Make the action_or_menu appear before the action with the identifier before. If None (default), add it to the end. If before is not None, before_section will be ignored.
before_section (str | None, optional) – Make the section appear prior to before_section. If None (the default), add the section to the end.

Return type:

None

Raises:

SpyderAPIError – If menu is not an instance of SpyderMenu.

create_menu( menu_id: str, title: str | None = None, icon: QIcon | None = None, reposition: bool = True, register: bool = True, ) → SpyderMenu[source]#

Create a menu for Spyder.

Parameters:

menu_id (str) – Unique string identifier name for the menu to create.
title (str | None, optional) – Localized title for the menu.
icon (QIcon | None, optional) – Icon object to use for the menu.
reposition (bool, optional) – If True (the default), vertically reposition the menu per its padding. If False, don’t reposition.
register (bool, optional) – If True (default), register the menu in the global registry. If False, don’t register it.

Returns:

The created menu object.

Return type:

SpyderMenu

get_menu( name: str, context: str | None = None, plugin: str | None = None, ) → SpyderMenu[source]#

Return a menu by name, context and plugin.

Parameters:

name (str) – Identifier of the menu to retrieve.
context (str | None, optional) – Context identifier under which the menu 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 menu was defined. If None, the default, then the PLUGIN_NAME attribute is used instead.

Returns:

The corresponding menu widget stored under the given name, context and plugin.

Return type:

SpyderMenu

Raises:

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

get_menus( context: str | None = None, plugin: str | None = None, ) → dict[str, SpyderMenu][source]#

Return all menus defined by a context on a given plugin.

Parameters:

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

Returns:

A dictionary that maps identifier name keys to their corresponding menu objects.

Return type:

dict[str, SpyderMenu]

class spyder.api.widgets.mixins.SpyderActionMixin[source]#

Bases: object

Provide methods to create, add and get actions in a unified way.

This mixin uses a custom action object.

create_action( name: str, text: str, icon: QIcon | str | None = None, icon_text: str = '', tip: str | None = None, toggled: Callable[[Any], None] | bool | None = None, triggered: Callable[[], None] | None = None, data: Any | None = None, shortcut: str | None = None, shortcut_context: str | None = None, context: ShortcutContext = 3, initial: bool | None = None, register_shortcut: bool = False, section: str | None = None, option: spyder.config.types.ConfigurationKey | None = None, parent: QWidget | None = None, register_action: bool = True, overwrite: bool = False, context_name: str | None = None, menurole: MenuRole | None = None, ) → spyder.utils.qthelpers.SpyderAction[source]#

Create a new Spyder-specialized QAction.

Note

There is no need to set a shortcut when creating an action, unless it’s a fixed (non-customizable) one. Otherwise, set the register_shortcut argument to True. If the shortcut is found in the shortcuts config section of your plugin, then it’ll be assigned; if not, it’ll be left blank for the user to define it in Spyder Preferences.

Parameters:

name (str) – Unique identifier for the action.
text (str) – Localized text for the action, displayed in the interface.
icon (QIcon | str | None, optional) – Icon name or object for the action when used in menus/toolbuttons. If None, the default, no icon is shown.
icon_text (str, optional) – Descriptive text for the action’s icon. If a non-empty string is passed, this will also disable the tooltip on this toolbutton if part of a toolbar. If the empty string ("") (the default), no icon text is set and the tooltip will not be disabled.
tip (str | None, optional) – Tooltip text for the action when used in menus or toolbars. If None (the default), no tooltip is shown.
toggled (Callable[[Any], None] | bool | None, optional) – If None (default) then the action doesn’t act like a checkbox. If True, then the action modifies the configuration option on the section specified (or the default CONF_SECTION if section is not set). Otherwise, must be a callable, called when toggling this action. One of toggled and triggered must not be None.
triggered (Callable[[], None] | None, optional) – If a callable, will be called when triggering this action. Otherwise, if None (the default), this will not be a triggered action and toggled must be non-None instead.
data (Any | None, optional) – Arbitrary user data to be set on the action. If None, the default, no custom data is set.
shortcut (str | None, optional) – A fixed (not configurable) keyboard shortcut to use for the action, in cases where it is not practical for the user to configure the shortcut. If None (the default), no fixed shortcut is set. For a normal configurable shortcut, you instead need to set register_shortcut to True and list the shortcut as one of the plugin’s configuration options. See spyder.api.shortcuts for more details.
shortcut_context (str | None, optional) – The context name of the fixed shortcut. None (the default) for no context or no shortcut. Use "_" for global shortcuts ( i.e. that can be used anywhere in the application).
context (ShortcutContext, optional) – Set the context object for the fixed shortcut. By default, Qt.WidgetWithChildrenShortcut.
initial (bool | None, optional) – Set the initial state of a togglable action. This does not emit the toggled signal. If None, the default, no initial state.
register_shortcut (bool, optional) – If True, the main window will expose the shortcut in the Spyder Preferences. If False, the default, the shortcut will not be registered.
section (str | None, optional) – Name of the configuration section whose option is going to be modified. If None (the default) and option is not None, then it defaults to the class’ CONF_SECTION attribute.
option (spyder.config.types.ConfigurationKey | None, optional) – Name of the configuration option whose value is reflected and affected by the action. If None (the default), no option is associated with this action, e.g. for actions that are triggered rather than toggled.
parent (QWidget | None, optional) – The parent of this widget. If None, the default, uses this instance object itself as the parent.
register_action (bool, optional) – If True (default) the action will be registered and searchable. If False, the action will be created but not registered.
overwrite (bool, optional) – If False (the default) and this action overwrites another with the same name and context_name, raise a warning. Set to True to disable this warning if intentionally overwriting another action.
context_name (str | None, optional) – Name of the context that holds the action when registered. The combination of name and context_name must be unique, and registering an action with the same name & context_name` will raise a warning by default unless overwrite is True.
menurole (MenuRole | None, optional) – Menu role for the action. Only has an effect on macOS.

Returns:

The Spyder action object that was created (a specialized QAction).

Return type:

spyder.utils.qthelpers.SpyderAction

Raises:

SpyderAPIError – If both triggered and toggled are None, as at least one must be provided; or if both initial is True and triggered is not None, as initial values can only apply to toggled actions.

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 widget 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.

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

Return all actions defined by a context on a given plugin.

Parameters:

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

Returns:

A dictionary that maps identifier name keys to their corresponding action objects.

Return type:

dict[str, spyder.utils.qthelpers.SpyderAction]

Notes

Actions should only be created once. Creating new actions on menu popup is highly discouraged.
Actions can be created directly on a PluginMainWidget or PluginMainContainer subclass. Child widgets can also create actions, but they need to subclass this class or SpyderWidgetMixin.
PluginMainWidget or PluginMainContainer will collect any actions defined in subwidgets (if defined) and expose them in the get_actions method at the plugin level.
There is no need to override this 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 this method is not implemented by the plugin, as is required.

class spyder.api.widgets.mixins.SpyderWidgetMixin( class_parent: QObject | None = None, parent: QWidget | None = None, )[source]#

Bases: SpyderActionMixin, SpyderMenuMixin, SpyderToolbarMixin, SpyderToolButtonMixin, SpyderShortcutsMixin

Basic functionality for all Spyder widgets and Qt items.

This provides a simple management of widget options, as well as Qt helpers for defining the actions a widget provides.

PLUGIN_NAME: str | None = None#

Plugin name in the action, toolbar, toolbutton & menu registries.

Usually the same as SpyderPluginV2.NAME, but may be different from CONTEXT_NAME.

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

__init__( class_parent: QObject | None = None, parent: QWidget | None = None, ) → None[source]#

Add methods and attributes for most Spyder widgets.

Parameters:

class_parent (QObject | None, optional) – The parent object of this object’s class, or None (default). Typically the plugin object.
parent (QWidget | None, optional) – The parent widget of this one, or None (default).

Return type:

None

static create_icon(name: str) → QIcon[source]#

Retrieve an icon from Spyder’s icon manager.

Parameters:: name (str) – The name of the icon to retrieve.
Returns:: The specified icon, as a QIcon instance.
Return type:: QIcon

update_style() → None[source]#

Modify the interface styling used by the plugin.

This must be reimplemented by plugins that need to adjust their style.

Changing from the dark to the light interface theme might require specific styles or stylesheets to be applied. When the theme is changed by the user through our Preferences, this method will be called for all plugins.

Return type:: None

update_translation() → None[source]#

Update localization of the widget.

This method will be called recursively on all widgets on language change.

Return type:: None

class spyder.api.widgets.mixins.SpyderMainWindowMixin[source]#

Bases: object

Mixin with additional functionality for Spyder’s QMainWindows.

move_to_primary_screen() → None[source]#

Move the window to the primary screen if necessary.

Return type:: None

class spyder.api.widgets.mixins.SvgToScaledPixmap[source]#

Bases: SpyderConfigurationAccessor

Mixin to transform an SVG to a QPixmap.

The resulting QPixmap is scaled according to the scale factor set by users in Spyder’s Preferences.

svg_to_scaled_pixmap( svg_file: str, rescale: float | None = None, in_package: bool = True, ) → QPixmap[source]#

Transform an SVG to a QPixmap.

The resulting QPixmap is scaled according to the scale factor set by users in Spyder’s Preferences.

Parameters:

svg_file (str) – Name of or path to the SVG file to convert.
rescale (float | None, optional) – Rescale pixmap according to a factor between 0 and 1. If None (default), will use the default scale factor.
in_package (bool, optional) – If True (the default), get the SVG from the images directory in the installed Spyder package. If False, retrieve it from the specified file on disk.

Returns:

The converted rasterized image.

Return type:

QPixmap

spyder.api.widgets.mixins

Contents

spyder.api.widgets.mixins#