updated settings doc, try prebuilt image

7 years ago · 4729b29cb0
5 changed files with 146 additions and 56 deletions
--- a/.travis.yml
+++ b/.travis.yml
@ -20,6 +20,7 @@ matrix:
        - PLATFORM=gcc_64
        - BUILD_DOC=true
        - BUILD_EXAMPLES=true
+        - DOCKER_IMAGE=datasync
    - os: linux
      env:
        - PLATFORM=android_armv7
--- a/doc/settingssetup.dox
+++ b/doc/settingssetup.dox
@ -0,0 +1,49 @@
+/*!
+@class QtMvvm::ISettingsSetupLoader
+
+It is used by the SettingsViewModel to load a SettingsElements::Setup from a generic file. The
+default implementation that is used by default implements a loader for an XML format. You can
+implement your own format, but unless you need to open things other then normal files/resources
+(or hate XML), there is no advantage of doing so.
+
+@sa #QtMvvm_ISettingsSetupLoaderIid, SettingsViewModel, SettingsLoaderException,
+SettingsElements::Setup, TODO link to xml doc
+*/
+
+/*!
+@fn QtMvvm::ISettingsSetupLoader::changeDefaultIcon
+
+@param defaultIcon The URL to the icon to use as overwrite
+
+The default icon used by the XML loader is `qrc:/de/skycoder42/qtmvvm/icons/settings.svg`. If
+you want to overwrite that path (for example because you want to use a png instead of a svg
+icon) you can do so via this function
+
+@sa SettingsDialog::iconOverwrite
+*/
+
+/*!
+@fn QtMvvm::ISettingsSetupLoader::loadSetup
+
+@param filePath The path to the file to be loaded
+@param frontend The name of the GUI frontend beeing used
+@param selector The currently active file selectors
+@returns The loaded and filtered settings setup
+@throws SettingsLoaderException In case the loaded file is invalid
+
+The frontend is used to filter elements by their `frontends` variable. It is always the name of
+the view type that is loading the settings via the viewmodel. Current values are:
+
+- `widgets` for the Widgets GUI
+- `quick` for the Quick Controls 2 GUI
+
+The selector should be used to a.) select the files to open (event the one passed). Use the
+select method to apply the paths. This applies for the elements as well, via the `selectors`
+variable.
+
+@note The syntax etc of these two variables depends on your loader and they are only used by you,
+not by anyone using this method. The default syntax used by the XML load implementation can be
+found in the TODO xml doc
+
+@sa SettingsElements::Setup, QFileSelector, TODO xml doc
+*/
--- a/src/mvvmcore/settingssetup.h
+++ b/src/mvvmcore/settingssetup.h
@ -15,73 +15,111 @@ namespace QtMvvm {
 //! A sub namespace for the different elements in a settings setup
 namespace SettingsElements {

+//! An entry in the settings to display and edit a value
 struct Entry
 {
+	//! The QSettings key this entry should handle
 	QString key;
+	//! The input view type (typically the actual data type) to show
 	QByteArray type;
+	//! A short title/label of the entry to give it a name
 	QString title;
+	//! A tooltip with more detailed information about the entry
 	QString tooltip;
+	//! A default value to display in case no value is in the settings yet
 	QVariant defaultValue;
+	//! A list of keys to find this entry by when searching
 	QStringList searchKeys;
+	//! Additional properties to be passed on to the edit view
 	QVariantMap properties;

+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };

+//! A logical group of settings entries
 struct Group
 {
+	//! The groups title
 	QString title;
+	//! A tooltip to describe what the group is about
 	QString tooltip;

+	//! A list of entries the group contains
 	QList<Entry> entries;

+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };

+//! A bigger section for different entries and groups
 struct Section
 {
+	//! The sections title
 	QString title;
+	//! An icon for the section
 	QUrl icon;
+	//! A tooltip to describe what the section is about
 	QString tooltip;

+	//! A list of groups the section contains
 	QList<Group> groups;

+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };

+//! A top level category to organize sections in
 struct Category
 {
+	//! The categories title
 	QString title;
+	//! An icon for the category
 	QUrl icon;
+	//! A tooltip to describe what the category is about
 	QString tooltip;

+	//! A list of sections the category contains
 	QList<Section> sections;

+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };

+//! The whole settings setup
 struct Setup
 {
+	//! Specifies if the user is allowed to search in the settings
 	bool allowSearch = true;
+	//! Specifies if the user is allowed to restore the factory defaults
 	bool allowRestore = true;

+	//! A list of categories the setup is build of
 	QList<Category> categories;
 };

 }

+//! An exception throw in case loading a settings setup went wrong
 class SettingsLoaderException : public QException {};

+//! An interface for a generic settings setup loader
 class ISettingsSetupLoader
 {
 public:
 	virtual inline ~ISettingsSetupLoader() = default;

+	//! Can be used to overwrite the default icon for categories
 	virtual void changeDefaultIcon(const QUrl &defaultIcon) = 0;
+	//! Loads the settings setup from the given file
 	virtual SettingsElements::Setup loadSetup(const QString &filePath, const QString &frontend, const QFileSelector *selector) const = 0;
 };

@ -93,8 +131,10 @@ Q_DECLARE_METATYPE(QtMvvm::SettingsElements::Section)
 Q_DECLARE_METATYPE(QtMvvm::SettingsElements::Category)
 Q_DECLARE_METATYPE(QtMvvm::SettingsElements::Setup)

+//! The Iid of the QtMvvm::ISettingsSetupLoader class
 #define QtMvvm_ISettingsSetupLoaderIid "de.skycoder42.qtmvvm.settings.core.ISettingsSetupLoader"
 Q_DECLARE_INTERFACE(QtMvvm::ISettingsSetupLoader, QtMvvm_ISettingsSetupLoaderIid)
 Q_DECLARE_METATYPE(QtMvvm::ISettingsSetupLoader*)

+//! @file settingssetup.h The settings setup header
 #endif // QTMVVM_SETTINGSSETUP_H
--- a/src/mvvmcore/settingssetuploader.cpp
+++ b/src/mvvmcore/settingssetuploader.cpp
@ -34,7 +34,7 @@ Setup SettingsSetupLoader::loadSetup(const QString &filePath, const QString &fro
 {
 	Setup setup;
 	if(!_cache.contains(filePath)) {
-		QFile file(QDir::cleanPath(filePath));
+		QFile file(QDir::cleanPath(selector->select(filePath)));
 		if(!file.open(QIODevice::ReadOnly | QIODevice::Text))
 			throw SettingsXmlException(file);

@ -55,13 +55,13 @@ Setup SettingsSetupLoader::loadSetup(const QString &filePath, const QString &fro
 				do {
 					if(reader.name() == QStringLiteral("Include")) {
 						Category category;
-						if(readCategoryInclude(reader, category))
+						if(readCategoryInclude(reader, category, selector))
 							setup.categories.append(category);
 					} else
-						setup.categories.append(readCategory(reader));
+						setup.categories.append(readCategory(reader, selector));
 				} while(reader.readNextStartElement());
 			} else
-				setup.categories.append(readDefaultCategory(reader));
+				setup.categories.append(readDefaultCategory(reader, selector));
 		}
 		testXmlValid(reader);
 		file.close();
@ -89,7 +89,7 @@ bool SettingsSetupLoader::event(QEvent *event)
 	return QObject::event(event);
 }

-Category SettingsSetupLoader::readCategory(QXmlStreamReader &reader) const
+Category SettingsSetupLoader::readCategory(QXmlStreamReader &reader, const QFileSelector *selector) const
 {
 	testXmlValid(reader);
 	if(reader.name() != QStringLiteral("Category"))
@ -107,38 +107,38 @@ Category SettingsSetupLoader::readCategory(QXmlStreamReader &reader) const
 	category.selectors = reader.stringValue("selectors");

 	if(reader.readNextStartElement())
-		readCategoryChildren(reader, category);
+		readCategoryChildren(reader, category, selector);
 	testXmlValid(reader);

 	return category;
 }

-Category SettingsSetupLoader::readDefaultCategory(QXmlStreamReader &reader) const
+Category SettingsSetupLoader::readDefaultCategory(QXmlStreamReader &reader, const QFileSelector *selector) const
 {
 	testXmlValid(reader);
 	auto category = createDefaultCategory();
-	readCategoryChildren(reader, category);
+	readCategoryChildren(reader, category, selector);
 	testXmlValid(reader);
 	return category;
 }

-void SettingsSetupLoader::readCategoryChildren(QXmlStreamReader &reader, Category &category) const
+void SettingsSetupLoader::readCategoryChildren(QXmlStreamReader &reader, Category &category, const QFileSelector *selector) const
 {
 	if(reader.name() == QStringLiteral("Section") ||
 	   reader.name() == QStringLiteral("Include")) {
 		do {
 			if(reader.name() == QStringLiteral("Include")) {
 				Section section;
-				if(readSectionInclude(reader, section))
+				if(readSectionInclude(reader, section, selector))
 					category.sections.append(section);
 			} else
-				category.sections.append(readSection(reader));
+				category.sections.append(readSection(reader, selector));
 		} while(reader.readNextStartElement());
 	} else
-		category.sections.append(readDefaultSection(reader));
+		category.sections.append(readDefaultSection(reader, selector));
 }

-Section SettingsSetupLoader::readSection(QXmlStreamReader &reader) const
+Section SettingsSetupLoader::readSection(QXmlStreamReader &reader, const QFileSelector *selector) const
 {
 	testXmlValid(reader);
 	if(reader.name() != QStringLiteral("Section"))
@ -156,38 +156,38 @@ Section SettingsSetupLoader::readSection(QXmlStreamReader &reader) const
 	section.selectors = reader.stringValue("selectors");

 	if(reader.readNextStartElement())
-		readSectionChildren(reader, section);
+		readSectionChildren(reader, section, selector);
 	testXmlValid(reader);

 	return section;
 }

-Section SettingsSetupLoader::readDefaultSection(QXmlStreamReader &reader) const
+Section SettingsSetupLoader::readDefaultSection(QXmlStreamReader &reader, const QFileSelector *selector) const
 {
 	testXmlValid(reader);
 	auto section = createDefaultSection();
-	readSectionChildren(reader, section);
+	readSectionChildren(reader, section, selector);
 	testXmlValid(reader);
 	return section;
 }

-void SettingsSetupLoader::readSectionChildren(QXmlStreamReader &reader, Section &section) const
+void SettingsSetupLoader::readSectionChildren(QXmlStreamReader &reader, Section &section, const QFileSelector *selector) const
 {
 	if(reader.name() == QStringLiteral("Group") ||
 	   reader.name() == QStringLiteral("Include")) {
 		do {
 			if(reader.name() == QStringLiteral("Include")) {
 				Group group;
-				if(readGroupInclude(reader, group))
+				if(readGroupInclude(reader, group, selector))
 					section.groups.append(group);
 			} else
-				section.groups.append(readGroup(reader));
+				section.groups.append(readGroup(reader, selector));
 		} while(reader.readNextStartElement());
 	} else
-		section.groups.append(readDefaultGroup(reader));
+		section.groups.append(readDefaultGroup(reader, selector));
 }

-Group SettingsSetupLoader::readGroup(QXmlStreamReader &reader) const
+Group SettingsSetupLoader::readGroup(QXmlStreamReader &reader, const QFileSelector *selector) const
 {
 	testXmlValid(reader);
 	if(reader.name() != QStringLiteral("Group"))
@ -202,29 +202,29 @@ Group SettingsSetupLoader::readGroup(QXmlStreamReader &reader) const
 	group.selectors = reader.stringValue("selectors");

 	if(reader.readNextStartElement())
-		readGroupChildren(reader, group);
+		readGroupChildren(reader, group, selector);
 	testXmlValid(reader);

 	return group;
 }

-Group SettingsSetupLoader::readDefaultGroup(QXmlStreamReader &reader) const
+Group SettingsSetupLoader::readDefaultGroup(QXmlStreamReader &reader, const QFileSelector *selector) const
 {
 	testXmlValid(reader);
 	Group group;
-	readGroupChildren(reader, group);
+	readGroupChildren(reader, group, selector);
 	testXmlValid(reader);
 	return group;
 }

-void SettingsSetupLoader::readGroupChildren(QXmlStreamReader &reader, Group &group) const
+void SettingsSetupLoader::readGroupChildren(QXmlStreamReader &reader, Group &group, const QFileSelector *selector) const
 {
 	if(reader.name() == QStringLiteral("Entry") ||
 	   reader.name() == QStringLiteral("Include")) {
 		do {
 			if(reader.name() == QStringLiteral("Include")) {
 				Entry entry;
-				if(readEntryInclude(reader, entry))
+				if(readEntryInclude(reader, entry, selector))
 					group.entries.append(entry);
 			} else
 				group.entries.append(readEntry(reader));
@ -342,35 +342,35 @@ QVariant SettingsSetupLoader::readElement(QXmlStreamReader &reader) const
 	return mVariant;
 }

-bool SettingsSetupLoader::readCategoryInclude(QXmlStreamReader &reader, Category &category) const
+bool SettingsSetupLoader::readCategoryInclude(QXmlStreamReader &reader, Category &category, const QFileSelector *selector) const
 {
-	return readInclude(reader, [this, &category](QXmlStreamReader &reader){
-		category = readCategory(reader);
-	}, QStringLiteral("Category"));
+	return readInclude(reader, [this, &category, selector](QXmlStreamReader &reader){
+		category = readCategory(reader, selector);
+	}, QStringLiteral("Category"), selector);
 }

-bool SettingsSetupLoader::readSectionInclude(QXmlStreamReader &reader, Section &section) const
+bool SettingsSetupLoader::readSectionInclude(QXmlStreamReader &reader, Section &section, const QFileSelector *selector) const
 {
-	return readInclude(reader, [this, &section](QXmlStreamReader &reader){
-		section = readSection(reader);
-	}, QStringLiteral("Section"));
+	return readInclude(reader, [this, &section, selector](QXmlStreamReader &reader){
+		section = readSection(reader, selector);
+	}, QStringLiteral("Section"), selector);
 }

-bool SettingsSetupLoader::readGroupInclude(QXmlStreamReader &reader, Group &group) const
+bool SettingsSetupLoader::readGroupInclude(QXmlStreamReader &reader, Group &group, const QFileSelector *selector) const
 {
-	return readInclude(reader, [this, &group](QXmlStreamReader &reader){
-		group = readGroup(reader);
-	}, QStringLiteral("Group"));
+	return readInclude(reader, [this, &group, selector](QXmlStreamReader &reader){
+		group = readGroup(reader, selector);
+	}, QStringLiteral("Group"), selector);
 }

-bool SettingsSetupLoader::readEntryInclude(QXmlStreamReader &reader, Entry &entry) const
+bool SettingsSetupLoader::readEntryInclude(QXmlStreamReader &reader, Entry &entry, const QFileSelector *selector) const
 {
 	return readInclude(reader, [this, &entry](QXmlStreamReader &reader){
 		entry = readEntry(reader);
-	}, QStringLiteral("Entry"));
+	}, QStringLiteral("Entry"), selector);
 }

-bool SettingsSetupLoader::readInclude(QXmlStreamReader &reader, const std::function<void(QXmlStreamReader &)> &readFn, const QString &typeName) const
+bool SettingsSetupLoader::readInclude(QXmlStreamReader &reader, const std::function<void(QXmlStreamReader &)> &readFn, const QString &typeName, const QFileSelector *selector) const
 {
 	testXmlValid(reader);
 	if(reader.name() != QStringLiteral("Include"))
@ -388,7 +388,7 @@ bool SettingsSetupLoader::readInclude(QXmlStreamReader &reader, const std::funct
 		if(dev)
 			dir = QFileInfo(dev->fileName()).dir();

-		QFile incFile(QDir::cleanPath(dir.absoluteFilePath(fileName)));
+		QFile incFile(QDir::cleanPath(selector->select(dir.absoluteFilePath(fileName))));
 		if(!incFile.open(QIODevice::ReadOnly | QIODevice::Text))
 			throw SettingsXmlException(incFile);

--- a/src/mvvmcore/settingssetuploader_p.h
+++ b/src/mvvmcore/settingssetuploader_p.h
@ -32,17 +32,17 @@ private:
 	mutable QCache<QString, SettingsElements::Setup> _cache;

 	//Functions to read the settings XML
-	SettingsElements::Category readCategory(QXmlStreamReader &reader) const;
-	SettingsElements::Category readDefaultCategory(QXmlStreamReader &reader) const;
-	void readCategoryChildren(QXmlStreamReader &reader, SettingsElements::Category &category) const;
+	SettingsElements::Category readCategory(QXmlStreamReader &reader, const QFileSelector *selector) const;
+	SettingsElements::Category readDefaultCategory(QXmlStreamReader &reader, const QFileSelector *selector) const;
+	void readCategoryChildren(QXmlStreamReader &reader, SettingsElements::Category &category, const QFileSelector *selector) const;

-	SettingsElements::Section readSection(QXmlStreamReader &reader) const;
-	SettingsElements::Section readDefaultSection(QXmlStreamReader &reader) const;
-	void readSectionChildren(QXmlStreamReader &reader, SettingsElements::Section &section) const;
+	SettingsElements::Section readSection(QXmlStreamReader &reader, const QFileSelector *selector) const;
+	SettingsElements::Section readDefaultSection(QXmlStreamReader &reader, const QFileSelector *selector) const;
+	void readSectionChildren(QXmlStreamReader &reader, SettingsElements::Section &section, const QFileSelector *selector) const;

-	SettingsElements::Group readGroup(QXmlStreamReader &reader) const;
-	SettingsElements::Group readDefaultGroup(QXmlStreamReader &reader) const;
-	void readGroupChildren(QXmlStreamReader &reader, SettingsElements::Group &group) const;
+	SettingsElements::Group readGroup(QXmlStreamReader &reader, const QFileSelector *selector) const;
+	SettingsElements::Group readDefaultGroup(QXmlStreamReader &reader, const QFileSelector *selector) const;
+	void readGroupChildren(QXmlStreamReader &reader, SettingsElements::Group &group, const QFileSelector *selector) const;

 	SettingsElements::Entry readEntry(QXmlStreamReader &reader) const;

@ -53,11 +53,11 @@ private:
 	QVariant readElement(QXmlStreamReader &reader) const;

 	//Functions to read included files
-	bool readCategoryInclude(QXmlStreamReader &reader, SettingsElements::Category &category) const;
-	bool readSectionInclude(QXmlStreamReader &reader, SettingsElements::Section &section) const;
-	bool readGroupInclude(QXmlStreamReader &reader, SettingsElements::Group &group) const;
-	bool readEntryInclude(QXmlStreamReader &reader, SettingsElements::Entry &entry) const;
-	bool readInclude(QXmlStreamReader &reader, const std::function<void(QXmlStreamReader&)> &readFn, const QString &typeName) const;
+	bool readCategoryInclude(QXmlStreamReader &reader, SettingsElements::Category &category, const QFileSelector *selector) const;
+	bool readSectionInclude(QXmlStreamReader &reader, SettingsElements::Section &section, const QFileSelector *selector) const;
+	bool readGroupInclude(QXmlStreamReader &reader, SettingsElements::Group &group, const QFileSelector *selector) const;
+	bool readEntryInclude(QXmlStreamReader &reader, SettingsElements::Entry &entry, const QFileSelector *selector) const;
+	bool readInclude(QXmlStreamReader &reader, const std::function<void(QXmlStreamReader&)> &readFn, const QString &typeName, const QFileSelector *selector) const;

 	//Functions to filter the elements
 	void clearSetup(SettingsElements::Setup &setup, const QString &frontend, const QStringList &selectors) const;