Home · All Classes · Main Classes · Deprecated |
The MDialog class is the base class of dialog windows. More...
Inherits MSceneWindow.
Inherited by MMessageBox, and MPopupList.
The MDialog class is the base class of dialog windows.
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:
MDialog provides a return value, based on the user's choice. It also knows which button from the button box was pressed (if any).
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.) |
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.
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.
enum MDialog::DialogCode |
MDialog::MDialog | ( | ) |
Constructs a dialog.
MDialog::MDialog | ( | const QString & | title, | |
M::StandardButtons | buttons | |||
) |
Constructs a dialog with a given title and a set of standard buttons specified by buttons.
MDialog::~MDialog | ( | ) | [virtual] |
Destructor for dialog class.
void MDialog::accept | ( | ) | [virtual, slot] |
Dismisses the modal dialog and sets the result code to Accepted.
Equals to done(Accepted).
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.
void MDialog::addButton | ( | MButtonModel * | button | ) |
Adds a given button to the button box.
button | Button model to be added. |
Causes the reference count of button to be increased by one.
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.
text | - dialog caption | |
role | - role of the button |
MButtonModel * MDialog::addButton | ( | const QString & | text | ) |
Creates a button with the given text and adds it to the button box.
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.
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.
window | The window on which the dialog is going to be shown. | |
policy | Deletion policy, defines the ownership for this dialog |
Reimplemented from MSceneWindow.
void MDialog::appear | ( | MSceneWindow::DeletionPolicy | policy = KeepWhenDone |
) | [virtual, slot] |
Shows the dialog on the currently active window or seperately on its own.
If isSystem() is true, it will be displayed as a separate top level MWindow regardless of whether there's an active window and if isModal() is true as well the user also won't be able to switch to any other application or to the home screen until that dialog is closed (the home button won't be accessible).
policy | Deletion policy, defines the ownership for this window |
Reimplemented from MSceneWindow.
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.
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.
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.
MPannableWidget::PanningPolicy MDialog::contentsVerticalPanningPolicy | ( | ) | const |
Returns current vertical panning policy of dialog's contents.
void MDialog::done | ( | int | result | ) | [virtual, slot] |
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).
Ownership is transfered to the MScene visualized by the MWindow that is used.
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.
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.
result | Result code of this dialog. |
bool MDialog::isButtonBoxVisible | ( | ) | const |
Returns true if the dialog's button box is visible, false otherwise.
bool MDialog::isCloseButtonVisible | ( | ) | const |
Returns true if the dialog's close button is visible, false otherwise.
bool MDialog::isModal | ( | ) | const |
bool MDialog::isProgressIndicatorVisible | ( | ) | const |
Returns true if the dialog's progress indicator is visible, false otherwise.
bool MDialog::isSystem | ( | ) | const |
Returns whether the dialog should be displayed as System Dialog.
If false, dialog will be application modal.
bool MDialog::isTitleBarVisible | ( | ) | const |
Returns true if the dialog's title bar is visible and false otherwise.
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.
void MDialog::reject | ( | ) | [virtual, slot] |
Dismisses the modal dialog and sets the result code to Rejected.
Equals to 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.
void MDialog::removeButton | ( | MButtonModel * | button | ) |
Removes button from dialog's button box.
button | Button model to be removed. |
Causes the reference count of button to be decreased by one.
int MDialog::result | ( | ) | const |
Returns the modal dialog's result code, Accepted or Rejected.
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.
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.
centralWidget | the central widget. |
void MDialog::setCloseButtonVisible | ( | bool | visible | ) |
Sets the visibility of the dialog's close button.
void MDialog::setContentsVerticalPanningPolicy | ( | MPannableWidget::PanningPolicy | policy | ) |
Sets vertical panning policy of dialog's contents.
policy | Vertical panning 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.
void MDialog::setModal | ( | bool | enabled | ) |
Defines whether the dialog should be modal.
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.
void MDialog::setResult | ( | int | result | ) |
Sets the modal dialog's result code to result.
result | Result code of this dialog. |
void MDialog::setSystem | ( | bool | enabled | ) |
Defines whether the dialog should be displayed as System Dialog.
void MDialog::setTitle | ( | const QString & | title | ) |
void MDialog::setTitleBarIconId | ( | const QString & | iconId | ) |
Sets the dialog's title bar icon.
iconId | Logical id of icon to be displayed in title bar. |
void MDialog::setTitleBarVisible | ( | bool | visible | ) |
Sets the visibility of the dialog's title bar.
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.
QString MDialog::title | ( | ) | const |
Returns the title of the dialog.
QString MDialog::titleBarIconId | ( | ) | const |
Returns the dialog's title bar icon id.
bool MDialog::buttonBoxVisible [read, write] |
MDialog::closeButtonVisible [read, write] |
Whether the close button should be visible.
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.
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.
bool MDialog::modal [read, write] |
bool MDialog::progressIndicatorVisible [read, write] |
int MDialog::result [read, write] |
bool MDialog::system [read, write] |
QString MDialog::title [read, write] |
MDialog::titleBarIconId [read, write] |
Id of Icon to be displayed in dialog's title bar.
Icon with supplied Id appears leftmost in dialog's title bar. If icon Id is set and dialog's progress indicator is shown, then the progress indicator replaces the icon.
By default its value is empty QString.
MDialog::titleBarVisible [read, write] |
Whether the title bar should be visible.
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.
Copyright © 2010 Nokia Corporation | MeeGo Touch |