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

equal deleted inserted replaced

-:923ff622b8b9
+:4633027730f5
 }
 }
 void HbMenuPrivate::delayedLayout()
 {
-createMenuView();
+if (delayMenuConstruction) {
-if(menuItemView)
+createMenuView();
-menuItemView->doDelayedLayout();
+if(menuItemView)
-delayMenuConstruction = false;
+menuItemView->doDelayedLayout();
+delayMenuConstruction = false;
+}
 }
 void HbMenuPrivate::changeToOptionsMenu()
 {
 menuType = HbMenu::OptionsMenu;
 if (menuItemView)
 menuItemView->updateActionItem(actionEvent->action());
 }
 /*
 Returns current focusable action based on current row of the menuItemView or index if specified.
 If there is no focusable action it returns 0.
 Also returns the active item representing the active action or 0.
 */
 HbAction *HbMenuPrivate::activeAction(HbMenuItem *&activeItem) const
 {
 if(!menuItemView)
 return 0;
 }
 return action;
 }
 /*
 Convenience overload
 */
 HbAction *HbMenuPrivate::activeAction() const
 {
 HbMenuItem* activeItem = 0;
 return activeAction(activeItem);
 }
 /*
 Opens a submenu for activeItem. If activeItem is 0 it uses activeAction() to determine active item
 and opens submenu for it if active action has submenu.
 */
 void HbMenuPrivate::openSubmenu(HbMenuItem *activeItem)
 {
 Q_Q(HbMenu);
 }
 q->close();
 }
 }
-/*!
+/*
 Handles menu close
 */
 void HbMenuPrivate::closeMenu()
 {
 Q_Q(HbMenu);
 HbMainWindow* w(q->mainWindow());
 /*!
 @beta
 @hbcore
 \class HbMenu
-\brief HbMenu is a menu widget for use in HbView.
+\brief The HbMenu class provides a widget that shows a list of options.
-\image html hbmenu.png A menu with checkable items and a sub-menu.
+A menu consists of a list of options that the user can select. When the user selects
+an option, it triggers a command. Menus are hidden by default and open in response
-Use an HbMenu to show a list of options. There are two main types of menus:
+to an action from the user. For this reason, the toolbar (HbToolBar class) usually
+provides access to the most important commands (called first order commands) and
-- The view options menu
+menus provide access to second order commands.
-- Context menus (popup menus)
+\image html hbmenu.png An options menu with a submenu that has checkable actions
-There is one view options menu for each view.
-It is shown by tapping the title bar. You can access the view options menu by calling
+You can use the %HbMenu class to create the following:
-HbView::menu() which returns a pointer to a new empty menu if one does not already exist.
+- An \b options \b menu, which shows options that relate to the whole view. It is
-You can create any number of context menus.
+a drop-down menu that is directly owned by the view (HbView object). It opens when the
-Context menus are usually invoked by a user action, such as tapping a widget.
+user taps on the view's title bar. You can access a view's options menu by calling
+HbView::menu(). This returns a pointer to a new empty menu if the menu does not
-A menu contains a list of items. You can add three kinds of items to a menu:
+already exist. A view can have only one options menu.
-- Actions
+- A \b context \b menu, which is a pop-up menu that shows options that relate to a
-- Sub-menus
+specific item, rather than to the entire view. It typically opens in response to a
-- Separators
+UI event, such as a tap on a widget or a particular point within the view. You can
+create any number of context menus.
-An action is an object of class HbAction that performs an action when it is triggered.
-Use addAction() to add an action to a menu. Actions can be checkable (QAction::setCheckable).
+A menu is a list of actions, which are objects of class HbAction. A menu can contain:
-Use clearActions() to clear all actions from a menu.
-Use removeAction() to remove individual actions from a menu.
+- \b Separators, which are actions that group related items. Use addSeparator() or
+insertSeparator() to create a separator and add it to a menu.
-A sub-menu is a menu that is nested within another menu. Use addMenu() or insertMenu() to add a sub-menu to a menu.
-Sub-menus can be nested within sub-menus.
+- Actions that trigger a \b submenu to open. Submenus are menus that are nested within
+another menu. Use addMenu() or insertMenu() to add a submenu to a menu. Although it is
-Separators group related items in a menu.
+possible to nest submenus within other submenus, generally this is not considered good
-Use addSeparator() or insertSeparator() to create and add a separator to a menu.
+design practice.
-\image html hbmenu.png A menu with checkable actions and a sub-menu.
+- \b Action \b items, which represent the menu options. Use addAction() and insertAction() to
+add an action to a menu. Use addActions() and insertActions() to add and insert multiple
-After you add an action to your menu, you specify a receiver object and its slot (you can also
+actions in one operation. Use clearActions() to clear all of the actions from a menu and
-add an action and specify a receiver slot at the same time).
+removeAction() to remove individual actions from a menu.
-The receiver is notifed when the action is triggered (QAction::triggered()).
-HbMenu also has a triggered() menu signal, which signals which HbAction was triggered in the menu.
+The order of the actions within the menu controls the order of the options that the user sees.
+When you add the actions directly to the menu, addAction() and addActions() append the actions
-An example of how to create an option menu.
+to the end of the menu and insertAction() and insertActions() enable you to specify the position.
+For options menus, however, there is an alternative approach to ordering the action items.
+This 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.
+An action item can be checkable, which means that it has an on/off state. You specify that an
+action item is checkable by calling \c setCheckable() on the action. Use \c isChecked()
+to discover if an action is checked. You can also use the QAction::toggled(bool) signal to
+receive notification of a change in the checked status.
+After you add an action item to a menu, you can connect its \link HbAction::triggered()
+triggered()\endlink signal to a slot on a receiver object. Alternatively you can use the
+addAction(const QString &, const QObject *, const char *) overload to add an action item and
+specify a receiver slot at the same time. The receiver is notified when the action item
+is \link HbAction::triggered() triggered()\endlink.
+You can also connect the HbMenu::triggered(HbAction*) signal to a receiver object's slot. This
+signal is emitted when any menu action is triggered. You can find out which action was
+triggered from the HbAction parameter.
+\section _usecases_hbmenu Using the HbMenu class
+\subsection _uc_001_hbmenu Creating an options menu
+The following example creates an options menu for a view.
 \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,2}
-An example of how to create and show a context menu from the gesture.
+\subsection _uc_002_hbmenu Creating a context menu
+The following example creates a context menu and shows it in response to a tap and hold gesture.
 \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,54}
-\sa HbDialog, HbView
+\subsection _uc_004_hbmenu Adding actions to the view
+The following example creates two action items, specifies their command roles, and then
+adds them to the view. The view places them in the menu or toolbar according to the
+priorities of the actions and the space available in the toolbar and the menu orders them
+according to their roles and priorities.
+\code
+HbAction* actionExit = new HbAction(tr("Exit"));
+actionExit->setCommandRole(HbAction::ExitRole);
+HbAction* actionHelp = new HbAction(tr("Help"));
+actionHelp->setCommandRole(HbAction::HelpRole);
+// Add actions to the view.
+myView->addAction(actionExit);
+myView->addAction(actionHelp);
+\endcode
+\subsection _uc_003_hbmenu Creating action items that are checkable
+You can create a menu that contains multiple checkable actions (actions with checkbox behavior).
+For simple checkbox behavior, just set the actions to be checkable by calling \c setCheckable(true).
+For example:
+\code
+...
+checkAction1->setCheckable(true);
+checkAction2->setCheckable(true);
+checkAction3->setCheckable(true);
+...
+\endcode
+\subsection _uc_005_hbmenu Creating radio button style options
+To create a group of related actions, only one of which can be checked (radio button behavior),
+create a QActionGroup object and add the actions to that. For example:
+\code
+HbAction *redAction = menu->addAction(tr("Red"));
+HbAction *blueAction = menu->addAction(tr("Blue"));
+redAction->setCheckable(true);
+blueAction->setCheckable(true);
+QActionGroup *actionGroup = new QActionGroup(view);
+actionGroup->addAction(redAction);
+actionGroup->addAction(blueAction);
+\endcode
+\sa HbView, HbToolBar, HbAction
 */
 /*!
 \property HbMenu::menuType
 \brief
 */
 /*!
 \fn void HbMenu::triggered(HbAction *action)
-This signal is emitted when one of the action items is selected.
+This signal is emitted when one of the menu options is selected.
-\param action the action that was triggered in the menu.
+\param action The action that was selected.
 */
 /*!
 \enum HbMenu::MenuType
-This enum describes different types of HbMenu.
+The MenuType enum identifies the possible HbMenu types.
 */
 /*!
 \var HbMenu::ContextMenu
+A popup menu.
-ContextMenu is a menu which position is set by user.
+*/
-*/
+/*!
-/*!
+\var HbMenu::OptionsMenu
-\var HbMenu::OptionMenu
+The main options menu in a view. Its position cannot be changed.
-OptionMenu is set by HbView. Its position cannot be changed.
 */
 /*!
 \var HbMenu::SubMenu
+A submenu, which is a menu that has been added to another menu.
-Menu becomes SubMenu when it is added to another menu.
 */
 /*!
 Constructs a menu with \a parent graphics item.
-\param parent is the parent graphics item.
 */
 HbMenu::HbMenu(QGraphicsItem *parent) :
 HbPopup(*new HbMenuPrivate, parent)
 {
 Q_D(HbMenu);
 setModal(true);
 }
 /*!
 Constructs a menu with \a title and \a parent graphics item.
-\param title is the menu title.
-\param parent is the parent graphics item.
 */
 HbMenu::HbMenu(const QString &title, QGraphicsItem *parent) :
 HbPopup(*new HbMenuPrivate, parent)
 {
 Q_D(HbMenu);
 Q_D(HbMenu);
 d->q_ptr = this;
 d->init();
 }
+/*!
+Destructor
+*/
 HbMenu::~HbMenu()
 {
 if (!scene() || !scene()->property("destructed").isValid()) {
 foreach (QAction *action, actions()) {// krazy:exclude=qclasses
 HbAction* hbAction = qobject_cast<HbAction *>(action);
 HbPopup::showEvent(event);
 }
 /*!
-Creates a new action with title \a text. It adds the newly created action to the menu's list of actions.
+Creates a new action and adds it to the end of the menu.
-\param text is the text for the new action.
-\return the new action.
+\overload
+\param text The menu text for the new action.
+\return The new action.
 */
 HbAction *HbMenu::addAction(const QString &text)
 {
 HbAction *action = new HbAction(text, this);
 addAction(action);
 return action;
 }
 /*!
-Creates a new action with \a text.
+Creates a new action, adds it to the end of the menu and connects the action's
-The action's triggered() signal is connected to the
+\link HbAction::triggered() triggered()\endlink signal to a receiver's slot.
-\a receiver's \a member slot. The function adds the newly created
-action to the menu's list of actions.
+\overload
-\return the new action.
-*/
+\param text The menu 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 *HbMenu::addAction(const QString &text, const QObject *receiver, const char *member)
 {
 HbAction *action = new HbAction(text, this);
 connect(action, SIGNAL(triggered(bool)), receiver, member);
 addAction(action);
 return action;
 }
 /*!
-Adds \a menu as a sub-menu.
+Adds \a menu to the current menu as a submenu.
-\param menu is the menu that is added to this one.
-\return the action for the added sub-menu.
+\return  The action for the added submenu.
 */
 HbAction *HbMenu::addMenu(HbMenu *menu)
 {
 return insertMenu(0, menu);
 }
 /*!
-Creates a new HbMenu with \a title and adds it to this menu.
+Creates a new HbMenu with \a title and adds it to the current menu as a submenu.
-\param title is the menu title.
-\return the new menu.
+\return The new menu.
 */
 HbMenu *HbMenu::addMenu(const QString &title)
 {
 HbMenu *menu = new HbMenu(title);
-addMenu(menu);
+if ( menu ) {
+menu->setParent(this);
+addMenu(menu);
+}
 return menu;
 }
 /*!
-Inserts \a menu before action \a before.
+Inserts \a menu into the current menu as a submenu before the \a before action.
-\param before is the action before which this new menu is inserted.
-\param menu is the menu that is inserted.
 \return the action associated with the inserted menu.
 */
 HbAction *HbMenu::insertMenu(HbAction *before, HbMenu *menu)
 {
 QObject::connect(menu, SIGNAL(triggered(HbAction*)), this, SLOT(_q_subMenuItemTriggered(HbAction*)));
 QObject::connect(menu, SIGNAL(triggered(HbAction*)), this, SIGNAL(triggered(HbAction*)));
 insertAction(before, menu->menuAction());
 return menu->menuAction();
 }
 /*!
-\return the action associated with this menu.
+Returns the action that is directly associated with a menu (rather than actions that are contained
-*/
+within the menu). Although all menus have an assoicated action, it is only actually used for submenus.
+The parent menu uses a submenu's action to trigger the opening of the submenu. A submenu's action
+also defines the submenu's title.
+*/
 HbAction *HbMenu::menuAction() const
 {
 Q_D(const HbMenu);
 return d->subMenuAction;
 }
 /*!
-Creates a new separator action, which is an action that returns \c true from HbAction::isSeparator(),
+Creates a new separator and adds it to the current menu's list of actions. A separator
-and adds it to this menu's list of actions.
+is an action for which HbAction::isSeparator() returns \c true.
-\return the new separator action
+\return The new separator action.
-\sa insertSeparator
-*/
+\sa insertSeparator()
+*/
 HbAction *HbMenu::addSeparator()
 {
 //functionality removed for now
 //return insertSeparator(0);
 return 0;
 }
 /*!
-Inserts a new separator action and inserts it into this menu's list of actions before \a action.
+Creates a new separator and inserts it into the current menu's list of actions before \a before.
-\param before is the action before which the separator is inserted.
+A separator is an action for which HbAction::isSeparator() returns \c true.
-\return the new action.
+\return The new separator action.
-\sa addSeparator
+\sa addSeparator()
 */
 HbAction *HbMenu::insertSeparator(HbAction *before)
 {
 Q_UNUSED(before);
 //functionality removed for now
 /*HbAction *action = new HbAction(this);
 return action;*/
 return 0;
 }
 /*!
-\return the current active action, or 0 if no action item is currently active.
+Returns the active action or 0 if no action item is currently active. The active action is
-*/
+the last action that was triggered, unless this has been overridden by a call to setActiveAction().
+*/
 HbAction *HbMenu::activeAction() const
 {
 Q_D(const HbMenu);
 return d->activeAction();
 }
 /*!
-Sets the active action in menu. If \a action is not found from the list of
+Sets \a action as the current active action in the menu. If \a action is not
-menu actions then the current active action remains active.
+found in the list of menu actions, the action that is currently active remains active.
 \sa activeAction()
 */
 void HbMenu::setActiveAction(HbAction *action)
 {
 d->menuItemView->setCurrentItem(action);
 }
 }
 /*!
-\return \c true if the menu is empty (contains no actions) and \c false otherwise.
+Returns \c true if the menu contains no actions and \c false otherwise.
-\sa clear()
+\sa clearActions()
 */
 bool HbMenu::isEmpty() const
 {
 return actions().isEmpty();
 }
 /*!
-Sets the menu title. For a sub-menu, the title is the sub-menu action text.
+Sets the menu title. For a submenu, the title is the submenu's action text.
 \sa title()
 */
 void HbMenu::setTitle(const QString &title)
 {
 menuAction()->setText(title);
 }
 /*!
-Returns the menu title. For a sub-menu, the title is the sub-menu action text.
+Returns the menu title. For a submenu, the title is the submenu's action text.
-\return the menu title.
 \sa setTitle()
 */
 QString HbMenu::title() const
 {
 return menuAction()->text();
 }
 /*!
-Returns the menu type. By default a menu is a context menu.
+Returns the menu type. The default menu type is context menu.
-\return the menu type.
 */
 HbMenu::MenuType HbMenu::menuType() const
 {
 Q_D(const HbMenu);
 return d->menuType;
 }
-/*!
-\reimp
-*/
 QVariant HbMenu::itemChange( GraphicsItemChange change, const QVariant & value )
 {
 Q_D(HbMenu);
 if (change == QGraphicsItem::ItemSceneHasChanged) {
 d->closeMenu();
 }
 if (change == QGraphicsItem::ItemVisibleChange) {
-if (value.toBool() && d->delayMenuConstruction) {
+if (value.toBool() && d->polished) {
 d->delayedLayout();
 }
 if (value.toBool()) {
 d->actionTriggered = false;
 }
 }
 }
 return HbPopup::itemChange(change,value);
 }
-/*!
-\reimp
-*/
 bool HbMenu::event(QEvent *event)
 {
 Q_D(HbMenu);
 if(!d->inDestruction) {
 }
 return HbPopup::event(event);
 }
-/*!
-\reimp
-*/
 void HbMenu::polish(HbStyleParameters &params)
 {
-Q_D(HbMenu);
+if (isVisible()) {
-const QString NumberOfCols = "number-of-columns";
+Q_D(HbMenu);
-params.addParameter(NumberOfCols);
+const QLatin1String NumberOfCols("number-of-columns");
+params.addParameter(NumberOfCols);
-if (d->mSubMenuItem) {
-const QString RightMargin = "submenu-right-offset";
+if (d->mSubMenuItem) {
-const QString DownMargin = "submenu-bottom-margin";
+const QLatin1String RightMargin("submenu-right-offset");
-params.addParameter(RightMargin);
+const QLatin1String DownMargin("submenu-bottom-margin");
-params.addParameter(DownMargin);
+params.addParameter(RightMargin);
+params.addParameter(DownMargin);
-HbPopup::polish(params);
+HbPopup::polish(params);
-if (!params.value(RightMargin).isNull()) {
-d->mRightMargin = params.value(RightMargin).toDouble();
+if (!params.value(RightMargin).isNull()) {
-}
+d->mRightMargin = params.value(RightMargin).toDouble();
-if (!params.value(DownMargin).isNull()) {
+}
-d->mDownMargin = params.value(DownMargin).toDouble();
+if (!params.value(DownMargin).isNull()) {
-}
+d->mDownMargin = params.value(DownMargin).toDouble();
-d->setSubMenuPosition();
+}
+d->setSubMenuPosition();
+} else {
+HbPopup::polish(params);
+}
+if (!params.value(NumberOfCols).isNull()) {
+int cols = params.value(NumberOfCols).toInt();
+if (d->mNumberOfColumns != cols) {
+d->mNumberOfColumns = cols;
+if (d->menuItemView) {
+d->menuItemView->updateContainer();
+}
+}
+}
+d->delayedLayout();
 } else {
 HbPopup::polish(params);
 }
+}
-if (!params.value(NumberOfCols).isNull()) {
-int cols = params.value(NumberOfCols).toInt();
+/*!
-if (d->mNumberOfColumns != cols) {
+Returns the shape of this item as a QPainterPath.
-d->mNumberOfColumns = cols;
+*/
-if (d->menuItemView) {
-d->menuItemView->updateContainer();
-}
-}
-}
-}
-/*!
-\reimp
-Returns the shape of this item as a QPainterPath.
-*/
 QPainterPath HbMenu::shape() const
 {
 /*QRectF rect = QRectF(-1.0, -1.0, boundingRect().width() + 1.0, boundingRect().height() + 1.0);
 QRectF clipRect = rect.intersected(mapRectFromParent(QRectF(pos().x() - 1.0, pos().y() - 1.0, size().width() + 1.0, size().height() + 1.0)));
 return path;*/
 return HbPopup::shape();
 }
 /*!
+Displays the menu on the screen and returns immediately. It can also connect the HbMenu::triggered()
-Opens the menu and returns immediately.
+signal to a specified slot. The signal is disconnected when the menu closes.
-Connects triggered(HbAction*) signal to the slot specified by \a
+\param receiver The object that is to receive the signal.
-receiver and \a member. The signal will be disconnected when menu
+\param member The slot on the receiver to which the signal is to connect.
-is closed.
+*/
-An example of how to create a simple context menu and show it
-\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,54}
-*/
 void HbMenu::open( QObject *receiver, const char *member )
 {
 Q_D(HbMenu);
 if ( d->receiverToDisconnectOnClose ) { // cant do on closeevent
 disconnect(this, SIGNAL(triggered(HbAction*)),

changeset 21	4633027730f5
parent 6	c3690ec91ef8
child 23	e6ad4ef83b23