| Home | |
The QtPieMenu class provides a pie menu popup widget. More...
#include <qtpiemenu.h>
The QtPieMenu class provides a pie menu popup widget.
A pie menu is a popup menu that is usually invoked as a context menu, and that supports several forms of navigation.
Using conventional navigation, menu items can be highlighted simply by moving the mouse over them, or by single-clicking them, or by using the keyboard's arrow keys. Menu items can be chosen (invoking a submenu or the menu item's action), by clicking a highlighted menu item, or by pressing \key{Enter}.
Pie menus can also be navigated using gestures. Gesture navigation is where a menu item is chosen as the result of moving the mouse in a particular sequence of movements, for example, up-left-down, without the user having to actually read the menu item text.
The user can cancel a pie menu in the conventional way by clicking outside of the pie menu, or by clicking the center of the pie (the "cancel zone"), or by pressing \key{Esc}.
Pie menus are faster to navigate with the mouse than conventional menus because all the menu items are available at an equal distance from the origin of the mouse pointer.
The circular layout and the length of the longest menu text imposes a natural limit on how many items can be displayed at a time. For this reason, submenus are very commonly used.
Use popup() to pop up the pie menu. Note that QtPieMenu is different from QPopupMenu in that it pops up with the mouse cursor in the center of the menu (i.e. over the cancel zone), instead of having the cursor at the top left corner.
Pie menus can only be used as popup menus; they cannot be used as normal widgets.
A pie menu contains of a list of items, where each item is displayed as a slice of a pie. Items are added with insertItem(), and are displayed with a richtext text label, an icon or with both. The items are laid out automatically, starting from the top at index 0 and going counter clockwise. Each item can either pop up a submenu, or perform an action when activated. To get an item at a particular position, use itemAt().
When inserting action items, you specify a receiver and a slot. The slot is invoked in the receiver when the action is activated. In the following example, a pie menu is created with three items: "Open" and "Close" are actions, and "New" pops up a submenu. The submenu has two items, "New project" and "New dialog", which are both actions.
Editor::Editor(QWidget *parent, const char *name)
: QTextEdit(parent, name)
{
// Create a root menu and insert two action items.
QtPieMenu *rootMenu = new QtPieMenu(tr("Root menu"), this);
rootMenu->insertItem(tr("Open"), storage, SLOT(open()));
rootMenu->insertItem(tr("<i>Close</i>"), storage, SLOT(close());
// Now create a submenu and insert two action items.
QtPieMenu *subMenu = new QtPieMenu(tr("New"), rootMenu);
subMenu->insertItem(tr("New project"), formEditor, SLOT(newProject()));
subMenu->insertItem(tr("New dialog"), formEditor, SLOT(newDialog()));
// Finally add the submenu to the root menu.
rootMenu->insertItem(subMenu);
}
By default, each slice of the pie takes up an equal amount of space. Sometimes it can be useful to have certain slices take up more space than others. QtPieItem::setItemWeight() changes an item's space weighting, which by default is 1. QtPieMenu uses the weightings when laying out the pie slices. Each slice gets a share of the size proportional to its weight.
At the center of a pie menu is a cancel zone, which cancels the menu if the user clicks in it. The radius of the whole pie menu and of the cancel zone are set in the constructor, or with setOuterRadius() and setInnerRadius().
Any shape or layout of items is possible by subclassing QtPieMenu and reimplementing paintEvent(), indexAt(), generateMask() and reposition().
See also
This enum describes the reason for the activation of an item in a pie menu.
See also activateItem().
If this pie menu is a submenu, the richtext text argument is displayed by its parent menu.
The parent and name arguments are passed on to QWidget's constructor.
If this pie menu is a submenu, the icon argument is displayed by its parent menu.
The parent and name arguments are passed on to QWidget's constructor.
If this pie menu is a submenu, the icon and richtext text arguments are displayed by its parent menu.
The parent and name arguments are passed on to QWidget's constructor.
This signal is emitted just before the pie menu is hidden after it has been displayed.
Warning: Do not open a widget in a slot connected to this signal.
See also aboutToShow(), insertItem(), and removeItemAt().
This signal is emitted just before the pie menu is displayed. You can connect it to any slot that sets up the menu contents (e.g. to ensure that the correct items are enabled).
See also aboutToHide(), insertItem(), and removeItemAt().
See also QtPieMenu::ActivateReason.
This signal is emitted when a pie menu action item is activated, causing the popup menu to hide. It is used internally by QtPieMenu. Most users will find activated(int) more useful.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
This signal is emitted when the action item at index position i in the pie menu's list of menu items is activated.
See also highlighted().
This signal is emitted when the pie menu is canceled. Only the menu that emits this signal is canceled; any parent menus are still shown.
See also canceledAll().
This signal is emitted when the pie menu is canceled in such a way that the entire menu (including submenus) hides. For example, this would happen if the user clicked somewhere outside all the pie menus.
See also canceled().
When subclassing QtPieMenu, this function should be reimplemented if the shape of the new menu is different from QtPieMenu's shape.
Example: ../hexagon/hexagonpie.cpp.
This signal is emitted when the item at index position i in the pie menu's list of menu items is highlighted.
See also activated().
This function is reimplemented if a subclass of QtPieMenu provides a new item layout.
Returns the inner radius of the pie menu. See the "innerRadius" property for details.
QIconSet icon(QPixmap("save.png"));
rootMenu->insertItem(icon, this, SLOT(save()));
The items are ordered by their ordinal position, starting from the top of the pie and going counter clockwise.
Examples: ../editor/editor.cpp and ../hexagon/main.cpp.
Adds an action item to this pie menu at position index. The text is used as the item's text, or the text that is displayed on this item's slice in the pie. The receiver gets notified through the signal or slot in member when the item is activated.
rootMenu->insertItem("Save", this, SLOT(save()));
The items are ordered by their ordinal position, starting from the top of the pie and going counter clockwise.
Adds an action item to this pie menu at position index. The icons and text are used as the item's text and icon, or the text and icon that is displayed on this item's slice in the pie. The receiver gets notified through the signal or slot in member when the item is activated.
QIconSet icon(QPixmap("save.png"));
rootMenu->insertItem(icon, "Save", this, SLOT(save()));
The items are ordered by their ordinal position, starting from the top of the pie and going counter clockwise.
Adds the submenu item to this pie menu at position index. The items are ordered by their ordinal position, starting from the top of the pie and counting counter clockwise.
QtPieMenu *subMenu = new QtPieMenu("<i>Undo</i>", this, SLOT(undo()));
rootMenu->insertItem(subMenu);
See also setItemEnabled().
See also setItemIcon() and itemText().
See also setItemText().
See also setItemWeight().
Returns the outer radius of the pie menu. See the "outerRadius" property for details.
To translate a widget's contents coordinates into global coordinates, use QWidget::mapToGlobal().
Examples: ../editor/editor.cpp and ../hexagon/main.cpp.
The default implementation does nothing.
Example: ../hexagon/hexagonpie.cpp.
Sets the inner radius of the pie menu to r. See the "innerRadius" property for details.
See also isItemEnabled().
Example: ../editor/editor.cpp.
See also itemIcon() and setItemText().
pieMenu->setItemText("<i>Undo</i>", 0);
See also itemText() and itemIcon().
The pie menu in this image has three pie menu items with icons and no text. The item at position 0 has a weight of 2, and the rest have the default weight of 1.
See also itemWeight().
Example: ../editor/editor.cpp.
Sets the outer radius of the pie menu to r. See the "outerRadius" property for details.
Examples: ../hexagon/hexagonpie.cpp and ../hexagon/main.cpp.
This property holds the inner radius of the pie menu.
The radius in pixels of the cancel zone (in the center) of the pie menu. Setting the radius to 0 disables the cancel zone.
See also outerRadius.
Set this property's value with setInnerRadius() and get this property's value with innerRadius().
This property holds the outer radius of the pie menu.
The outer radius of the pie menu in pixels.
See also innerRadius.
Set this property's value with setOuterRadius() and get this property's value with outerRadius().
This file is part of the Qt Solutions.
Copyright © 2003-2006
Trolltech. All Rights Reserved.
| Copyright © 2003-2006 Trolltech | Trademarks | Qt Solutions
|