58     \brief HbToolBar is a toolbar decorator.

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

    59 

    59     associated with the view.

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

    60 

    61     interface for adding actions to the toolbar.

    61     organizing a set of commands.

    62 

    62 

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

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

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

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

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

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

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

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

    67 

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

    68     HbToolBar also provides methods for adding pop-up toolbar

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

    69     extensions, represented by HbToolBarExtension objects.

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

    70 

    70     enables the user to switch quickly between views.

    71     Example usage:

    71 

    72     \dontinclude ultimatecodesnippet/ultimatecodesnippet.cpp

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

    73     \skip Start of snippet 1

    73 

    74     \until End of snippet 1

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

    75 

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

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

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

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

    77 

    78     this example:

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

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

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

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

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

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

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

    85     individual actions.

    86 

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

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

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

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

    91     buttons that the user sees.

    92 

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

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

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

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

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

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

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

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

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

   102 

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

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

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

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

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

   108     tapping it.

   109 

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

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

   112     the right of the view.

   113 

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

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

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

   117     setVisible()\endlink on the toolbar itself.

   118 

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

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

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

   122     set a keyboard shortcut, and so on.

   123 

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

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

   126     might change in the future.

   127 

   128     \section _usecases_hbtoolbar Using the HbToolBar class

   129 

   130     \subsection _uc_001_hbtoolbar Creating a toolbar

   131 

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

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

   134 

   135     \code

   136     // Create the toolbar object.

   137     HbToolBar *toolBar = new HbToolBar();

   138 

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

   140 

   141     // Add the toolbar to the view.

   142     myView->setToolBar(toolBar);

   143     \endcode

   144 

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

   146 

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

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

   149     For example:

   150 

   151     \code

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

   153     \endcode

   154 

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

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

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

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

   159 

   160     \code

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

   162     \endcode

   163 

   164     \subsection _uc_003_hbtoolbar Adding actions to the view

   165 

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

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

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

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

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

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

   172     command roles.

   173 

   174     \code

   175     HbAction *actionCircle = new HbAction();

   176     actionCircle->setToolTip("Circle");

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

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

   179 

   180     HbAction *actionStar = new HbAction();

   181     actionStar->setToolTip("Star");

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

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

   184 

   185     // Add actions to the view.

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

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

   188     \endcode

   189 

   190     \subsection _uc_004_hbtoolbar Hiding the toolbar

   191 

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

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

    83    

   198     \sa HbToolBarExtension, HbView, HbMenu, HbAction

    84 */

   199 */

    85 

   200 

    86 /*!

   201 /*!

    87     \reimp

    89  */

   203 */

    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.

   208     Constructs a toolbar with the given \a parent.

   144 

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

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

   285     \param text The text for the new action.

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

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

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

   288     \return The new action.

   174     receiver. Toolbar retains ownership of the action.

   186 

   305     \param icon The image for the new action.

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

   306     \param text The text for the new action.

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

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

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

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

   309     \return The new action.

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

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

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

   321 

   322     \return The action that opens the new extension.

   323 

   324     \sa insertExtension()

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

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

   211     before the action \a before.

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

   212 

   334     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

   335 

   214     action for this widget.

   336     \return The action that opens the new extension.

   215 

   337 

   216     Returns the HbAction triggering the \a extension.

   338     \sa addExtension()

   228 /*! @beta

   350 /*!

   229     \brief  Returns the orientation of the tool bar.

   351     Returns the orientation of the toolbar.

   230 

   352 

   231     \sa setOrientation

   353     @beta

   232  */

   354 

   355     \sa setOrientation()

   356 */

   239 /*! @beta

   363 /*!

   240     Sets the \a orientation of the tool bar.

   364     Sets the orientation of the toolbar.

   241 

   365 

   242     \sa orientation

   366     @beta

   243  */

   367 

   368     \b Example:

   369 

   370     \code

   371     HbToolBar *toolBar = new HbToolBar();

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

   373     \endcode

   374 

   375     \sa orientation()

   376 */

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

   386     \reimp

   254 */

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

   473     \reimp

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

   479     if (isVisible()) {

   409   \reimp

   542     \reimp

   410   */

   543  */