|
Home |
The QtPieMenu class provides a pie menu popup widget. More...
#include <QtPieMenu>
Inherits QtPieItem.
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 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 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)
{
setObjectName(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("Close"), 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().
This enum describes the reason for the activation of an item in a pie menu.
| Constant | Value | Description |
|---|---|---|
| QtPieMenu::MousePress | 0x01 | The activation was caused by a mouse button press. |
| QtPieMenu::MouseRelease | 0x02 | The activation was caused by a mouse button release. |
| QtPieMenu::KeyPress | 0x04 | The activation was caused by a key press. |
| QtPieMenu::Hovering | 0x08 | The activation was caused by hovering the mouse pointer over an item. |
| QtPieMenu::Dragging | 0x10 | The activation was caused by dragging. |
See also activateItem().
| Constant | Value | Description |
|---|---|---|
| QtPieMenu::Invalid | 0 | The item has an invalid type or doesn't exist; for example if QtPiePenu::itemType() is called with an invalid index. |
| QtPieMenu::SubMenu | 1 | Activating the item will pop up a submenu. |
| QtPieMenu::Action | 2 | Activating this item will trigger an action. |
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.
Access functions:
See also outerRadius.
This property holds the outer radius of the pie menu.
The outer radius of the pie menu in pixels.
Access functions:
See also innerRadius.
Constructs a pie menu. The innerRadius argument is the radius of the cancel zone at the center of the pie. The outerRadius is the radius of the outer edge of the pie.
If this pie menu is a submenu, the richtext text argument is displayed by its parent menu.
The parent argument is passed on to QWidget's constructor. The object name is set to the name argument.
Constructs a pie menu. The innerRadius argument is the radius of the cancel zone at the center of the pie. The outerRadius is the radius of the outer edge of the pie.
If this pie menu is a submenu, the icon argument is displayed by its parent menu.
The parent argument is passed on to QWidget's constructor. The object name is set to the name argument.
Constructs a pie menu. The innerRadius argument is the radius of the cancel zone at the center of the pie. The outerRadius is the radius of the outer edge of the pie.
If this pie menu is a submenu, the icon and richtext text arguments are displayed by its parent menu.
The parent argument is passed on to QWidget's constructor. The object name is set to the name argument.
Destructs the pie menu.
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().
Activates an item. The reason for the activation is given in reason. Activating an item either causes an action to be activated, a submenu to popup, or the menu to be canceled.
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 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().
With origin set to the center of the pie, this function returns the angle in radians between the line that starts at (0,0) and ends at (1,0) and the line that starts at (0,0) and ends at pos.
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().
Removes all the items from the pie menu.
Returns the number of items in this pie menu.
Draws the outline of the pie menu using the bitmap mask. This is used as a QWidget mask.
When subclassing QtPieMenu, this function should be reimplemented if the shape of the new menu is different from QtPieMenu's shape.
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().
Returns the index of the item that is currently selected, or -1 if no item is selected.
See also setHighlightedItem().
Returns the index of the item that is highlighted when the cursor is at position pos.
This function is reimplemented if a subclass of QtPieMenu provides a new item layout.
Adds an action item to this pie menu at position index. The icon 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.
QIcon 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.
This is an overloaded function.
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("Undo", this, SLOT(undo()));
rootMenu->insertItem(subMenu);
This is an overloaded function.
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.
This is an overloaded function.
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.
QIcon 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.
Returns true if the pie menu item at position index is enabled; otherwise returns false.
See also setItemEnabled().
Returns true if the menu is shaded (inactive); otherwise returns false.
Returns the icon set of the pie menu item at position index. If no icon has been set an invalid icon is returned.
See also setItemIcon() and itemText().
Returns the text of the pie menu item at position index. The string may be a rich text string.
See also setItemText() and itemIcon().
Returns the type of the item at position index, or QtPieItem::Invalid if there is no item at position index.
Returns the weight of the pie menu item at position index.
See also setItemWeight().
Displays the pie menu with the center of the pie at the global position pos.
To translate a widget's contents coordinates into global coordinates, use QWidget::mapToGlobal().
Returns the distance from pos to the center of the pie menu.
Removes the item at position index.
Repositions a pie menu. This function is called in popup() after the pie menu's initial position has been set. Reimplement this function when subclassing QtPieMenu to gain finer control of where submenus are positioned when popped up.
The default implementation does nothing.
Highlights the item at position index, then schedules a display update.
See also highlightedItem().
If enabled is true, this function enables the pie menu item at position index; otherwise the item is disabled. When an item is disabled, it will not respond to mouse clicks or releases. All all items are enabled by default.
See also isItemEnabled().
Sets the icon of the pie menu item at position index to icon.
See also itemIcon() and setItemText().
Sets the text of the pie menu item at position index to text. Currently QtPieMenu only supports plain text, and HTML tags will be stripped from text.
pieMenu->setItemText("Undo", 0);
See also itemText() and setItemIcon().
Sets the relative weight of the pie menu item at position index to weight. The weight of an item decides how big its slice of the pie menu will be. By default, all pie menu items have a weight of 1. If one item has a weight of 2, it will be twice as big as the other items.
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().
If the item at position index is a submenu, a pointer to the corresponding QtPieMenu is returned; otherwise returns 0.
| Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) | Trademarks | Qt Solutions |