diff --git a/src/libcalamares/utils/CalamaresUtils.h b/src/libcalamares/utils/CalamaresUtils.h index bc6eb92cb..66650ff57 100644 --- a/src/libcalamares/utils/CalamaresUtils.h +++ b/src/libcalamares/utils/CalamaresUtils.h @@ -33,15 +33,41 @@ class QDir; class QObject; +/** + * @brief The CalamaresUtils namespace contains utility functions. + */ namespace CalamaresUtils { DLLEXPORT QDir qmlModulesDir(); + + /** + * @brief appDataDir returns the directory with common application data. + * Defaults to CMAKE_INSTALL_FULL_DATADIR (usually /usr/share/calamares). + */ DLLEXPORT QDir appDataDir(); + + /** + * @brief appLogDir returns the directory for Calamares logs. + * Defaults to QStandardPaths::CacheLocation (usually ~/.cache/Calamares). + */ DLLEXPORT QDir appLogDir(); + + /** + * @brief systemLibDir returns the system's lib directory. + * Defaults to CMAKE_INSTALL_FULL_LIBDIR (usually /usr/lib64 or /usr/lib). + */ DLLEXPORT QDir systemLibDir(); + + /** + * @brief installTranslator changes the application language. + * @param locale the new locale. + * @param brandingTranslationsPrefix the branding path prefix, from Calamares::Branding. + * @param parent the parent QObject. + */ DLLEXPORT void installTranslator( const QLocale& locale, const QString& brandingTranslationsPrefix, QObject* parent ); + DLLEXPORT QString translatorLocaleName(); /** @@ -52,10 +78,24 @@ namespace CalamaresUtils DLLEXPORT void setQmlModulesDir( const QDir& dir ); + /** + * @brief removeDiacritics replaces letters with diacritics and ligatures with + * alternative forms and digraphs. + * @param string the string to transform. + * @return the output string with plain characters. + */ DLLEXPORT QString removeDiacritics( const QString& string ); + /** + * @brief obscure is a bidirectional obfuscation function, from KStringHandler. + * @param string the input string. + * @return the obfuscated string. + */ DLLEXPORT QString obscure( const QString& string ); + /** + * @brief crash makes Calamares crash immediately. + */ DLLEXPORT void crash(); } diff --git a/src/libcalamares/utils/CalamaresUtilsSystem.h b/src/libcalamares/utils/CalamaresUtilsSystem.h index c5e99744b..bf3acb41c 100644 --- a/src/libcalamares/utils/CalamaresUtilsSystem.h +++ b/src/libcalamares/utils/CalamaresUtilsSystem.h @@ -26,10 +26,20 @@ namespace CalamaresUtils { +/** + * @brief The System class is a singleton with utility functions that perform + * system-specific operations. + */ class DLLEXPORT System : public QObject { Q_OBJECT public: + /** + * @brief System the constructor. Only call this once in a Calamares instance. + * @param doChroot set to true if all external commands should run in the + * target system chroot, otherwise false to run everything on the current system. + * @param parent the QObject parent. + */ explicit System( bool doChroot, QObject* parent = nullptr ); virtual ~System(); @@ -37,6 +47,10 @@ public: /** * Runs the mount utility with the specified parameters. + * @param devicePath the path of the partition to mount. + * @param mountPoint the full path of the target mount point. + * @param filesystemName the name of the filesystem (optional). + * @param options any additional options as passed to mount -o (optional). * @returns the program's exit code, or: * -1 = QProcess crash * -2 = QProcess cannot start @@ -49,6 +63,13 @@ public: /** * Runs the specified command in the chroot of the target system. + * @param args the call with arguments, as a string list. + * @param workingPath the current working directory for the QProcess + * call (optional). + * @param stdInput the input string to send to the running process as + * standard input (optional). + * @param timeoutSec the timeout after which the process will be + * killed (optional, default is 0 i.e. no timeout). * @returns the program's exit code, or: * -1 = QProcess crash * -2 = QProcess cannot start @@ -77,9 +98,11 @@ public: const QString& stdInput = QString(), int timeoutSec = 0 ); - DLLEXPORT qint64 getPhysicalMemoryB(); //Better guess, doesn't work in VirualBox - + /** + * @brief getTotalMemoryB returns the total main memory, in bytes. + */ DLLEXPORT qint64 getTotalMemoryB(); //Always underguessed, but always works on Linux + DLLEXPORT qint64 getPhysicalMemoryB(); //Better guess, doesn't work in VirualBox private: static System* s_instance; diff --git a/src/libcalamaresui/utils/CalamaresUtilsGui.h b/src/libcalamaresui/utils/CalamaresUtilsGui.h index 224a3c2b2..d838024f2 100644 --- a/src/libcalamaresui/utils/CalamaresUtilsGui.h +++ b/src/libcalamaresui/utils/CalamaresUtilsGui.h @@ -29,6 +29,14 @@ class QLayout; namespace CalamaresUtils { + +/** + * @brief The ImageType enum lists all common Calamares icons. + * Icons are loaded from SVGs and cached. Each icon has an enum value, through which + * it can be accessed. + * You can forward-declare this as: + * enum ImageType : int; + */ enum ImageType : int { Yes, @@ -49,6 +57,10 @@ enum ImageType : int Squid }; +/** + * @brief The ImageMode enum contains different transformations that can be applied. + * Most of these are currently unused. + */ enum ImageMode { Original, @@ -58,15 +70,46 @@ enum ImageMode RoundedCorners }; -UIDLLEXPORT QPixmap defaultPixmap( ImageType type, ImageMode mode = CalamaresUtils::Original, const QSize& size = QSize( 0, 0 ) ); -UIDLLEXPORT QPixmap createRoundedImage( const QPixmap& avatar, const QSize& size, float frameWidthPct = 0.20 ); +/** + * @brief defaultPixmap returns a resized and/or transformed pixmap for a given + * ImageType. + * @param type the ImageType i.e. the enum value for an SVG. + * @param mode the transformation to apply (default: no transformation). + * @param size the target pixmap size (default: original SVG size). + * @return the new pixmap. + */ +UIDLLEXPORT QPixmap defaultPixmap( ImageType type, + ImageMode mode = CalamaresUtils::Original, + const QSize& size = QSize( 0, 0 ) ); +/** + * @brief createRoundedImage returns a rounded version of a pixmap. + * @param avatar the input pixmap. + * @param size the new size. + * @param frameWidthPct the frame size, as percentage of width. + * @return the transformed pixmap. + * This one is currently unused. + */ +UIDLLEXPORT QPixmap createRoundedImage( const QPixmap& avatar, + const QSize& size, + float frameWidthPct = 0.20 ); + +/** + * @brief unmarginLayout recursively walks the QLayout tree and removes all margins. + * @param layout the layout to unmargin. + */ UIDLLEXPORT void unmarginLayout( QLayout* layout ); + +/** + * @brief clearLayout recursively walks the QLayout tree and deletes all the child + * widgets and layouts. + * @param layout the layout to clear. + */ UIDLLEXPORT void clearLayout( QLayout* layout ); UIDLLEXPORT void setDefaultFontSize( int points ); -UIDLLEXPORT int defaultFontSize(); -UIDLLEXPORT int defaultFontHeight(); +UIDLLEXPORT int defaultFontSize(); // in points +UIDLLEXPORT int defaultFontHeight(); // in pixels, DPI-specific UIDLLEXPORT QFont defaultFont(); UIDLLEXPORT QSize defaultIconSize(); diff --git a/src/libcalamaresui/viewpages/PythonQtUtilsWrapper.h b/src/libcalamaresui/viewpages/PythonQtUtilsWrapper.h index 4e3833833..d1d9bed7b 100644 --- a/src/libcalamaresui/viewpages/PythonQtUtilsWrapper.h +++ b/src/libcalamaresui/viewpages/PythonQtUtilsWrapper.h @@ -24,6 +24,10 @@ #include +/** + * @brief The Utils class wraps around functions from CalamaresUtils to make them + * available in the PythonQt interface. + */ class Utils : public QObject { Q_OBJECT diff --git a/src/modules/partition/core/ColorUtils.h b/src/modules/partition/core/ColorUtils.h index e5a77dea7..50f4fd785 100644 --- a/src/modules/partition/core/ColorUtils.h +++ b/src/modules/partition/core/ColorUtils.h @@ -34,6 +34,12 @@ QColor freeSpaceColor(); QColor unknownDisklabelColor(); +/** + * @brief colorForPartition iterates over partitions, caches their colors and returns + * a color for the given partition. + * @param partition the partition for which to return a color. + * @return a color for the partition. + */ QColor colorForPartition( Partition* partition ); /** @@ -42,6 +48,9 @@ QColor colorForPartition( Partition* partition ); */ QColor colorForPartitionInFreeSpace( Partition* freeSpacePartition ); +/** + * @brief invalidateCache clears the partition colors cache. + */ void invalidateCache(); } diff --git a/src/modules/partition/core/PartUtils.h b/src/modules/partition/core/PartUtils.h index 2cd63c241..21d995965 100644 --- a/src/modules/partition/core/PartUtils.h +++ b/src/modules/partition/core/PartUtils.h @@ -29,12 +29,37 @@ class Partition; namespace PartUtils { +/** + * @brief canBeReplaced checks whether the given Partition satisfies the criteria + * for replacing it with the new OS. + * @param candidate the candidate partition to replace. + * @return true if the criteria are met, otherwise false. + */ bool canBeReplaced( Partition* candidate ); +/** + * @brief canBeReplaced checks whether the given Partition satisfies the criteria + * for resizing (shrinking) it to make room for a new OS. + * @param candidate the candidate partition to resize. + * @return true if the criteria are met, otherwise false. + */ bool canBeResized( Partition* candidate ); +/** + * @brief canBeReplaced checks whether the given Partition satisfies the criteria + * for resizing (shrinking) it to make room for a new OS. + * @param core the PartitionCoreModule instance. + * @param partitionPath the device path of the candidate partition to resize. + * @return true if the criteria are met, otherwise false. + */ bool canBeResized( PartitionCoreModule* core, const QString& partitionPath ); +/** + * @brief runOsprober executes os-prober, parses the output and writes relevant + * data to GlobalStorage. + * @param core the PartitionCoreModule instance. + * @return a list of os-prober entries, parsed. + */ OsproberEntryList runOsprober( PartitionCoreModule* core ); }