MSceneWindow objects are the base graphical items in a MeeGo Touch scene. More...
Detailed Description
MSceneWindow objects are the base graphical items in a MeeGo Touch scene.
All graphical components of a standard MeeGo Touch application are held in a MSceneWindow of some type. MSceneWindow instances form the base level of a MeeGo Touch application's scene graph.
MSceneWindows in a MScene are analogous to top level windows in a traditional windowing system.
The actual size and position of a MSceneWindow are by default managed by MSceneManager according to MSceneWindowStyle properties. If you want to manually resize and position a MSceneWindow you have to explicitly set the managedManually property to true.
Appearing and disappearing scene windows
Scene windows introduce a new concept: They also appear and disappear instead of just being shown and hidden like regular graphics items.
Thus the family of methods appear()/disappear()/dismiss()/sceneWindowState() is different from show()/hide()/close()/isVisible().
The second group revolves around the isVisible() property which has its meaning defined in the documentation of QGraphicsItem::setVisible().
The first group is a higher level concept introduced by MSceneWindow/MSceneManager and is about the scene manager taking a scene window, adding it to the scene managed by him and setting its proper position, size, z value, parent item, etc (usually with animated transitions).
Managed scene windows
After a scene window has been added to a scene manager (through an appear() call), the following attributes are controlled by that scene manager and therefore should not be manually modified:
- scene()
- parentItem()
- zValue()
- rotation()
- scale()
- transformOriginPoint()
- isVisible()
In addition to those, if isManuallyManaged() is false, the following attributes will also be under scene manager control:
- pos()
- size()
- geometry()
Manually changing attributes that are under the control of a scene manager is not supported and can lead to unpredictable behavior.
- See also:
- MSceneManager
Definition at line 86 of file corelib/widgets/mscenewindow.h.
Member Enumeration Documentation
This enum defines how to handle scene window after hiding it using disappear() or dismiss().
- Enumerator:
Definition at line 97 of file corelib/widgets/mscenewindow.h.
{
KeepWhenDone,
DestroyWhenDone,
DestroyWhenDismissed
};
This enum describes the possible states of a scene window.
- Enumerator:
Appearing An appearance animation is running on the scene window. A scene window enters this appearance state when appear() is called from Disappeared state.
Appeared The scene window is properly positioned in the scene. It enters this state from Appearing, after its appearance animation has finished. This state can also be reached directly from Disappeared if the transition was immediate. The appeared() signal gets emitted when this state is reached.
Disappearing A disappearance animation is running on the scene window. A scene window enters this state when disappear() is called from Appeared state.
Disappeared Initial state. The scene window is outside the visible scene area and therefore cannot be seen. It enters this appearance state from Disappearing, after its disappearance animation has finished. This state might also be reached directly from Appeared if the transition was immediate. The disappeared() signal gets emitted when this state is reached.
Definition at line 131 of file corelib/widgets/mscenewindow.h.
{
Appearing,
Appeared,
Disappearing,
Disappeared
};
Defines multiple window types which will have different Z value
- Enumerator:
Definition at line 106 of file corelib/widgets/mscenewindow.h.
{
ApplicationPage = 0, // MApplicationPage
NavigationBar, // MNavigationBar
EscapeButtonPanel, // MEscapeButtonPanel
DockWidget, // MDockWidget
LayerEffect, // MSceneLayerEffect
Dialog, // MDialog
MessageBox, // MMessageBox
ApplicationMenu, // MApplicationMenu
ObjectMenu, // MObjectMenu
ModalSceneWindow, // MModalSceneWindow
PopupList, // MPopupList
NotificationInformation, // MNotification - Information
NotificationEvent, // MNotification - Event
Overlay, // MOverlay
Completer, // MCompleter
HomeButtonPanel, // MHomeButtonPanel
PlainSceneWindow, // MSceneWindow
StatusBar // MStatusBar
};
Constructor & Destructor Documentation
| MSceneWindow::MSceneWindow | ( | QGraphicsItem * | parent = 0 |
) | [explicit] |
Creates an empty scene window. It's a fullscreen container of the lowest Z value, that can be a parent for its child widgets and layouts.
- Note:
- You normally wouldn't want to instantiate this class directly and instead use one of the provided subclasses.
Definition at line 94 of file mscenewindow.cpp.
:
MWidgetController(new MSceneWindowPrivate, new MSceneWindowModel, parent)
{
Q_D(MSceneWindow);
d->windowType = PlainSceneWindow;
grabGesture(Qt::PanGesture);
grabGesture(Qt::TapGesture);
grabGesture(Qt::TapAndHoldGesture);
grabGesture(Qt::PinchGesture);
grabGesture(Qt::SwipeGesture);
setFlag(QGraphicsItem::ItemStopsClickFocusPropagation);
}
| MSceneWindow::~MSceneWindow | ( | ) | [virtual] |
Destructor of the MSceneWindow class.
Definition at line 124 of file mscenewindow.cpp.
{
if (sceneManager())
sceneManager()->d_func()->removeSceneWindow(this);
}
Member Function Documentation
| Qt::Alignment MSceneWindow::alignment | ( | ) | const [protected] |
Returns the current alignment. Alignment defines how scene manager will position the window on the screen. This property has no effect if the window is being managed manually.
- See also:
- isManagedManually()
- Returns:
- The current alignment.
Definition at line 221 of file mscenewindow.cpp.
{
Qt::Alignment result = 0;
// There is an implicit property interface between the controller and the views
// The controller expects the view to provide an "alignment" property.
if (view()) {
QVariant v = view()->property("alignment");
if (v.isValid()) {
result = Qt::Alignment(v.toInt());
}
else {
}
}
if (layoutDirection() == Qt::RightToLeft) {
if (result.testFlag(Qt::AlignLeft)) {
result &= ~Qt::AlignLeft;
result |= Qt::AlignRight;
} else if (result.testFlag(Qt::AlignRight)) {
result &= ~Qt::AlignRight;
result |= Qt::AlignLeft;
}
}
return result;
}
| void MSceneWindow::appear | ( | QGraphicsScene * | scene, | |
| MSceneWindow::DeletionPolicy | policy = KeepWhenDone | |||
| ) | [slot] |
Makes the scene window appear on the given scene.
- Parameters:
-
scene The scene on which the scene window is going to appear. policy Deletion policy. Defines whether this scene window should be automatically deleted when no longer used.
The scene window will be managed by the MSceneManager of the given scene. Since the appearance and disappearance of scene windows is handled by a scene manager, if scene has no scene manager this method won't have any effect.
Ownership is transfered to scene.
- Note:
- This is different from calling
scene->addItem(sceneWindow).
Usage example:
void AlbumPage::showSong(Song *song) { MSceneWindow *songPage = new SongPage(song); songPage->appear(scene(), MSceneWindow::DestroyWhenDismissed); }
- See also:
- MSceneManager::appearSceneWindow()
Definition at line 160 of file mscenewindow.cpp.
{
if (!scene) {
mWarning("MSceneWindow") << Q_FUNC_INFO << "NULL scene.";
return;
}
MScene *mScene = qobject_cast<MScene *>(scene);
if (!mScene || !mScene->sceneManager()) {
mWarning("MSceneWindow") << Q_FUNC_INFO << "scene has no scene manager.";
return;
}
if (view()) {
if (model()->disappearTimeout() != 0) {
QTimer::singleShot(model()->disappearTimeout(), this, SLOT(disappear()));
}
}
mScene->sceneManager()->appearSceneWindow(this, policy);
}
| void MSceneWindow::appear | ( | MWindow * | window, | |
| MSceneWindow::DeletionPolicy | policy = KeepWhenDone | |||
| ) | [virtual, slot] |
Makes the scene window appear on window.
- Parameters:
-
window The window whose scene will receive the appearing scene window. policy Deletion policy. Defines whether this scene window should be automatically deleted when no longer used.
If window doesn't have a scene manager, one will be automatically created (along with a scene) and assigned to it.
Ownership is transfered to window->scene().
Usage example:
MWindow *window = new SomeWindow; MSceneWindow *sceneWindow = new SomeSceneWindow; sceneWindow->appear(window); window->show();
Reimplemented in MDialog.
Definition at line 182 of file mscenewindow.cpp.
{
if (!window) {
// Remove this behavior along with the deprecated
// MSceneWindow::appear(DeletionPolicy);
window = MApplication::activeWindow();
if (!window) {
mWarning("MSceneWindow")
<< "Construct and show MWindow before showing a scene window";
return;
}
}
// Force the creation of a scene manager (and scene) if none was
// set to this window yet.
//
// Therefore:
// sceneWindow->appear(window);
// Will yield a different result than:
// sceneWindow->appear(window->scene());
// If window didn't have a scene and scene manager.
window->sceneManager();
appear(window->scene(), policy);
}
| void MSceneWindow::appear | ( | MSceneWindow::DeletionPolicy | policy = KeepWhenDone |
) | [virtual, slot] |
Makes the scene window appear on the currently active window and registers it with the associated MSceneManager.
- Deprecated:
- Please use appear(QGraphicsScene) or appear(MWindow) instead.
- Attention:
- If your application has multiple MWindows, usage of this method is strongly discouraged since it can make a scene window 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 whether this scene window should be automatically deleted when no longer used.
Ownership is transfered to the MScene visualized by the active MWindow (MApplication::activeWindow()->scene()).
- See also:
- appear(QGraphicsScene*, DeletionPolicy), appear(MWindow*, DeletionPolicy), MApplication::activeWindow(), MSceneManager::appearSceneWindow()
Reimplemented in MDialog.
Definition at line 208 of file mscenewindow.cpp.
{
mWarning("MSceneWindow") << Q_FUNC_INFO << "is deprecated."
"Use appear(QGraphicsScene*) or appear(MWindow*) instead.";
appear((MWindow *)0, policy);
}
| void MSceneWindow::appeared | ( | ) | [signal] |
Emitted when the scene window enters the MSceneWindow::Appeared state.
At this point the scene window has assumed its final position in the visible area of the scene.
- See also:
- appear()
| void MSceneWindow::appearing | ( | ) | [signal] |
Emitted when the scene window enters the MSceneWindow::Appearing state. This means that the scene window is starting its appearance animation. From that point in time onwards, some or all of it might be inside the visible area of the scene.
| void MSceneWindow::closeEvent | ( | QCloseEvent * | event | ) | [protected, virtual] |
Default implementation calls dismiss() and ignores the event. Reimplement in a subclass to specify a different behavior
- See also:
- QGraphicsWidget::closeEvent()
Reimplemented from QGraphicsWidget.
Definition at line 288 of file mscenewindow.cpp.
{
event->ignore();
dismiss();
}
| MSceneWindow::DeletionPolicy MSceneWindow::deletionPolicy | ( | ) | const |
Returns the currently active deletion policy of this window.
- Returns:
- Deletion policy of this window, KeepWhenDone as a default.
- See also:
- DeletionPolicy
Definition at line 136 of file mscenewindow.cpp.
{
Q_D(const MSceneWindow);
return d->policy;
}
| void MSceneWindow::disappear | ( | ) | [virtual, slot] |
Makes this scene window disappear and unregisters it from the associated MSceneManager.
This is the same as calling: sceneWindow->sceneManager()->disappearSceneWindow(sceneWindow);
Definition at line 215 of file mscenewindow.cpp.
{
if (sceneManager())
sceneManager()->disappearSceneWindow(this);
}
| void MSceneWindow::disappeared | ( | ) | [signal] |
Emitted when the scene window enters the MSceneWindow::Disappeared state.
The scene window is not longer present in the visible area of the scene.
- See also:
- disappear()
| void MSceneWindow::disappearing | ( | ) | [signal] |
Emitted when the scene window enters the MSceneWindow::Disappearing state. This means that the scene window is starting its disappearance animation.
| bool MSceneWindow::dismiss | ( | ) | [slot] |
Definition at line 267 of file mscenewindow.cpp.
{
MDismissEvent dismissEvent;
QApplication::sendEvent(this, &dismissEvent);
if (!dismissEvent.isAccepted()) {
return false;
}
if (sceneManager()) {
sceneManager()->dismissSceneWindow(this);
}
return true;
}
| void MSceneWindow::dismissEvent | ( | MDismissEvent * | event | ) | [protected, virtual] |
Definition at line 283 of file mscenewindow.cpp.
{
event->accept();
}
| bool MSceneWindow::isManagedManually | ( | ) | const |
Returns true if window is managed manually, i.e. scene manager doesn't care about its size and position. Default value is false, i.e. window is resized and positioned inside the scene by the scene manager, according to its style attributes.
Definition at line 142 of file mscenewindow.cpp.
{
Q_D(const MSceneWindow);
return d->managedManually;
}
| QPointF MSceneWindow::offset | ( | ) | const [protected] |
Returns the current offset.
- Returns:
- The current offset.
Definition at line 249 of file mscenewindow.cpp.
{
QPointF result;
// There is an implicit property interface between the controller and the views
// The controller expects the view to provide an "offset" property.
if (view()) {
QVariant v = view()->property("offset");
if (v.isValid()) {
result = v.toPointF();
}
} else {
result = QPointF(0, 0);
}
return result;
}
| void MSceneWindow::repositionNeeded | ( | ) | [signal] |
Emitted when window's style attributes have changed and it needs to be repositioned by the scene manager.
| MSceneWindow::SceneWindowState MSceneWindow::sceneWindowState | ( | ) | const |
Returns the state of the scene window.
- See also:
- sceneWindowStateChanged()
Definition at line 154 of file mscenewindow.cpp.
{
Q_D(const MSceneWindow);
return d->sceneWindowState;
}
| void MSceneWindow::sceneWindowStateChanged | ( | MSceneWindow::SceneWindowState | newState, | |
| MSceneWindow::SceneWindowState | oldState | |||
| ) | [signal] |
Emitted when the scene window state changes.
- Parameters:
-
newState The new state of the scene window. oldState The previous state of the scene window.
| void MSceneWindow::setManagedManually | ( | bool | managedManually | ) |
Allows to explicitly enable/disable manual management of the size and position of the window by the scene manager. Manual management is disabled by default, letting the scene manager adjust size and position of the window accorting to its style attributes. If manual management is enabled, the window can be positioned using e.g. resize(), setPos() and/or setGeometry() and it's responsible itself for proper adjusting its geometry when viewport orientation changes.
Scene manager will still control other attributes such as the assigned scene (scene()), the assigned parent item (parentItem()) and Z value (zValue()) regardless of the value of this property.
Definition at line 148 of file mscenewindow.cpp.
{
Q_D(MSceneWindow);
d->managedManually = managedManually;
}
| MSceneWindow::WindowType MSceneWindow::windowType | ( | ) | const |
Returns the window type.
- See also:
- WindowType
Definition at line 130 of file mscenewindow.cpp.
{
Q_D(const MSceneWindow);
return d->windowType;
}
Property Documentation
bool MSceneWindow::managedManually [read, write] |
Definition at line 91 of file corelib/widgets/mscenewindow.h.