Kirigami2

mnemonicattached.h
1 /*
2  * SPDX-FileCopyrightText: 2017 Marco Martin <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 
7 #ifndef MNEMONICATTACHED_H
8 #define MNEMONICATTACHED_H
9 
10 #include <QObject>
11 #include <QQuickWindow>
12 #include <QtQml>
13 
14 /**
15  * This Attached property is used to calculate automated keyboard sequences
16  * to trigger actions based upon their text: if an "&" mnemonic is
17  * used (ie "&Ok"), the system will attempt to assign the desired letter giving
18  * it priority, otherwise a letter among the ones in the label will be used if
19  * possible and not conflicting.
20  * Different kinds of controls will have different priorities in assigning the
21  * shortcut: for instance the "Ok/Cancel" buttons in a dialog will have priority
22  * over fields of a FormLayout.
23  * @see ControlType
24  *
25  * Usually the developer shouldn't use this directly as base components
26  * already use this, but only when implementing a custom graphical Control.
27  * @since 2.3
28  */
29 class MnemonicAttached : public QObject
30 {
31  Q_OBJECT
32  /**
33  * The label of the control we want to compute a mnemonic for, instance
34  * "Label:" or "&Ok"
35  */
36  Q_PROPERTY(QString label READ label WRITE setLabel NOTIFY labelChanged)
37 
38  /**
39  * The user-visible final label, which will have the shortcut letter underlined,
40  * such as "&lt;u&gt;O&lt;/u&gt;k"
41  */
42  Q_PROPERTY(QString richTextLabel READ richTextLabel NOTIFY richTextLabelChanged)
43 
44  /**
45  * The label with an "&" mnemonic in the place which will have the shortcut
46  * assigned, regardless of whether the & was assigned by the user or automatically generated.
47  */
48  Q_PROPERTY(QString mnemonicLabel READ mnemonicLabel NOTIFY mnemonicLabelChanged)
49 
50  /**
51  * Only if true this mnemonic will be considered for the global assignment
52  * default: true
53  */
54  Q_PROPERTY(bool enabled READ enabled WRITE setEnabled NOTIFY enabledChanged)
55 
56  /**
57  * The type of control this mnemonic is attached: different types of controls have different importance and priority for shortcut assignment.
58  * @see ControlType
59  */
60  Q_PROPERTY(MnemonicAttached::ControlType controlType READ controlType WRITE setControlType NOTIFY controlTypeChanged)
61 
62  /**
63  * The final key sequence assigned, if any: it will be Alt+alphanumeric char
64  */
65  Q_PROPERTY(QKeySequence sequence READ sequence NOTIFY sequenceChanged)
66 
67  /**
68  * True when the user is pressing alt and the accelerators should be shown
69  *
70  * @since 5.72
71  * @since 2.15
72  */
73  Q_PROPERTY(bool active READ active WRITE setActive NOTIFY activeChanged)
74 
75 public:
76  enum ControlType {
77  ActionElement, /**< pushbuttons, checkboxes etc */
78  DialogButton, /**< buttons for dialogs */
79  MenuItem, /**< Menu items */
80  FormLabel, /**< Buddy label in a FormLayout*/
81  SecondaryControl, /**< Other controls that are considered not much important and low priority for shortcuts */
82  };
84 
85  explicit MnemonicAttached(QObject *parent = nullptr);
86  ~MnemonicAttached() override;
87 
88  void setLabel(const QString &text);
89  QString label() const;
90 
91  QString richTextLabel() const;
92  QString mnemonicLabel() const;
93 
94  void setEnabled(bool enabled);
95  bool enabled() const;
96 
97  void setControlType(MnemonicAttached::ControlType controlType);
98  ControlType controlType() const;
99 
101 
102  void setActive(bool active);
103  bool active() const;
104 
105  // QML attached property
106  static MnemonicAttached *qmlAttachedProperties(QObject *object);
107 
108 protected:
109  bool eventFilter(QObject *watched, QEvent *e) override;
110  void updateSequence();
111 
112 Q_SIGNALS:
113  void labelChanged();
114  void enabledChanged();
115  void sequenceChanged();
116  void richTextLabelChanged();
117  void mnemonicLabelChanged();
118  void controlTypeChanged();
119  void activeChanged();
120 
121 private:
122  void calculateWeights();
123  bool installEventFilterForWindow(QQuickWindow *wnd);
124  bool removeEventFilterForWindow(QQuickWindow *wnd);
125 
126  // TODO: to have support for DIALOG_BUTTON_EXTRA_WEIGHT etc, a type enum should be exported
127  enum {
128  // Additional weight for first character in string
129  FIRST_CHARACTER_EXTRA_WEIGHT = 50,
130  // Additional weight for the beginning of a word
131  WORD_BEGINNING_EXTRA_WEIGHT = 50,
132  // Additional weight for a 'wanted' accelerator ie string with '&'
133  WANTED_ACCEL_EXTRA_WEIGHT = 150,
134  // Default weight for an 'action' widget (ie, pushbuttons)
135  ACTION_ELEMENT_WEIGHT = 50,
136  // Additional weight for the dialog buttons (large, we basically never want these reassigned)
137  DIALOG_BUTTON_EXTRA_WEIGHT = 300,
138  // Weight for FormLayout labels (low)
139  FORM_LABEL_WEIGHT = 20,
140  // Weight for Secondary controls which are considered less important (low)
141  SECONDARY_CONTROL_WEIGHT = 10,
142  // Default weight for menu items
143  MENU_ITEM_WEIGHT = 250,
144  };
145 
146  // order word letters by weight
147  int m_weight = 0;
148  int m_baseWeight = 0;
149  ControlType m_controlType = SecondaryControl;
150  QMap<int, QChar> m_weights;
151 
152  QString m_label;
153  QString m_actualRichTextLabel;
154  QString m_richTextLabel;
155  QString m_mnemonicLabel;
156  QKeySequence m_sequence;
157  bool m_enabled = true;
158  bool m_active = false;
159 
160  QPointer<QQuickWindow> m_window;
161 
162  // global mapping of mnemonics
163  // TODO: map by QWindow
164  static QHash<QKeySequence, MnemonicAttached *> s_sequenceToObject;
165 };
166 
167 QML_DECLARE_TYPEINFO(MnemonicAttached, QML_HAS_ATTACHED_PROPERTIES)
168 
169 #endif // MnemonicATTACHED_H
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_ENUM(...)
bool active
True when the user is pressing alt and the accelerators should be shown.
@ FormLabel
Buddy label in a FormLayout.
bool enabled
Only if true this mnemonic will be considered for the global assignment default: true.
QString label
The label of the control we want to compute a mnemonic for, instance "Label:" or "&Ok".
@ MenuItem
Menu items.
QString richTextLabel
The user-visible final label, which will have the shortcut letter underlined, such as "<u>O</u>k".
Q_SIGNALSQ_SIGNALS
QString mnemonicLabel
The label with an "&" mnemonic in the place which will have the shortcut assigned,...
This Attached property is used to calculate automated keyboard sequences to trigger actions based upo...
QKeySequence sequence
The final key sequence assigned, if any: it will be Alt+alphanumeric char.
@ DialogButton
buttons for dialogs
@ ActionElement
pushbuttons, checkboxes etc
QObject * parent() const const
@ SecondaryControl
Other controls that are considered not much important and low priority for shortcuts.
MnemonicAttached::ControlType controlType
The type of control this mnemonic is attached: different types of controls have different importance ...
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.