Home · All Classes · Main Classes · Deprecated
Public Types | Public Slots | Signals | Public Member Functions | Properties

MDialog Class Reference

The MDialog class is the base class of dialog windows. More...

Inherits MSceneWindow.

Inherited by MMessageBox, and MPopupList.

List of all members.

Public Types

enum  DialogCode { Accepted = QMessageBox::Ok, Rejected = QMessageBox::Cancel }

Public Slots

virtual void appear (MSceneWindow::DeletionPolicy policy=KeepWhenDone)
virtual void appear (MWindow *window, MSceneWindow::DeletionPolicy policy=KeepWhenDone)
virtual void accept ()
virtual void done (int result)
virtual void reject ()
int exec (MWindow *window=0)
void setLayout (QGraphicsLayout *layout)
QGraphicsLayoutlayout ()

Signals

void accepted ()
void finished (int result)
void rejected ()

Public Member Functions

 MDialog ()
 MDialog (const QString &title, M::StandardButtons buttons)
virtual ~MDialog ()
MButtonModelclickedButton () const
int result () const
void setResult (int result)
bool isButtonBoxVisible () const
void setButtonBoxVisible (bool visible)
bool isCloseButtonVisible () const
void setCloseButtonVisible (bool visible)
bool isProgressIndicatorVisible () const
void setProgressIndicatorVisible (bool visible)
bool isTitleBarVisible () const
void setTitleBarVisible (bool visible)
bool isModal () const
void setModal (bool enabled)
bool isSystem () const
void setSystem (bool enabled)
void addButton (MButtonModel *button)
MButtonModeladdButton (const QString &text)
MButtonModeladdButton (const QString &text, M::ButtonRole role)
MButtonModeladdButton (M::StandardButton button)
void removeButton (MButtonModel *button)
MButtonModelbutton (M::StandardButton which)
M::StandardButton standardButton (MButtonModel *button) const
QString title () const
void setTitle (const QString &title)
QGraphicsWidgetcentralWidget ()
void setCentralWidget (QGraphicsWidget *centralWidget)
MPannableWidget::PanningPolicy contentsVerticalPanningPolicy () const
void setContentsVerticalPanningPolicy (MPannableWidget::PanningPolicy policy)
QString titleBarIconId () const
void setTitleBarIconId (const QString &iconId)

Properties

int result
bool buttonBoxVisible
bool closeButtonVisible
bool titleBarVisible
QString title
bool system
bool modal
bool progressIndicatorVisible
QString titleBarIconId
MPannableWidget::PanningPolicy contentsVerticalPanningPolicy

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:

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

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

Member Enumeration Documentation

This enum provides values that can be returned by a call to exec() method.

When a dialog is closed with either accept() or reject(), the equivalent enum values are returned by exec().

See also:
exec()
Enumerator:
Accepted 

The dialog was accepted.

Rejected 

The dialog was rejected.


Constructor & Destructor Documentation

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.


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()
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()
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)
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()
MButtonModel * MDialog::addButton ( const QString text  ) 

Creates a button with the given text and adds it to the button box.

See also:
removeButton()
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
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.

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).

Attention:
If your application has multiple MWindows and isSystem() is false, usage of this method is strongly discouraged since it can make a dialog appear in an MWindow different from the intended one. That's due to the fact that it depends on which MWindow happens to be active when this method is called. In such scenarios use either appear(MWindow*) or appear(QGraphicsScene*).
Parameters:
policy Deletion policy, defines the ownership for this window
See also:
isSystem(), isModal()

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.

Returns:
the pointer to the central widget.
See also:
setCentralWidget()
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.

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()
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.

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.
Note:
If the window gets deleted while exec() is running, when this method returns MDialog might be already null. Therefore if your code wants to delete the dialog after exec() returns it's advisable to hold it in a QWeakPointer or a QPointer so that you can check whether the dialog pointer is still valid after the exec(). Take heed of the warning above.
See also:
StandardButton, setSystemModal()
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()
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()
bool MDialog::isModal (  )  const

Tells whether the dialog is modal or not.

By default this value is set to true.

See also:
setModal()
bool MDialog::isProgressIndicatorVisible (  )  const

Returns true if the dialog's progress indicator is visible, false otherwise.

See also:
setProgressIndicatorVisible()
bool MDialog::isSystem (  )  const

Returns whether the dialog should be displayed as System Dialog.

If false, dialog will be application modal.

See also:
setSystem()
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()
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).

See also:
reject()
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)
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()
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.
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()
void MDialog::setContentsVerticalPanningPolicy ( MPannableWidget::PanningPolicy  policy  ) 

Sets vertical panning policy of dialog's contents.

Parameters:
policy Vertical panning policy
See also:
contentsVerticalPanningPolicy()
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.

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()
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.

See also:
isProgressIndicatorVisible(), setTitleBarVisible()
void MDialog::setResult ( int  result  ) 

Sets the modal dialog's result code to result.

Parameters:
result Result code of this dialog.
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()
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()
void MDialog::setTitleBarIconId ( const QString iconId  ) 

Sets the dialog's title bar icon.

Parameters:
iconId Logical id of icon to be displayed in title bar.
See also:
titleBarIconId()
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()
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)
QString MDialog::title (  )  const

Returns the title of the dialog.

See also:
setTitle()
QString MDialog::titleBarIconId (  )  const

Returns the dialog's title bar icon id.

Returns:
Id of icon being displayed in dialog's title bar.
See also:
setTitleBarIconId()

Property Documentation

bool MDialog::buttonBoxVisible [read, write]
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.

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.

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.


Copyright © 2010 Nokia Corporation
MeeGo Touch