--- a/src/hbcore/gui/hbtoolbar.cpp Tue Jul 06 14:36:53 2010 +0300
+++ b/src/hbcore/gui/hbtoolbar.cpp Wed Aug 18 10:05:37 2010 +0300
@@ -55,49 +55,157 @@
@beta
@hbcore
\class HbToolBar
- \brief HbToolBar is a toolbar decorator.
+ \brief The HbToolBar class provides a widget that gives quick access to commands
+ associated with the view.
+
+ organizing a set of commands.
+
+ A toolbar provides similar functions to an options menu (HbMenu class). Like an options
+ menu, a toolbar represents commands that apply to the entire view and not to individual
+ items in the view. However, there are some important differences. A toolbar shows the
+ options as buttons (each of which can have an image and a label) whereas a menu shows the
+ options in a simple list. Typically the toolbar gives access to the view's most important
+ commands (called first order commands) and menus provide access to second order commands.
+ In an application that has multiple views (HbView class), typically the toolbar also
+ enables the user to switch quickly between views.
- The HbToolBar class represents an HbView toolbar. It provides the
- interface for adding actions to the toolbar.
+ \image html toolbar.png A toolbar that has five buttons
+
+ Toolbars contain \b actions, which are objects of class HbAction. A toolbar can contain
+ actions that represent a button and actions that open a popup, called a toolbar extension
+ (HbToolBarExtension class). This can contain additional actions or a widget, such as a list.
+
+ Use addAction() to create an action and add it to the toolbar. There are several overloads
+ of this function, which allow you to specify both a text and image or just a text and also to
+ connect the action's \link HbAction::triggered() triggered()\endlink signal to a slot on
+ a receiver object. The image and text, if specified, are applied to the toolbar button.
+ Using an image is recommended. Use the insertAction(), addActions() and insertActions() methods
+ (which are inherited from QGraphicsWidget) to add existing actions to the toolbar. Use
+ clearActions() to clear all of the actions from a toolbar and removeAction() to remove
+ individual actions.
- Toolbar actions are added using one of the addAction() methods.
- Calling addAction() adds an HbToolButton to the toolbar and
- triggers the action when the button is pressed. The image and text
- specified with the action are applied to the toolbar button.
+ Typically a toolbar can accommodate up to five actions. If you add more actions than can
+ fit, the additional actions are hidden behind the endmost button, which activates
+ a popup containing the extra actions. However, usability guidelines suggest that this
+ should be avoided. The order of the actions within the toolbar controls the order of the
+ buttons that the user sees.
+
+ When you add the actions directly to the toolbar, addAction() and addActions() append
+ the actions to the end of the toolbar and insertAction() and insertActions() enable you to
+ specify the required position. However, there is an alternative approach to ordering the
+ action items. That is to call HbView::addAction() to add actions to the \b view and
+ let the view distribute them to the options menu or toolbar, depending on the preference
+ set, the UI command distribution template, and taking into account the available space in
+ the toolbar. The menu and toolbar then order the actions according to their defined roles
+ and the UI command container template. This approach makes it easier to create consistent
+ user interfaces and applications that work well on a variety of different devices.
+
+ After you add an action item to a toolbar, you can connect its \link HbAction::triggered()
+ triggered()\endlink signal to a slot on a receiver object. Alternatively you can use one of
+ the addAction() overloads that allow you to add an action and specify a receiver slot at
+ the same time. The receiver is notified when the action is \link HbAction::triggered()
+ triggered()\endlink, which means that the user has selected the button; for example, by
+ tapping it.
+
+ By default, the toolbar is horizontal and positioned at the bottom of the view. Use
+ setOrientation() to change the orientation to vertical. The toolbar is then positioned on
+ the right of the view.
+
+ You add the toolbar to the view by calling HbView::setToolBar(). If you want to hide the
+ toolbar, it is recommended that you call HbView::setItemVisible() rather than calling
+ \link QGraphicsItem::hide() hide()\endlink or \link QGraphicsItem::setVisible()
+ setVisible()\endlink on the toolbar itself.
+
+ You can disable a toolbar button by calling \c setEnabled(false) on the action. This
+ property is inherited from QAction. Other properties inherited from QAction enable
+ you to specify that an action is checkable (which means it has an on/off state), to
+ set a keyboard shortcut, and so on.
- HbToolBar also provides methods for adding pop-up toolbar
- extensions, represented by HbToolBarExtension objects.
+ \b Note: When you add an action to the toolbar, the HbToolBar implementation creates an
+ internal HbToolButton object. This is not accessible and is an implementation detail that
+ might change in the future.
+
+ \section _usecases_hbtoolbar Using the HbToolBar class
+
+ \subsection _uc_001_hbtoolbar Creating a toolbar
+
+ The following example demonstrates creating a toolbar and adding an action
+ to it and then adding the toolbar to the view:
+
+ \code
+ // Create the toolbar object.
+ HbToolBar *toolBar = new HbToolBar();
+
+ HbAction *closeAction = toolBar->addAction(tr("Close"));
+
+ // Add the toolbar to the view.
+ myView->setToolBar(toolBar);
+ \endcode
+
+ \subsection _uc_002_hbtoolbar Connecting a toolbar action's signal to a slot
+
+ You must connect the action's \link HbAction::triggered() triggered()\endlink
+ signal to a suitable slot on the receiver object that is to carry out the command.
+ For example:
+
+ \code
+ QObject::connect(closeAction, SIGNAL(triggered(bool)), this, SLOT(closeAccount(bool)));
+ \endcode
- Example usage:
- \dontinclude ultimatecodesnippet/ultimatecodesnippet.cpp
- \skip Start of snippet 1
- \until End of snippet 1
+ Alternatively you can add the action and connect its signal to a slot by using one of the
+ the convenience \link HbToolBar::addAction(const QString &, const QObject *, const char *)
+ addAction() \endlink overloads that let you add the action to the toolbar and connect its
+ signal to a suitable slot in one call. For example:
+
+ \code
+ toolBar->addAction(tr("Open"), d, SLOT(openAccount(bool)));
+ \endcode
+
+ \subsection _uc_003_hbtoolbar Adding actions to the view
+
+ As mentioned above, there are advantages in terms of consistency and portability to
+ adding toolbar actions to the view rather than to the toolbar itself. The following example
+ demonstrates this. It creates two action items, specifies their command roles, and then
+ adds them to the view, specifying the toolbar as the preferred container. The view takes
+ this preference into account but may place them in the options menu if, for example, the
+ toolbar is already full. The menu and toolbar order the actions according to their defined
+ command roles.
- Note: calling hide() or setVisible(bool) on toolbar is not
- recommended. Instead, use \a HbView::setItemVisible(), as in
- this example:
+ \code
+ HbAction *actionCircle = new HbAction();
+ actionCircle->setToolTip("Circle");
+ actionCircle->setIcon(HbIcon("circle.png"));
+ actionCircle->setCommandRole(HbAction::OtherRole);
+
+ HbAction *actionStar = new HbAction();
+ actionStar->setToolTip("Star");
+ actionStar->setIcon(HbIcon("star.png"));
+ actionStar->setCommandRole(HbAction::OtherRole);
+
+ // Add actions to the view.
+ myView->addAction(actionStar, HbView::ToolBar);
+ myView->addAction(actionCircle, HbView::ToolBar);
+ \endcode
+
+ \subsection _uc_004_hbtoolbar Hiding the toolbar
+
+ The next example demonstrates calling HbView::setItemVisible() to hide the
+ toolbar. This is the recommended way of hiding a toolbar:
\dontinclude ultimatecodesnippet/ultimatecodesnippet.cpp
\skip Start of snippet 59
\until End of snippet 59
-
+ \sa HbToolBarExtension, HbView, HbMenu, HbAction
*/
/*!
- \reimp
\fn int HbToolBar::type() const
- */
-
-/*!
- \fn void HbToolBar::addAction(QAction *action)
- Adds a new action to the toolbar. It's appended to the end
- of the toolbar. Toolbar doesn't take ownership of the QAction.
- */
+*/
// ======== MEMBER FUNCTIONS ========
/*!
- Constructs a tool bar with \a parent.
+ Constructs a toolbar with the given \a parent.
*/
HbToolBar::HbToolBar( QGraphicsItem *parent )
@@ -140,10 +248,11 @@
}
/*!
- \overload
+ Creates a new action with the given \a text and adds the action to
+ the end of the toolbar. The toolbar takes ownership of the new action.
- Creates a new action with the given \a text. This action is added to
- the end of the toolbar. Toolbar retains ownership of the action.
+ \overload
+ \return The new action.
*/
HbAction *HbToolBar::addAction( const QString &text )
{
@@ -153,10 +262,11 @@
}
/*!
- \overload
+ Creates a new action with the given \a icon and \a text and adds the
+ action to the end of the toolbar. The toolbar takes ownership of the new action.
- Creates a new action with the given \a icon and \a text. This
- action is added to the end of the toolbar. Toolbar retains ownership of the action.
+ \overload
+ \return The new action.
*/
HbAction *HbToolBar::addAction( const HbIcon &icon, const QString &text )
{
@@ -166,12 +276,16 @@
}
/*!
- \overload
+ Creates a new action with the given \a text, adds the action to the
+ end of the toolbar, and connects the action's \link HbAction::triggered()
+ triggered()\endlink signal to a receiver object's slot. The toolbar takes ownership
+ of the new action.
- Creates a new action with the given \a text. This action is added to
- the end of the toolbar. The action's \link HbAction::triggered()
- triggered()\endlink signal is connected to \a member in \a
- receiver. Toolbar retains ownership of the action.
+ \overload
+ \param text The text for the new action.
+ \param receiver The object that is to receive the new action's signal.
+ \param member The slot on the receiver to which the action's signal is to connect.
+ \return The new action.
*/
HbAction *HbToolBar::addAction( const QString &text, const QObject *receiver, const char *member )
{
@@ -182,12 +296,17 @@
}
/*!
- \overload
+ Creates a new action with the given \a icon and \a text, adds the action
+ to the end of the toolbar, and connects the action's \link HbAction::triggered()
+ triggered()\endlink signal to a receiver object's slot. The toolbar takes ownership
+ of the new action.
- Creates a new action with the icon \a icon and text \a text. This
- action is added to the end of the toolbar. The action's \link
- HbAction::triggered() triggered()\endlink signal is connected to \a
- member in \a receiver. Toolbar retains ownership of the action.
+ \overload
+ \param icon The image for the new action.
+ \param text The text for the new action.
+ \param receiver The object that is to receive the new action's signal.
+ \param member The slot on the receiver to which the action's signal is to connect.
+ \return The new action.
*/
HbAction *HbToolBar::addAction( const HbIcon &icon, const QString &text, const QObject *receiver, const char *member )
{
@@ -198,8 +317,11 @@
}
/*!
- This convenience function adds the \a extension as an extension popup
- to the toolbar. Returns the HbAction triggering the \a extension.
+ Adds \a extension as a toolbar extension at the end of the toolbar.
+
+ \return The action that opens the new extension.
+
+ \sa insertExtension()
*/
HbAction *HbToolBar::addExtension( HbToolBarExtension *extension )
{
@@ -207,13 +329,13 @@
}
/*!
- This convenience function inserts the \a extension as an extension popup
- before the action \a before.
+ Inserts \a extension as a toolbar extension in front of the \a before action, provided
+ it is a valid toolbar action. If \a before is 0 or is not valid, this function adds
+ the extension to the end of the toolbar.
- It appends the action if \a before is 0 or \a before is not a valid
- action for this widget.
+ \return The action that opens the new extension.
- Returns the HbAction triggering the \a extension.
+ \sa addExtension()
*/
HbAction *HbToolBar::insertExtension( HbAction *before, HbToolBarExtension *extension )
{
@@ -225,22 +347,33 @@
return extension->extensionAction();
}
-/*! @beta
- \brief Returns the orientation of the tool bar.
+/*!
+ Returns the orientation of the toolbar.
- \sa setOrientation
- */
+ @beta
+
+ \sa setOrientation()
+*/
Qt::Orientation HbToolBar::orientation() const
{
Q_D(const HbToolBar);
return d->mOrientation;
}
-/*! @beta
- Sets the \a orientation of the tool bar.
+/*!
+ Sets the orientation of the toolbar.
+
+ @beta
+
+ \b Example:
- \sa orientation
- */
+ \code
+ HbToolBar *toolBar = new HbToolBar();
+ toolBar->setOrientation(Qt::Vertical);
+ \endcode
+
+ \sa orientation()
+*/
void HbToolBar::setOrientation( Qt::Orientation orientation )
{
Q_D(HbToolBar);
@@ -250,8 +383,8 @@
}
/*!
- Emits areaChanged() whenever the tool bar's visibility or position changes.
-*/
+ \reimp
+ */
QVariant HbToolBar::itemChange( GraphicsItemChange change, const QVariant &value )
{
Q_D(HbToolBar);
@@ -268,7 +401,7 @@
if (d->mOrientationEffectsRunning)
return result;
if (value.toBool()) {
- if (d->mDoLayout && d->mDoLayoutPending) {
+ if (d->mDoLayoutPending && d->polished) {
d->doLayout();
}
if (!d->mDialogToolBar) {
@@ -277,10 +410,10 @@
if (!d->delayedStartEffects && d->hasEffects && !d->mSuppressNextAppearEffect) {
d->startAppearEffect();
}
- d->mSuppressNextAppearEffect = false;
d->delayedHide = d->hasEffects;
}
} else {
+ d->mSuppressNextAppearEffect = false;
if(d->moreExtension && d->moreExtension->isVisible()){
d->moreExtension->setVisible(false);
}
@@ -323,7 +456,7 @@
}
/*!
- Reimplemented from QGraphicsWidget::changeEvent().
+ \reimp
*/
void HbToolBar::changeEvent( QEvent *event )
{
@@ -337,13 +470,13 @@
}
/*!
- Reimplemented from QGraphicsWidget::resizeEvent().
+ \reimp
*/
void HbToolBar::resizeEvent(QGraphicsSceneResizeEvent *event)
{
Q_D(HbToolBar);
HbWidget::resizeEvent(event);
- if (isVisible() && d->mDoLayout) {
+ if (isVisible()) {
d->updateToolBarForSizeChange();
}
}
@@ -357,9 +490,6 @@
}
/*!
- \reimp
- */
-/*!
\reimp
*/
bool HbToolBar::event(QEvent *event)
@@ -394,6 +524,9 @@
}
+/*!
+ \reimp
+ */
void HbToolBar::updatePrimitives()
{
Q_D(HbToolBar);
@@ -406,15 +539,15 @@
}
/*!
- \reimp
- */
+ \reimp
+ */
void HbToolBar::polish(HbStyleParameters ¶ms)
{
Q_D(HbToolBar);
- HbWidget::polish(params);
- if (d->mDoLayoutPending) {
+ if (d->mDoLayoutPending && isVisible()) {
d->doLayout();
}
+ HbWidget::polish(params);
}
#include "moc_hbtoolbar.cpp"