MWindow is the base class for all MeeGo Touch UI windows. More...
Detailed Description
MWindow is the base class for all MeeGo Touch UI windows.
An MWindow is completely empty by default. For developing an application conforming to the MeeGo Touch UI style, use MApplicationWindow instead.
MWindow is a QGraphicsView widget that visualizes the contents of the application scene. The key differences compared to the standard QGraphicsView is:
- The coordinate system of a MWindow starts with (0,0) in the top-left corner and does typically not change during an application's execution.
- MWindows have an OpenGL viewport by default, which causes QPainter commands for the window to use one of Qt's OpenGL backends.
- Fullscreen updates are enabled by default for the window, as OpenGL partial updates are not supported in Qt.
- New concept of window orientation. MeeGo Touch applications change orientation through a scene graph transformation. The window widget coordinates stay the same after an orientation change while the root element of the scene graph can have an arbitary transformation angle. See Screen Rotation.
- New concept of scene management. MeeGo Touch UI supports in-scene variants of traditional UI components such as dialogs, popups and menus. MSceneManager acts like an in-application window manager to orchestrate the various components.
- New concept of display visibility. MeeGo Touch UI applications typically operate in a fully composited environment, meaning that a shown window still doesn't guarantee that it is visible. Display visibility tells whether the user is able to see the window.
Example: Showing scene windows on MWindow.
MApplication app; MWindow window; MSceneWindow *sceneWindow = new MMessageBox("Hello World!"); window.show(); sceneWindow->appear(&window); app.exec();
Definition at line 78 of file corelib/widgets/mwindow.h.
Constructor & Destructor Documentation
| MWindow::MWindow | ( | QWidget * | parent = 0 |
) | [explicit] |
Creates a MWindow without a scene manager.
parent is passed to QGraphicsView's constructor.
A scene manager can be assigned later by calling setSceneManager(), however a default scene manager will be automatically created as needed unless explicitly set whenever any scene management is required (adding a managed class like MDialog to the application).
- See also:
- setSceneManager(), sceneManager()
Definition at line 640 of file mwindow.cpp.
: QGraphicsView(parent), d_ptr(new MWindowPrivate) { Q_D(MWindow); d->q_ptr = this; d->init(); MComponentData::registerWindow(this); }
| MWindow::MWindow | ( | MSceneManager * | sceneManager, | |
| QWidget * | parent = 0 | |||
| ) | [explicit] |
Creates a MWindow with a provided scenemanager.
parent is passed to QGraphicsView's constructor.
MWindow will take ownership of the given scene manager.
Definition at line 630 of file mwindow.cpp.
: QGraphicsView(parent), d_ptr(new MWindowPrivate) { Q_D(MWindow); d->q_ptr = this; d->init(); MComponentData::registerWindow(this); setSceneManager(sceneManager); }
| MWindow::~MWindow | ( | ) | [virtual] |
Destructs the MWindow object.
If a scene manager is associated with the window, it is destroyed as well.
Definition at line 650 of file mwindow.cpp.
{
#ifdef Q_WS_X11
MOrientationTracker::instance()->d_func()->stopFollowingCurrentAppWindow(this);
#endif
MComponentData::unregisterWindow(this);
delete d_ptr;
}
Member Function Documentation
| bool MWindow::closeOnLazyShutdown | ( | ) | const |
Returns true if window closes on lazy shutdown.
Definition at line 1322 of file mwindow.cpp.
{
Q_D(const MWindow);
return d->closeOnLazyShutdown;
}
| void MWindow::displayEntered | ( | ) | [signal] |
This signal is emitted when the window is shown or is not obscured anymore by another window.
Note: this is different from Qt's visibilityChanged(), which is emitted due to show() and hide().
| void MWindow::displayExited | ( | ) | [signal] |
A signal that is emitted when the window gets obscured by another window.
Note: this is different from Qt's visibilityChanged(), which is emitted due to show() and hide().
| void MWindow::enterDisplayEvent | ( | ) | [protected, virtual] |
A handler that is called when the window is shown or is not obscured anymore by another window.
Note: this is different from Qt's visibilityChanged(), which is emitted due to show() and hide().
Definition at line 1019 of file mwindow.cpp.
{}
| void MWindow::exitDisplayEvent | ( | ) | [protected, virtual] |
A handler that is called when the window gets obscured by another window.
Note: this is different from Qt's visibilityChanged(), which is emitted due to show() and hide().
Definition at line 1022 of file mwindow.cpp.
{}
| qreal MWindow::globalAlpha | ( | ) |
Returns the global alpha of the hardware graphics overlay for use by this window.
| bool MWindow::isInSwitcher | ( | ) | const |
Returns true if the window is currently minimized to the switcher. It doesn't matter whether the window is visible or not in the switcher.
Definition at line 382 of file mwindow.cpp.
{
Q_D(const MWindow);
return d->isInSwitcher;
}
| bool MWindow::isOnDisplay | ( | ) | const |
Returns the current visibility state of the window.
Definition at line 1012 of file mwindow.cpp.
{
Q_D(const MWindow);
return d->onDisplay;
}
| bool MWindow::isOrientationAngleLocked | ( | ) | const |
Returns true if the window orientation angle is not allowed to change when device orientation changes.
The default value is false.
- See also:
- setOrientationAngleLocked()
Definition at line 815 of file mwindow.cpp.
{
Q_D(const MWindow);
return d->orientationAngleLocked;
}
| bool MWindow::isOrientationLocked | ( | ) | const |
Returns true if the window orientation is not allowed to change when device orientation changes.
The default value is false.
- See also:
- setOrientationLocked()
Definition at line 835 of file mwindow.cpp.
{
Q_D(const MWindow);
return d->orientationLocked;
}
| void MWindow::lockOrientation | ( | ) | [slot] |
Locks window's orientation changes. Equal to calling setOrientationLocked(true).
- See also:
- setOrientationLocked(), unlockOrientation()
Definition at line 865 of file mwindow.cpp.
{
setOrientationLocked(true);
}
| void MWindow::lockOrientationAngle | ( | ) | [slot] |
Locks window's orientation angle changes. Equal to calling setOrientationAngleLocked(true).
Definition at line 855 of file mwindow.cpp.
{
setOrientationAngleLocked(true);
}
| void MWindow::onDisplayChangeEvent | ( | MOnDisplayChangeEvent * | event | ) | [protected, virtual] |
This event handler allows a window to notify subscribers about changes in its presence on the display. enterDisplayEvent() and exitDisplayEvent() convenience handlers are called by the default implementation. MOnDisplayChangeEvent is sent e.g. if the window gets obscured by another window.
Definition at line 1025 of file mwindow.cpp.
{
Q_D(MWindow);
switch (event->state()) {
case MOnDisplayChangeEvent::FullyOnDisplay:
d->displayExitedTimer.stop();
if (!d->onDisplay || !d->onDisplaySet) {
d->doEnterDisplayEvent();
if (scene()) {
d->propagateMOnDisplayChangeEventToScene(event);
}
}
break;
case MOnDisplayChangeEvent::FullyOffDisplay:
if (d->onDisplay || !d->onDisplaySet) {
// displayEntered signal is emitted immediately above, but
// emitting displayExited is delayed by default. Emitting
// will be canceled if FullyOnDisplay event is received
// during the delay. displayExitedTimer timeout will call
// d->doExitDisplayEvent() which will take care of
// propagating delayedMOnDisplayChangeEvent to the scene.
d->sendExitDisplayEvent(true);
}
break;
default:
event->ignore();
break;
}
}
| M::Orientation MWindow::orientation | ( | ) | const |
Returns the current orientation of the window's scene.
Definition at line 923 of file mwindow.cpp.
{
Q_D(const MWindow);
if (d->sceneManager) {
return d->sceneManager->orientation();
} else {
return d->orientation(d->angle);
}
}
| M::OrientationAngle MWindow::orientationAngle | ( | ) | const |
Returns the current orientation angle of the window's scene.
Definition at line 934 of file mwindow.cpp.
{
Q_D(const MWindow);
if (d->sceneManager) {
return d->sceneManager->orientationAngle();
} else {
return d->angle;
}
}
| void MWindow::orientationAngleChanged | ( | M::OrientationAngle | ) | [signal] |
Emitted after the scene geometry has changed during rotation.
This is for widgets that need to react when the orientation is about to change, and is emitted after the scene geometry has changed and the rotation animation is about to start.
- Note:
- This signal is emitted at start of the rotation animation.
- See also:
- orientationChanged()
| void MWindow::orientationChanged | ( | M::Orientation | ) | [signal] |
Emitted after scene geometry has changed for a rotation.
This is for widgets that need to react when the orientation is about to change, and is emitted after the scene geometry has changed and the rotation animation is about to start.
- Note:
- This signal is emitted at start of the rotation animation.
- See also:
- orientationAngleChanged()
| void MWindow::orientationChangeFinished | ( | M::Orientation | ) | [signal] |
This signal is emitted when the rotation animation (if any) has finished. It's emitted in tandem with MSceneManager::orientationChangeFinished().
If window doesn't have the scene manager, this signal is emitted together with orientationChanged().
- Note:
- This signal is emitted with every orientation angle change.
- See also:
- orientationChanged()
| MScene * MWindow::scene | ( | ) |
Returns the window's MScene.
Reimplemented from QGraphicsView.
Definition at line 810 of file mwindow.cpp.
{
return qobject_cast<MScene *>(QGraphicsView::scene());
}
| MSceneManager * MWindow::sceneManager | ( | ) |
Returns the scene manager of the window. A scene manager will be automatically created if none was previously set.
The scene manager is responsible for positioning, animating and generally managing MSceneWindows such as MDialog and MApplicationPage inside the window's scene.
Definition at line 903 of file mwindow.cpp.
{
Q_D(MWindow);
// A scene manager is needed. Let's create one on the fly
// if we don't have one already.
if (!d->sceneManager) {
setSceneManager(new MSceneManager);
}
return d->sceneManager;
}
| MSceneManager * MWindow::sceneManager | ( | ) | const |
Returns the scene manager of the window, or 0 if not set.
The scene manager is responsible for positioning, animating and generally managing MSceneWindows such as MDialog and MApplicationPage inside the window's scene.
Definition at line 916 of file mwindow.cpp.
{
Q_D(const MWindow);
return d->sceneManager;
}
| void MWindow::setCloseOnLazyShutdown | ( | bool | enable | ) |
Allows to force close instead of hide during lazy shutdown.
Definition at line 1315 of file mwindow.cpp.
{
Q_D(MWindow);
d->closeOnLazyShutdown = enable;
}
| void MWindow::setGlobalAlpha | ( | qreal | level | ) |
Sets the global alpha of the hardware graphics overlay for use by this window.
Global alpha is used when you want to blend the contents of this window, which is rendering to the graphics overlay with the video overlay. This can be used to draw translucent controls on top of video, for example.
By default, each MWindow does not enable the global alpha. When this window is destroyed or hidden, the system will revert the global alpha back to its previous state.
Platform notes:
- This is a Harmattan-specific implementation and will require interaction with the Harmattan compositing window manager (MCompositor)
- Parameters:
-
level The valid range of global alpha can be 1.0 (completely opaque) to 0.0 (completely transparent).
Definition at line 770 of file mwindow.cpp.
{
#ifdef Q_WS_X11
Q_D(MWindow);
d->setX11Property("_MEEGOTOUCH_GLOBAL_ALPHA", level);
#else
Q_UNUSED(level);
#endif
}
| void MWindow::setLandscapeOrientation | ( | ) | [slot] |
Sets the orientation of the window to landscape.
This is a convenience function that sets the current orientation angle to 0 if it is not already in a landscape orientation (either 0 or 180 degrees angle).
If the window is hidden or it hasn't been shown yet, the orientation change is immediate (i.e. without an rotation animation), otherwise there may be an animated transition.
Definition at line 981 of file mwindow.cpp.
{
if (orientation() != M::Landscape)
setOrientationAngle(M::Angle0);
}
| void MWindow::setOrientationAngle | ( | M::OrientationAngle | angle | ) | [slot] |
Sets the orientation angle of the window.
If the window is hidden or it hasn't been shown yet, the orientation angle change is immediate (i.e. without an rotation animation), otherwise there may be an animated transition.
Definition at line 945 of file mwindow.cpp.
{
Q_D(MWindow);
//orientation was forced by command line option
if (MComponentData::isOrientationForced())
return;
M::OrientationAngle targetAngle;
if (d->sceneManager && d->sceneManager->d_ptr->pendingRotation)
targetAngle = d->sceneManager->d_ptr->pendingRotation->angle;
else
targetAngle = orientationAngle();
if (targetAngle != angle) {
d->oldOrientation = orientation();
d->angle = angle;
if (d->sceneManager) {
MSceneManager::TransitionMode mode = isVisible() ?
MSceneManager::AnimatedTransition :
MSceneManager::ImmediateTransition;
d->sceneManager->setOrientationAngle(angle, mode);
} else {
// first notify widgets, then emit the signal (in case someone
// would like to connect to the signal and get correct size hints for widgets)
d->notifyWidgetsAboutOrientationChange();
emit orientationAngleChanged(angle);
}
#ifdef Q_WS_X11
d->setX11OrientationAngleProperty(angle);
#endif
}
}
| void MWindow::setOrientationAngleLocked | ( | bool | locked | ) |
Controls whether the window orientation angle follows the device orientation.
If you require your window to be displayed only in a certain orientation angle, set the desired angle using setOrientationAngle() and set this property to true.
Note: Locking the orientation is discouraged by the MeeGo Touch UI application style guidelines.
Example of locking the window orientation angle:
MApplication app; MWindow window; // Forces an orientation angle. window.setOrientationAngle(M::Angle270); window.setOrientationAngleLocked(true); window.show(); return app.exec();
Definition at line 822 of file mwindow.cpp.
{
Q_D(MWindow);
if (d->orientationAngleLocked != locked) {
d->orientationAngleLocked = locked;
// update from the orientation tracker if we're unlocking orientation changes
if (!locked)
setOrientationAngle(MOrientationTracker::instance()->orientationAngle());
}
}
| void MWindow::setOrientationLocked | ( | bool | locked | ) |
Controls whether the window orientation follows the device orientation.
If you require your window to be displayed only in a certain orientation, set the desired angle using setOrientationAngle() and set this property to true.
Note: Locking the orientation is discouraged by the MeeGo TouchUI application style guidelines.
- Note:
- Setting this property to true locks orientation changes, but allows automatic adjustments of the angle for the given orientation. This means that a window locked in portrait mode will adjust between M::Angle90 and M::Angle270 to keep "top edge" always on top and avoid upside-down situations. In order to lock to a single specific orientation angle, use setOrientationAngleLocked().
Example of locking the window orientation:
MApplication app; MWindow window; // Forces the orientation to be portrait window.setPortraitOrientation(); window.setOrientationLocked(true); window.show(); return app.exec();
Definition at line 842 of file mwindow.cpp.
{
Q_D(MWindow);
if (d->orientationLocked != locked) {
d->orientationLocked = locked;
// update from the orientation tracker if we're unlocking orientation changes
if (!locked)
setOrientationAngle(MOrientationTracker::instance()->orientationAngle());
}
}
| void MWindow::setPortraitOrientation | ( | ) | [slot] |
Sets the orientation of the window to portrait.
This is a convenience function that sets the current orientation angle to 270 if it is not already in a portrait orientation (either 90 or 270 degrees angle).
If the window is hidden or it hasn't been shown yet, the orientation change is immediate (i.e. without an rotation animation), otherwise there may be an animated transition.
Definition at line 987 of file mwindow.cpp.
{
if (orientation() != M::Portrait)
setOrientationAngle(M::Angle270);
}
| void MWindow::setSceneManager | ( | MSceneManager * | sceneManager | ) |
Assigns a scene manager to the window.
The existing scene manager (if any) will be deleted and replaced by sceneManager. The new sceneManager can be 0.
MWindow will take ownership of the given scene manager.
Definition at line 875 of file mwindow.cpp.
{
Q_D(MWindow);
if (d->sceneManager == sceneManager) {
return;
}
if (d->sceneManager) {
delete d->sceneManager;
}
d->sceneManager = sceneManager;
if (sceneManager) {
connect(sceneManager, SIGNAL(orientationAngleChanged(M::OrientationAngle)),
SIGNAL(orientationAngleChanged(M::OrientationAngle)));
connect(sceneManager, SIGNAL(orientationChanged(M::Orientation)),
SIGNAL(orientationChanged(M::Orientation)));
connect(sceneManager, SIGNAL(orientationChangeFinished(M::Orientation)),
SIGNAL(orientationChangeFinished(M::Orientation)));
sceneManager->setParent(this);
setScene(sceneManager->scene());
setSceneRect(QRectF(QPointF(), visibleSceneSize(M::Landscape)));
centerOn(sceneRect().center());
}
}
| void MWindow::setTranslucentBackground | ( | bool | enabled | ) |
Sets the translucency of the window.
Background translucency is disabled by default.
Having a translucent background means that any window behind it will show through the parts not otherwise filled by the application, for example by widgets.
Calling this method is costly when invoking it after showing the window as it involves recreating the window's viewport. This method usually should be called only once, before showing the window.
Platform notes:
- Device: This feature requires that a compositing manager is running and an EGL surface with alpha channels
- Desktop/Scratchbox: MesaGL does not support ARGB GLX visuals. As a workaround, translucency also works in software mode.
Definition at line 659 of file mwindow.cpp.
{
Q_D(MWindow);
if (enable) {
setAttribute(Qt::WA_TranslucentBackground);
#ifdef Q_WS_X11
// This is workaround for NB#170883
// Setting Qt::WA_TranslucentBackground property for window
// changes mask for yet unknown reason, only on hardware,
// not in scratchbox and supposingly its a candidate for
// filing bug against Qt when confirmed
d->appendVisibilityChangeMask();
#endif
}
// when the gl widget is not initialized yet we will also not initialize it
if (MApplication::softwareRendering() || MApplication::isPrestarted() ||
(MGraphicsSystemHelper::isRunningNativeGraphicssystem() && !dynamic_cast<QGLWidget*>(viewport()))) {
d->initSoftwareViewport();
} else {
d->initGLViewport();
}
if (MApplication::softwareRendering())
viewport()->setAutoFillBackground(!enable);
}
| void MWindow::setVideoGlobalAlpha | ( | qreal | level | ) |
Sets the alpha of the hardware video overlay for use by this window.
Video alpha is the is used to control the dimming of the video overlay where hardware accelerated video is rendering.
By default, each MWindow does not enable the video alpha. When this window is destroyed or hidden, the system will revert the video alpha back to its previous state.
Platform notes:
- This is a Harmattan-specific implementation and will require interaction with the Harmattan compositing window manager (MCompositor)
- Parameters:
-
level The valid range of video alpha can be 1.0 (completely opaque) to 0.0 (completely transparent)
Definition at line 790 of file mwindow.cpp.
{
#ifdef Q_WS_X11
Q_D(MWindow);
d->setX11Property("_MEEGOTOUCH_VIDEO_ALPHA", level);
#else
Q_UNUSED(level);
#endif
}
| void MWindow::switcherEntered | ( | ) | [signal] |
This signal is emitted when the window has entered the task switcer.
| void MWindow::switcherExited | ( | ) | [signal] |
This signal is emitted when the window has exited the task switcer.
| void MWindow::unlockOrientation | ( | ) | [slot] |
Unlocks window's orientation changes. Equal to calling setOrientationLocked(false).
- See also:
- setOrientationLocked(), lockOrientation()
Definition at line 870 of file mwindow.cpp.
{
setOrientationLocked(false);
}
| void MWindow::unlockOrientationAngle | ( | ) | [slot] |
Unlocks window's orientation angle changes. Equal to calling setOrientationAngleLocked(false).
Definition at line 860 of file mwindow.cpp.
{
setOrientationAngleLocked(false);
}
| qreal MWindow::videoGlobalAlpha | ( | ) |
Returns the alpha of the hardware video overlay for use by this window.
| QSize MWindow::visibleSceneSize | ( | ) | const |
Returns the visible size of the window (being also the size of its scene).
Definition at line 1007 of file mwindow.cpp.
{
return visibleSceneSize(orientation());
}
| QSize MWindow::visibleSceneSize | ( | M::Orientation | orientation | ) | const |
Returns the visible size of the window (being also the size of its scene) for the given orientation.
Definition at line 993 of file mwindow.cpp.
{
QSize s;
if (orientation == M::Landscape) {
s = MDeviceProfile::instance()->resolution();
} else {
s = QSize(MDeviceProfile::instance()->resolution().height(),
MDeviceProfile::instance()->resolution().width());
}
return s;
}
Property Documentation
MWindow::globalAlpha [read, write] |
The global alpha of the hardware graphics overlay for use by this window.
Definition at line 97 of file corelib/widgets/mwindow.h.
MWindow::orientationAngleLocked [read, write] |
Is the orientation angle locked
Definition at line 86 of file corelib/widgets/mwindow.h.
MWindow::orientationLocked [read, write] |
Is the orientation locked
Definition at line 91 of file corelib/widgets/mwindow.h.
MWindow::videoGlobalAlpha [read, write] |
The global alpha of the hardware video overlay for use by this window.
Definition at line 103 of file corelib/widgets/mwindow.h.