Various editor helper functions for working with librepcb::Image. More...

#include <imagehelpers.h>

Collaboration diagram for ImageHelpers:

Public Types
enum class	Target

Public Member Functions
	ImageHelpers ()=delete

	ImageHelpers (const ImageHelpers &other)=delete

	~ImageHelpers ()=delete

ImageHelpers &	operator= (const ImageHelpers &rhs)=delete

Static Public Member Functions
static std::optional< FileProofName >	findExistingFile (const TransactionalDirectory &dir, const QByteArray &data)
	Find a file with specific content in a directory.

static FileProofName	getUnusedFileName (const TransactionalDirectory &dir, QString nameUserInput, const QString &extension)
	Build a valid filename for an image file to be created.

static bool	execImageChooserDialog (QByteArray &data, QString &format, QString &basename, const QString &settingsKey)
	Execute "open file" dialog to choose an image.

static std::optional< FileProofName >	findExistingOrAskForNewImageFileName (const TransactionalDirectory &dir, Target target, const QByteArray &data, const QString &format, const QString &basename, bool &exists)
	Determine the filename of an image to be added to a directory.

static bool	isImageInClipboard () noexcept
	Check if the clipboard contains any kind of image.

static bool	getImageFromClipboard (QByteArray &data, QString &format, QString &basename) noexcept
	Try to get the image from the clipboard.

Detailed Description

Various editor helper functions for working with librepcb::Image.

Intended to share code between various editors resp. their state machines.

Member Enumeration Documentation

◆ Target

enum class Target

strong

Enumerator
Symbol
Project

Constructor & Destructor Documentation

◆ ImageHelpers() [1/2]

ImageHelpers ( )

delete

◆ ImageHelpers() [2/2]

ImageHelpers ( const ImageHelpers & other )

delete

◆ ~ImageHelpers()

~ImageHelpers ( )

delete

Member Function Documentation

◆ operator=()

ImageHelpers & operator= ( const ImageHelpers & rhs )

delete

◆ findExistingFile()

std::optional< FileProofName > findExistingFile	(	const TransactionalDirectory &	dir,
		const QByteArray &	data
	)

static

Find a file with specific content in a directory.

Intended to reuse image files already existing in a directory.

Parameters

dir	The directory to search for files.
data	The content of the file to search for.

Returns: The filename if a file was found, std::nullopt otherwise.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getUnusedFileName()

FileProofName getUnusedFileName	(	const TransactionalDirectory &	dir,
		QString	nameUserInput,
		const QString &	extension
	)

static

Build a valid filename for an image file to be created.

This method builds a filename that is a valid librepcb::FileProofName for a file which doesn't exist yet in a given directory by guarantee. If there are filename conflicts, a number will be appended to make it unique. Intended to be used to determine a valid filename before adding a new file to a directory.

Parameters

dir	The directory where a new file shall be created.
nameUserInput	The desired file basename (untrusted input accepted). If empty or completely invalid, a fallback name will be used instead.
extension	The image file extension. Must be one of librepcb::Image::getSupportedExtensions() (case sensitive), otherwise an exception is thrown!

Returns: A guaranteed valid filename of a non-existent file.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ execImageChooserDialog()

bool execImageChooserDialog	(	QByteArray &	data,
		QString &	format,
		QString &	basename,
		const QString &	settingsKey
	)

static

Execute "open file" dialog to choose an image.

Note: If neccessary, this method does convert the selected image file to a supported image format. However, if the file extension is one of the supported formats, this method does not open or validate the file. Always call librepcb::Image::tryLoad() afterwards to do so.

Parameters

data	Content of the chosen image (may have been converted into a supported image format).
format	Image format of `data` (e.g. "png").
basename	Basename of the chosen file (untrusted user input).
settingsKey	The dialog saves the chosen file under this QSettings key and preselects the file when opening the next time. Set to something like "schematic_editor/add_image/file".

Return values

true	An image has been chosen (and converted if neccessary).
false	The user canceled the file dialog.

Exceptions

Exception If a format conversion was needed and it failed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ findExistingOrAskForNewImageFileName()

std::optional< FileProofName > findExistingOrAskForNewImageFileName	(	const TransactionalDirectory &	dir,
		Target	target,
		const QByteArray &	data,
		const QString &	format,
		const QString &	basename,
		bool &	exists
	)

static

Determine the filename of an image to be added to a directory.

This may show a blocking input dialog where the user can enter a file name.

Parameters

dir	Directory where the file is asked to be added (this method does not actually add it).
target	The target type that the directory represents. Only used for a UI translation string.
data	The image data asked to be added.
format	The image format of `data`.
basename	The desired basename of the image (untrusted user input).
exists	Output variable whether the file already existed in `dir` or not.

Returns: The filename of the new file to be created, or std::nullopt if the user aborted the input dialog.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isImageInClipboard()

bool isImageInClipboard ( )

staticnoexcept

Check if the clipboard contains any kind of image.

If the clipboard contains a filepath to an image file (rather than the image itself), it is also taken into account (i.e. true returned) since getImageFromClipboard() is able to load it.

Call this method for a lightweight check if theres is any data getImageFromClipboard() is able to load.

Return values

true	The clipboard contains an image.
false	There's no image in the clipboard.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getImageFromClipboard()

bool getImageFromClipboard	(	QByteArray &	data,
		QString &	format,
		QString &	basename
	)

staticnoexcept

Try to get the image from the clipboard.

If the clipboard contains a filepath to an image file (rather than the image itself), this method tries to load the image from that file.

Note: If neccessary, this method does convert the image to a supported image format. However, if the clipboard already contains one of the supported formats, this method does not validate the file. Always call librepcb::Image::tryLoad() afterwards to do so.

Parameters

data	Content of the image (may have been converted into a supported image format).
format	Image format of `data` (e.g. "png").
basename	Basename of the image (untrusted user input).

Return values

true	Successfully fetched the image.
false	No image in the clipboard, or failed to fetch it.

Here is the call graph for this function:

Here is the caller graph for this function:

The documentation for this class was generated from the following files:

/__w/1/s/libs/librepcb/editor/utils/imagehelpers.h
/__w/1/s/libs/librepcb/editor/utils/imagehelpers.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Target

Constructor & Destructor Documentation

◆ ImageHelpers() [1/2]

◆ ImageHelpers() [2/2]

◆ ~ImageHelpers()

Member Function Documentation

◆ operator=()

◆ findExistingFile()

◆ getUnusedFileName()

◆ execImageChooserDialog()

◆ findExistingOrAskForNewImageFileName()

◆ isImageInClipboard()

◆ getImageFromClipboard()