/****************************************************************************

**

** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (developer.feedback@nokia.com)

**

** This file is part of the HbCore module of the UI Extensions for Mobile.

**

** GNU Lesser General Public License Usage

** This file may be used under the terms of the GNU Lesser General Public

** License version 2.1 as published by the Free Software Foundation and

** appearing in the file LICENSE.LGPL included in the packaging of this file.

** Please review the following information to ensure the GNU Lesser General

** Public License version 2.1 requirements will be met:

** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at developer.feedback@nokia.com.

**

****************************************************************************/

#include "hbview.h"

#include "hbview_p.h"

#include "hbinstance.h"

#include "hbmenu.h"

#include "hbmenu_p.h"

#include "hbtoolbar.h"

#include "hbstackedlayout.h"

#include "hbdockwidget.h"

#include "hbwidget_p.h"

#include "hbmainwindow_p.h"

#include "hbtitlebar_p.h"

#include "hbstatusbar_p.h"

#include "hbscreen_p.h"

#include "hbviewactionmanager_p.h"

#include "hbglobal_p.h"

#include <QPointer>

/*!

    @stable

    @hbcore

    \class HbView

    \brief The HbView class defines one screen of user interface content.

    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.

    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.

    \image html hbview_wireframes.png "Wireframes of two different views in a messaging application"

    \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.

    See the HbMainWindow class for information about switching between different views.

    \subsection _uc_001_hbview Hiding and showing the chrome

    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.

    \code

    // Hide all the chrome items

    myView.setContentFullScreen(true)

    // Show all the chrome items

    myView.setContentFullScreen(false)

    // Hide the toolbar

    myView.hideItems(Hb::SceneItem::ToolBarItem)

    // Show the toolbar

    myView.showItems(Hb::SceneItem::ToolBarItem)

    \endcode

    \subsection _uc_002_hbview Creating a simple view

    This code snippet shows the most basic way to create an application with a single view.

    \code

    #include <hbapplication.h>

    #include <hbmainwindow.h>

    #include <hbview.h>

    int main(int argc, char *argv[])

    {

        HbApplication app(argc, argv);

        HbMainWindow window;

        HbView *view = new HbView();

        view->setTitle("My View");

        window.addView(view);

        window.show();

        return app.exec();

    }

    \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 the titlebar showing the possibility to

    minimize the titlebar, e.g. swipe it off the screen.

*/

/*!

    \var HbView::ViewTitleBarMinimized

    Show the title bar in minimized state.

*/

/*!

    \var HbView::ViewTitleBarHidden

    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

    Show normal style title bar but make it transparent.

    This flag is normally used in combination with TitleBarFloating flag.

*/

/*!

    \var HbView::ViewTitleBarFloating

    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

    Do not show the statusbar at all.

    This flag is normally used in combination with the ViewTitleBarHidden flag.

*/

/*!

    \var HbView::ViewStatusBarTransparent

    Show the statusbar with normal content but transparent.

    This flag is normally used in combination with ViewStatusBarFloating flag.

*/

/*!

    \var HbView::ViewStatusBarFloating

    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.

*/

/*!

    \var HbView::ViewDisableRelayout

    This flag disables relayoting of the view when hiding the title and/or status bar.

    This flag is normally used in combination with ViewTitleBarHidden and/or ViewStatusBarHiddenflag.

*/

/*!

    \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 is replaced by a different title.

    \sa setTitle()

 */

/*!

    \fn void HbView::iconChanged(const HbIcon &icon)

    This signal is emitted when the icon is replaced by a different icon.

    \sa setIcon()

 */

/*!

    \fn void HbView::toolBarChanged()

    This signal is emitted when toolbar is replaced by a different toolbar.

    \sa setToolBar()

 */

/*!

   \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),

      mViewFlags(HbView::ViewFlagNone),

      actionManager(0),

      preferredActionContainer(HbView::NotSpecified),

      mNavigationAction(0),

      mNavigationActionSet(false)

{

}

/*!

    \internal

 */

HbViewPrivate::~HbViewPrivate()

{

}

/*!

    Constructs a view with the given \a parent.

*/

HbView::HbView(QGraphicsItem *parent) :

    HbWidget(*new HbViewPrivate, parent)

{

    Q_D(HbView);

    d->q_ptr = this;

}

/*!

    \internal

 */

HbView::HbView(HbViewPrivate &dd, QGraphicsItem *parent):

    HbWidget(dd, parent)

{

    Q_D(HbView);

    d->q_ptr = this;

}

/*!

    Destructor.

*/

HbView::~HbView()

{

}

/*!

  Returns the title of the view. If no title has been defined, the return value is a null string.

    \sa setTitle()

 */

QString HbView::title() const

{

    Q_D(const HbView);

    return d->title;

}

/*!

    Sets the title of the view.

    \sa title()

 */

void HbView::setTitle(const QString &title)

{

    Q_D(HbView);

    if (d->title != title) {

        d->title = title;

        emit titleChanged(title);

    }

}

/*!

    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 associated with the view.

    \sa icon()

 */

void HbView::setIcon(const HbIcon &icon)

{

    Q_D(HbView);

    if (d->icon != icon) {

        d->icon = icon;

        emit iconChanged(icon);

    }

}

/*!

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

*/

HbMenu *HbView::menu() const

{

    Q_D(const HbView);

    if (!d->menu) {

        const_cast<HbView *>(this)->setMenu(new HbMenu());

    }

    if (mainWindow()) {

        d->menu->setLayoutDirection(mainWindow()->layoutDirection());

    }

    return d->menu;

}

/*!

    Sets the menu for the view. Setting the menu to 0 will remove any existing menu from the view.

    The view takes ownership of the \a menu.

    \sa HbMenu menu()

*/

void HbView::setMenu(HbMenu *menu)

{

    Q_D(HbView);

    if (d->menu != menu) {

        if (d->menu) {

            d->menu->deleteLater();

        }

        d->menu = menu;

        if (d->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 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()

*/

HbToolBar *HbView::toolBar() const

{

    Q_D(const HbView);

    if (!d->toolBar) {

        HbView *that = const_cast<HbView *>(this);

        that->setToolBar(new HbToolBar);

    }

    return d->toolBar;

}

/*!

    Sets the toolbar for the view. Setting the toolbar to 0 will remove it from the view.

    The view takes ownership of the toolbar, but the view is not set as the parent.

    \sa HbToolBar toolBar()

*/

void HbView::setToolBar(HbToolBar *toolBar)

{

    Q_D(HbView);

    if (d->toolBar != toolBar) {

        if (d->toolBar) {

            d->toolBar->deleteLater();

        }

        d->toolBar = toolBar;

        emit toolBarChanged();

    }

}

/*!

Removes the toolbar from the view and returns it to the caller.

Ownership of the toolbar is transferred to the caller.

\note This function is particularly useful if you want to switch to a

different view and keep the same toolbar.

    \sa setToolBar()

*/

HbToolBar *HbView::takeToolBar()

{

    Q_D(HbView);

    HbToolBar *toolBar = d->toolBar;

    d->toolBar = 0;

    // Reset the ownership

    if (toolBar) {

        toolBar->setParentItem(0);

    }

    return toolBar;

}

/*!

    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 when a new dock widget is created by this method.

    Ownership is not transferred.

    \sa HbDockWidget setDockWidget()

*/

HbDockWidget *HbView::dockWidget() const

{

    Q_D(const HbView);

    if (!d->dockWidget) {

        HbView *that = const_cast<HbView *>(this);

        that->setDockWidget(new HbDockWidget);

    }

    return d->dockWidget;

}

/*!

    Sets the dock widget for the view. Setting the dock widget to \c 0 will remove it from the view.

    This does take ownership of the \a dockWidget, but does not become the parent.

    \sa HbDockWidget dockWidget()

*/

void HbView::setDockWidget(HbDockWidget *dockWidget)

{

    Q_D(HbView);

    if (d->dockWidget != dockWidget) {

        if (d->dockWidget) {

            d->dockWidget->deleteLater();

        }

        d->dockWidget = dockWidget;

        emit dockWidgetChanged();

    }

}

/*!

    Returns the widget that makes up the view. If the widget has not been set, this method will return 0.

    \sa setWidget takeWidget

*/

QGraphicsWidget *HbView::widget() const

{

    Q_D(const HbView);

    return d->widget;

}