Qt Accessibility Client

registry.h
1 /*
2  SPDX-FileCopyrightText: 2012 Frederik Gladhorn <[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 QACCESSIBILITYCLIENT_REGISTRY_H
8 #define QACCESSIBILITYCLIENT_REGISTRY_H
9 
10 #include <qobject.h>
11 
12 #include "qaccessibilityclient_export.h"
13 #include "accessibleobject.h"
14 #include <QUrl>
15 
16 #define accessibleRegistry (QAccessibleClient::Registry::instance())
17 
18 namespace QAccessibleClient {
19 
20 class RegistryPrivate;
21 class RegistryPrivateCacheApi;
22 
23 /**
24  This class represents the global accessibility registry.
25 
26  It provides information about running applications.
27  All updates of accessible objects will result in signals emitted by this class.
28 */
29 class QACCESSIBILITYCLIENT_EXPORT Registry : public QObject
30 {
31  Q_OBJECT
32 
33 public:
34 
35  /**
36  This enum describes the different types of events that can be observed.
37  */
39  NoEventListeners = 0x0, /*!< No event listeners registered or wanted */
40  Window = 0x1, /*!< Window changes, such as new applications being started */
41  Focus = 0x2, /*!< Focus listener reacts to focus changes - see signal \sa focusChanged */
42  //FocusPoint = 0x4,
43 
44  //BoundsChanged = 0x8,
45  //LinkSelected = 0x10,
46  StateChanged = 0x20, /*!< State of the accessible changed - see signal \sa stateChanged */
47  ChildrenChanged = 0x40, /*!< Children changed - see signal \sa childrenChanged */
48  VisibleDataChanged = 0x80, /*!< Visibility of the accessible changed - see signal \sa visibleDataChanged */
49  SelectionChanged = 0x100, /*!< Selection changed - see signal \sa selectionChanged */
50  ModelChanged = 0x200, /*!< The model changed - see signal \sa modelChanged */
51 
52  TextCaretMoved = 0x400, /*!< The text caret moved its position - see signal \sa textCaretMoved */
53  TextChanged = 0x800, /*!< The text changed - see signal \sa textChanged */
54  TextSelectionChanged = 0x1000, /*!< The text selection changed - see signal \sa textSelectionChanged */
55  PropertyChanged = 0x2000, /*!< A property changed. See signals \sa accessibleNameChanged and \sa accessibleDescriptionChanged */
56  //TextBoundsChanged = 0x2000,
57  //TextAttributesChanged = 0x4000,
58  //AttributesChanged = 0x8000,
59 
60  AllEventListeners = 0xffffffff /*!< All possible event listeners */
61  };
62  Q_ENUM(EventListener)
63  Q_DECLARE_FLAGS(EventListeners, EventListener)
64 
65  /**
66  Construct a Registry object with \a parent as QObject parent.
67  */
68  explicit Registry(QObject *parent = nullptr);
69  /**
70  Destroys this Registry.
71  */
72  ~Registry() override;
73 
74 public Q_SLOTS:
75 
76  /**
77  Returns true if the accessibility stack is enabled.
78 
79  This means that an atspi registry daemon is running and available as
80  org.a11y.bus at the session dbus. The org.a11y.bus implments the
81  org.a11y.Status dbus interface that offers the IsEnabled property. The
82  \a isEnabled and \a setEnabled methods do read/write the boolean value
83  of that org.a11y.Status.IsEnabled dbus property..
84  */
85  bool isEnabled() const;
86  /**
87  Activates accessibility when \a enabled and tells
88  toolkits to provide updates such as focus changes.
89  */
90  void setEnabled(bool enable);
91 
92  /**
93  Returns true if the screen reader is enabled.
94 
95  This means that there is potentially a screen reader, if installed,
96  that is enabled or disabled. This allows to enable system wide a
97  screen reader with just one switch.
98  */
99  bool isScreenReaderEnabled() const;
100  /**
101  Tells the system that a screen reader is \a enabled.
102  */
103  void setScreenReaderEnabled(bool enable);
104 
105  /**
106  In order to get notified of changes in accessible applications
107  it is neccessary to subscribe to the listeners that are relevant.
108 
109  This will unsubscribe all previously subscribed event listeners.
110  */
111  void subscribeEventListeners(const EventListeners &listeners) const;
112  /**
113  Returns the active event listeners.
114  */
115  EventListeners subscribedEventListeners() const;
116 
117  /**
118  List of all currently running applications that
119  expose an accessibility interface.
120  */
121  QList<AccessibleObject> applications() const;
122 
123  /**
124  Creates the AccessibleObject for the \a url.
125 
126  This can be used to deserialize an AccessibleObject
127  after passing it around as string.
128 
129  The returned QUrl returns a scheme of "accessibleobject".
130  */
131  AccessibleObject accessibleFromUrl(const QUrl &url) const;
132 
133 Q_SIGNALS:
134 
135  /**
136  Emitted if the \a isEnabled state changed.
137 
138  If the accessibility daemon got enabled or disabled either by us or
139  ny someone else then this signal is emitted.
140  */
141  void enabledChanged(bool enabled);
142 
143  /**
144  Emitted if the \a isScreenReaderEnabled state changed.
145 
146  If the screen reader enabled property got enabled or disabled either
147  by us or by someone else then this signal is emitted.
148  */
149  void screenReaderEnabledChanged(bool enabled);
150 
151  /**
152  Emitted if a AccessibleObject is created.
153 
154  This signal indicates that the \a AccessibleObject instance was
155  created and is going to be added/attached.
156  */
157  void added(const QAccessibleClient::AccessibleObject &object);
158 
159  /**
160  Emitted if a AccessibleObject is destroyed.
161 
162  This signal indicates that the \a AccessibleObject instance was
163  destroyed and ended its life-time.
164  */
165  void removed(const QAccessibleClient::AccessibleObject &object);
166 
167  /**
168  Emitted if a AccessibleObject is marked defunct.
169 
170  This signal indicates that the \a AccessibleObject became invalid
171  and does not point any longer to any valid accessible object.
172  */
173  void defunct(const QAccessibleClient::AccessibleObject &object);
174 
175  /// Emitted when a window is created
176  void windowCreated(const QAccessibleClient::AccessibleObject &object);
177  /// Emitted when a window is destroyed
178  void windowDestroyed(const QAccessibleClient::AccessibleObject &object);
179  /// Emitted when a window is closed
180  void windowClosed(const QAccessibleClient::AccessibleObject &object);
181  /// Emitted when a window is reparented
182  void windowReparented(const QAccessibleClient::AccessibleObject &object);
183  /// Emitted when a window is minimized
184  void windowMinimized(const QAccessibleClient::AccessibleObject &object);
185  /// Emitted when a window is maximized
186  void windowMaximized(const QAccessibleClient::AccessibleObject &object);
187  /// Emitted when a window is restored to normal size
188  void windowRestored(const QAccessibleClient::AccessibleObject &object);
189  /// Emitted when a window is activated
190  void windowActivated(const QAccessibleClient::AccessibleObject &object);
191  /// Emitted when a window is deactivated
192  void windowDeactivated(const QAccessibleClient::AccessibleObject &object);
193  /// Emitted when a desktop window is created
194  void windowDesktopCreated(const QAccessibleClient::AccessibleObject &object);
195  /// Emitted when a desktop window is destroyed
196  void windowDesktopDestroyed(const QAccessibleClient::AccessibleObject &object);
197  /// Emitted when a window is raised
198  void windowRaised(const QAccessibleClient::AccessibleObject &object);
199  /// Emitted when a window is lowered
200  void windowLowered(const QAccessibleClient::AccessibleObject &object);
201  /// Emitted when a window is moved
202  void windowMoved(const QAccessibleClient::AccessibleObject &object);
203  /// Emitted when a window is resized
204  void windowResized(const QAccessibleClient::AccessibleObject &object);
205  /// Emitted when a window is shaded
206  void windowShaded(const QAccessibleClient::AccessibleObject &object);
207  /// Emitted when a window is unshaded
208  void windowUnshaded(const QAccessibleClient::AccessibleObject &object);
209 
210  //void boundsChanged(const QAccessibleClient::AccessibleObject &object);
211  //void linkSelected(const QAccessibleClient::AccessibleObject &object);
212 
213  /**
214  \brief Notifies about a state change in an object.
215 
216  The \a state of \a object has change.
217  If the state is now set \a active is true, otherwise the state was removed.
218  */
219  void stateChanged(const QAccessibleClient::AccessibleObject &object, const QString &state, bool active);
220 
221  /**
222  \brief Notifies about a new AccessibleObject
223 
224  The childAdded signal is emitted when a new accessible object is created.
225  This signal depends on the implementation of the server side and is not
226  reliable for all applications.
227  The parameter \a childIndex is the index of the child that has been added.
228  \sa AccessibleObject::child(), childRemoved()
229  */
230  void childAdded(const QAccessibleClient::AccessibleObject &parent, int childIndex);
231 
232  /**
233  \brief Notifies that an AccessibleObject has been removed
234 
235  The parameter \a childIndex is the index of the child that has been removed.
236  \sa AccessibleObject::child(), childAdded()
237  */
238  void childRemoved(const QAccessibleClient::AccessibleObject &parent, int childIndex);
239 
240  /**
241  \brief Notifies that the \a object's visible data changed.
242  */
243  void visibleDataChanged(const QAccessibleClient::AccessibleObject &object);
244 
245  /**
246  \brief Notifies that the \a object's selection changed.
247  */
248  void selectionChanged(const QAccessibleClient::AccessibleObject &object);
249 
250  /**
251  \brief Notifies that the \a object's table model changed.
252  */
253  void modelChanged(const QAccessibleClient::AccessibleObject &object);
254 
255  /**
256  \brief Emitted when the focus changed.
257 
258  When subscribed to the Focus EventListener then this signal is emitted
259  every time the focus changes. \a object is the newly focused AccessibleObject.
260  */
261  void focusChanged(const QAccessibleClient::AccessibleObject &object);
262 
263  /**
264  \brief Emitted when the text cared moved.
265 
266  When subscribed to the TextCaretMoved EventListener then this signal
267  is emitted every time the caret in an accessible object that implements
268  a text-interface (like QLineEdit, QTextArea and QComboBox) moved to
269  another position.
270  */
271  void textCaretMoved(const QAccessibleClient::AccessibleObject &object, int pos);
272 
273  /**
274  \brief Emitted when the text selection changed.
275 
276  When subscribed to the TextSelectionChanged EventListener then this signal
277  is emitted every time the selection in an accessible object that implements
278  a text-interface (like QLineEdit, QTextArea and QComboBox) changed.
279  */
280  void textSelectionChanged(const QAccessibleClient::AccessibleObject &object);
281 
282 
283  /**
284  \brief Emitted when an accessible name changes
285 
286  When subscribed to the PropertyChanged EventListener, this signal is emitted
287  whenever the accessible-name property changes its value.
288  */
289  void accessibleNameChanged(const QAccessibleClient::AccessibleObject &object);
290 
291  /**
292  \brief Emitted when an accessible description changes
293 
294  When subscribed to the PropertyChanged EventListener, this signal is emitted
295  whenever the accessible-description property changes its value.
296  */
297  void accessibleDescriptionChanged(const QAccessibleClient::AccessibleObject &object);
298 
299  /**
300  \brief Emitted when an object's text was changed.
301 
302  The new text will be \a text. The change starts at \a startOffset and goes to \a endOffset.
303 
304  \sa textInserted, textRemoved
305  */
306  void textChanged(const QAccessibleClient::AccessibleObject &object, const QString& text, int startOffset, int endOffset);
307 
308  /**
309  \brief Emitted when text was inserted in an object's text.
310 
311  The new text will be \a text. The change starts at \a startOffset and goes to \a endOffset.
312 
313  \sa textInserted, textRemoved
314  */
315  void textInserted(const QAccessibleClient::AccessibleObject &object, const QString& text, int startOffset, int endOffset);
316 
317  /**
318  \brief Emitted when an object's text was removed.
319 
320  The removed text will be \a text, but this string may be emtpy for some implementations.
321  The removal starts at \a startOffset and goes to \a endOffset.
322 
323  \sa textInserted, textRemoved
324  */
325  void textRemoved(const QAccessibleClient::AccessibleObject &object, const QString& text, int startOffset, int endOffset);
326 
327  //void textBoundsChanged(const QAccessibleClient::AccessibleObject &object);
328  //void textAttributesChanged(const QAccessibleClient::AccessibleObject &object);
329  //void attributesChanged(const QAccessibleClient::AccessibleObject &object);
330 
331 private:
332  Q_DISABLE_COPY(Registry)
333  RegistryPrivate *d;
334  friend class RegistryPrivate;
335  friend class RegistryPrivateCacheApi;
336 
337  enum CacheType { NoCache, WeakCache};
338  CacheType cacheType() const;
339  void setCacheType(CacheType type);
340  AccessibleObject clientCacheObject(const QString &id) const;
341  QStringList clientCacheObjects() const;
342  void clearClientCache();
343 };
344 
345 Q_DECLARE_OPERATORS_FOR_FLAGS(Registry::EventListeners)
346 
347 }
348 
349 #endif
This class represents the global accessibility registry.
Definition: registry.h:29
This class represents an accessible object.
EventListener
This enum describes the different types of events that can be observed.
Definition: registry.h:38
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 23 2021 23:04:35 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.