QtMvvm/doc/message.dox

/*!
@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
- MessageConfig::TypeColorDialog
- MessageConfig::TypeProgressDialog

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

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

/*!
@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
- For MessageConfig::TypeColorDialog:
	- MessageConfig::SubTypeRgb
	- MessageConfig::SubTypeArgb
- For MessageConfig::TypeProgressDialog:
	- MessageConfig::SubTypeProgress
	- MessageConfig::SubTypeBusy

@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()}
	@writeAc{addButton()}
	@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

The widgets implementation does support a few extra properties for this type:
- modal (bool = true), configure application modality
- windowTitle (QString), the window title
- details (QString), the message box details box
- checkable (bool = false), gives the messagebox a small checkbox
- checkString (QString), the string to display for that checkbox

@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	| Quick delegate
------------------------|-------------------------------|---------------|----------------
 bool					| QCheckBox						| CheckBox		| BoolDelegate
 switch					| QCheckBox						| Switch		| SwitchDelegate
 QString, string		| QLineEdit						| TextField		| MsgDelegate (*)
 int					| QSpinBox						| SpinBox		| MsgDelegate
 double, number			| QDoubleSpinBox				| DoubleSpinBox	| MsgDelegate
 range (int)			| QSlider						| Slider		| RangeDelegate
 QDate					| QDateEdit						| DateEdit		| MsgDelegate
 QTime					| QTimeEdit						| TimeEdit		| MsgDelegate
 QDateTime, date		| QDateTimeEdit					| DateTimeEdit	| MsgDelegate
 QColor, color			| ColorButton					| ColorEdit		| ColorDelegate
 QFont, font			| QFontComboBox					| FontEdit		| MsgDelegate
 QKeySequence			| QKeySequenceEdit				| -/-			| -/-
 QUrl, url				| QLineEdit with QUrlValidator	| UrlField		| MsgDelegate
 selection, list		| QComboBox						| ListEdit		| ListDelegate
 radiolist				| -/-							| RadioListEdit	| -/-
 action (settings only)	| QPushButton					| -/-			| ItemDelegate

(*) The MsgDelegate is used for any type but the ones that have explicit delegates. It will
show a dialog with an input of the "Quick edit" column

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::TypeColorDialog

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

Shows a generic color dialog. If possible, this will use the systems default, otherwise a
simple color picker gui.

 Dialog Type					| subType value
--------------------------------|---------------
 Select a color without alpha	| MessageConfig::SubTypeRgb
 Select a color with alpha		| MessageConfig::SubTypeArgb

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

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

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

Shows a generic progress dialog. The dialog can by dynamically and asynchronously controlled
from the core app via the ProgressControl class. You must pass an instance of a ProgressControl
via the MessageConfig::defaultValue property when creating one yourself. The passed control
will automatically be connected to the corresponding dialog.

 Dialog Type				| subType value
----------------------------|---------------
 Display a progress bar		| MessageConfig::SubTypeProgress
 Display a busy indicator	| MessageConfig::SubTypeBusy

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

/*!
@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
*/

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

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

A color dialog that lets the user select a color, without allowing editing of the alpha channel.
The alpha channel will always be set to `0xFF`, i.e. non transparent.

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

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

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

A color dialog that lets the user select a color, including the alpha channel. Please note that
not all native dialogs support alpha channel editing.

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

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

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

A dialog with a standard progess bar. This bar can either display a classical progress with min,
max and value, or be shown as indeterminate progress (can be switched dynamically via the
ProgressControl)

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeProgressDialog,
ProgressControl
*/

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

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

A dialog with a busy indicator shown. This indicator can and will always only show an
indeterminate progress, other values of the ProgressControl are ignored. On platforms that do
not have a seperate busy indicator, an indeterminate progress bar can be shown.

@sa MessageConfig::type, MessageConfig::subType, MessageConfig::TypeProgressDialog,
ProgressControl
*/



/*!
@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.

The class is semi threadsafe, as it is designed to be used in parallel from the core app and
the GUI code. From the core app, you can use:

- all properties (read, write, notify)
- hasResult() method
- discardMessage() slot
- dialogDone() signal

From the GUI, if you intend to create your own presenter frontend, you can use:

- result property (read, write)
- setCloseTarget() method
- complete() method

@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

@privsig

@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
*/



/*!
@class QtMvvm::ProgressControl

This class is used together with dialogs of the MessageConfig::TypeProgressDialog type to
control the currently displayed progress from the core code. The class is semi thread safe,
as it is designed to be used from the core an the gui in parallel.

From the core code, i.e. wherever you created the progress instance (directly or indirectly),
you can access:

- all properties (read, write, notify)
- close() slot
- updateLabel() slot
- canceled() signal
- closed() signal

From the GUI, if you intend to create your own presenter frontend, you can use:

- all properties (read, notify, **not** write)
- requestCancel() method
- notifyClosed() method
- changeLabel() signal
- closeRequested() signal

@sa MessageConfig::TypeProgressDialog, QtMvvm::showProgress,
QtMvvm::showIndeterminateProgress, QtMvvm::showBusy
*/

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

@default{`true`}

If set to true, the progress control will delete itself automatically right after closed()
has been emitted.

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

@sa ProgressControl::closed
*/

/*!
@property QtMvvm::ProgressControl::indeterminate

@default{`false`}

If set to true, the dialog will ignore the minimum, maximum and progress properties and simply
show an indeterminate progress. Setting it back to false restores a normal progress bar using
these 3.

@accessors{
	@readAc{isIndeterminate()}
	@writeAc{setIndeterminate()}
	@notifyAc{indeterminateChanged()}
}

@sa ProgressControl::minimum, ProgressControl::maximum, ProgressControl::progress
*/

/*!
@property QtMvvm::ProgressControl::minimum

@default{`0`}

The progress percentage (as number in [0,1]) is calculated as
`(progress - minimum)/(maximum - minimum)` and that value is used to display a progress.
Chaning this property affects the result accordingly.

@accessors{
	@readAc{minimum()}
	@writeAc{setMinimum()}
	@notifyAc{minimumChanged()}
}

@sa ProgressControl::maximum, ProgressControl::progress, ProgressControl::indeterminate
*/

/*!
@property QtMvvm::ProgressControl::maximum

@default{`100`}

The progress percentage (as number in [0,1]) is calculated as
`(progress - minimum)/(maximum - minimum)` and that value is used to display a progress.
Chaning this property affects the result accordingly.

@accessors{
	@readAc{maximum()}
	@writeAc{setMaximum()}
	@notifyAc{maximumChanged()}
}

@sa ProgressControl::minimum, ProgressControl::progress, ProgressControl::indeterminate
*/

/*!
@property QtMvvm::ProgressControl::progress

@default{`-1`}

The progress percentage (as number in [0,1]) is calculated as
`(progress - minimum)/(maximum - minimum)` and that value is used to display a progress.
Chaning this property affects the result accordingly.

Setting it to `-1` is a "special value", that means no progress has been set yet, and may
or may not lead to a different presentation of that state from the simple minimum.

@accessors{
	@readAc{progress()}
	@writeAc{setProgress()}
	@notifyAc{progressChanged()}
}

@sa ProgressControl::minimum, ProgressControl::maximum, ProgressControl::indeterminate
*/

/*!
@fn QtMvvm::ProgressControl::requestCancel

@param btn The button that was pressed by the user

Call this method when the user either presses the cancel button (then pass
MessageConfig::Cancel) or tried to close the window (pass MessageConfig::NoButton). Your GUI
implementation should react to that with disabling the cancel button, but still show the
progress, as the core app is to decide whether to accept that cancel request and if yes will
eventually close the dialog. Internally, this method will emit canceled() in a thread-safe
manner.

@note Your dialog should only allow cancelling when the MessageConfig has the
MessageConfig::Cancel set as a button.

@sa ProgressControl::canceled
*/

/*!
@fn QtMvvm::ProgressControl::notifyClosed

You must call this method as soon as you received a closeRequested() and have actually closed
the dialog. You must call both, this method and MessageResult::complete.

@sa ProgressControl::closeRequested, ProgressControl::closed, MessageResult::complete
*/

/*!
@fn QtMvvm::ProgressControl::close

You must use this method from the core code to close the dialog, either after successfully
completing your long running operation, or as the result of a canceled operation, in case
the user did cancel.

@sa ProgressControl::canceled, ProgressControl::closeRequested
*/

/*!
@fn QtMvvm::ProgressControl::updateLabel

The label text refers to the text initially set via MessageConfig::text. With this method,
you can easily update this text as your operation commences.

@sa MessageConfig::text, ProgressControl::changeLabel
*/

/*!
@fn QtMvvm::ProgressControl::canceled

@param btn The button that was pressed by the user

Cancelling in this case means the user pressed the cancel button (MessageConfig::Cancel) or
tried to close the dialog (MessageConfig::NoButton). In both cases, the dialog
*stays visible*! Your core code must react to the request by connecting this signal and
ideally gracefully cancel the operation and then close() the dialog.

You can ignore the signal in case you showed a non cancelable dialog.

@note For cancel-operations that take a while, it is recommended to tell the user that
cancelling is in progress, as after pressing cancel he can't do anything until the dialog
is closed.

@sa ProgressControl::close, ProgressControl::requestCancel
*/

/*!
@fn QtMvvm::ProgressControl::closed

@sa ProgressControl::close, ProgressControl::closeRequested, ProgressControl::notifyClosed
*/

/*!
@fn QtMvvm::ProgressControl::changeLabel

@param text The new label text

You should use this text and replace the default descriptive text set by MessageConfig::text

@sa ProgressControl::updateLabel, MessageConfig::text
*/

/*!
@fn QtMvvm::ProgressControl::closeRequested

When the close() method is called from the core app, this signal eventually gets emitted.
You must close the dialog immediatly and report that via the notifyClosed() method.

@sa ProgressControl::close, ProgressControl::notifyClosed, ProgressControl::closed
*/



/*!
@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
*/


/*!
@fn QtMvvm::getInput(const QString &, const QString &, const char *, const QVariant &, const QVariantMap &, const QString &, const QString &)

@param title The input dialog title (MessageConfig::title)
@param text A label to describe what to input (MessageConfig::text)
@param inputType The data type of the edit to be used (MessageConfig::subType)
@param defaultValue A default value to initialize the edit with (MessageConfig::defaultValue)
@param viewProperties Additional properties to be passed to the edit (MessageConfig::viewProperties)
@param okText An optional text overwrite for the OK button (MessageConfig::buttonTexts)
@param cancelText An optional text overwrite for the CANCEL button (MessageConfig::buttonTexts)

Shows an input dialog. The kind of edit to use is determined by using the `inputType`. The
view properties will be applied to both, the dialog and the edit.

@sa MessageConfig, CoreApp::showDialog
*/

/*!
@fn QtMvvm::getInput(const QString &, const QString &, const char *, const std::function<void(QVariant)> &, const QVariant &, const QVariantMap &, const QString &, const QString &)

@param onResult A handler to be called when the input dialog has been closed. Reports the
result or an invalid variant in case the input has been canceled.
@copydetails QtMvvm::getInput(const QString &, const QString &, const char *, const QVariant &, const QVariantMap &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::getInput(const QString &, const QString &, const char *, QObject *, const std::function<void(QVariant)> &, const QVariant &, const QVariantMap &, 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::getInput(const QString &, const QString &, const char *, const std::function<void(QVariant)> &, const QVariant &, const QVariantMap &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::getInput(const QString &, const QString &, const TEdit &, const QVariantMap &, const QString &, const QString &)

@param title The input dialog title (MessageConfig::title)
@param text A label to describe what to input (MessageConfig::text)
@param defaultValue A default value to initialize the edit with (MessageConfig::defaultValue)
@param viewProperties Additional properties to be passed to the edit (MessageConfig::viewProperties)
@param okText An optional text overwrite for the OK button (MessageConfig::buttonTexts)
@param cancelText An optional text overwrite for the CANCEL button (MessageConfig::buttonTexts)
@tparam TEdit The input to type to create an edit for and to get a value of

Shows an input dialog. The kind of edit to use is determined by using the `TEdit` type name.
The view properties will be applied to both, the dialog and the edit.

@sa MessageConfig, CoreApp::showDialog
*/

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

@param onResult A handler to be called when the input dialog has been closed. Reports the
result and `true` as second parameter, or a default constructed value and `false` in case the
input has been canceled
@copydetails QtMvvm::getInput(const QString &, const QString &, const TEdit &, const QVariantMap &, const QString &, const QString &)
*/

/*!
@fn QtMvvm::getInput(const QString &, const QString &, QObject *, const std::function<void(TEdit, bool)> &, const TEdit &, const QVariantMap &, 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::getInput(const QString &, const QString &, const std::function<void(TEdit, bool)> &, const TEdit &, const QVariantMap &, const QString &, const QString &)
*/


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

@param title The file dialog title (MessageConfig::title)
@param dir The directory URL to start the file dialog from (MessageConfig::defaultValue)

Shows a folder dialog to let the user select an existing directory.

@sa MessageConfig, CoreApp::showDialog
*/

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

@param onResult A handler to be called when the folder dialog has been closed. Reports the
selected directory URL or an invalid URL in case the input has been canceled.
@copydetails QtMvvm::getExistingDirectory(const QString &, const QUrl &)
*/

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

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

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

@param title The file dialog title (MessageConfig::title)
@param supportedMimeTypes A list of all allowed mimetypes (MessageConfig::viewProperties, extra property named `mimeTypes`)
@param dir The directory URL to start the file dialog from (MessageConfig::defaultValue)

Shows a file dialog to let the user select an existing file. The selectable files are limited
to the mime types allowed.

@sa MessageConfig, CoreApp::showDialog
*/

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

@param onResult A handler to be called when the file dialog has been closed. Reports the
selected file URL or an invalid URL in case the input has been canceled.
@copydetails QtMvvm::getOpenFile(const QString &, const QStringList &, const QUrl &)
*/

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

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

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

@param title The file dialog title (MessageConfig::title)
@param supportedMimeTypes A list of all allowed mimetypes (MessageConfig::viewProperties, extra property named `mimeTypes`)
@param dir The directory URL to start the file dialog from (MessageConfig::defaultValue)

Shows a file dialog to let the user select multiple existing files. The selectable files are
limited to the mime types allowed.

@sa MessageConfig, CoreApp::showDialog
*/

/*!
@fn QtMvvm::getOpenFiles(const std::function<void(QList<QUrl>)> &, const QString &, const QStringList &, const QUrl &)

@param onResult A handler to be called when the file dialog has been closed. Reports the
selected file URLs in a list or an empty list in case the input has been canceled.
@copydetails QtMvvm::getOpenFiles(const QString &, const QStringList &, const QUrl &)
*/

/*!
@fn QtMvvm::getOpenFiles(QObject *, const std::function<void(QList<QUrl>)> &, const QString &, const QStringList &, const QUrl &)

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

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

@param title The file dialog title (MessageConfig::title)
@param supportedMimeTypes A list of all allowed mimetypes (MessageConfig::viewProperties, extra property named `mimeTypes`)
@param dir The directory URL to start the file dialog from (MessageConfig::defaultValue)

Shows a file dialog to let the user select an (non existing) file name for saving. The
selectable files are limited to the mime types allowed.

@sa MessageConfig, CoreApp::showDialog
*/

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

@param onResult A handler to be called when the file dialog has been closed. Reports the
selected file URL or an invalid URL in case the input has been canceled.
@copydetails QtMvvm::getSaveFile(const QString &, const QStringList &, const QUrl &)
*/

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

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

/*!
@fn QtMvvm::getColor(const QString &, const QColor &, bool)

@param title The color dialog title (MessageConfig::title)
@param color The color to initially show in the dialog (MessageConfig::defaultValue)
@param argb Specify whether the dialog should allow editing of the alpha channel (MessageConfig::subType)

Shows a color dialog to let the user select a color. Depending on the argb parameter the
alpha channel may or may not be editable.

@sa MessageConfig, CoreApp::showDialog
*/

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

@param onResult A handler to be called when the color dialog has been closed. Reports the
selected color or an invalid color in case the input has been canceled.
@copydetails QtMvvm::getColor(const QString &, const QColor &, bool)
*/

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

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

/*!
@fn QtMvvm::showProgress(const QString &, const QString &, ProgressControl*, bool, bool, const QString &)

@param title The progress dialog title (MessageConfig::title)
@param label The progress dialog label (MessageConfig::text)
@param control The progress control to be used to control the progress dialog  (MessageConfig::defaultValue)
@param allowCancel Specify, whether the user can cancel the dialog (MessageConfig::buttons,
set to `MessageConfig::Cancel` if enabled, `MessageConfig::NoButton` otherwise)
@param isBusy Specify whether a busy dialog or a progress dialog should be shown (MessageConfig::subType)
@param cancelText The text for the cancel button, if enabled (MessageConfig::buttonTexts)

Shows a progress dialog to let the user know a long running operation is going on. Unlike
other dialogs, this one can be "controlled" from within the core code to update the progress
etc. via the control passed to the method.

@sa ProgressControl, MessageConfig, CoreApp::showDialog
*/

/*!
@fn QtMvvm::showProgress(const QString &, const QString &, int, int, bool, int, const QString &)

@param title The progress dialog title (MessageConfig::title)
@param label The progress dialog label (MessageConfig::text)
@param maximum The initial maxmium value of the progress (ProgressControl::maximum)
@param minimum The initial minimum value of the progress (ProgressControl::minimum)
@param allowCancel Specify, whether the user can cancel the dialog (MessageConfig::buttons,
set to `MessageConfig::Cancel` if enabled, `MessageConfig::NoButton` otherwise)
@param value The initial progress value of the progress (ProgressControl::progress)
@param cancelText The text for the cancel button, if enabled (MessageConfig::buttonTexts)
@returns A newly created progress control to be used to control the progress dialog (MessageConfig::defaultValue)

Shows a normal progress dialog to let the user know a long running operation is going on. Unlike
other dialogs, this one can be "controlled" from within the core code to update the progress
etc. via the returned control. The control is initialized with the parameters passed to this
method.

@note It is possible to conver the dialog to a indeterminate progress and back by setting the
ProgressControl::indeterminate property.

@sa ProgressControl, MessageConfig, CoreApp::showDialog
*/

/*!
@fn QtMvvm::showProgress(QObject*, const QString &, const QString &, int, int, bool, int, const QString &)

@param scope A scope to limit to. `onResult` is only called as long as scope has not been deleted
@copydetails QtMvvm::showProgress(const QString &, const QString &, int, int, bool, int, const QString &)
*/

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

@param title The progress dialog title (MessageConfig::title)
@param label The progress dialog label (MessageConfig::text)
@param allowCancel Specify, whether the user can cancel the dialog (MessageConfig::buttons,
set to `MessageConfig::Cancel` if enabled, `MessageConfig::NoButton` otherwise)
@param cancelText The text for the cancel button, if enabled (MessageConfig::buttonTexts)
@returns A newly created progress control to be used to control the progress dialog (MessageConfig::defaultValue)

Shows an indeterminate progress dialog to let the user know a long running operation is going on.
Unlike other dialogs, this one can be "controlled" from within the core code to update the
label etc. via the returned control. The control is initialized with the parameters
passed to this method.

@note It is possible to conver the dialog to a normal progress and back by setting the
ProgressControl::indeterminate property.

@sa ProgressControl, MessageConfig, CoreApp::showDialog
*/

/*!
@fn QtMvvm::showIndeterminateProgress(QObject*, const QString &, const QString &, bool, const QString &)

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

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

@param title The progress dialog title (MessageConfig::title)
@param label The progress dialog label (MessageConfig::text)
@param allowCancel Specify, whether the user can cancel the dialog (MessageConfig::buttons,
set to `MessageConfig::Cancel` if enabled, `MessageConfig::NoButton` otherwise)
@param cancelText The text for the cancel button, if enabled (MessageConfig::buttonTexts)
@returns A newly created progress control to be used to control the progress dialog (MessageConfig::defaultValue)

Shows an busy indicator dialog to let the user know a long running operation is going on.
Unlike other dialogs, this one can be "controlled" from within the core code to update the
label etc. via the returned control. The control is initialized with the parameters
passed to this method.

@sa ProgressControl, MessageConfig, CoreApp::showDialog
*/

/*!
@fn QtMvvm::showBusy(QObject*, const QString &, const QString &, bool, const QString &)

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