FCL/sf/mw/hb: comparison src/hbcore/gui/hbview.cpp

equal deleted inserted replaced

-:f7ac710697a9
+:06ff229162e9
 #include "hbdockwidget.h"
 #include "hbwidget_p.h"
 #include "hbmainwindow_p.h"
 #include "hbtitlebar_p.h"
 #include "hbstatusbar_p.h"
-#include "hbsoftkeygroup_p.h"
 #include "hbscreen_p.h"
 #include "hbviewactionmanager_p.h"
 #include "hbglobal_p.h"
 #include <QPointer>
 /*!
-@beta
+@stable
 @hbcore
 	\class HbView
-	\brief HbView is a base class for all the views that can be set to HbMainWindow.
+	\brief The HbView class defines one screen of user interface content.
-	HbView is a QGraphicsWidget, which contains a title, an icon, a menu and
+The screen area of a mobile device is small, so an application's user interface is often composed of a set of separate screens of content or "views". Each view can contain a number of widgets. A view can also contain a title, an icon (not used at present), a menu and a toolbar. These additional components are called decorators and together they make up the "chrome" of the interface.
-	a tool bar for one view in HbMainWindow.
+An application will have a number of views to present different kinds of information to the user. You can add multiple views to the \link HbMainWindow main window \endlink of your application and then manage them through the main window object. When a view is activated, the main window handles the updating of the view contents, i.e. the title, icon, menu and toolbar. The view object itself handles the visibility of the toolbar, but the main window will repaint it whenever the view is activated.
-	HbMainWindow will handle updating title, icon, menu and tool bar, when
-	the view is activated. Title is used in application's title pane area.
+\image html hbview_wireframes.png "Wireframes of two different views in a messaging application"
-	HbView handles the visibility of tool bar, though HbMainWindow will
-	reparent it when ever view comes active.
+\section _usecases_hbview Using the HbView class
+In general, the actual widgets, menu and toolbar that make up the content of a view will be designed with a UI layout tool. This means you do not need to use code to place each widget into the layout but instead load the layout from a file with HbDocumentLoader. Once the view is populated with widgets, you can manipulate them and connect their signals to methods in your application.
-	Example 1 for creating a simple view
+See the HbMainWindow class for information about switching between different views.
-	\include view1/main.cpp
+\subsection _uc_001_hbview Hiding and showing the chrome
-	Example 2 for creating view with title, icon, menu, toolbar and a widget.
+The chrome, (i.e. title, menu and toolbar of the view) can be hidden to allow your application to fill the whole screen. Also, individual components of the chrome can be hidden if desired.
-	\include view2/main.cpp
+\code
+// Hide all the chrome items
-\sa HbMenu
+myView.setContentFullScreen(true)
-*/
-/*!
+// Show all the chrome items
-\deprecated HbView::HbTitleBarFlag
+myView.setContentFullScreen(false)
-is deprecated. Use HbView::::HbViewFlag instead.
-\enum HbView::HbTitleBarFlag
+// Hide the toolbar
-Defines policy for showing the HbTitleBar in the current HbView.
+myView.hideItems(Hb::SceneItem::ToolBarItem)
-*/
-/*!
+// Show the toolbar
-\var HbView::TitleBarFlagNone
+myView.showItems(Hb::SceneItem::ToolBarItem)
-Titlebar is shown with the default attributes.
+\endcode
-*/
-/*!
+\subsection _uc_002_hbview Creating a simple view
-\var HbView::TitleBarMinimizable When this flag is set, there will be an
+This code snippet shows the most basic way to create an application with a single view.
-indication in titlebar showing the possibility to minimize (swipe out of the
-screen) titlebar.  */
+\code
-/*!
+#include <hbapplication.h>
-\var HbView::TitleBarMinimized
+#include <hbmainwindow.h>
-When this flag is set, the titlebar is shown in minimized state.
+#include <hbview.h>
-*/
-/*!
+int main(int argc, char *argv[])
-\var HbView::TitleBarHidden When this flag is set, the titlebar is not shown
+{
-at all, so that even the titlebar handle is not shown and it is not possible
+HbApplication app(argc, argv);
-to maximize the titlebar.  */
+HbMainWindow window;
-/*!
-\var HbView::TitleBarTransparent When this flag is set, the titlebar is
+HbView *view = new HbView();
-shown normally, but as transparent. This flag is normally used in
+view->setTitle("My View");
-combination with TitleBarFloating flag.  */
-/*!
+window.addView(view);
-\var HbView::TitleBarFloating When this flag is set, the titlebar is shown
-on top of underlying content. Setting this flag also changes application
+window.show();
-area to start from the top of the screen. This flag is normally used in
+return app.exec();
-combination with TitleBarTransparent flag.  */
+}
+\endcode
+\section _methodgroups_hbview Methods and properties grouped
+\li \b Chrome: setViewFlags(), showItems(), hideItems(), visibleItems(), isItemVisible(), setItemVisible(), unsetVisibleItems(),visibleItemsChanged() [signal], setContentFullScreen(), contentFullScreenChanged() [signal], isContentFullScreen(), contentFullScreen [property]
+\li \b Title: title(), setTitle(), titleChanged() [signal], title [property]
+\li \b Icon: icon(), setIcon(), iconChanged() [signal], icon [property]
+\li \b Menu: menu(), setMenu(), takeMenu()
+\li \b Toolbar: toolBar(), setToolBar(), toolBarChanged() [signal], takeToolBar()
+\li \b Actions: addAction(), setNavigationAction()
+\li \b Event: event()
+\li \b TitleBar: setTitleBarVisible()
+\li \b StatusBar: setStatusBarVisible()
+\li \b DockWidget: dockWidget(), setDockWidget(), dockWidgetChanged() [signal]
+\li \b Widget: widget(), setWidget(), takeWidget()
+\sa HbApplication, HbMainWindow, HbDocumentLoader, HbMenu, HbToolBar, HbDockWidget
+*/
 /*!
 \enum HbView::HbViewFlag
 Defines policy for showing the HbTitleBar in the current HbView.
 */
 /*!
 \var HbView::ViewFlagNone
 Titlebar and statusbar is shown with the default attributes.
 */
 /*!
 \var HbView::ViewTitleBarMinimizable
-When this flag is set, there will be an indication in titlebar showing the possibility to minimize (swipe out of the screen) titlebar.
+When this flag is set, there will be an indication in the titlebar showing the possibility to minimize the titlebar, e.g. swipe it off the screen.
 */
 /*!
 \var HbView::ViewTitleBarMinimized
-When this flag is set, the titlebar is shown in minimized state.
+Show the title bar in minimized state.
 */
 /*!
 \var HbView::ViewTitleBarHidden
-When this flag is set, the titlebar is not shown at all, so that even the titlebar handle is not shown and it is not possible to maximize the titlebar.
+Do not show the title bar at all. The title bar handle is not shown and it is not possible to maximize the title bar.
 */
 /*!
 \var HbView::ViewTitleBarTransparent
-When this flag is set, the titlebar is shown normally, but as transparent. This flag is normally used in combination with ViewTitleBarFloating flag.
+Show normal style title bar but make it transparent. This flag is normally used in combination with TitleBarFloating flag.
 */
 /*!
 \var HbView::ViewTitleBarFloating
-When this flag is set, the titlebar is shown on top of underlying content. Setting this flag also changes application area to start from the top of the screen. This flag is normally used in combination with TitleBarTransparent flag.
+Show the title bar floating on top of the underlying content. Setting this flag also make the application area start from the top of the screen. This flag is normally used in combination with TitleBarTransparent flag.
 */
 /*!
 \var HbView::ViewStatusBarHidden
-When this flag is set, the statusbar is not shown at all. This flag is normally used in combination with ViewTitleBarHidden flag.
+Do not show the statusbar at all. This flag is normally used in combination with the ViewTitleBarHidden flag.
 */
 /*!
 \var HbView::ViewStatusBarTransparent
-When this flag is set, the statusbar is shown normally, but as transparent. This flag is normally used in combination with ViewStatusBarFloating flag.
+Show the statusbar with normal content but transparent. This flag is normally used in combination with ViewStatusBarFloating flag.
 */
 /*!
 \var HbView::ViewStatusBarFloating
-When this flag is set, the statusbar is shown on top of underlying content. Setting this flag also changes application area to start from the top of the screen. This flag is normally used in combination with ViewStatusBarTransparent flag.
+Show the statusbar on top of the underlying content. Setting this flag also changes the application area to start from the top of the screen. This flag is normally used in combination with the ViewStatusBarTransparent flag.
+*/
+/*!
+\enum HbView::ActionContainer
+Defines the default container when you add actions to a view.
+\sa navigationAction()
+*/
+/*!
+\var HbView::NotSpecified
+Indicate that no particular action container is preferred.
+*/
+/*!
+\var HbView::OptionsMenu
+Indicate that the options menu is the preferred location for an action.
+*/
+/*!
+\var HbView::ToolBar
+Indicate that the tool bar is the preferred location for an action.
 */
 /*!
 \fn void HbView::titleChanged(const QString &title)
-This signal is emitted when the title changes.
+This signal is emitted when the title is replaced by a different title.
+\sa setTitle()
 */
 /*!
 \fn void HbView::iconChanged(const HbIcon &icon)
-This signal is emitted when the icon changes.
+This signal is emitted when the icon is replaced by a different icon.
+\sa setIcon()
 */
 /*!
 \fn void HbView::toolBarChanged()
-This signal is emitted when tool bar changes.
+This signal is emitted when toolbar is replaced by a different toolbar.
-*/
+\sa setToolBar()
-/*!
+*/
-\reimp
+/*!
+\fn void HbView::visibleItemsChanged()
+This signal is emitted when items in the chrome (e.g. toolbar, menu) are made visible or hidden.
+\sa visibleItems()
+*/
+/*!
+\fn void HbView::contentFullScreenChanged()
+This signal is emitted when the view is set to occupy the whole screen.
+\sa setContentFullScreen()
+*/
+/*!
+\fn void HbView::dockWidgetChanged()
+This signal is emitted when the dock widget is replaced by a different dock widget.
+\sa setDockWidget()
+*/
+/*!
 \fn int HbView::type() const
 */
+/*!
+\internal
+*/
 HbViewPrivate::HbViewPrivate()
 : mLayout(0),
 menu(0),
 toolBar(0),
 dockWidget(0),
 widget(0),
 mVisibleItems(Hb::AllItems),
 mVisibleItemsSet(false),
 mFullscreen(false),
 mVisited(false),
-mTitleBarFlags(HbView::TitleBarFlagNone),
 mViewFlags(HbView::ViewFlagNone),
 actionManager(0),
 preferredActionContainer(HbView::NotSpecified),
 mNavigationAction(0),
 mNavigationActionSet(false)
 {
 }
+/*!
+\internal
+*/
 HbViewPrivate::~HbViewPrivate()
 {
 }
 /*!
-Constructs a view with given \a parent.
+Constructs a view with the given \a parent.
 */
 HbView::HbView(QGraphicsItem *parent) :
 HbWidget(*new HbViewPrivate, parent)
 {
 Q_D(HbView);
 Q_D(HbView);
 d->q_ptr = this;
 }
 /*!
-Destructs the view.
+Destructor.
 */
 HbView::~HbView()
 {
 Q_D(HbView);
 if (d->menu) {
 d->dockWidget->deleteLater();
 }
 }
 /*!
-Returns the title of the view.
+Returns the title of the view. If no title has been defined, the return value is a null string.
-The default value is a null string.
 \sa setTitle()
 */
 QString HbView::title() const
 {
 emit titleChanged(title);
 }
 }
 /*!
-Returns the icon of the view.
+Returns the icon associated with the view.
 The default value is a null icon.
 \sa setIcon(), HbIcon::isNull()
 */
 HbIcon HbView::icon() const
 Q_D(const HbView);
 return d->icon;
 }
 /*!
-Sets the icon of the view. The icon is associated with view.
+Sets the icon associated with the view.
 \sa icon()
 */
 void HbView::setIcon(const HbIcon &icon)
 {
 emit iconChanged(icon);
 }
 }
 /*!
-Returns the menu for the view. This function creates and returns an empty menu if it does not exist.
+Returns the menu for the view. This function creates and returns an empty menu if one does not already exist.
 Ownership is not transferred.
 \sa HbMenu setMenu()
 */
 }
 return d->menu;
 }
 /*!
-Sets the menu for the view. Setting the menu to 0 will remove it from the view.
+Sets the menu for the view. Setting the menu to 0 will remove any existing menu from the view.
-Takes the ownership of the \a menu.
+The view takes ownership of the \a menu.
 \sa HbMenu menu()
 */
 void HbView::setMenu(HbMenu *menu)
 {
 HbMenuPrivate::d_ptr(d->menu)->changeToOptionsMenu();
 if (mainWindow()) {
 d->menu->setLayoutDirection(mainWindow()->layoutDirection());
 }
 }
-}
+// Titlebar must be informed
-}
+if (mainWindow()) {
+HbMainWindowPrivate::d_ptr(mainWindow())->mTitleBar->propertiesChanged();
-/*!
+}
-Returns the tool bar for the view. This function creates and returns an empty tool bar if it does not exist.
+}
-The toolBarChanged() signal is not emitted if a new tool bar is created.
+}
+/*!
+Returns the toolbar for the view. If the view does not already have a toolbar, an
+	empty toolbar is created and returned to the caller but the toolBarChanged()
+	signal is not emitted.
 Ownership is not transferred.
 \sa HbToolBar setToolBar()
 */
 }
 return d->toolBar;
 }
 /*!
-Sets the toolbar for the view. Setting the tool bar to 0 will remove it from the view.
+Sets the toolbar for the view. Setting the toolbar to 0 will remove it from the view.
-Takes the ownership of the \a toolBar, though it is not a parent.
+The view takes ownership of the toolbar, but the view is not set as the parent.
 \sa HbToolBar toolBar()
 */
 void HbView::setToolBar(HbToolBar *toolBar)
 {
 emit toolBarChanged();
 }
 }
 /*!
-Removes the HbToolBar, which is set to view and returns it.
+Removes the toolbar from the view and returns it to the caller.
-The ownership of the \a HbToolBar is transferred to the caller.
+Ownership of the toolbar is transferred to the caller.
-\note This function is particularly useful if one wants to switch between
+\note This function is particularly useful if you want to switch to a
-different views without deleting previous toolbar.
+different view and keep the same toolbar.
 \sa setToolBar()
 */
 HbToolBar* HbView::takeToolBar()
 {
 return toolBar;
 }
 /*!
-Returns the dock widget for the view. This function creates and returns an empty dock widget if it does not exist.
+Returns the dock widget belonging to the view. If the view does not have a dock widget, an empty dock widget is created and returned.
-The dockWidgetChanged() signal is not emitted if a new dock widget is created.
+The dockWidgetChanged() signal is not emitted when a new dock widget is created by this method.
 Ownership is not transferred.
 \sa HbDockWidget setDockWidget()
 */
 }
 return d->dockWidget;
 }
 /*!
-Sets the dock widget for the view. Setting the dock widget to 0 will remove it from the view.
+Sets the dock widget for the view. Setting the dock widget to \c 0 will remove it from the view.
-Takes the ownership of the \a dockWidget, though it is not a parent.
+This does take ownership of the \a dockWidget, but does not become the parent.
 \sa HbDockWidget dockWidget()
 */
 void HbView::setDockWidget(HbDockWidget *dockWidget)
 {
 emit dockWidgetChanged();
 }
 }
 /*!
-Returns the widget if set, otherwise \c 0.
+Returns the widget that makes up the view. If the widget has not been set, this method will return 0.
-\sa setWidget widget takeWidget
+\sa setWidget takeWidget
 */
 QGraphicsWidget *HbView::widget() const
 {
 Q_D(const HbView);
 return d->widget;
 }
 /*!
-Sets the widget to be \a widget. Setting the widget to 0 will remove it from the view. Already set
+Sets the widget that makes up the view. Setting the \a widget value to 0 will delete the current widget.
-widget is deleted.
+The view takes the ownership of the \a widget.
-Takes the ownership of the \a widget.
 \sa widget takeWidget
 */
 void HbView::setWidget(QGraphicsWidget *widget)
 {
 d->widget = widget;
 }
 }
 /*!
-Removes the QGraphicsWidget, which is set to view and returns it.
+Removes the widget that makes up the view and returns the widget to the caller.
-The ownership of the \a widget is transferred to the caller.
+Ownership of the widget is transferred to the caller.
-\note This function is particularly useful if one wants to switch between
+\note This function is particularly useful if you want to use
-different widgets inside a view without deleting them.
+different widgets in a view without deleting them.
 \sa widget() setWidget()
 */
 QGraphicsWidget *HbView::takeWidget()
 {
 Q_D(HbView);
 QGraphicsWidget *widget = d->widget;
 if ( d->mLayout ) {
 }
 return widget;
 }
 /*!
-Sets \a items to be visible in this view. Changes will be visible
+Makes the given scene items visible in this view. Changes are visible
-instantly if the view is currently active, otherwise next time when
+instantly if the view is active, otherwise they will be shown the next time the
-view is activated. View's visibility flag overrides the similar
+view is activated.
-setting in HbMainWindow.
+The flag values in \a items override the corresponding settings in HbMainWindow.
 \sa hideItems() setItemVisible() isItemVisible() unsetVisibleItems() visibleItems() isContentFullScreen() setContentFullScreen()
 */
 void HbView::showItems(Hb::SceneItems items)
 {
 d->mVisibleItems |= items;
 d->mVisibleItemsSet = true;
 if (items & Hb::TitleBarItem) {
 d->mViewFlags &= ~HbView::ViewTitleBarHidden;
-d->mTitleBarFlags &= ~HbView::TitleBarHidden;
 }
 if (items & Hb::StatusBarItem) {
 d->mViewFlags &= ~HbView::ViewStatusBarHidden;
 }
 emit visibleItemsChanged();
 }
 /*!
-Sets \a items to be invisible in this view. Changes will be visible
+Hides the given scene items in this view. Changes are visible
-instantly if the view is currently active, otherwise next time when
+instantly if the view is active, otherwise they will be shown the next time the
-view is activated. View's visibility flag overrides the similar
+view is activated.
-setting in HbMainWindow.
+The flag values in \a items override the corresponding settings in HbMainWindow.
 \sa showItems() setItemVisible() isItemVisible() unsetVisibleItems() visibleItems() isContentFullScreen() setContentFullScreen()
 */
 void HbView::hideItems(Hb::SceneItems items)
 {
 Q_D(HbView);
 d->mVisibleItems &= ~items;
 d->mVisibleItemsSet = true;
 if (items & Hb::TitleBarItem) {
 d->mViewFlags |= HbView::ViewTitleBarHidden;
-d->mTitleBarFlags |= HbView::TitleBarHidden;
 }
 if (items & Hb::StatusBarItem) {
 d->mViewFlags |= HbView::ViewStatusBarHidden;
 }
 emit visibleItemsChanged();
 }
 /*!
-Returns visible items of this view.
+Returns the scene items that are visible in this view.
 \sa isItemVisible() setItemVisible() hideItems() showItems() unsetVisibleItems() isContentFullScreen() setContentFullScreen()
 */
 Hb::SceneItems HbView::visibleItems() const
 return HbMainWindowPrivate::d_ptr(mainWindow())->mVisibleItems;
 }
 }
 /*!
-Returns \c true if \a item is set to be visible.
+Returns \c true if \a item is set to be visible, otherwise returns \c false.
 \sa setItemVisible() hideItems() showItems() unsetVisibleItems() visibleItems() isContentFullScreen() setContentFullScreen()
 */
 bool HbView::isItemVisible(Hb::SceneItem item) const
 Q_D(const HbView);
 return d->mVisibleItems & item;
 }
 /*!
-Sets \a item to be \a visible in this view. Changes will be visible
+Shows or hides the given scene item for the view. If \a visible is \c true,
-instantly if the view is currently active, otherwise next time when
+then the given \a item is shown. If \a visible is \c false, then
-view is activated. View's visibility flag overrides the similar
+the given \a item is hidden.
-setting in HbMainWindow.
+	Changes are visible instantly if the view is active, otherwise they will be shown the next time the
+view is activated.
+This overrides the corresponding scene item settings in HbMainWindow.
 \sa isItemVisible() hideItems() showItems() unsetVisibleItems() visibleItems() isContentFullScreen() setContentFullScreen()
 */
 void HbView::setItemVisible(Hb::SceneItem item, bool visible)
 {
 Q_D(HbView);
 emit visibleItemsChanged();
 }
 /*!
-\deprecated HbView::unsetVisibleItems()
-is deprecated.
-Resets the view specific definition of visible items and
-uses the HbMainWindow's default visible items. Changes will be visible
-instantly if the view is currently active, otherwise next time when
-view is activated.
-\sa setItemVisible() isItemVisible() hideItems() showItems() visibleItems() isContentFullScreen() setContentFullScreen()
-*/
-void HbView::unsetVisibleItems()
-{
-HB_DEPRECATED("HbMainWindow::unsetVisibleItems is deprecated!");
-Q_D(HbView);
-d->mVisibleItemsSet = false;
-emit visibleItemsChanged();
-}
-/*!
 Returns \c true if view is set to use fullscreen.
 \sa setContentFullScreen() setItemVisible() isItemVisible() hideItems() showItems() visibleItems()
 */
 bool HbView::isContentFullScreen() const
 Q_D(const HbView);
 return d->mFullscreen;
 }
 /*!
-Sets the view to use full content area for drawing. Decorators like
+Makes the view content fill the whole screen area. The decorators that make up the chrome (such as
-signal bar, title pane etc can be shown on top of view content area.
+signal bar, title pane etc.) can still be shown on top of view content.
-Changes will be visible instantly if the view is currently active,
+	Changes are visible instantly if the view is active, otherwise they will
-otherwise next time when view is activated.
+	be shown the next time the view is activated.
 \sa isContentFullScreen() setItemVisible() isItemVisible() hideItems() showItems() visibleItems()
 */
 void HbView::setContentFullScreen(bool enable)
 {
 emit contentFullScreenChanged();
 }
 }
 /*!
-\deprecated HbView::titleBarFlags() const
+Returns the view flags bit vector.
-is deprecated. Use HbView::viewFlags() instead.
+This consists of values specified in HbViewFlag.
-Returns titlebar flags bit vector.
+\sa setViewFlags()
-It consists of bits specified in HbTitleBarFlag.
-\sa setTitleBarFlags()
-*/
-HbView::HbTitleBarFlags HbView::titleBarFlags() const
-{
-Q_D(const HbView);
-int statusBarFlagMask = ViewStatusBarHidden | ViewStatusBarTransparent | ViewStatusBarFloating;
-int flags(d->mViewFlags & ~statusBarFlagMask);
-return HbView::HbTitleBarFlags(flags);
-}
-/*!
-Returns view flags bit vector.
-It consists of bits specified in HbViewFlag.
-\sa setTitleBarFlags()
 */
 HbView::HbViewFlags HbView::viewFlags() const
 {
 Q_D(const HbView);
 return d->mViewFlags;
-}
-/*!
-\deprecated HbView::setTitleBarFlags(HbView::HbTitleBarFlags flags)
-is deprecated. Use HbView::setViewFlags(HbView::HbViewFlags flags) instead.
-Sets the titlebar flags bit vector. It consists of bits specified
-in HbTitleBarFlag. These flags can be set before the view is
-added to the main window or while the view is active.
-\sa titleBarFlags()
-*/
-void HbView::setTitleBarFlags(HbView::HbTitleBarFlags flags)
-{
-const int statusBarFlagMask = ViewStatusBarHidden | ViewStatusBarTransparent | ViewStatusBarFloating;
-Q_D(HbView);
-setViewFlags(HbView::HbViewFlags((d->mViewFlags & statusBarFlagMask) | flags));
 }
 /*!
 Sets the view flags bit vector. It consists of bits specified
 in HbViewFlag. These flags can be set before the view is
 d->mViewFlags = flags;
 if (mainWindow()) {
 // Statusbar-animation
 bool statusBarAnimating = false;
 HbStatusBar *statusBar = HbMainWindowPrivate::d_ptr(mainWindow())->mStatusBar;
-if ((d->mViewFlags & HbView::ViewStatusBarHidden) && statusBar->isVisible()) {
+if ((d->mViewFlags & HbView::ViewStatusBarHidden) && !(originalFlags & HbView::ViewStatusBarHidden)) {
 #ifdef HB_EFFECTS
 HbEffect::start(statusBar, "statusbar", "disappear", this, "statusBarEffectFinished");
 #endif // HB_EFFECTS
 statusBarAnimating = true;
-} else if (!(d->mViewFlags & HbView::ViewStatusBarHidden) && !statusBar->isVisible()) {
+} else if (!(d->mViewFlags & HbView::ViewStatusBarHidden) && (originalFlags & HbView::ViewStatusBarHidden)) {
 #ifdef HB_EFFECTS
 HbEffect::start(statusBar, "statusbar", "appear", this, "statusBarEffectFinished");
 #endif // HB_EFFECTS
 statusBarAnimating = true;
 }
 // Titlebar-animation
 bool titleBarAnimating = false;
 HbTitleBar *titleBar = HbMainWindowPrivate::d_ptr(mainWindow())->mTitleBar;
-if ((d->mViewFlags & HbView::ViewTitleBarHidden) && titleBar->isVisible()) {
+if ((d->mViewFlags & HbView::ViewTitleBarHidden) && !(originalFlags & HbView::ViewTitleBarHidden)) {
 #ifdef HB_EFFECTS
-HbEffect::start(titleBar, "titleBar", "disappear", this, "titleBarEffectFinished");
+HbEffect::start(titleBar, "titlebar", "disappear", this, "titleBarEffectFinished");
 #endif // HB_EFFECTS
 titleBarAnimating = true;
-} else if (!(d->mViewFlags & HbView::ViewTitleBarHidden) && !titleBar->isVisible()) {
+} else if (!(d->mViewFlags & HbView::ViewTitleBarHidden) && (originalFlags & HbView::ViewTitleBarHidden)) {
 #ifdef HB_EFFECTS
-HbEffect::start(titleBar, "titleBar", "appear", this, "titleBarEffectFinished");
+HbEffect::start(titleBar, "titlebar", "appear", this, "titleBarEffectFinished");
 #endif // HB_EFFECTS
 titleBarAnimating = true;
 }
 if (!statusBarAnimating) {
 }
 }
 }
 /*!
-Changes titlebar's visibility with pre-defined effect.
+Changes the titlebar's visibility and uses the pre-defined effect.
+\note This is a convenience function which uses setViewFlags() to (un)set
+the HbView::ViewTitleBarHidden flag.
+\sa setViewFlags()
 */
 void HbView::setTitleBarVisible(bool visible)
 {
 Q_D(HbView);
 if (visible) {
 setViewFlags(d->mViewFlags | HbView::ViewTitleBarHidden);
 }
 }
 /*!
-Changes statusbar's visibility with pre-defined effect.
+Changes the statusbar's visibility and uses the pre-defined effect.
+\note This is a convenience function which uses setViewFlags() to (un)set
+the HbView::ViewStatusBarHidden flag.
+\sa setViewFlags()
 */
 void HbView::setStatusBarVisible(bool visible)
 {
 Q_D(HbView);
 if (visible) {
 }
 /*!
 \overload
-The function adds \a action to preferred container's list of actions.  The
-ownership of \a action is not transferred.  The preferred container
+This adds the \a action to the list of actions in the view. You specify a preferred container
-specifies the action container (options menu, toolbar) where the action is
+in the UI where you would like the action to be added, e.g. the options menu or the toolbar.
-placed. If the container is the toolbar and the maximum toolbar button count
+However, if you choose the toolbar as the preferred container but no more buttons can fit in the
-is exceeded then the action may be moved to the options menu (if there are
+the toolbar, then the action might be moved to the options menu or it might displace another item in the toolbar.
-enough more prioritized actions).
+The result depends on the prioties of the actions already in the toolbar compared with the priority of
+the action you are adding.
+Ownership of the \a action is not transferred.
 */
 void HbView::addAction(HbAction *action, ActionContainer preferredActionContainer)
 {
 Q_D(HbView);
 d->preferredActionContainer = preferredActionContainer;
 addAction(action);
 }
 /*!
-\reimp
 */
 bool HbView::event(QEvent *event)
 {
 Q_D(HbView);
 if (event->type() == QEvent::ActionRemoved) {
 }
 return HbWidget::event(event);
 }
 /*!
-Removes the HbMenu, which is set to view and returns it.
+Removes the menu from the view and returns it to the caller.
-The ownership of the \a HbMenu is transferred to the caller.
+Ownership of the menu is transferred to the caller.
-\note This function is particularly useful if one wants to switch between
+\note This function is particularly useful if you want to switch between
-different views without deleting previous menu.
+different views without deleting the menu.
 \sa setMenu()
 */
 HbMenu* HbView::takeMenu()
 {
 // Reset the ownership
 if (menu) {
 menu->setParentItem(0);
 }
+// Titlebar must be informed
+if (mainWindow()) {
+HbMainWindowPrivate::d_ptr(mainWindow())->mTitleBar->propertiesChanged();
+}
 return menu;
 }
 #ifdef HB_EFFECTS
 /*
 Handles effect finished event for title bar animation
 */
 void HbView::titleBarEffectFinished(const HbEffect::EffectStatus &status)
 {
-if (status.reason == Hb::EffectFinished || status.reason == Hb::EffectCancelled
+Q_D(HbView);
-|| status.reason == Hb::EffectNotStarted) {
-HbMainWindowPrivate::d_ptr(mainWindow())->mTitleBar->propertiesChanged();
+HbMainWindow *mw = mainWindow();
-HbMainWindowPrivate::d_ptr(mainWindow())->mClippingItem->decoratorVisibilityChanged();
-}
+if (d->mNavigationActionSet) {
-if (mainWindow()) {
+HbMainWindowPrivate::d_ptr(mw)->mTitleBar->setNavigationAction(d->mNavigationAction);
-HbTitleBar *titleBar = HbMainWindowPrivate::d_ptr(mainWindow())->mTitleBar;
+} else {
+HbMainWindowPrivate::d_ptr(mw)->mTitleBar->setDefaultNavigationAction();
+}
+HbMainWindowPrivate::d_ptr(mw)->mTitleBar->propertiesChanged();
+HbMainWindowPrivate::d_ptr(mw)->mClippingItem->decoratorVisibilityChanged();
+if (mw) {
+HbTitleBar *titleBar = HbMainWindowPrivate::d_ptr(mw)->mTitleBar;
 if (titleBar) {
 if (status.effectEvent == "disappear") {
 titleBar->setVisible(false);
 } else {
 titleBar->setVisible(true);
 }
 }
 }
 /*
-Handles effect finished event for title bar animation
+Handles the effect finished event for title bar animation
 */
 void HbView::statusBarEffectFinished(const HbEffect::EffectStatus &status)
 {
-HbStatusBar *statusBar = HbMainWindowPrivate::d_ptr(mainWindow())->mStatusBar;
+HbMainWindow *mw = mainWindow();
+HbStatusBar *statusBar = HbMainWindowPrivate::d_ptr(mw)->mStatusBar;
 if (!statusBar) {
 return;
 }
-if (status.reason == Hb::EffectFinished || status.reason == Hb::EffectCancelled
+statusBar->propertiesChanged();
-|| status.reason == Hb::EffectNotStarted) {
+HbMainWindowPrivate::d_ptr(mw)->mClippingItem->decoratorVisibilityChanged();
-statusBar->propertiesChanged();
-HbMainWindowPrivate::d_ptr(mainWindow())->mClippingItem->decoratorVisibilityChanged();
+if (mw) {
-}
-if (mainWindow()) {
 if (status.effectEvent == "disappear") {
 statusBar->setVisible(false);
 } else {
 statusBar->setVisible(true);
 }
 }
 }
 #endif // HB_EFFECTS
 /*!
-Returns the currently set navigation action or 0 if there is none.
+Returns the current navigation action. If no navigation action has been set, then
+0 is returned.
-If setNavigationAction() was not called before for this view at all then the
+If setNavigationAction() has not been called for this view, then the
 default action will be returned.
 \sa setNavigationAction()
 */
 HbAction *HbView::navigationAction() const
 return mw ? HbMainWindowPrivate::d_ptr(mw)->mTitleBar->navigationAction() : 0;
 }
 }
 /*!
-Sets the navigation action, that is, the action that is associated with the
+Sets the navigation action, i.e., the action associated with the
 button that is typically located in the top-right corner. By default the
 action is the "quit" action.
-\a action can also be 0 in which case the previous navigation action is
+If you set the \a action to 0, the previous navigation action is
 unset and no new one will be set.
 Ownership of \a action is not taken.
 \sa navigationAction()

changeset 2	06ff229162e9
parent 1	f7ac710697a9
child 3	11d3954df52a