Libplasma

qmenu.h
1/*
2 SPDX-FileCopyrightText: 2011 Viranch Mehta <viranch.mehta@gmail.com>
3
4 SPDX-License-Identifier: GPL-2.0-or-later
5*/
6
7#ifndef QMENU_PROXY_H
8#define QMENU_PROXY_H
9
10#include "plasma.h"
11#include "qmenuitem.h"
12#include <QMenu>
13#include <QObject>
14#include <QPointer>
15#include <QQmlListProperty>
16#include <QWindow>
17
18#include <qqmlregistration.h>
19
20class QDeclarativeItem;
21class QQuickItem;
22
23/**
24 * @class Menu
25 *
26 * An Item provides a menu for use in context specific situations.
27 * You can specify the position for the menu to open by setting its visualParent.
28 * MenuItems should be used to draw entries in the menu.
29 * The open() function opens up the menu at the given visualParent.
30 *
31 *
32 * Example usage:
33 * @code
34 * import org.kde.plasma.extras 2.0 as PlasmaExtras
35 *
36 * [...]
37 * PlasmaExtras.Menu {
38 * id: menu
39 * ...
40 * PlasmaExtras.MenuItem {
41 * text: "Delete"
42 * onClicked: {
43 * myListItem.remove();
44 * }
45 * }
46 * }
47 * PlasmaExtras.Button {
48 * id: btn
49 * onClicked: {
50 * menu.visualParent = btn
51 * menu.open()
52 * }
53 * }
54 * [...]
55 * @endcode
56 *
57 */
58
59class QMenuProxy : public QObject
60{
62 QML_ELEMENT
63 QML_NAMED_ELEMENT(Menu)
64
65 Q_PROPERTY(QQmlListProperty<QMenuItem> content READ content CONSTANT)
66 Q_CLASSINFO("DefaultProperty", "content")
67
68 /**
69 * This is a hint to the window manager that this window is a dialog or pop-up on
70 * behalf of the given window.
71 */
72 Q_PROPERTY(QWindow *transientParent READ transientParent WRITE setTransientParent NOTIFY transientParentChanged)
73
74 /**
75 * The visualParent is used to position the menu. it can be an item on the
76 * scene, like a button (that will open the menu on clicked) or another menuitem
77 * (in this case this will be a submenu).
78 */
79 Q_PROPERTY(QObject *visualParent READ visualParent WRITE setVisualParent NOTIFY visualParentChanged())
80 Q_PROPERTY(Status status READ status NOTIFY statusChanged)
81
82 /**
83 * This property holds the requested placement for the menu. It will be
84 * automatically flipped horizontally in Right-to-left User Interfaces.
85 * Additionally it may be flipped to the other side in any direction if
86 * there is not enough space on a screen to fit the menu.
87 */
88 Q_PROPERTY(PopupPlacement placement READ placement WRITE setPlacement NOTIFY placementChanged)
89
90 /**
91 * This property allows to request a seamless appearance in the direction
92 * adjacent to the visualParent item, as determined by the menu's placement
93 * policy.
94 */
95 Q_PROPERTY(bool preferSeamlessEdges READ preferSeamlessEdges WRITE setPreferSeamlessEdges NOTIFY preferSeamlessEdgesChanged)
96
97 /**
98 * A minimum width for the menu.
99 */
100 Q_PROPERTY(int minimumWidth READ minimumWidth WRITE setMinimumWidth NOTIFY minimumWidthChanged)
101
102 /**
103 * A maximum width for the menu.
104 *
105 * @since 5.31
106 */
107 Q_PROPERTY(int maximumWidth READ maximumWidth WRITE setMaximumWidth RESET resetMaximumWidth NOTIFY maximumWidthChanged)
108
109public:
110 /**
111 * The popup position enumeration relatively to his attached widget
112 *
113 **/
114 enum PopupPlacement {
115 FloatingPopup = 0, /**< Free floating, non attached popup */
116 TopPosedLeftAlignedPopup, /**< Popup positioned on the top, aligned
117 to the left of the widget */
118 TopPosedRightAlignedPopup, /**< Popup positioned on the top, aligned
119 to the right of the widget */
120 LeftPosedTopAlignedPopup, /**< Popup positioned on the left, aligned
121 to the top of the widget */
122 LeftPosedBottomAlignedPopup, /**< Popup positioned on the left, aligned
123 to the bottom of the widget */
124 BottomPosedLeftAlignedPopup, /**< Popup positioned on the bottom, aligned
125 to the left of the widget */
126 BottomPosedRightAlignedPopup, /**< Popup positioned on the bottom, aligned
127 to the right of the widget */
128 RightPosedTopAlignedPopup, /**< Popup positioned on the right, aligned
129 to the top of the widget */
130 RightPosedBottomAlignedPopup, /**< Popup positioned on the right, aligned
131 to the bottom of the widget */
132 };
133 Q_ENUM(PopupPlacement)
134
135 enum Status {
136 Opening,
137 Open,
138 Closing,
139 Closed,
140 };
141 Q_ENUM(Status)
142
143 explicit QMenuProxy(QObject *parent = nullptr);
144 ~QMenuProxy() override;
145
147 int actionCount() const;
148 QMenuItem *action(int) const;
149 Status status() const;
150
151 QObject *visualParent() const;
152 void setVisualParent(QObject *parent);
153
154 QWindow *transientParent();
155 void setTransientParent(QWindow *parent);
156
157 PopupPlacement placement() const;
158 void setPlacement(PopupPlacement placement);
159
160 bool preferSeamlessEdges() const;
161 void setPreferSeamlessEdges(bool request);
162
163 int minimumWidth() const;
164 void setMinimumWidth(int width);
165
166 int maximumWidth() const;
167 void setMaximumWidth(int maximumWidth);
168 void resetMaximumWidth();
169
170 /**
171 * This opens the menu at position x,y on the given visualParent. By default x and y are set to 0
172 */
173 Q_INVOKABLE void open(int x = 0, int y = 0);
174 /**
175 * This opens the menu at the specified placement relative to the visualParent.
176 */
177 Q_INVOKABLE void openRelative();
178 /**
179 * This closes the menu
180 */
181 Q_INVOKABLE void close();
182 /**
183 * This removes all menuItems inside the menu
184 */
185 Q_INVOKABLE void clearMenuItems();
186 /**
187 * This adds a menu item from a String
188 */
189 Q_INVOKABLE void addMenuItem(const QString &text);
190 /**
191 * This adds MenuItem 'item' to the menu before MenuItem 'before'.
192 * If MenuItem 'before' is 0 or does not exist in the menu, 'item'
193 * is appended to the menu instead.
194 * If MenuItem 'item' already exists in the menu, it is removed and
195 * inserted at the new position.
196 */
197 Q_INVOKABLE void addMenuItem(QMenuItem *item, QMenuItem *before = nullptr);
198 /**
199 * This adds a section header with a string used as name for the section
200 */
201 Q_INVOKABLE void addSection(const QString &text);
202
203 /**
204 * This removes MenuItem 'item'
205 *
206 * @since 5.27
207 */
208 Q_INVOKABLE void removeMenuItem(QMenuItem *item);
209
210protected:
211 bool event(QEvent *event) override;
212
214 void statusChanged();
215 void visualParentChanged();
216 void transientParentChanged();
217 void placementChanged();
218 void preferSeamlessEdgesChanged();
219 void minimumWidthChanged();
220 void maximumWidthChanged();
221 void triggered(QMenuItem *item);
222 void triggeredIndex(int index);
223
224private Q_SLOTS:
225 void itemTriggered(QAction *item);
226
227private:
228 void rebuildMenu();
229 void openInternal(QPoint pos);
230 QQuickItem *parentItem() const;
231 /*
232 * Mirrors popup placement horizontally in Right-To-Left environments.
233 *
234 * Mirroring behavior can be explicitly overridden by passing a specific
235 * direction with layoutDirection parameter, or left at default value of
236 * Qt::LayoutDirectionAuto, in which case it will be deduced from shared
237 * QGuiApplication instance.
238 **/
239 static PopupPlacement visualPopupPlacement(PopupPlacement placement, Qt::LayoutDirection layoutDirection = Qt::LayoutDirectionAuto);
240 Qt::Edges seamlessEdgesForPlacement(std::optional<PopupPlacement> placement);
241 void setupSeamlessEdges(std::optional<PopupPlacement> placement);
242
243 QList<QMenuItem *> m_items;
244 QMenu *m_menu;
245 Status m_status;
246 QPointer<QObject> m_visualParent;
247 PopupPlacement m_placement;
248 bool m_preferSeamlessEdges;
249};
250
251#endif // QMENU_PROXY_H
An Item provides a menu for use in context specific situations.
Q_CLASSINFO(Name, Value)
Q_ENUM(...)
Q_INVOKABLEQ_INVOKABLE
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
QObject * parent() const const
typedef Edges
LayoutDirection
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 22 2024 12:06:24 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.