spacr.qt.widgets.picture_export¶

Right-click a picture and save it, as a PNG or as a PDF.

A picture on screen is often the thing somebody wants in a slide an hour later, and the route to it was a screenshot of a window, at the window’s resolution, with the surrounding chrome in it. This saves THE PICTURE, at the resolution it was rendered at rather than the size it happens to be shown at, into a file of the user’s choosing.

TWO FORMATS, AND THE PDF IS NOT A PNG WITH A DIFFERENT EXTENSION. A raster dropped into a PDF satisfies the file name and nothing else; a figure panel is a page, and a page has a size in millimetres. save_picture() gives the PDF a page the image’s own shape and tells the writer the resolution Preferences carries, so the picture lands at the size it was measured at and prints at that resolution.

The resolution and the default format are the ones the Figures preferences already own – spacr.qt.preferences.get_figure_png_dpi() and spacr.qt.preferences.get_figure_format() – so a user who has already said “300 DPI, PDF” is not asked a second time in different words.

Functions¶

`as_image`(→ Optional[PySide6.QtGui.QImage])	Whatever was handed over, as a `QImage`, or `None`.
`ask_where_to_save`(→ str)	Ask for a path. `""` when the user walked away.
`build_menu`(parent, enabled)	The right-click menu: save as PNG, save as PDF.
`choose_format`(→ str)	Pop the menu at `point` and return the chosen suffix, or `""`.
`install_picture_save`(→ bool)	Give `view` a right-click menu that saves what it is showing.
`picture_dpi`(→ int)	The resolution a saved picture is written at.
`preferred_suffix`(→ str)	`".pdf"` or `".png"`, following the Figures format preference.
`save_as`(→ str)	Ask for a path and write `picture` there. `""` if nothing was.
`save_picture`(→ bool)	Write `picture` to `path`, as a PNG or a PDF by its suffix.
`suggested_name`(→ str)	A file name for `stem`, with the preferred suffix on it.

Module Contents¶

spacr.qt.widgets.picture_export.as_image(picture) → PySide6.QtGui.QImage | None[source]¶

Whatever was handed over, as a QImage, or None.

A caller may hold a QPixmap (what a view shows), a QImage (what a renderer produced) or nothing at all yet.

Parameters:: picture – a QPixmap, a QImage or None; a null image or any other type also gives None.

spacr.qt.widgets.picture_export.ask_where_to_save(parent, stem: str) → str[source]¶

Ask for a path. "" when the user walked away.

THE SUFFIX IS PUT BACK IF THE USER DROPS IT. A name typed without one would otherwise be written as a PNG whatever filter was selected, which is how “save as PDF” quietly produces a raster.

Parameters:

parent – the widget the save dialog is parented to.
stem – the file name offered, without a suffix; cleaned by suggested_name().

spacr.qt.widgets.picture_export.build_menu(parent, enabled: bool)[source]¶

The right-click menu: save as PNG, save as PDF.

Each action carries its suffix as its data, so the caller reads the choice off the action rather than comparing it against two references it had to keep.

Parameters:

parent – the widget that owns the menu.
enabled – False when there is no picture yet. The actions are SHOWN AND GREYED rather than left out, and a line underneath says why: a menu that is empty on one field and full on the next reads as a bug, not as a state.

spacr.qt.widgets.picture_export.choose_format(view, point, enabled: bool) → str[source]¶

Pop the menu at point and return the chosen suffix, or "".

THE MODAL CALL IS ALONE IN HERE so everything around it can be driven by a test. QMenu.exec spins an event loop of its own, and a test that reached it would hang rather than fail; substituting this one function is how the rest of the gesture is checked at all.

Parameters:

view – the widget the menu belongs to; point is mapped to global coordinates through it.
point – where the right-click happened, in view coordinates.
enabled – False greys out the save actions, as in build_menu().

spacr.qt.widgets.picture_export.install_picture_save(view, picture: Callable[[], object], stem: str = 'picture', unless: Callable[[], bool] | None = None) → bool[source]¶

Give view a right-click menu that saves what it is showing.

Parameters:

view – the widget the user right-clicks.
picture – called when the menu is used; returns the QPixmap or QImage to write. Called AT SAVE TIME rather than now, so the menu always writes the picture currently on screen.
stem – the file name offered, without a suffix. A callable is asked at save time, so a view whose contents change – Overlay one moment, Flows the next – offers the name of what is on it now.
unless – asked first; True means the right button belongs to something else at this moment and no menu is shown. The live preview’s ruler is cleared with a right-click while it is active, and a menu appearing over that would take a tool away to add a file dialog nobody asked for.

Returns:

whether the menu was installed.

spacr.qt.widgets.picture_export.picture_dpi() → int[source]¶

The resolution a saved picture is written at.

Returns:: the Figures preference, or FALLBACK_DPI.

spacr.qt.widgets.picture_export.preferred_suffix() → str[source]¶: ".pdf" or ".png", following the Figures format preference.

spacr.qt.widgets.picture_export.save_as(view, picture, stem: str, want: str) → str[source]¶

Ask for a path and write picture there. "" if nothing was.

Parameters:

view – the widget the save dialog and any warning are parented to.
picture – the QPixmap or QImage to write.
stem – the file name offered, without a suffix.
want – the suffix the user picked in the menu. It WINS over what the file dialog came back with, so “save as PDF” followed by a name ending in .png still writes a PDF rather than quietly changing format because of a typed extension.

Returns:

the path written, or "".

spacr.qt.widgets.picture_export.save_picture(picture, path, dpi: int | None = None) → bool[source]¶

Write picture to path, as a PNG or a PDF by its suffix.

Parameters:

picture – a QPixmap or QImage.
path – where to write. .pdf writes a page; anything else writes a PNG.
dpi – resolution; picture_dpi() when omitted.

Returns:

whether a file was written.

spacr.qt.widgets.picture_export.suggested_name(stem: str) → str[source]¶

A file name for stem, with the preferred suffix on it.

Parameters:: stem – the base name; whitespace runs become underscores, and an empty result (or None) becomes picture.

Nested helpers¶

install_picture_save._menu(point) → str¶

Offer the save menu at point; the path written, or "".

Parameters:: point – where the right-click landed, in view coordinates.

spacr/qt/widgets/picture_export.py:338