QContextMenuEvent Class | Qt GUI | Qt 6.12.0
Description: The QContextMenuEvent class contains parameters that describe a context menu event.
Keywords: class

- Qt 6.12
- Qt GUI
- C++ Classes
- QContextMenuEvent
- Qt 6.12.0 Reference Documentation

# QContextMenuEvent Class

The QContextMenuEvent class contains parameters that describe a context menu event. More...

Header: | `#include <QContextMenuEvent>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Gui)` `target_link_libraries(mytarget PRIVATE Qt6::Gui)`
qmake: | `QT += gui`
Inherits: | QInputEvent

- List of all members, including inherited members
- Deprecated members
- QContextMenuEvent is part of Event Classes.

## Public Types

enum | Reason { Mouse, Keyboard, Other }

## Public Functions

| QContextMenuEvent(QContextMenuEvent::Reason reason, const QPoint &pos, const QPoint &globalPos, Qt::KeyboardModifiers modifiers = Qt::NoModifier)
const QPoint & | globalPos() const
int | globalX() const
int | globalY() const
const QPoint & | pos() const
QContextMenuEvent::Reason | reason() const
int | x() const
int | y() const

## Protected Functions

| QContextMenuEvent(QContextMenuEvent &&)
QContextMenuEvent & | operator=(QContextMenuEvent &&)
QContextMenuEvent & | operator=(const QContextMenuEvent &other)

## Detailed Description

A context menu event is sent when a user performs an action that should open a contextual menu:

- clicking the right mouse button
- pressing a dedicated keyboard menu key (if the keyboard has one, such as the menu key on standard 104-key PC keyboards)
- pressing some other keyboard shortcut (such as "Ctrl+Return" by default on macOS 15 and newer)

The expected context menu should contain actions that are relevant to some content within the application (the "context"). In Qt, the context is at least the particular widget or Qt Quick Item that receives the QContextMenuEvent. If there is a selection, that should probably be treated as the context. The context can be further refined using QContextMenuEvent::pos() to pinpoint the content within the widget, item or selection.

Widgets can override QWidget::contextMenuEvent() to handle this event. Many widgets already do that, and have useful context menus by default. Some widgets have a function such as createStandardContextMenu() to populate the default set of actions into a QMenu, which can be customized further in your subclass and then shown.

In Qt Quick, the event can be handled via the ContextMenu attached property. Some QtQuick.Controls Controls already provide context menus by default.

Unlike most synthetic events (such as a QMouseEvent that is sent only after a QTouchEvent or QTabletEvent was not accepted), QContextMenuEvent is sent regardless of whether the original mouse or key event was already handled and accepted. This is to accommodate the Windows UI pattern of selecting some kind of items (icons, drawing elements, or cells in an Item View) using the right mouse button (clicking or dragging), and then getting a context menu as soon as you release the right mouse button. (The actions on the menu are meant to apply to the selection.) Therefore, on Windows the QContextMenuEvent is sent on mouse release; while on other platforms, it's sent on press. Qt follows the platform convention by default.

There are also some Qt Quick Controls such as Pane that accept mouse events, and nevertheless receive a QContextMenuEvent after a mouse press or click.

If you prefer to support the press-drag-release UI pattern to open a context menu on press, and drag over a menu item to select it on release, you will need to do that by handling QMouseEvents directly (by overriding virtual functions in QWidget subclasses, or using TapHandler to open a Menu in Qt Quick); and then the QContextMenuEvent will be redundant when the reason() is `Mouse`. You should ignore() the event in that case; but you should still ensure that the widget, custom control or application can respond to a QContextMenuEvent that comes from the platform-specific keyboard shortcut.

When a QContextMenuEvent is ignored, Qt attempts to deliver it to other widgets and/or Items under the position (which is usually translated from the cursor position).

## Member Type Documentation

### enum QContextMenuEvent::Reason

This enum describes the reason why the event was sent.

Constant | Value | Description
--- | --- | ---
`QContextMenuEvent::Mouse` | `0` | The mouse caused the event to be sent. Normally this means the right mouse button was clicked, but this is platform dependent.
`QContextMenuEvent::Keyboard` | `1` | The keyboard caused this event to be sent. On Windows, this means the menu button was pressed.
`QContextMenuEvent::Other` | `2` | The event was sent by some other means (i.e. not by the mouse or keyboard).

## Member Function Documentation

### QContextMenuEvent::QContextMenuEvent(QContextMenuEvent::Reason reason, const QPoint &pos, const QPoint &globalPos, Qt::KeyboardModifiers modifiers = Qt::NoModifier)

Constructs a context menu event object with the accept parameter flag set to false.

The reason parameter must be QContextMenuEvent::Mouse or QContextMenuEvent::Keyboard.

The pos parameter specifies the mouse position relative to the receiving widget. globalPos is the mouse position in absolute coordinates. The modifiers holds the keyboard modifiers.

### `[protected delete]` QContextMenuEvent::QContextMenuEvent(QContextMenuEvent &&)

Move-constructs an instance of QContextMenuEvent. This function is deleted.

### const QPoint &QContextMenuEvent::globalPos() const

Returns the global position of the mouse pointer at the time of the event.

See also x(), y(), and pos().

### int QContextMenuEvent::globalX() const

Returns the global x position of the mouse pointer at the time of the event.

See also globalY() and globalPos().

### int QContextMenuEvent::globalY() const

Returns the global y position of the mouse pointer at the time of the event.

See also globalX() and globalPos().

### const QPoint &QContextMenuEvent::pos() const

Returns the position of the mouse pointer relative to the widget that received the event.

Note: If the QContextMenuEvent did not come from the right mouse button, `pos()` may be null.

See also x(), y(), and globalPos().

### QContextMenuEvent::Reason QContextMenuEvent::reason() const

Returns the reason for this context event.

### int QContextMenuEvent::x() const

Returns the x position of the mouse pointer, relative to the widget that received the event.

See also y() and pos().

### int QContextMenuEvent::y() const

Returns the y position of the mouse pointer, relative to the widget that received the event.

See also x() and pos().

### `[protected delete]` QContextMenuEvent &QContextMenuEvent::operator=(QContextMenuEvent &&)

Move-assigns other to this QContextMenuEvent instance. This function is deleted.

### `[noexcept protected default]` QContextMenuEvent &QContextMenuEvent::operator=(const QContextMenuEvent &other)

Copy-assigns other to this QContextMenuEvent instance.