/*!
@class QtMvvm::MessageConfig

You can use the configuration to show simple dialogs from the core application. Typically, you
can use the wrapper methods, but for more advanced dialogs you may need to create a message
config explicitly.

@sa CoreApp::showDialog, QtMvvm::information, QtMvvm::question, QtMvvm::warning,
QtMvvm::critical, QtMvvm::about, QtMvvm::getInput, QtMvvm::getExistingDirectory,
QtMvvm::getOpenFile, QtMvvm::getOpenFiles, QtMvvm::getSaveFile
*/

/*!
@enum QtMvvm::MessageConfig::StandardButton

@note The values are kept in sync with QMessageBox::StandardButton etc. This means you can
simply cast the values to the other standard buttons without any risk. This goes for other
classes like QDialogButtonBox and the QML variants as well.
*/

/*!
@property QtMvvm::MessageConfig::type

@default{`MessageConfig::TypeMessageBox`}

The type determines what kind of dialog is show. The type is a general category of dialogs. The
MessageConfig::subType is used to set the final type of dialog shown. It's interpretation
depends on the type used.

It is possible to define your own types, but that means you have to customize the presenters to
add support for those dialogs.

The types supported by default are:

- MessageConfig::TypeMessageBox
- MessageConfig::TypeInputDialog
- MessageConfig::TypeFileDialog

@accessors{
	@readAc{type()}
	@writeAc{setType()}
}

@sa MessageConfig::subType, MessageConfig::TypeMessageBox, MessageConfig::TypeInputDialog,
MessageConfig::TypeFileDialog
*/

/*!
@property QtMvvm::MessageConfig::subType

@default{<i>Depends on the type used</i>}

The subType is a finer specification of what kind of dialog to show. It depends on the
MessageConfig::type that is used. The possible valid subtypes depend on the MessageConfig::type
used.

It is possible to define your own subtypes, but that means you have to customize the presenters
to add support for those dialogs.

The subtypes supported by default are:

- For MessageConfig::TypeMessageBox:
	- MessageConfig::SubTypeInformation
	- MessageConfig::SubTypeWarning
	- MessageConfig::SubTypeCritical
	- MessageConfig::SubTypeQuestion
	- MessageConfig::SubTypeAbout
- For MessageConfig::TypeInputDialog:
	- The name of the type to get an input value for, e.g. `QString`, `int`, ...
- For MessageConfig::TypeFileDialog:
	- MessageConfig::SubTypeDir
	- MessageConfig::SubTypeOpenFile
	- MessageConfig::SubTypeOpenFiles
	- MessageConfig::SubTypeSaveFile

@accessors{
	@readAc{subType()}
	@writeAc{setSubType()}
	@resetAc{resetSubType()}
}

@sa MessageConfig::type, MessageConfig::TypeMessageBox, MessageConfig::TypeInputDialog,
MessageConfig::TypeFileDialog
*/

/*!
@property QtMvvm::MessageConfig::title

@default{<i>Emtpy</i>}

The title is typically bigger then the rest of the text and serves as a short text to hint the
content. Depending on the platform and type it may be shown as window title or other kind of
decorative text.

@accessors{
	@readAc{title()}
	@writeAc{setTitle()}
}

@sa MessageConfig::text
*/

/*!
@property QtMvvm::MessageConfig::text

@default{<i>Emtpy</i>}

The text is shown as primary content, a more descriptive label, or tooltip or similar. It can
be of arbitrary length. It's role and contents heavily depend on the type and subtype beeing
used.

@accessors{
	@readAc{text()}
	@writeAc{setText()}
}

@sa MessageConfig::title, MessageConfig::buttonTexts, MessageConfig::viewProperties
*/

/*!
@property QtMvvm::MessageConfig::buttons

@default{<i>Depends on the type used</i>}

The buttons are the buttons in the dialog to "complete" it. Use these flags to select the
buttons the user can click on. Each button will close the dialog and be reported back via
the MessageResult::dialogDone signal.

@note The RESET-Accessor will reset both, the buttons and the buttonTexts

@accessors{
	@readAc{buttons()}
	@writeAc{setButtons()}
	@resetAc{resetButtons()}
}

@sa MessageConfig::StandardButton, MessageConfig::buttonTexts, MessageResult::dialogDone
*/

/*!
@property QtMvvm::MessageConfig::buttonTexts

@default{<i>Empty</i>}

All buttons in this map will be shown in addition to the ones in the MessageConfig::buttons
property. The will keep their role, but show the text specified in the map instead of their
normal text.

@note The RESET-Accessor will reset both, the buttons and the buttonTexts

@accessors{
	@readAc{buttonTexts()}
	@writeAc{setButtonTexts()}
	@writeAc{setButtonText()}
	@resetAc{resetButtons()}
}

@sa MessageConfig::StandardButton, MessageConfig::buttons
*/

/*!
@property QtMvvm::MessageConfig::defaultValue

@default{<i>Invalid</i>}

Some dialogs allow the users to enter some kind of result besides of the buttons they can
press. For such dialogs, this property can be used to provide the input with a default value.
For others, this may serve as a hint for the input.

@accessors{
	@readAc{defaultValue()}
	@writeAc{setDefaultValue()}
}

@sa MessageConfig::type
*/

/*!
@property QtMvvm::MessageConfig::viewProperties

@default{<i>Empty</i>}

The view properties are additional properties to be set on the created views. This allows you
to configure the appearance of the dialog from within the core code.

@note The properties are always set on all views. If a view does not have such a property, it
will do nothing. This allows you to set properties for all the different views you support.

@accessors{
	@readAc{viewProperties()}
	@writeAc{setViewProperties()}
	@writeAc{setViewProperty()}
}

@sa MessageConfig::type
*/

/*!
@var QtMvvm::MessageConfig::TypeMessageBox

<b>Value:</b> `"msgbox"`

Shows a generic message box with a title and primary text to inform the user of some kind of
event or ask him a question. The MessageConfig:subType is used to determine the kind of
message to show:

 Message Type	| subType value
----------------|---------------
 Information	| MessageConfig::SubTypeInformation
 Question		| MessageConfig::SubTypeWarning
 Warning		| MessageConfig::SubTypeCritical
 Critical Error	| MessageConfig::SubTypeQuestion
 About Dialog	| MessageConfig::SubTypeAbout

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeInputDialog,
MessageConfig::TypeFileDialog
*/

/*!
@var QtMvvm::MessageConfig::TypeInputDialog

<b>Value:</b> `"input"`

Shows a generic input dialog with a title and a short label, together with some kind of edit
view in order to input a single value. The datatype to get as well as the kind of input view
to create is determined by MessageConfig:subType. Theoretically, and type that can be passed
via QVariant can be used as input value. However, only for the most common types do default
edit views exist. In case you want to use types not present in the list below, you need to
create edit views yourself

 Type				| Widgets edit					| Quick edit
--------------------|-------------------------------|------------
 bool				| QCheckBox						| CheckBox
 switch				| -/-							| Switch
 QString, string	| QLineEdit						| TextField
 int				| QSpinBox						| SpinBox
 double, number		| QDoubleSpinBox				| DoubleSpinBox
 QDate				| QDateEdit						| -/-
 QTime				| QTimeEdit						| -/-
 QDateTime, date	| QDateTimeEdit					| -/-
 QFont				| QFontComboBox					| FontEdit
 QKeySequence		| QKeySequenceEdit				| -/-
 QUrl, url			| QLineEdit with QUrlValidator	| UrlField
 selection, list	| QComboBox						| ListEdit
 radiolist			| -/-							| RadioListEdit

The following types have special properties as well:

- QString, string:
	- `regexp`: A regular expression pattern (QString) to be used as input validator for the
text
	- `patternOptions`: QRegularExpression::PatternOptions as options for the regular
expression
- QUrl, url:
	- `allowedSchemes`: A QStringList with allowed schemes for the URL
- selection, list, radiolist:
	- `listElements`: A list of elemets the user can select from. Can either be:
		- QString elements: They will serve as display value and returned value
		- QVariantMap elements: A map containing the following values:
			- `name`: A QString shown to the user to select
			- `value`: A QVariant value that is returned instead of the selected name


@sa MessageConfig::type, MessageConfig::subType, InputViewFactory, InputWidgetFactory,
MessageConfig::TypeMessageBox, MessageConfig::TypeFileDialog
*/

/*!
@var QtMvvm::MessageConfig::TypeFileDialog

<b>Value:</b> `"file"`

Shows a generic file dialog utilizing the operating systems default file dialogs in order to
show a native dialog the user can use to select files or directories

 Dialog Type	| subType value
----------------|---------------
 Open Directory	| MessageConfig::SubTypeDir
 Open File		| MessageConfig::SubTypeOpenFile
 Open Files		| MessageConfig::SubTypeOpenFiles
 Save File		| MessageConfig::SubTypeSaveFile

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeInputDialog,
MessageConfig::TypeMessageBox
*/

/*!
@var QtMvvm::MessageConfig::SubTypeInformation

<b>Value:</b> `"information"`

An information message box typically shows a neutral/positiv information.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeMessageBox
*/

/*!
@var QtMvvm::MessageConfig::SubTypeWarning

<b>Value:</b> `"warning"`

An warning message box typically shows a (non critical) warning.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeMessageBox
*/

/*!
@var QtMvvm::MessageConfig::SubTypeCritical

<b>Value:</b> `"critical"`

An critical message box typically shows a critical and often unrecoverable error.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeMessageBox
*/

/*!
@var QtMvvm::MessageConfig::SubTypeQuestion

<b>Value:</b> `"question"`

An question message box typically asks the user a simple Yes-No question he can reply using
the buttons.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeMessageBox
*/

/*!
@var QtMvvm::MessageConfig::SubTypeAbout

<b>Value:</b> `"about"`

An about dialog is a simple informative dialog showing information about the application in
a neutral manner, but in a sligthly different style than a simple information message.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeMessageBox
*/

/*!
@var QtMvvm::MessageConfig::SubTypeDir

<b>Value:</b> `"dir"`

A file dialog to open a directory lets the user select a single, existing directory. Depending
on the platform he might be able to create a new directory via the dialog, but he can only
select an existing one.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeFileDialog
*/

/*!
@var QtMvvm::MessageConfig::SubTypeOpenFile

<b>Value:</b> `"open"`

A file dialog to open a file lets the user select a single, existing file.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeFileDialog
*/

/*!
@var QtMvvm::MessageConfig::SubTypeOpenFiles

<b>Value:</b> `"files"`

A file dialog to open multiple files lets the user select a list of existing files. They can
be in different folders, if the platform allows this.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeFileDialog
*/

/*!
@var QtMvvm::MessageConfig::SubTypeSaveFile

<b>Value:</b> `"save"`

A file dialog to save a file lets the user select a single file to be created or overwritten
to save content to it.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeFileDialog
*/



/*!
@class QtMvvm::MessageResult

This class is used to keep track of an active dialog an get the result once it has been
completed. You should not create it yourself, is is returned from the core app.

@sa CoreApp::showDialog, MessageConfig
*/

/*!
@property QtMvvm::MessageResult::result

@default{<i>Invalid</i>}

If the dialog accepts some kind of input, the result is reported via this property. Please
note that the property may be changed multiple times with invalid values while the dialog is
still open. Only use the result after dialogDone() has been emitted.

@accessors{
	@readAc{result()}
	@writeAc{setResult()}
}

@sa MessageResult::hasResult, MessageResult::complete, MessageResult::dialogDone
*/

/*!
@property QtMvvm::MessageResult::autoDelete

@default{`true`}

If set to true, the message result will delete itself automatically right after dialogDone()
has been emitted. This means it is still safe to access the result in the slots connected to
dialogDone(), as long as they are direct connected.

@accessors{
	@readAc{autoDelete()}
	@writeAc{setAutoDelete()}
	@notifyAc{autoDeleteChanged()}
}

@sa MessageResult::complete, MessageResult::dialogDone
*/

/*!
@fn QtMvvm::MessageResult::setCloseTarget(QObject *, const QString &)

@param closeObject The object to call the method on
@param closeMethod The method to be called

@attention This method should be used by the presenter only, not from the core

Use it from the presenter to register a view and a method on the view to be called to close
the view. The `closeMethod` should be a paremeterless method signature (e.g. `close()`). Not
settings a close target means that the dialog cannot be closed from code via discardMessage().

@sa MessageResult::discardMessage
*/

/*!
@fn QtMvvm::MessageResult::complete(QtMvvm::MessageConfig::StandardButton)

@param button The button that was pressed by the user

@attention This method should be used by the presenter only, not from the core

You must use this method from the GUI view code to mark a message result as completed as soon
as the user completed the dialog. The `button` should be the button the user pressed, or
MessageConfig::NoButton if close by another reason. The pressed button should be one that was
in the list of buttons specified by the MessageConfig that created the dialog (with the
NoButton beeing the only exception).

The method automatically emits the dialogDone() signal and handels self deletion in a
threadsafe manner.

@sa MessageResult::dialogDone, MessageResult::result, MessageResult::autoDelete
*/

/*!
@fn QtMvvm::MessageResult::complete(QtMvvm::MessageConfig::StandardButton, const QVariant &)

@param result The input result to be set as MessageResult::result
@copydetails MessageResult::complete(QtMvvm::MessageConfig::StandardButton)
*/

/*!
@fn QtMvvm::MessageResult::discardMessage

Calls the closeMethod set by the presenter (if one was set) to close the dialog. Connect to
the dialogDone() signal to be notified when the dialog was closed. It is typically emitted with
MessageConfig::NoButton when beeing discarded this way.

@sa MessageResult::setCloseTarget, MessageResult::dialogDone
*/

/*!
@fn QtMvvm::MessageResult::dialogDone

@param button The button that was pressed by the user to complete the dialog

Is emitted as soon as the dialog was closed with the button that was pressed, or
MessageConfig::NoButton when closed another way. If the dialog had an input edit for the user
to enter a value, you can retrieve the result via MessageResult::result.

@warning You must always direct connect to this signal, because if the auto deletion is
enabled, the result will be deleted right after the signal was emitted (and thus after all
direct connected slots have been called). You may use MessageResult::result only in a slot
connect to this signal, because auf the reason above, and because before the signal it is
considered invalid.

@sa MessageResult::result, MessageResult::complete
*/



/*!
@fn QtMvvm::information(const QString &, const QString &, const QString &)

@param title The messagebox title (MessageConfig::title)
@param text The primary message text (MessageConfig::text)
@param okText An optional text overwrite for the OK button (MessageConfig::buttonTexts)

Shows a simple informative dialog with a title, a text and the OK button present.

@sa QtMvvm::question, QtMvvm::warning, QtMvvm::critical, QtMvvm::about, MessageConfig,
CoreApp::showDialog
*/

/*!
@fn QtMvvm::information(const QString &, const QString &, const std::function<void()> &, const QString &)

@param onResult A handler to be called when the message box has been closed
@copydetails QtMvvm::information(const QString &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::information(const QString &, const QString &, QObject *, const std::function<void()> &, const QString &)

@param scope A scope to limit to. `onResult` is only called as long as scope has not been deleted
@copydetails QtMvvm::information(const QString &, const QString &, const std::function<void()> &, const QString &)
*/

/*!
@fn QtMvvm::question(const QString &, const QString &, const QString &, const QString &)

@param title The messagebox title (MessageConfig::title)
@param text The primary message text (MessageConfig::text)
@param yesText An optional text overwrite for the YES button (MessageConfig::buttonTexts)
@param noText An optional text overwrite for the NO button (MessageConfig::buttonTexts)

Shows a simple question dialog with a title, a text and two buttons (typically YES and NO) to
ask the user a simple boolean question.

@sa QtMvvm::information, QtMvvm::warning, QtMvvm::critical, MessageConfig,
CoreApp::showDialog
*/

/*!
@fn QtMvvm::question(const QString &, const QString &, const std::function<void(bool)> &, const QString &, const QString &)

@param onResult A handler to be called when the message box has been closed. The parameter is
`true` if the user pressed YES, `false` if he pressed NO or cancled the dialog
@copydetails QtMvvm::question(const QString &, const QString &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::question(const QString &, const QString &, QObject *, const std::function<void(bool)> &, const QString &, const QString &)

@param scope A scope to limit to. `onResult` is only called as long as scope has not been deleted
@copydetails QtMvvm::question(const QString &, const QString &, const std::function<void(bool)> &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::warning(const QString &, const QString &, const QString &)

@param title The messagebox title (MessageConfig::title)
@param text The primary message text (MessageConfig::text)
@param okText An optional text overwrite for the OK button (MessageConfig::buttonTexts)

Shows a simple warning dialog with a title, a text and the OK button present.

@sa QtMvvm::question, QtMvvm::information, QtMvvm::critical, MessageConfig,
CoreApp::showDialog
*/

/*!
@fn QtMvvm::warning(const QString &, const QString &, const std::function<void()> &, const QString &)

@param onResult A handler to be called when the message box has been closed
@copydetails QtMvvm::warning(const QString &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::warning(const QString &, const QString &, QObject *, const std::function<void()> &, const QString &)

@param scope A scope to limit to. `onResult` is only called as long as scope has not been deleted
@copydetails QtMvvm::warning(const QString &, const QString &, const std::function<void()> &, const QString &)
*/

/*!
@fn QtMvvm::critical(const QString &, const QString &, const QString &)

@param title The messagebox title (MessageConfig::title)
@param text The primary message text (MessageConfig::text)
@param okText An optional text overwrite for the OK button (MessageConfig::buttonTexts)

Shows a simple critical error dialog with a title, a text and the OK button present.

@sa QtMvvm::question, QtMvvm::warning, QtMvvm::information, MessageConfig,
CoreApp::showDialog
*/

/*!
@fn QtMvvm::critical(const QString &, const QString &, const std::function<void()> &, const QString &)

@param onResult A handler to be called when the message box has been closed
@copydetails QtMvvm::critical(const QString &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::critical(const QString &, const QString &, QObject *, const std::function<void()> &, const QString &)

@param scope A scope to limit to. `onResult` is only called as long as scope has not been deleted
@copydetails QtMvvm::critical(const QString &, const QString &, const std::function<void()> &, const QString &)
*/

/*!
@fn QtMvvm::about(const QString &, const QUrl &, const QString &, const QUrl &, const QString &, bool, const QStringList &, const QString &)

@param description A short descriptive text what your application is all about
@param websiteUrl The URL to your website
@param licenseName The name of the License you are using
@param licenseUrl A URL to an online (or offline) variant of the license to read
for the user
@param companyName The name of your company or your name as creator of the application
@param addQtVersion Specify whether the Qt Version should be visible as part of the about
dialog
@param extraTopInfos Additional short texts to be shown below the version
@param extraBottomInfos An additional text to be shown at the bottom of the dialog

Creates an advanced about dialog out of all of this information in an organized manner. The
`extraTopInfos` are ment as short extra information about configurations etc, for example a
specific plattform plugin used, as selected style or further important links. The
`extraBottomInfos` can be a long and rich text with anything else you want to put in the about
dialog that is not applicabale for the previous part (for example a list of contributers).

@note All the texts can be richtext (HTML). But be aware that they are already beeing wrapped
in `<p></p>` blocks. Furthermore, QML only supports a small subset of HTML in the default text
mode that is used.

@sa QtMvvm::information, MessageConfig, CoreApp::showDialog
*/