The MDialog class is the base class of dialog windows. More...
Detailed Description
The MDialog class is the base class of dialog windows.
Overview
MDialog is a top-level scene window mostly used for short-term tasks and brief communications with the user. It can either be embedded in an existing MWindow (and therefore be application modal) or displayed in its own separate MWindow (which may be system modal). MDialogs are never modeless.
A MDialog is comprised by three components:
- A title bar containing a title text, a progress indicator and a close button. The close button, the progress indicator or the entire title bar can be hidden. The progress indicator is hidden by default.
- A customizable central widget, that is meant to contain either the message or query for the user, or the content requesting user's selection.
- A button box, that can contain buttons for providing means of selection for simple queries. Can be hidden when central widget is customized.
MDialog provides a return value, based on the user's choice. It also knows which button from the button box was pressed (if any).
Usage guidelines
It is not always instantly clear whether to use a MDialog or MApplicationPage in your application, here are some characteristics and guidelines for making the decision:
| Use an application page when... | Use a dialog when... |
|---|---|
| When you have a main task in the application; one page for each main task. | When you are performing a secondary task related to the contents within the view. |
| When you are staying inside the contents of particular application. | When you are utilizing information from some other application source only as intermediate step, to avoid branching away. |
| When you want to return to this step when pressing Back from following page. | When it does not make sense to return to this step after pressing Back from following page. |
| You need a complex UI for the selection; many levels, functionalities, different styles etc. | A simple selection is enough, the action can be quickly finished, optionally with one click. |
| When you need multiple instances of the same action (compose multiple separate emails at the same time, each in their own page.) | When multiple instances do not make sense (for instance Select Connection is a dialog, since it does not make sense to have two of them open at the same time.) |
System Dialogs and System Modal Dialogs
MDialog is application modal by default. It means that it pops up on top of the current window and blocks interaction with the application until the selection is made by user.
Then a dialog can be a System Dialog, which means that it's displayed in a separate top-level MWindow, A System Dialog can be modeless or modal - the difference between System Dialog and System Modal Dialog is that System Dialog can be temporarily skipped - it provides a home button that can minimize the dialog to switcher and reveal the underlying application. When the System Dialog is skipped it's not deleted nor closed and it can be later accessed from the task switcher.
The System Modal Dialog doesn't provide the home button and therefore it can't be skipped - it should be used for queries that require user's immediate action.
- Note:
- When displayed inside a given MWindow (by supplying a window parameter to appear() or exec()) a dialog will ignore the system property and will be application modal.
- See also:
- setSystem(), setModal()
Variants
- MMessageBox is designed for asking the user simple yes/no-type of questions. It contains text in its central area and has the title bar hidden.
- MPopupList is for picking one option from several alternatives. It has no button box, closes immediately after user makes selection.
Examples
Constructing an entry dialog:
MWidget *centralWidget = new MWidget; QGraphicsLinearLayout *layout = new QGraphicsLinearLayout(Qt::Vertical); MLabel *label = new MLabel("Name", centralWidget); MTextEdit *textEdit = new MTextEdit(MTextEditModel::SingleLine, QString(), centralWidget); centralWidget->setLayout(layout); layout->addItem(label); layout->addItem(textEdit); MDialog* dialog = new MDialog("Please enter your name", M::OkButton | M::ResetButton); dialog->setCentralWidget(centralWidget); connect(dialog, SIGNAL(disappeared()), SLOT(processDialogResult())); dialog->appear(myScene);
Constructing a question dialog, it is easier to use MMessageBox instead:
MDialog* dialog = new MDialog("Question", M::YesButton | M::NoButton); dialog->setCentralWidget(new MLabel("Lorem ipsum dolor sit amet?")); connect(dialog, SIGNAL(disappeared()), SLOT(processDialogResult())); dialog->appear(myScene);
Adding standard and non standard buttons:
\\First two are standard buttons with positive and negative roles.
addButton(M::OkButton);
addButton(M::CancelButton);
\\The third is custom button with positive role
addButton("Custom Action", M::ActionRole);
Order of buttons will be: Ok, Custom Action, Cancel.
- See also:
- MDialogView, MDialogStyle
Definition at line 167 of file corelib/widgets/mdialog.h.
Member Enumeration Documentation
| enum MDialog::DialogCode |
Constructor & Destructor Documentation
| MDialog::MDialog | ( | ) |
Constructs a dialog.
Definition at line 273 of file mdialog.cpp.
:
MSceneWindow(new MDialogPrivate(), new MDialogModel(), MSceneWindow::Dialog, QString())
{
model()->setResultCode(MDialog::Rejected);
}
| MDialog::MDialog | ( | const QString & | title, | |
| M::StandardButtons | buttons | |||
| ) |
Constructs a dialog with a given title and a set of standard buttons specified by buttons.
Definition at line 279 of file mdialog.cpp.
:
MSceneWindow(new MDialogPrivate(), new MDialogModel(), MSceneWindow::Dialog, QString())
{
Q_D(MDialog);
model()->setResultCode(MDialog::Rejected);
setTitle(title);
d->addStandardButtons(buttons);
}
| MDialog::~MDialog | ( | ) | [virtual] |
Member Function Documentation
| void MDialog::accept | ( | ) | [virtual, slot] |
Dismisses the modal dialog and sets the result code to Accepted.
Equals to done(Accepted).
- See also:
- accept()
Definition at line 400 of file mdialog.cpp.
| void MDialog::accepted | ( | ) | [signal] |
This signal is emitted when the dialog has been accepted either by the user or by calling accept() or done() with the MDialog::Accepted argument.
Note that this signal is not emitted when hiding the dialog with hide() or setVisible(false). This includes deleting the dialog while it is visible.
- See also:
- accept()
| MButtonModel * MDialog::addButton | ( | const QString & | text | ) |
Creates a button with the given text and adds it to the button box.
- See also:
- removeButton()
Definition at line 340 of file mdialog.cpp.
{
MButtonModel *buttonModel = 0;
buttonModel = new MButtonModel;
buttonModel->setText(text);
model()->addButton(buttonModel);
return buttonModel;
}
| MButtonModel * MDialog::addButton | ( | const QString & | text, | |
| M::ButtonRole | role | |||
| ) |
Creates a button with the given text and adds it to the button box placing it according to given role. It should be used in case it is necessary to place nonstandard buttons before standard ones.
Positive roles like AcceptRole, ActionRole, YesRole will be placed always before buttons with negative role: CancelRole, RejectRole.
Secondary order depends on order of addButton() calls in code.
- Parameters:
-
text - dialog caption role - role of the button
- See also:
- addButton(MButtonModel *button), addButton(M::StandardButton button), M::ButtonRole, removeButton()
Definition at line 351 of file mdialog.cpp.
{
MButtonModel *buttonModel = 0;
buttonModel = new MButtonModel;
buttonModel->setRole(role);
buttonModel->setText(text);
addButton(buttonModel);
return buttonModel;
}
| MButtonModel * MDialog::addButton | ( | M::StandardButton | button | ) |
Creates a standard button specified by the button value.
The standard button has a predefined caption.
Returns a pointer to the newly created button. If button was already added, his model is returned instead and no new button is created.
- See also:
- StandardButton
Definition at line 363 of file mdialog.cpp.
{
return model()->addButton(buttonType);
}
| void MDialog::addButton | ( | MButtonModel * | button | ) |
Adds a given button to the button box.
- Parameters:
-
button Button model to be added.
Causes the reference count of button to be increased by one.
- See also:
- removeButton(MButtonModel *button)
Definition at line 335 of file mdialog.cpp.
{
model()->addButton(buttonModel);
}
| void MDialog::appear | ( | MSceneWindow::DeletionPolicy | policy = KeepWhenDone |
) | [virtual, slot] |
Shows the dialog on the currently active window and registers it in the associated MSceneManager. Uses an animation to show the window.
If systemModal property is true, it will be displayed as a separate top level MWindow regardless of whether there's an active window and the user won't be able to switch to any other application or to the home screen until the dialog is closed (the home button won't be accessible).
- Parameters:
-
policy Deletion policy, defines the ownership for this window
- See also:
- setSystemModal()
Reimplemented from MSceneWindow.
Definition at line 383 of file mdialog.cpp.
{
Q_D(MDialog);
d->appear(policy);
}
| void MDialog::appear | ( | MWindow * | window, | |
| MSceneWindow::DeletionPolicy | policy = KeepWhenDone | |||
| ) | [virtual, slot] |
Shows the dialog on the window specified by window and registers it in the associated MSceneManager. Uses animation to show the dialog.
If window is 0, it functions just like appear() (without window parameter). Otherwise it ignores the systemModal property and is displayed as application modal.
- Parameters:
-
window The window on which the dialog is going to be shown. policy Deletion policy, defines the ownership for this dialog
- See also:
- setSystemModal()
Reimplemented from MSceneWindow.
Definition at line 389 of file mdialog.cpp.
{
Q_D(MDialog);
if (window) {
MSceneWindow::appear(window, policy);
} else {
d->appear(policy);
}
}
| MButtonModel * MDialog::button | ( | M::StandardButton | which | ) |
Returns a pointer to the standard button specified by which.
Returns a null pointer if there is no given standard button in the button box.
Definition at line 373 of file mdialog.cpp.
{
return model()->button(which);
}
| QGraphicsWidget * MDialog::centralWidget | ( | ) |
Returns the central widget for the dialog.
By default dialog provides a widget (panel) on which other widgets can be placed. It's also possible to set a central widget for a dialog with setCentralWidget() method.
- Returns:
- the pointer to the central widget.
- See also:
- setCentralWidget()
Definition at line 322 of file mdialog.cpp.
{
return model()->centralWidget();
}
| MButtonModel * MDialog::clickedButton | ( | ) | const |
Returns the button that was clicked by the user, or 0 if the close button was clicked. If exec() hasn't been called yet, returns 0.
Definition at line 464 of file mdialog.cpp.
{
Q_D(const MDialog);
return d->clickedButton;
}
| MPannableWidget::PanningPolicy MDialog::contentsVerticalPanningPolicy | ( | ) | const |
Returns current vertical panning policy of dialog's contents.
- See also:
- setContentsVerticalPanningPolicy()
| void MDialog::done | ( | int | result | ) | [virtual, slot] |
Dismisses the dialog and sets its result code to result. If the dialog is shown with exec(), done() causes the local event loop to quit, and exec() to return result.
- Parameters:
-
result Result code of this dialog.
- See also:
- exec()
Definition at line 416 of file mdialog.cpp.
{
setResult(result);
emit finished(result);
if (result == MDialog::Accepted)
emit accepted();
else if (result == MDialog::Rejected)
emit rejected();
if (sceneManager())
sceneManager()->disappearSceneWindow(this);
}
| int MDialog::exec | ( | MWindow * | window = 0 |
) | [slot] |
Makes the dialog appear and returns only when the user dismisses it.
If the window is specified, the dialog appears on the specified window and will be application modal, ignoring the value of systemModal property.
If no window is specified and systemModal property is false, the dialog will appear in the currently active window. If no window is currently active, the method will fail.
If no window is specified and systemModal property is true, it will be displayed as a separate top level MWindow regardless of whether there's an active window and the user won't be able to switch to any other application or to the home screen until the dialog is dismissed (the home button won't be accessible).
When using a MDialog with standard buttons, this method returns a StandardButton value indicating the standard button that was clicked. When using MDialog with custom buttons, this function returns an opaque value; use clickedButton() to determine which button was clicked.
If the dialog was dismissed with either accept() or reject() (or the equivalent done() calls), a DialogCode result is returned instead.
- Warning:
- Usage of this method is discouraged as running a local event loop can lead to hard-to-predict code paths and therefore is likely to cause bugs. See Unpredictable exec() article for more info. Instead, summon the dialog with appear() and process its result upon the emission of its disappeared() signal.
- See also:
- StandardButton, setSystemModal()
Definition at line 430 of file mdialog.cpp.
{
Q_D(MDialog);
MSceneManager *targetSceneManager = 0;
int result;
d->clickedButton = 0;
d->policy = MSceneWindow::KeepWhenDone;
if (window) {
targetSceneManager = window->sceneManager();
} else {
if (isSystem()) {
d->prepareStandAloneAppearance(KeepWhenDone);
targetSceneManager = d->standAloneWindow->sceneManager();
} else {
window = MApplication::activeWindow();
if (window) {
targetSceneManager = window->sceneManager();
} else {
mWarning("MDialog") << "Cannot appear. No MWindow currently active.";
}
}
}
if (targetSceneManager) {
result = targetSceneManager->execDialog(this);
} else {
result = Rejected;
}
return result;
}
| void MDialog::finished | ( | int | result | ) | [signal] |
This signal is emitted when the dialog's result code has been set, either by the user or by calling done(), accept(), or reject().
Note that this signal is not emitted when hiding the dialog with hide() or setVisible(false). This includes deleting the dialog while it is visible.
- Parameters:
-
result Result code of this dialog.
- See also:
- done()
| bool MDialog::isButtonBoxVisible | ( | ) | const |
Returns true if the dialog's button box is visible, false otherwise.
- See also:
- setButtonBoxVisible()
Definition at line 481 of file mdialog.cpp.
{
return model()->buttonBoxVisible();
}
| bool MDialog::isCloseButtonVisible | ( | ) | const |
Returns true if the dialog's close button is visible, false otherwise.
- Deprecated:
- Use MDialogStyle::hasCloseButton instead. OBS: Style properties are set in CSS files and consumed by the assigned view.
- See also:
- setCloseButtonVisible()
Definition at line 491 of file mdialog.cpp.
{
mWarning("MDialog") << Q_FUNC_INFO << "is deprecated. Use styles instead";
return model()->closeButtonVisible();
}
| bool MDialog::isModal | ( | ) | const |
Tells whether the dialog is modal or not.
By default this value is set to true.
- See also:
- setModal()
Definition at line 525 of file mdialog.cpp.
{
return model()->modal();
}
| bool MDialog::isProgressIndicatorVisible | ( | ) | const |
Returns true if the dialog's progress indicator is visible, false otherwise.
- See also:
- setProgressIndicatorVisible()
Definition at line 503 of file mdialog.cpp.
{
return model()->progressIndicatorVisible();
}
| bool MDialog::isSystem | ( | ) | const |
Returns whether the dialog should be displayed as System Dialog.
If false, dialog will be application modal.
- See also:
- setSystem()
Definition at line 535 of file mdialog.cpp.
{
return model()->system();
}
| bool MDialog::isTitleBarVisible | ( | ) | const |
Returns true if the dialog's title bar is visible and false otherwise.
- Deprecated:
- Use MDialogStyle::hasTitleBar instead. OBS: Style properties are set in CSS files and consumed by the assigned view.
- See also:
- setTitleBarVisible()
Definition at line 513 of file mdialog.cpp.
{
mWarning("MDialog") << Q_FUNC_INFO << "is deprecated. Use styles instead";
return model()->titleBarVisible();
}
| QGraphicsLayout * MDialog::layout | ( | ) | [slot] |
Users of MDialog shouldn't fiddle with its layout. Be advised that if you directly manipulate the layout the dialog won't work as it's supposed to anymore.
Reimplemented from QGraphicsWidget.
Definition at line 572 of file mdialog.cpp.
{
Q_D(MDialog);
mWarning("MDialog:") << "Please don't change the layout directly.";
d->dumbMode = true;
return QGraphicsWidget::layout();
}
| void MDialog::reject | ( | ) | [virtual, slot] |
Dismisses the modal dialog and sets the result code to Rejected.
Equals to done(Rejected).
- See also:
- reject()
Definition at line 405 of file mdialog.cpp.
{
Q_D(MDialog);
QObject *sender= QObject::sender();
if (sender != 0 && sender->objectName() == "MDialogCloseButton") {
d->clickedButton = 0;
}
done(Rejected);
}
| void MDialog::rejected | ( | ) | [signal] |
This signal is emitted when the dialog has been rejected either by the user or by calling reject() or done() with the MDialog::Rejected argument.
Note that this signal is not emitted when hiding the dialog with hide() or setVisible(false). This includes deleting the dialog while it is visible.
- See also:
- reject()
| void MDialog::removeButton | ( | MButtonModel * | button | ) |
Removes button from dialog's button box.
- Parameters:
-
button Button model to be removed.
Causes the reference count of button to be decreased by one.
- See also:
- addButton(MButtonModel *button)
Definition at line 368 of file mdialog.cpp.
{
model()->removeButton(buttonModel);
}
| int MDialog::result | ( | ) | const |
Returns the modal dialog's result code, Accepted or Rejected.
- See also:
- DialogCode
| void MDialog::setButtonBoxVisible | ( | bool | visible | ) |
Sets the visibility of the dialog's button box.
It is possible to hide the button box because it doesn't necessarily have to be used for making a selection/decision/response. Custom widgets that can be placed as a dialog's central widget may contain input widget(s) sufficient for the dialog needs. The button box is visible by default.
- See also:
- setCentralWidget(), isButtonBoxVisible()
Definition at line 486 of file mdialog.cpp.
{
model()->setButtonBoxVisible(visible);
}
| void MDialog::setCentralWidget | ( | QGraphicsWidget * | centralWidget | ) |
Sets the given widget to be the page's central widget.
It's also possible to use the default widget, as a parent for all widgets using the centralWidget() function.
NOTE: MDialog takes ownership of the widget pointer and deletes it when needed.
- Parameters:
-
centralWidget the central widget.
Definition at line 327 of file mdialog.cpp.
{
if (model()->centralWidget())
delete model()->centralWidget();
model()->setCentralWidget(centralWidget);
}
| void MDialog::setCloseButtonVisible | ( | bool | visible | ) |
Sets the visibility of the dialog's close button.
- Deprecated:
- Use MDialogStyle::hasCloseButton instead. OBS: Style properties are set in CSS files and consumed by the assigned view.
- See also:
- isCloseButtonVisible(), setTitleBarVisible()
Definition at line 497 of file mdialog.cpp.
{
mWarning("MDialog") << Q_FUNC_INFO << "is deprecated. Use styles instead";
model()->setCloseButtonVisible(visible);
}
| void MDialog::setContentsVerticalPanningPolicy | ( | MPannableWidget::PanningPolicy | policy | ) |
Sets vertical panning policy of dialog's contents.
- Parameters:
-
policy Vertical panning policy
- See also:
- contentsVerticalPanningPolicy()
Definition at line 612 of file mdialog.cpp.
{
model()->setContentsVerticalPanningPolicy(policy);
}
| void MDialog::setLayout | ( | QGraphicsLayout * | layout | ) | [slot] |
Users of MDialog shouldn't fiddle with its layout. Be advised that if you directly manipulate the layout the dialog won't work as it's supposed to anymore.
Reimplemented from QGraphicsWidget.
Definition at line 564 of file mdialog.cpp.
{
Q_D(MDialog);
mWarning("MDialog:") << "Please don't change the layout directly.";
d->dumbMode = true;
QGraphicsWidget::setLayout(layout);
}
| void MDialog::setModal | ( | bool | enabled | ) |
Defines whether the dialog should be modal.
- Note:
- Changing this property will affect only subsequent calls to appear() and exec(). I.e., if called between an appear() and a disappear() it won't affect the current appearance.
- See also:
- isModal(), setSystem()
Definition at line 530 of file mdialog.cpp.
{
model()->setModal(enabled);
}
| void MDialog::setProgressIndicatorVisible | ( | bool | visible | ) |
Sets the visibility of the dialog's progress indicator.
The progress indicator is used to indicate that some process is ongoing. It sits on the title bar, next to the title text, and is hidden by default.
Since the progress indicator is part of the title bar, setting its visibility to true when the title bar is invisible has no effect.
Definition at line 508 of file mdialog.cpp.
{
model()->setProgressIndicatorVisible(visible);
}
| void MDialog::setResult | ( | int | result | ) |
Sets the modal dialog's result code to result.
- Parameters:
-
result Result code of this dialog.
Definition at line 476 of file mdialog.cpp.
| void MDialog::setSystem | ( | bool | enabled | ) |
Defines whether the dialog should be displayed as System Dialog.
- Note:
- Changing this property will affect only subsequent calls to appear() and exec(). I.e., if called between an appear() and a disappear() it won't affect the current appearance.
- See also:
- isSystem(), setModal()
Definition at line 540 of file mdialog.cpp.
{
model()->setSystem(enabled);
}
| void MDialog::setTitle | ( | const QString & | title | ) |
Sets the dialog's title to the given title.
The MDialog class provides a header that contains the close button and the label widget for displaying the title of the dialog window. By default the title is an empty string.
- See also:
- title()
Definition at line 317 of file mdialog.cpp.
{
model()->setTitle(title);
}
| void MDialog::setTitleBarVisible | ( | bool | visible | ) |
Sets the visibility of the dialog's title bar.
- Deprecated:
- Use MDialogStyle::hasTitleBar instead. OBS: Style properties are set in CSS files and consumed by the assigned view.
- See also:
- isTitleBarVisible(), setCloseButtonVisible(), setTitle()
Definition at line 519 of file mdialog.cpp.
{
mWarning("MDialog") << Q_FUNC_INFO << "is deprecated. Use styles instead";
model()->setTitleBarVisible(visible);
}
| M::StandardButton MDialog::standardButton | ( | MButtonModel * | button | ) | const |
Returns the standard button enum value corresponding to the given button, or NoButton if the given button isn't a standard button.
- See also:
- MDialog::button(M::StandardButton)
Definition at line 378 of file mdialog.cpp.
{
return model()->standardButton(buttonModel);
}
| QString MDialog::title | ( | ) | const |
Returns the title of the dialog.
- See also:
- setTitle()
Property Documentation
bool MDialog::buttonBoxVisible [read, write] |
Definition at line 174 of file corelib/widgets/mdialog.h.
MDialog::closeButtonVisible [read, write] |
Whether the close button should be visible.
- Deprecated:
- Use MDialogStyle::hasCloseButton instead. OBS: Style properties are set in CSS files and consumed by the assigned view.
The dialog's optional close button is provided as a convenient way of rejecting the dialog and discarding all changes. It's visible by default.
Since the close button is part of the title bar, setting its visibility to true when the title bar is invisible has no effect.
Definition at line 188 of file corelib/widgets/mdialog.h.
MDialog::contentsVerticalPanningPolicy [read, write] |
Panning policy for the dialog's contents.
The contents of a dialog are normally put inside a pannable viewport since they can exceed the maximum height of a dialog.
This property defines the vertical panning policy to be used when a pannable viewport is holding the dialog's contents.
By default its value is MPannableWidget::PanningAsNeeded.
Definition at line 227 of file corelib/widgets/mdialog.h.
bool MDialog::modal [read, write] |
Definition at line 209 of file corelib/widgets/mdialog.h.
bool MDialog::progressIndicatorVisible [read, write] |
Definition at line 213 of file corelib/widgets/mdialog.h.
int MDialog::result [read, write] |
Definition at line 172 of file corelib/widgets/mdialog.h.
bool MDialog::system [read, write] |
Definition at line 208 of file corelib/widgets/mdialog.h.
QString MDialog::title [read, write] |
Definition at line 207 of file corelib/widgets/mdialog.h.
MDialog::titleBarVisible [read, write] |
Whether the title bar should be visible.
- Deprecated:
- Use MDialogStyle::hasTitleBar instead. OBS: Style properties are set in CSS files and consumed by the assigned view.
The title bar sits on top of the dialog and contains a title text, an optional close button and an optional progress indicator.
Since both close button and progress indicator are part of the title bar, setting their visibilities to true when the title bar itself is invisible has no effect.
The title bar is visible by default.
Definition at line 205 of file corelib/widgets/mdialog.h.