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

MSceneWindow Class Reference

MSceneWindow objects are the base graphical items in a MeeGo Touch scene. More...

Inherits MWidgetController.

Inherited by MApplicationMenu, MApplicationPage, MBanner, MCompleter, MDialog, MEscapeButtonPanel, MHomeButtonPanel, MInfoBanner, MModalSceneWindow, MNavigationBar, MOverlay, MSheet, and MStatusBar.

List of all members.

Public Types

enum  DeletionPolicy { KeepWhenDone, DestroyWhenDone, DestroyWhenDismissed }
enum  WindowType {
  ApplicationPage = 0, NavigationBar, EscapeButtonPanel, DockWidget,
  LayerEffect, Dialog, MessageBox, ApplicationMenu,
  ObjectMenu, ModalSceneWindow, PopupList, Banner,
  Overlay, Completer, HomeButtonPanel, PlainSceneWindow,
  StatusBar, Sheet, BorderDecoration
}
enum  SceneWindowState { Appearing, Appeared, Disappearing, Disappeared }

Public Slots

void appear (QGraphicsScene *scene, MSceneWindow::DeletionPolicy policy=KeepWhenDone)
virtual void appear (MWindow *window, MSceneWindow::DeletionPolicy policy=KeepWhenDone)
virtual void appear (MSceneWindow::DeletionPolicy policy=KeepWhenDone)
virtual void disappear ()
bool dismiss ()

Signals

void appearing ()
void appeared ()
void disappearing ()
void disappeared ()
void sceneWindowStateChanged (MSceneWindow::SceneWindowState newState, MSceneWindow::SceneWindowState oldState)
void repositionNeeded ()

Public Member Functions

 MSceneWindow (QGraphicsItem *parent=0)
virtual ~MSceneWindow ()
DeletionPolicy deletionPolicy () const
MSceneWindow::WindowType windowType () const
bool isManagedManually () const
void setManagedManually (bool managedManually)
SceneWindowState sceneWindowState () const

Protected Member Functions

Qt::Alignment alignment () const
QPointF offset () const
virtual void dismissEvent (MDismissEvent *event)
virtual void closeEvent (QCloseEvent *event)

Properties

bool managedManually

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:

In addition to those, if isManuallyManaged() is false, the following attributes will also be under scene manager control:

Manually changing attributes that are under the control of a scene manager is not supported and can lead to unpredictable behavior.

See also:
MSceneManager

Member Enumeration Documentation

This enum defines how to handle scene window after hiding it using disappear() or dismiss().

We have both DestroyWhenDone + disappear() and DestroyWhenDismissed + dismiss() to cover the use case where you want your scene windows to be deleted only when they are no longer in the page history.

Example:

When drilling down (from root page to sub page and then to sub-sub page) you want your previous pages (root page and sub page) to be kept alive since the user might go back to them by pressing a back button (which calls dismiss() on current page). But once the user have moved away from a page for good (pressed back on sub-sub page, reaching sub page), that page can be deleted (sub-sub page gets deleted). You will get that for free by using DestroyWhenDismissed.

If you use DestroyWhenDone for your pages you will never be able to go back to them in a drill down navigational pattern as they will be deleted as soon as they leave the screen. If you use DestroyWhenDismissed they will only be deleted if they get dismissed, for instance, by the user via the back button.

See also:
appear()
Enumerator:
KeepWhenDone 

Window is kept alive after being dismissed or disappeared.

DestroyWhenDone 

Window is destroyed after being dismissed or disappeared.

DestroyWhenDismissed 

Window is destroyed after being dismissed.

This enum describes the possible states of a scene window.

See also:
sceneWindowState(), sceneWindowStateChanged(), appeared(), disappeared()
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.

Defines multiple window types which will have different Z value

Enumerator:
ApplicationPage 
NavigationBar 
EscapeButtonPanel 
DockWidget 
LayerEffect 
Dialog 
MessageBox 
ApplicationMenu 
ObjectMenu 
ModalSceneWindow 
PopupList 
Banner 
Overlay 
Completer 
HomeButtonPanel 
PlainSceneWindow 
StatusBar 
Sheet 
BorderDecoration 

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.
MSceneWindow::~MSceneWindow (  )  [virtual]

Destructor of the MSceneWindow class.


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.
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()
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();
See also:
appear(QGraphicsScene *, DeletionPolicy), MSceneManager::appearSceneWindow()

Reimplemented in MDialog.

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.

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.

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

If DestroyWhenDone was used on the last appear() call, the scene window will be deleted after its disappearance is finished. Note that nothing will happen if the scene window is already in Disappeared state.

See also:
MSceneManager::disappearSceneWindow(), SceneWindowState
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]
void MSceneWindow::dismissEvent ( MDismissEvent event  )  [protected, virtual]
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.

QPointF MSceneWindow::offset (  )  const [protected]

Returns the current offset.

Returns:
The current offset.
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()
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.

MSceneWindow::WindowType MSceneWindow::windowType (  )  const

Returns the window type.

See also:
WindowType

Property Documentation

bool MSceneWindow::managedManually [read, write]

Copyright © 2010 Nokia Corporation
MeeGo Touch