58     \brief HbToolBar is a toolbar decorator.

    59     \brief The HbToolBar class provides a widget that gives quick access to commands

    59 

    60     associated with the view.

    60     The HbToolBar class represents an HbView toolbar. It provides the

    61 

    61     interface for adding actions to the toolbar.

    62     A toolbar provides similar functions to an options menu (HbMenu class). Like an options

    62 

    63     menu, a toolbar represents commands that apply to the entire view and not to individual

    63     Toolbar actions are added using one of the addAction() methods.

    64     items in the view. However, there are some important differences. A toolbar shows the

    64     Calling addAction() adds an HbToolButton to the toolbar and

    65     options as buttons (each of which can have an image and a label) whereas a menu shows the

    65     triggers the action when the button is pressed. The image and text

    66     options in a simple list. Typically the toolbar gives access to the view's most important

    66     specified with the action are applied to the toolbar button.

    67     commands (called first order commands) and menus provide access to second order commands.

    67 

    68     In an application that has multiple views (HbView class), typically the toolbar also

    68     HbToolBar also provides methods for adding pop-up toolbar

    69     enables the user to switch quickly between views.

    69     extensions, represented by HbToolBarExtension objects.

    70 

    70 

    71     \image html toolbar.png A toolbar that has five buttons

    71     Example usage:

    72 

    72     \dontinclude ultimatecodesnippet/ultimatecodesnippet.cpp

    73     Toolbars contain \b actions, which are objects of class HbAction. A toolbar can contain

    73     \skip Start of snippet 1

    74     actions that represent a button and actions that open a popup, called a toolbar extension

    74     \until End of snippet 1

    75     (HbToolBarExtension class). This can contain additional actions or a widget, such as a list.

    75 

    76 

    76     Note: calling hide() or setVisible(bool) on toolbar is not

    77     Use addAction() to create an action and add it to the toolbar. There are several overloads

    77     recommended.  Instead, use \a HbView::setItemVisible(), as in 

    78     of this function, which allow you to specify both a text and image or just a text and also to

    78     this example:

    79     connect the action's \link HbAction::triggered() triggered()\endlink signal to a slot on

    80     a receiver object. The image and text, if specified, are applied to the toolbar button.

    81     Using an image is recommended. Use the insertAction(), addActions() and insertActions() methods

    82     (which are inherited from QGraphicsWidget) to add existing actions to the toolbar. Use

    83     clearActions() to clear all of the actions from a toolbar and removeAction() to remove

    84     individual actions.

    85 

    86     Typically a toolbar can accommodate up to five actions. If you add more actions than can

    87     fit, the additional actions are hidden behind the endmost button, which activates

    88     a popup containing the extra actions. However, usability guidelines suggest that this

    89     should be avoided. The order of the actions within the toolbar controls the order of the

    90     buttons that the user sees.

    91 

    92     When you add the actions directly to the toolbar, addAction() and addActions() append

    93     the actions to the end of the toolbar and insertAction() and insertActions() enable you to

    94     specify the required position. However, there is an alternative approach to ordering the

    95     action items. That is to call HbView::addAction() to add actions to the \b view and

    96     let the view distribute them to the options menu or toolbar, depending on the preference

    97     set, the UI command distribution template, and taking into account the available space in

    98     the toolbar. The menu and toolbar then order the actions according to their defined roles

    99     and the UI command container template. This approach makes it easier to create consistent

   100     user interfaces and applications that work well on a variety of different devices.

   101 

   102     After you add an action item to a toolbar, you can connect its \link HbAction::triggered()

   103     triggered()\endlink signal to a slot on a receiver object. Alternatively you can use one of

   104     the addAction() overloads that allow you to add an action and specify a receiver slot at

   105     the same time. The receiver is notified when the action is \link HbAction::triggered()

   106     triggered()\endlink, which means that the user has selected the button; for example, by

   107     tapping it.

   108 

   109     By default, the toolbar is horizontal and positioned at the bottom of the view. Use

   110     setOrientation() to change the orientation to vertical. The toolbar is then positioned on

   111     the right of the view.

   112 

   113     You add the toolbar to the view by calling HbView::setToolBar(). If you want to hide the

   114     toolbar, it is recommended that you call HbView::setItemVisible() rather than calling

   115     \link QGraphicsItem::hide() hide()\endlink or \link QGraphicsItem::setVisible()

   116     setVisible()\endlink on the toolbar itself.

   117 

   118     You can disable a toolbar button by calling \c setEnabled(false) on the action. This

   119     property is inherited from QAction. Other properties inherited from QAction enable

   120     you to specify that an action is checkable (which means it has an on/off state), to

   121     set a keyboard shortcut, and so on.

   122 

   123     \b Note: When you add an action to the toolbar, the HbToolBar implementation creates an

   124     internal HbToolButton object. This is not accessible and is an implementation detail that

   125     might change in the future.

   126 

   127     \section _usecases_hbtoolbar Using the HbToolBar class

   128 

   129     \subsection _uc_001_hbtoolbar Creating a toolbar

   130 

   131     The following example demonstrates creating a toolbar and adding an action

   132     to it and then adding the toolbar to the view:

   133 

   134     \code

   135     // Create the toolbar object.

   136     HbToolBar *toolBar = new HbToolBar();

   137 

   138     HbAction *closeAction = toolBar->addAction(tr("Close"));

   139 

   140     // Add the toolbar to the view.

   141     myView->setToolBar(toolBar);

   142     \endcode

   143 

   144     \subsection _uc_002_hbtoolbar Connecting a toolbar action's signal to a slot

   145 

   146     You must connect the action's \link HbAction::triggered() triggered()\endlink

   147     signal to a suitable slot on the receiver object that is to carry out the command.

   148     For example:

   149 

   150     \code

   151     QObject::connect(closeAction, SIGNAL(triggered(bool)), this, SLOT(closeAccount(bool)));

   152     \endcode

   153 

   154     Alternatively you can add the action and connect its signal to a slot by using one of the

   155     the convenience \link HbToolBar::addAction(const QString &, const QObject *, const char *)

   156     addAction() \endlink overloads that let you add the action to the toolbar and connect its

   157     signal to a suitable slot in one call. For example:

   158 

   159     \code

   160     toolBar->addAction(tr("Open"), d, SLOT(openAccount(bool)));

   161     \endcode

   162 

   163     \subsection _uc_003_hbtoolbar Adding actions to the view

   164 

   165     As mentioned above, there are advantages in terms of consistency and portability to

   166     adding toolbar actions to the view rather than to the toolbar itself. The following example

   167     demonstrates this. It creates two action items, specifies their command roles, and then

   168     adds them to the view, specifying the toolbar as the preferred container. The view takes

   169     this preference into account but may place them in the options menu if, for example, the

   170     toolbar is already full. The menu and toolbar order the actions according to their defined

   171     command roles.

   172 

   173     \code

   174     HbAction *actionCircle = new HbAction();

   175     actionCircle->setToolTip("Circle");

   176     actionCircle->setIcon(HbIcon("circle.png"));

   177     actionCircle->setCommandRole(HbAction::OtherRole);

   178 

   179     HbAction *actionStar = new HbAction();

   180     actionStar->setToolTip("Star");

   181     actionStar->setIcon(HbIcon("star.png"));

   182     actionStar->setCommandRole(HbAction::OtherRole);

   183 

   184     // Add actions to the view.

   185     myView->addAction(actionStar, HbView::ToolBar);

   186     myView->addAction(actionCircle, HbView::ToolBar);

   187     \endcode

   188 

   189     \subsection _uc_004_hbtoolbar Hiding the toolbar

   190 

   191     The next example demonstrates calling HbView::setItemVisible() to hide the

   192     toolbar. This is the recommended way of hiding a toolbar:

    83    

   197     \sa HbToolBarExtension, HbView, HbMenu, HbAction

    84 */

   198 */

    85 

   199 

    86 /*!

   200 /*!

    87     \reimp

    89  */

   202 */

    90 

    91 /*!

    92     \fn void HbToolBar::addAction(QAction *action)

    93     Adds a new action to the toolbar. It's appended to the end

    94     of the toolbar. Toolbar doesn't take ownership of the QAction.

    95   */

   100     Constructs a tool bar with \a parent.

   207     Constructs a toolbar with the given \a parent.

   110 

   217     setFlag(QGraphicsItem::ItemHasNoContents, true);

   144 

   254     \return The new action.

   145     Creates a new action with the given \a text. This action is added to

   146     the end of the toolbar. Toolbar retains ownership of the action.

   157 

   268     \return The new action.

   158     Creates a new action with the given \a icon and \a text. This

   159     action is added to the end of the toolbar. Toolbar retains ownership of the action.

   170 

   284     \param text The text for the new action.

   171     Creates a new action with the given \a text. This action is added to

   285     \param receiver The object that is to receive the new action's signal.

   172     the end of the toolbar. The action's \link HbAction::triggered()

   286     \param member The slot on the receiver to which the action's signal is to connect.

   173     triggered()\endlink signal is connected to \a member in \a

   287     \return The new action.

   174     receiver. Toolbar retains ownership of the action.

   186 

   304     \param icon The image for the new action.

   187     Creates a new action with the icon \a icon and text \a text. This

   305     \param text The text for the new action.

   188     action is added to the end of the toolbar. The action's \link

   306     \param receiver The object that is to receive the new action's signal.

   189     HbAction::triggered() triggered()\endlink signal is connected to \a

   307     \param member The slot on the receiver to which the action's signal is to connect.

   190     member in \a receiver. Toolbar retains ownership of the action.

   308     \return The new action.

   201     This convenience function adds the \a extension as an extension popup

   319     Adds \a extension as a toolbar extension at the end of the toolbar.

   202     to the toolbar. Returns the HbAction triggering the \a extension.

   320 

   321     \return The action that opens the new extension.

   322 

   323     \sa insertExtension()

   210     This convenience function inserts the \a extension as an extension popup

   331     Inserts \a extension as a toolbar extension in front of the \a before action, provided

   211     before the action \a before.

   332     it is a valid toolbar action. If \a before is 0 or is not valid, this function adds

   212 

   333     the extension to the end of the toolbar.

   213     It appends the action if \a before is 0 or \a before is not a valid

   334 

   214     action for this widget.

   335     \return The action that opens the new extension.

   215 

   336 

   216     Returns the HbAction triggering the \a extension.

   337     \sa addExtension()

   228 /*! @beta

   349 /*!

   229     \brief  Returns the orientation of the tool bar.

   350     Returns the orientation of the toolbar.

   230 

   351 

   231     \sa setOrientation

   352     @beta

   232  */

   353 

   354     \sa setOrientation()

   355 */

   239 /*! @beta

   362 /*!

   240     Sets the \a orientation of the tool bar.

   363     Sets the orientation of the toolbar.

   241 

   364 

   242     \sa orientation

   365     @beta

   243  */

   366 

   367     \b Example:

   368 

   369     \code

   370     HbToolBar *toolBar = new HbToolBar();

   371     toolBar->setOrientation(Qt::Vertical);

   372     \endcode

   373 

   374     \sa orientation()

   375 */

   250 }

   382    

   251 

   383 }

   252 /*!

   384 

   253     Emits areaChanged() whenever the tool bar's visibility or position changes.

   385 /*!

   254 */

   386     \reimp

   387  */

   271             if (d->mDoLayout && d->mDoLayoutPending) {

   404             if (d->mDoLayoutPending && d->polished) {

   326     Reimplemented from QGraphicsWidget::changeEvent().

   459     \reimp

   340     Reimplemented from QGraphicsWidget::resizeEvent().

   481     \reimp

   346     if (isVisible() && d->mDoLayout) {

   487     if (d->polished && isVisible()) {

   409   \reimp

   550     \reimp

   410   */

   551  */