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

MApplicationPage Class Reference

MApplicationPage provides a framework for building an application's user interface. By default the page creates a pannable viewport where a user can place his component by using centralWidget() or setCentralWidget(MWidget *). More...

Inherits MSceneWindow.

List of all members.

Public Types

enum  Component {
  NavigationBar = 0x1, HomeButton = 0x2, EscapeButton = 0x4, StatusBar = 0x8,
  AllComponents = NavigationBar | HomeButton | EscapeButton
}

Public Slots

void setAutoMarginsForComponentsEnabled (bool enabled)
void setCentralWidget (QGraphicsWidget *centralWidget)
void setTitle (const QString &title)
void setRememberPosition (bool remember)
void setPannable (bool pannable)
void setPanningDirection (Qt::Orientations directions)
void setProgressIndicatorVisible (bool visible)
void setEscapeMode (MApplicationPageModel::PageEscapeMode mode)

Signals

void backButtonClicked ()
void closeButtonClicked ()
void actionUpdated (QActionEvent *e)
void exposedContentRectChanged ()
void customNavigationBarContentChanged ()

Public Member Functions

 MApplicationPage (QGraphicsItem *parent=0)
virtual ~MApplicationPage ()
virtual void createContent ()
MApplicationPageModel::ComponentDisplayMode componentDisplayMode (Component) const
void setComponentsDisplayMode (Components components, MApplicationPageModel::ComponentDisplayMode displayMode)
bool autoMarginsForComponentsEnabled () const
bool isContentCreated () const
bool rememberPosition () const
bool isPannable () const
Qt::Orientations panningDirection () const
QGraphicsWidgetcentralWidget ()
MApplicationWindowapplicationWindow ()
const QString title () const
bool isProgressIndicatorVisible () const
MApplicationPageModel::PageEscapeMode escapeMode () const
MPannableViewportpannableViewport ()
QRectF exposedContentRect () const
void setCustomNavigationBarContent (QGraphicsWidget *customNavigationBarContent)
QGraphicsWidgetcustomNavigationBarContent ()

Properties

bool autoMarginsForComponentsEnabled
QString title
bool contentCreated
MApplicationPageModel::PageEscapeMode escapeMode
bool pannable
Qt::Orientations panningDirection
bool rememberPosition
bool progressIndicatorVisible
QRectF exposedContentRect

Detailed Description

MApplicationPage provides a framework for building an application's user interface. By default the page creates a pannable viewport where a user can place his component by using centralWidget() or setCentralWidget(MWidget *).

The page can be shown on the screen using appear(QGraphicsScene*, DeletionPolicy) or appear(MWindow*, DeletionPolicy). A call to appear() involves running the assiciated show animation for the page. If you want to show a page instantly, refer to MSceneManager API.

A page can contain actions, which will be shown in the navigation bar in the application menu.

To switch off panning, or change direction of panning:

A minimal application which would show a page would look like this:

      #include <MApplication>
      #include <MApplicationWindow>
      #include <MApplicationPage>
      #include <MButton>

      int main(int argc, char *argv[]){
          MApplication application(argc, argv);
          MApplicationWindow window;
          MApplicationPage page;

          new MButton("Hello", page.centralWidget());
          page.appear(&window);

          window.show();

          return application.exec();
       }

centralWidget() returns MWidget, layout can be used to group more than one widget.

Navigating between pages.

Only one page can be displayed at any given time. The framework enforces this behavior. Thus in order to make your application navigate to a child page all you have to do is call the child's appear() method. That will automatically make the current page disappear to make room for the child page that is starting to appear.

In an hypothetical music browser application, the following code snippet would make it transition from the current album page to a child page displaying one of its songs:

    class AlbumPage : public MApplicationPage {
        ...
        void displaySong(Song song) {
            MApplicationPage *songPage = new SongPage(song);

            // I don't need this page anymore after it gets dismissed
            songPage->appear(scene(), MSceneWindow::DestroyWhenDismissed);
        }
        ...
    };

The code above will put AlbumPage onto the top of the page history's stack and make SongPage be displayed. Since the escapeMode of the SongPage is MApplicationPageModel::EscapeAuto (the default value) the escape button panel will automatically show a back button that, when clicked, will bring the application back to the AlbumPage. Therefore no code is required to make your application navigate back to its previous page.

To implement a different behavior for the escape button you have set the escapeMode of the page to either MApplicationPageModel::EscapeManualBack or MApplicationPageModel::EscapeCloseWindow.

You can also check and manually modify the page navigation history of your application using the methods MSceneManager::pageHistory() and MSceneManager::setPageHistory().

For information on this and other navigational patterns see Navigation patterns for applications.


Member Enumeration Documentation

This enum is used to specify components in componentDisplayMode() and setComponentsDisplayMode().

Components are widgets held by the application window whose behavior is affected by the page being currently displayed.

Enumerator:
NavigationBar 

The navigation bar

HomeButton 

The home button

EscapeButton 

The escape button

StatusBar 

The status bar

AllComponents 

Navigation bar, home button and escape button. For historical reasons it does not include the status bar


Constructor & Destructor Documentation

MApplicationPage::MApplicationPage ( QGraphicsItem parent = 0  ) 

Default constructor. Creates a new page.

MApplicationPage::~MApplicationPage (  )  [virtual]

Destroys the page.


Member Function Documentation

void MApplicationPage::actionUpdated ( QActionEvent e  )  [signal]

Signal emitted when action is added(removed) from the page.

MApplicationWindow * MApplicationPage::applicationWindow (  ) 

Convenience function that returns a pointer to the application window into which the application page is shown or a null pointer if appear() hasn't been called yet. When you call appear() and the application window specified as a parameter exists, this method will return it.

See also:
appear(QGraphicsScene*, DeletionPolicy), appear(MWindow*, DeletionPolicy), createContent(), QGraphicsItem::scene(), QGraphicsScene::views()
bool MApplicationPage::autoMarginsForComponentsEnabled (  )  const
void MApplicationPage::backButtonClicked (  )  [signal]

Signal emitted when back button called.

QGraphicsWidget * MApplicationPage::centralWidget (  ) 

Returns the central widget for the page.

By default page provides a widget (panel) on which other widgets can be placed. It's also possible to set a central widget for a page with setCentralWidget(MWidget*) function.

Returns:
the pointer to the central widget.
void MApplicationPage::closeButtonClicked (  )  [signal]

Signal emitted when close button is clicked. This can happen when escapeButtonMode() is set to MEscapeButtonPanelModel::CloseMode.

Note that the close() slot of the associated MApplicationWindow will also get called when the close button is clicked.

For code that should be executed when a MApplicationWindow is closed you should consider reimplementing the QWidget::closeEvent() method of your MApplicationWindow instead of listening to this signal.

See also:
QWidget::close()
MApplicationPageModel::ComponentDisplayMode MApplicationPage::componentDisplayMode ( Component  component  )  const

Returns the display mode of a component.

All components are shown by default.

See also:
setComponentsDisplayMode()
void MApplicationPage::createContent (  )  [virtual]

This function will be called before page becomes visible. Override it in your page class and create content for a page. Framework calls this function only once.

QGraphicsWidget * MApplicationPage::customNavigationBarContent (  ) 

Returns the custom content for the navigation bar By default it returns 0 (null).

See also:
setCustomNavigationBarContent()
void MApplicationPage::customNavigationBarContentChanged (  )  [signal]

Emitted when a different custom navigation bar content widget is set.

See also:
setCustomNavigationBarContent()
MApplicationPageModel::PageEscapeMode MApplicationPage::escapeMode (  )  const

Returns the page's escape mode.

By default, it's EscapeAuto.

See also:
MApplicationPageMode::PageEscapeMode, setEscapeMode()
QRectF MApplicationPage::exposedContentRect (  )  const

Area of the page whose content is not covered by any bar.

Returns the current value of MApplicationPage::exposedContentRect property

See also:
exposedContentRectChanged()
void MApplicationPage::exposedContentRectChanged (  )  [signal]

Emitted when the exposed content rectangle changes.

That happens when some bar (navigation bar, status bar, tool bar) appears or disappears, which makes the exposed content area of the page bigger or smaller.

Appearance or disappearance of transient scene windows such as dialogs and notifications does not change the exposed content rectangle of the page. Overlays are also not considered.

See also:
exposedContentRect()
bool MApplicationPage::isContentCreated (  )  const

Returns true if createContent() was called by framework, otherwise false.

bool MApplicationPage::isPannable (  )  const

Returns true if page's is pannable.

See also:
setPannable(bool)
bool MApplicationPage::isProgressIndicatorVisible (  )  const

Returns whether progress indicator is visible.

Deprecated:
do not use
Returns:
true if the progress indicator is visible, otherwise false
See also:
setProgressIndicatorVisible()
MPannableViewport * MApplicationPage::pannableViewport (  ) 

Returns the viewport responsible for panning the page.

Qt::Orientations MApplicationPage::panningDirection (  )  const

Returns the orientations in which the page pans. The value can be Qt::Horizontal, Qt::Vertical or Qt::Horizontal | Qt::Vertical.

bool MApplicationPage::rememberPosition (  )  const

Returns value of MApplicationPage::rememberPosition property.

See also:
setRememberPosition()
void MApplicationPage::setAutoMarginsForComponentsEnabled ( bool  enabled  )  [slot]
void MApplicationPage::setCentralWidget ( QGraphicsWidget centralWidget  )  [slot]

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: MApplicationPage takes ownership of the widget pointer and deletes it when needed.

Parameters:
centralWidget the central widget.
void MApplicationPage::setComponentsDisplayMode ( Components  components,
MApplicationPageModel::ComponentDisplayMode  displayMode 
)

Sets the display mode of components.

Example code on how to make a page take the entire screen space (i.e., go fullscreen).

Parameters:
components The components whose display mode you want to set.
displayMode The new display mode for the given components.
See also:
componentDisplayMode(), MApplicationPageModel::ComponentDisplayMode
void MApplicationPage::setCustomNavigationBarContent ( QGraphicsWidget customNavigationBarContent  ) 

Sets custom content for the navigation bar.

If set with a valid widget (i.e., pointer different then 0), all navigation bar content will be replaced by the given widget. This is useful for cases that demand more flexibility than what tool buttons added via MAction can provide.

This means the application developer is responsible for adding any navigation control (back button, close button, menu button, etc) himself.

The navigation bar will then be composed by its regular background with navigationBarContent on top of it, taking the entire area of the navigation bar.

When a navigation bar has custom content, any MAction that would normally be represented by some widget on it (such as a tool button) will no longer have any effect. MActions located in the application menu will still work, but you will have to summon the menu yourself by calling:

A typical customNavigationBarContent will be a widget with an internal layout of subwidgets (such as buttons). If you want the text buttons of your custom navigation bar content to have a native look & feel you should set their syle names to "ToolBarLabelOnlyCommonButton".

The custom navigation bar content of a page is fetched when that page is about to start appearing (i.e. transitioning from MSceneWindow::Disappeared to MSceneWindow::Appearing or from MSceneWindow::Disappeared to MSceneWindow::Appeared). Therefore you should have your customNavigationBarContent() set either when your page is constructed or inside its createContent() method. Changing the customNavigationBarContent() of a page while it's being displayed (its state is different than MSceneWindow::Disappeared) is not supported and leads to undefined behavior.

While a page is being displayed, the widget returned by customNavigationBarContent() will be reparented to the navigation bar. When a page is leaving the screen, customNavigationBarContent() will be removed from the scene and will have its parent set to zero (null).

The widget pointed by customNavigationBarContent() is deleted by MApplicationPage's destructor. Any previously set customNavigationBarContent will be deleted and replaced by customNavigationBarContent.

See also:
customNavigationBarContent()
void MApplicationPage::setEscapeMode ( MApplicationPageModel::PageEscapeMode  mode  )  [slot]

Sets the page escape mode.

See also:
MApplicationPageModel::PageEscapeMode, escapeMode()
void MApplicationPage::setPannable ( bool  pannable  )  [slot]

Sets the MApplicationPage::pannable property.

void MApplicationPage::setPanningDirection ( Qt::Orientations  directions  )  [slot]

Sets to which direction(s) page should be pannable. Possible values: Qt::Horizontal, Qt::Vertical or Qt::Horizontal | Qt::Vertical.

void MApplicationPage::setProgressIndicatorVisible ( bool  visible  )  [slot]
Deprecated:
do not use

Sets the visibility of progress indicator

Parameters:
bool visible
void MApplicationPage::setRememberPosition ( bool  remember  )  [slot]
void MApplicationPage::setTitle ( const QString title  )  [slot]

Set the title for this page.

Sets the MApplicationPage::title property.

Parameters:
title New title for this page.
const QString MApplicationPage::title (  )  const
Returns:
Get the page's title. The title appears in the command area.

Property Documentation

MApplicationPage::autoMarginsForComponentsEnabled [read, write]

Whether extra margins will be automatically added around the central widget to avoid occlusion by other components.

If enabled, extra margins will be automatically added around the central widget according to the components that are currently being displayed in order to avoid parts of the central widget from being inaccessible.

When a navigation bar appears on the upper edge of the application window, for instance, an extra margin will be automatically added to the top of the central widget of roughly the height of that navigation bar. Therefore effectively avoiding the top part of the central widget from being inaccessible.

This property enabled by default.

Note:
When the navigation bar is in AutoHide mode the top margin won't be added to the central widget.

Use setAutoMarginsForComponentsEnabled() to set it and autoMarginsForComponentsEnabled() to get its current value.

See also:
setComponentsDisplayMode()
MApplicationPage::contentCreated [read]

Whether createContent() has already been called.

See also:
isContentCreated()
MApplicationPage::escapeMode [read, write]

The page escape mode See MApplicationPageModel::PageEscapeMode.

MApplicationPage::exposedContentRect [read]

Area of the page whose content is not covered by any bar.

Area of the page whose content is not covered by any bar (status bar, navigation bar, tool bar) and thus is accessible to the user.

Floating widgets can be implemented by making them children of the application page instead of the central widget (thus they are not panned). They should be positioned within this rectangle.

Note that this area can be covered by transient scene windows such as dialogs and notifications as well as by overlays.

The rectangle is in local item coordinates.

You can get its current values with exposedContentRect() and be notified about changes in it by connecting to the exposedContentRectChanged() signal.

MApplicationPage::pannable [read, write]

Whether the page can be panned. Set it with setPannable() and get its current value with isPannable().

MApplicationPage::panningDirection [read, write]

Defines in which directions the page can be panned. Set it with setPanningDirection() and get its current value with panningDirection().

MApplicationPage::progressIndicatorVisible [read, write]

Defines whether progress indicator is visible.

Deprecated:
do not use

It true, a progress indicator with unknown duration (such as a spinner) will be displayed in the navigation bar. Use it to hint the user that some process is ongoing or that the page is waiting for something to complete.

By default, this property is false.

Set it with setProgressIndicatorVisible() and get its current value with isProgressIndicatorVisible().

MApplicationPage::rememberPosition [read, write]

Whether the page should remember the pannable viewport position it had on its last appearance.

Default value is true. Set it to false to have the viewport scrolled to the top with every new appearance. The scrolling is immediate, i.e. it's not animated at all.

Set it with setRememberPosition() and get its current value with rememberPosition().

MApplicationPage::title [read, write]

Page title. It will be shown on the navigation bar. Set it with setTitle() and get its current value with title().


Copyright © 2010 Nokia Corporation
MeeGo Touch