Skycoder42
7 years ago
4 changed files with 616 additions and 27 deletions
@ -0,0 +1,71 @@ |
|||||
|
/*! |
||||
|
@class QtMvvm::IPresenter |
||||
|
|
||||
|
This class is what you need to implement if you want to create your own GUI frontend for mvvm. |
||||
|
Once you created your custom presenter class, register it as service before calling |
||||
|
CoreApp::bootApp() (Or entering the eventloop, in case of automatic startup, like with |
||||
|
#QTMVVM_REGISTER_CORE_APP) |
||||
|
|
||||
|
To register it, it is recommended to use a startup hook like this: |
||||
|
@code{.cpp} |
||||
|
void myPresenterInit() |
||||
|
{ |
||||
|
QtMvvm::ServiceRegistry::instance()->registerInterface<QtMvvm::IPresenter, MyPresenter>(); |
||||
|
} |
||||
|
Q_COREAPP_STARTUP_FUNCTION(myPresenterInit) |
||||
|
@endcode |
||||
|
*/ |
||||
|
|
||||
|
/*! |
||||
|
@fn QtMvvm::IPresenter::present |
||||
|
|
||||
|
@param viewModel The ViewModel to be presenter |
||||
|
@param params Additional parameters for the viemodel initialization |
||||
|
@param parent An optional parent for the viewmodels view |
||||
|
@throws PresenterException When presenting fails for whatever reason |
||||
|
|
||||
|
This method should: |
||||
|
|
||||
|
1. Find and create a view for the viewmodel |
||||
|
2. Use the view of the parent viewModel to make the new view a child of that parent view |
||||
|
3. Make the viewmodel a child of the view (via QObject::setParent) |
||||
|
4. Call the viewmodels ViewModel::onInit method with the given parameters |
||||
|
5. Find a presentation method for the view (based on the view/viewmodel and/or parent) |
||||
|
6. Show the view to the user |
||||
|
|
||||
|
If this method returns it is assumed the presentation was successful. If you throw the |
||||
|
exception, presenting has failed, and the app will automatically destroy the viewmodel and |
||||
|
handle cleanups and results. |
||||
|
|
||||
|
@note If you need to present asynchronous, then you need to perform this step yourself in case |
||||
|
the asynchronous presentation failed. |
||||
|
|
||||
|
@sa IPresenter::showDialog |
||||
|
*/ |
||||
|
|
||||
|
/*! |
||||
|
@fn QtMvvm::IPresenter::showDialog |
||||
|
|
||||
|
@param config The configuration for the dialog to be shown |
||||
|
@param result A reference to the object to report results to |
||||
|
@throws PresenterException When presenting fails for whatever reason |
||||
|
|
||||
|
This method should create a simple dialog based of the configuration passed to it. Read the |
||||
|
MessageConfig for more details on the parameters. The MessageConfig::type and |
||||
|
MessageConfig::subType properties are used to determine the kind of dialog to be shown. The other |
||||
|
properties are used to configure the dialog. |
||||
|
|
||||
|
The result is a reference to a result object to report the result value and the pressed button |
||||
|
to. The result is owned by the caller, you must never delete it. Use the special "GUI methods" to |
||||
|
report the result and configure a close target. |
||||
|
|
||||
|
If this method returns it is assumed the presentation was successful. If you throw the |
||||
|
exception, presenting has failed, and the app will automatically complete the message result with |
||||
|
the MessageConfig::NoButton constant. |
||||
|
|
||||
|
@note If you need to present asynchronous, then you need to perform this step yourself in case |
||||
|
the asynchronous presentation failed. |
||||
|
|
||||
|
@sa IPresenter::present, MessageConfig, MessageResult, MessageResult::complete, |
||||
|
MessageResult::setCloseTarget |
||||
|
*/ |
||||
@ -0,0 +1,381 @@ |
|||||
|
/*! |
||||
|
@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 |
||||
|
*/ |
||||
Loading…
Reference in new issue