Kirigami2

toolbarlayout.h
1 /*
2  * SPDX-FileCopyrightText: 2020 Arjen Hiemstra <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5  */
6 
7 #ifndef TOOLBARLAYOUT_H
8 #define TOOLBARLAYOUT_H
9 
10 #include <QQuickItem>
11 #include <memory>
12 
13 /**
14  * Attached property for ToolBarLayout delegates.
15  */
17 {
18  Q_OBJECT
19  /**
20  * The action this delegate was created for.
21  */
22  Q_PROPERTY(QObject *action READ action CONSTANT)
23 public:
25 
26  QObject *action() const;
27  void setAction(QObject *action);
28 
29 private:
30  QObject *m_action = nullptr;
31 };
32 
33 /**
34  * An item that creates delegates for actions and lays them out in a row.
35  *
36  * This effectively combines RowLayout and Repeater in a single item, with the
37  * addition of some extra performance enhancing tweaks. It will create instances
38  * of ::fullDelegate and ::itemDelegate for each action in ::actions . These are
39  * then positioned horizontally. Any action that ends up being placed outside
40  * the width of the item is hidden and will be part of ::hiddenActions.
41  *
42  * The items created as delegates are always created asynchronously, to avoid
43  * creation lag spikes. Each delegate has access to the action it was created
44  * for through the ToolBarLayoutAttached attached property.
45  */
46 class ToolBarLayout : public QQuickItem
47 {
48  Q_OBJECT
49  /**
50  * The actions this layout should create delegates for.
51  */
52  Q_PROPERTY(QQmlListProperty<QObject> actions READ actionsProperty NOTIFY actionsChanged)
53  /**
54  * A list of actions that do not fit in the current view and are thus hidden.
55  */
56  Q_PROPERTY(QList<QObject *> hiddenActions READ hiddenActions NOTIFY hiddenActionsChanged)
57  /**
58  * A component that is used to create full-size delegates from.
59  *
60  * Each delegate has three states, it can be full-size, icon-only or hidden.
61  * By default, the full-size delegate is used. When the action has the
62  * DisplayHint::IconOnly hint set, it will always use the iconDelegate. When
63  * it has the DisplayHint::KeepVisible hint set, it will use the full-size
64  * delegate when it fits. If not, it will use the iconDelegate, unless even
65  * that does not fit, in which case it will still be hidden.
66  */
67  Q_PROPERTY(QQmlComponent *fullDelegate READ fullDelegate WRITE setFullDelegate NOTIFY fullDelegateChanged)
68  /**
69  * A component that is used to create icon-only delegates from.
70  *
71  * \sa fullDelegate
72  */
73  Q_PROPERTY(QQmlComponent *iconDelegate READ iconDelegate WRITE setIconDelegate NOTIFY iconDelegateChanged)
74  /**
75  * A component that is used to create the "more button" item from.
76  *
77  * The more button is shown when there are actions that do not fit the
78  * current view. It is intended to have functionality to show these hidden
79  * actions, like popup a menu with them showing.
80  */
81  Q_PROPERTY(QQmlComponent *moreButton READ moreButton WRITE setMoreButton NOTIFY moreButtonChanged)
82  /**
83  * The amount of spacing between individual delegates.
84  */
85  Q_PROPERTY(qreal spacing READ spacing WRITE setSpacing NOTIFY spacingChanged)
86  /**
87  * How to align the delegates within this layout.
88  *
89  * When there is more space available than required by the visible delegates,
90  * we need to determine how to place the delegates. This property determines
91  * how to do that. Note that the moreButton, if visible, will always be
92  * placed at the end of the layout.
93  */
94  Q_PROPERTY(Qt::Alignment alignment READ alignment WRITE setAlignment NOTIFY alignmentChanged)
95  /**
96  * The combined width of visible delegates in this layout.
97  */
98  Q_PROPERTY(qreal visibleWidth READ visibleWidth NOTIFY visibleWidthChanged)
99  /**
100  * The minimum width this layout can have.
101  *
102  * This is equal to the width of the moreButton.
103  */
104  Q_PROPERTY(qreal minimumWidth READ minimumWidth NOTIFY minimumWidthChanged)
105  /**
106  * Which direction to layout in.
107  *
108  * This is primarily intended to support right-to-left layouts. When set to
109  * LeftToRight, delegates will be layout with the first item on the left and
110  * following items to the right of that. The more button will be placed at
111  * the rightmost position. Alignment flags work normally.
112  *
113  * When set to RightToLeft, delegates will be layout with the first item on
114  * the right and following items to the left of that. The more button will
115  * be placed at the leftmost position. Alignment flags are inverted, so
116  * AlignLeft will align items to the right, and vice-versa.
117  */
118  Q_PROPERTY(Qt::LayoutDirection layoutDirection READ layoutDirection WRITE setLayoutDirection NOTIFY layoutDirectionChanged)
119  /**
120  * How to handle items that do not match the toolbar's height.
121  *
122  * When toolbar items do not match the height of the toolbar, there are
123  * several ways we can deal with this. This property sets the preferred way.
124  *
125  * The default is HeightMode::ConstrainIfLarger .
126  *
127  * \sa HeightMode
128  */
129  Q_PROPERTY(HeightMode heightMode READ heightMode WRITE setHeightMode NOTIFY heightModeChanged)
130 
131 public:
133 
134  /**
135  * An enum describing several modes that can be used to deal with items with
136  * a height that does not match the toolbar's height.
137  */
138  enum HeightMode {
139  AlwaysCenter, ///< Always center items, allowing them to go outside the bounds of the layout if they are larger.
140  AlwaysFill, ///< Always match the height of the layout. Larger items will be reduced in height, smaller items will be increased.
141  ConstrainIfLarger, ///< If the item is larger than the toolbar, reduce its height. Otherwise center it in the toolbar.
142  };
144 
145  ToolBarLayout(QQuickItem *parent = nullptr);
146  ~ToolBarLayout() override;
147 
148  ActionsProperty actionsProperty() const;
149  /**
150  * Add an action to the list of actions.
151  *
152  * \param action The action to add.
153  */
154  void addAction(QObject *action);
155  /**
156  * Remove an action from the list of actions.
157  *
158  * \param action The action to remove.
159  */
160  void removeAction(QObject *action);
161  /**
162  * Clear the list of actions.
163  */
164  void clearActions();
165  Q_SIGNAL void actionsChanged();
166 
168  Q_SIGNAL void hiddenActionsChanged();
169 
170  QQmlComponent *fullDelegate() const;
171  void setFullDelegate(QQmlComponent *newFullDelegate);
172  Q_SIGNAL void fullDelegateChanged();
173 
174  QQmlComponent *iconDelegate() const;
175  void setIconDelegate(QQmlComponent *newIconDelegate);
176  Q_SIGNAL void iconDelegateChanged();
177 
178  QQmlComponent *moreButton() const;
179  void setMoreButton(QQmlComponent *newMoreButton);
180  Q_SIGNAL void moreButtonChanged();
181 
182  qreal spacing() const;
183  void setSpacing(qreal newSpacing);
184  Q_SIGNAL void spacingChanged();
185 
186  Qt::Alignment alignment() const;
187  void setAlignment(Qt::Alignment newAlignment);
188  Q_SIGNAL void alignmentChanged();
189 
190  qreal visibleWidth() const;
191  Q_SIGNAL void visibleWidthChanged();
192 
193  qreal minimumWidth() const;
194  Q_SIGNAL void minimumWidthChanged();
195 
197  void setLayoutDirection(Qt::LayoutDirection &newLayoutDirection);
198  Q_SIGNAL void layoutDirectionChanged();
199 
200  HeightMode heightMode() const;
201  void setHeightMode(HeightMode newHeightMode);
202  Q_SIGNAL void heightModeChanged();
203 
204  /**
205  * Queue a relayout of this layout.
206  *
207  * \note The layouting happens during the next scene graph polishing phase.
208  */
209  Q_SLOT void relayout();
210 
211  static ToolBarLayoutAttached *qmlAttachedProperties(QObject *object)
212  {
213  return new ToolBarLayoutAttached(object);
214  }
215 
216 protected:
217  void componentComplete() override;
218 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
219  void geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry) override;
220 #else
221  void geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry) override;
222 #endif
223  void itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &data) override;
224  void updatePolish() override;
225 
226 private:
227  class Private;
228  const std::unique_ptr<Private> d;
229 };
230 
231 QML_DECLARE_TYPEINFO(ToolBarLayout, QML_HAS_ATTACHED_PROPERTIES)
232 
233 #endif // TOOLBARLAYOUT_H
Qt::Alignment alignment
How to align the delegates within this layout.
Definition: toolbarlayout.h:94
Q_OBJECTQ_OBJECT
typedef Alignment
Q_PROPERTY(...)
Q_ENUM(...)
QQmlComponent iconDelegate
A component that is used to create icon-only delegates from.
Definition: toolbarlayout.h:73
Q_SIGNALQ_SIGNAL
QQmlComponent fullDelegate
A component that is used to create full-size delegates from.
Definition: toolbarlayout.h:67
HeightMode heightMode
How to handle items that do not match the toolbar's height.
void clearActions()
Clear the list of actions.
QList< QObject * > hiddenActions
A list of actions that do not fit in the current view and are thus hidden.
Definition: toolbarlayout.h:56
qreal minimumWidth
The minimum width this layout can have.
qreal spacing
The amount of spacing between individual delegates.
Definition: toolbarlayout.h:85
QQmlComponent moreButton
A component that is used to create the "more button" item from.
Definition: toolbarlayout.h:81
virtual void geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry)
@ AlwaysFill
Always match the height of the layout. Larger items will be reduced in height, smaller items will be ...
Q_SLOTQ_SLOT
Qt::LayoutDirection layoutDirection
Which direction to layout in.
QQmlListProperty< QObject > actions
The actions this layout should create delegates for.
Definition: toolbarlayout.h:52
QObject action
The action this delegate was created for.
Definition: toolbarlayout.h:22
An item that creates delegates for actions and lays them out in a row.
Definition: toolbarlayout.h:46
qreal visibleWidth
The combined width of visible delegates in this layout.
Definition: toolbarlayout.h:98
LayoutDirection
void addAction(QObject *action)
Add an action to the list of actions.
void removeAction(QObject *action)
Remove an action from the list of actions.
Q_SLOT void relayout()
Queue a relayout of this layout.
HeightMode
An enum describing several modes that can be used to deal with items with a height that does not matc...
@ ConstrainIfLarger
If the item is larger than the toolbar, reduce its height. Otherwise center it in the toolbar.
Attached property for ToolBarLayout delegates.
Definition: toolbarlayout.h:16
QObject * parent() const const
@ AlwaysCenter
Always center items, allowing them to go outside the bounds of the layout if they are larger.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jan 29 2023 04:11:03 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.