File indexing completed on 2024-11-03 04:21:02
0001 /* 0002 SPDX-FileCopyrightText: 2012 Frederik Gladhorn <gladhorn@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0005 */ 0006 0007 #ifndef QACCESSIBILITYCLIENT_REGISTRY_H 0008 #define QACCESSIBILITYCLIENT_REGISTRY_H 0009 0010 #include <QObject> 0011 0012 #include "qaccessibilityclient_export.h" 0013 #include "accessibleobject.h" 0014 #include <QUrl> 0015 0016 #define accessibleRegistry (QAccessibleClient::Registry::instance()) 0017 0018 namespace QAccessibleClient { 0019 0020 class RegistryPrivate; 0021 class RegistryPrivateCacheApi; 0022 0023 /** 0024 This class represents the global accessibility registry. 0025 0026 It provides information about running applications. 0027 All updates of accessible objects will result in signals emitted by this class. 0028 */ 0029 class QACCESSIBILITYCLIENT_EXPORT Registry : public QObject 0030 { 0031 Q_OBJECT 0032 0033 public: 0034 0035 /** 0036 This enum describes the different types of events that can be observed. 0037 */ 0038 enum EventListener { 0039 NoEventListeners = 0x0, /*!< No event listeners registered or wanted */ 0040 Window = 0x1, /*!< Window changes, such as new applications being started */ 0041 Focus = 0x2, /*!< Focus listener reacts to focus changes - see signal \sa focusChanged */ 0042 //FocusPoint = 0x4, 0043 0044 //BoundsChanged = 0x8, 0045 //LinkSelected = 0x10, 0046 StateChanged = 0x20, /*!< State of the accessible changed - see signal \sa stateChanged */ 0047 ChildrenChanged = 0x40, /*!< Children changed - see signal \sa childrenChanged */ 0048 VisibleDataChanged = 0x80, /*!< Visibility of the accessible changed - see signal \sa visibleDataChanged */ 0049 SelectionChanged = 0x100, /*!< Selection changed - see signal \sa selectionChanged */ 0050 ModelChanged = 0x200, /*!< The model changed - see signal \sa modelChanged */ 0051 0052 TextCaretMoved = 0x400, /*!< The text caret moved its position - see signal \sa textCaretMoved */ 0053 TextChanged = 0x800, /*!< The text changed - see signal \sa textChanged */ 0054 TextSelectionChanged = 0x1000, /*!< The text selection changed - see signal \sa textSelectionChanged */ 0055 PropertyChanged = 0x2000, /*!< A property changed. See signals \sa accessibleNameChanged and \sa accessibleDescriptionChanged */ 0056 //TextBoundsChanged = 0x2000, 0057 //TextAttributesChanged = 0x4000, 0058 //AttributesChanged = 0x8000, 0059 0060 AllEventListeners = 0xffffffff /*!< All possible event listeners */ 0061 }; 0062 Q_ENUM(EventListener) 0063 Q_DECLARE_FLAGS(EventListeners, EventListener) 0064 0065 /** 0066 Construct a Registry object with \a parent as QObject parent. 0067 */ 0068 explicit Registry(QObject *parent = nullptr); 0069 /** 0070 Destroys this Registry. 0071 */ 0072 ~Registry() override; 0073 0074 public Q_SLOTS: 0075 0076 /** 0077 Returns true if the accessibility stack is enabled. 0078 0079 This means that an atspi registry daemon is running and available as 0080 org.a11y.bus at the session dbus. The org.a11y.bus implments the 0081 org.a11y.Status dbus interface that offers the IsEnabled property. The 0082 \a isEnabled and \a setEnabled methods do read/write the boolean value 0083 of that org.a11y.Status.IsEnabled dbus property.. 0084 */ 0085 bool isEnabled() const; 0086 /** 0087 Activates accessibility when \a enabled and tells 0088 toolkits to provide updates such as focus changes. 0089 */ 0090 void setEnabled(bool enable); 0091 0092 /** 0093 Returns true if the screen reader is enabled. 0094 0095 This means that there is potentially a screen reader, if installed, 0096 that is enabled or disabled. This allows to enable system wide a 0097 screen reader with just one switch. 0098 */ 0099 bool isScreenReaderEnabled() const; 0100 /** 0101 Tells the system that a screen reader is \a enabled. 0102 */ 0103 void setScreenReaderEnabled(bool enable); 0104 0105 /** 0106 In order to get notified of changes in accessible applications 0107 it is neccessary to subscribe to the listeners that are relevant. 0108 0109 This will unsubscribe all previously subscribed event listeners. 0110 */ 0111 void subscribeEventListeners(const EventListeners &listeners) const; 0112 /** 0113 Returns the active event listeners. 0114 */ 0115 EventListeners subscribedEventListeners() const; 0116 0117 /** 0118 List of all currently running applications that 0119 expose an accessibility interface. 0120 */ 0121 QList<AccessibleObject> applications() const; 0122 0123 /** 0124 Creates the AccessibleObject for the \a url. 0125 0126 This can be used to deserialize an AccessibleObject 0127 after passing it around as string. 0128 0129 The returned QUrl returns a scheme of "accessibleobject". 0130 */ 0131 AccessibleObject accessibleFromUrl(const QUrl &url) const; 0132 0133 Q_SIGNALS: 0134 0135 /** 0136 Emitted if the \a isEnabled state changed. 0137 0138 If the accessibility daemon got enabled or disabled either by us or 0139 ny someone else then this signal is emitted. 0140 */ 0141 void enabledChanged(bool enabled); 0142 0143 /** 0144 Emitted if the \a isScreenReaderEnabled state changed. 0145 0146 If the screen reader enabled property got enabled or disabled either 0147 by us or by someone else then this signal is emitted. 0148 */ 0149 void screenReaderEnabledChanged(bool enabled); 0150 0151 /** 0152 Emitted if a AccessibleObject is created. 0153 0154 This signal indicates that the \a AccessibleObject instance was 0155 created and is going to be added/attached. 0156 */ 0157 void added(const QAccessibleClient::AccessibleObject &object); 0158 0159 /** 0160 Emitted if a AccessibleObject is destroyed. 0161 0162 This signal indicates that the \a AccessibleObject instance was 0163 destroyed and ended its life-time. 0164 */ 0165 void removed(const QAccessibleClient::AccessibleObject &object); 0166 0167 /** 0168 Emitted if a AccessibleObject is marked defunct. 0169 0170 This signal indicates that the \a AccessibleObject became invalid 0171 and does not point any longer to any valid accessible object. 0172 */ 0173 void defunct(const QAccessibleClient::AccessibleObject &object); 0174 0175 /// Emitted when a window is created 0176 void windowCreated(const QAccessibleClient::AccessibleObject &object); 0177 /// Emitted when a window is destroyed 0178 void windowDestroyed(const QAccessibleClient::AccessibleObject &object); 0179 /// Emitted when a window is closed 0180 void windowClosed(const QAccessibleClient::AccessibleObject &object); 0181 /// Emitted when a window is reparented 0182 void windowReparented(const QAccessibleClient::AccessibleObject &object); 0183 /// Emitted when a window is minimized 0184 void windowMinimized(const QAccessibleClient::AccessibleObject &object); 0185 /// Emitted when a window is maximized 0186 void windowMaximized(const QAccessibleClient::AccessibleObject &object); 0187 /// Emitted when a window is restored to normal size 0188 void windowRestored(const QAccessibleClient::AccessibleObject &object); 0189 /// Emitted when a window is activated 0190 void windowActivated(const QAccessibleClient::AccessibleObject &object); 0191 /// Emitted when a window is deactivated 0192 void windowDeactivated(const QAccessibleClient::AccessibleObject &object); 0193 /// Emitted when a desktop window is created 0194 void windowDesktopCreated(const QAccessibleClient::AccessibleObject &object); 0195 /// Emitted when a desktop window is destroyed 0196 void windowDesktopDestroyed(const QAccessibleClient::AccessibleObject &object); 0197 /// Emitted when a window is raised 0198 void windowRaised(const QAccessibleClient::AccessibleObject &object); 0199 /// Emitted when a window is lowered 0200 void windowLowered(const QAccessibleClient::AccessibleObject &object); 0201 /// Emitted when a window is moved 0202 void windowMoved(const QAccessibleClient::AccessibleObject &object); 0203 /// Emitted when a window is resized 0204 void windowResized(const QAccessibleClient::AccessibleObject &object); 0205 /// Emitted when a window is shaded 0206 void windowShaded(const QAccessibleClient::AccessibleObject &object); 0207 /// Emitted when a window is unshaded 0208 void windowUnshaded(const QAccessibleClient::AccessibleObject &object); 0209 0210 //void boundsChanged(const QAccessibleClient::AccessibleObject &object); 0211 //void linkSelected(const QAccessibleClient::AccessibleObject &object); 0212 0213 /** 0214 \brief Notifies about a state change in an object. 0215 0216 The \a state of \a object has change. 0217 If the state is now set \a active is true, otherwise the state was removed. 0218 */ 0219 void stateChanged(const QAccessibleClient::AccessibleObject &object, const QString &state, bool active); 0220 0221 /** 0222 \brief Notifies about a new AccessibleObject 0223 0224 The childAdded signal is emitted when a new accessible object is created. 0225 This signal depends on the implementation of the server side and is not 0226 reliable for all applications. 0227 The parameter \a childIndex is the index of the child that has been added. 0228 \sa AccessibleObject::child(), childRemoved() 0229 */ 0230 void childAdded(const QAccessibleClient::AccessibleObject &parent, int childIndex); 0231 0232 /** 0233 \brief Notifies that an AccessibleObject has been removed 0234 0235 The parameter \a childIndex is the index of the child that has been removed. 0236 \sa AccessibleObject::child(), childAdded() 0237 */ 0238 void childRemoved(const QAccessibleClient::AccessibleObject &parent, int childIndex); 0239 0240 /** 0241 \brief Notifies that the \a object's visible data changed. 0242 */ 0243 void visibleDataChanged(const QAccessibleClient::AccessibleObject &object); 0244 0245 /** 0246 \brief Notifies that the \a object's selection changed. 0247 */ 0248 void selectionChanged(const QAccessibleClient::AccessibleObject &object); 0249 0250 /** 0251 \brief Notifies that the \a object's table model changed. 0252 */ 0253 void modelChanged(const QAccessibleClient::AccessibleObject &object); 0254 0255 /** 0256 \brief Emitted when the focus changed. 0257 0258 When subscribed to the Focus EventListener then this signal is emitted 0259 every time the focus changes. \a object is the newly focused AccessibleObject. 0260 */ 0261 void focusChanged(const QAccessibleClient::AccessibleObject &object); 0262 0263 /** 0264 \brief Emitted when the text cared moved. 0265 0266 When subscribed to the TextCaretMoved EventListener then this signal 0267 is emitted every time the caret in an accessible object that implements 0268 a text-interface (like QLineEdit, QTextArea and QComboBox) moved to 0269 another position. 0270 */ 0271 void textCaretMoved(const QAccessibleClient::AccessibleObject &object, int pos); 0272 0273 /** 0274 \brief Emitted when the text selection changed. 0275 0276 When subscribed to the TextSelectionChanged EventListener then this signal 0277 is emitted every time the selection in an accessible object that implements 0278 a text-interface (like QLineEdit, QTextArea and QComboBox) changed. 0279 */ 0280 void textSelectionChanged(const QAccessibleClient::AccessibleObject &object); 0281 0282 0283 /** 0284 \brief Emitted when an accessible name changes 0285 0286 When subscribed to the PropertyChanged EventListener, this signal is emitted 0287 whenever the accessible-name property changes its value. 0288 */ 0289 void accessibleNameChanged(const QAccessibleClient::AccessibleObject &object); 0290 0291 /** 0292 \brief Emitted when an accessible description changes 0293 0294 When subscribed to the PropertyChanged EventListener, this signal is emitted 0295 whenever the accessible-description property changes its value. 0296 */ 0297 void accessibleDescriptionChanged(const QAccessibleClient::AccessibleObject &object); 0298 0299 /** 0300 \brief Emitted when an object's text was changed. 0301 0302 The new text will be \a text. The change starts at \a startOffset and goes to \a endOffset. 0303 0304 \sa textInserted, textRemoved 0305 */ 0306 void textChanged(const QAccessibleClient::AccessibleObject &object, const QString& text, int startOffset, int endOffset); 0307 0308 /** 0309 \brief Emitted when text was inserted in an object's text. 0310 0311 The new text will be \a text. The change starts at \a startOffset and goes to \a endOffset. 0312 0313 \sa textInserted, textRemoved 0314 */ 0315 void textInserted(const QAccessibleClient::AccessibleObject &object, const QString& text, int startOffset, int endOffset); 0316 0317 /** 0318 \brief Emitted when an object's text was removed. 0319 0320 The removed text will be \a text, but this string may be emtpy for some implementations. 0321 The removal starts at \a startOffset and goes to \a endOffset. 0322 0323 \sa textInserted, textRemoved 0324 */ 0325 void textRemoved(const QAccessibleClient::AccessibleObject &object, const QString& text, int startOffset, int endOffset); 0326 0327 //void textBoundsChanged(const QAccessibleClient::AccessibleObject &object); 0328 //void textAttributesChanged(const QAccessibleClient::AccessibleObject &object); 0329 //void attributesChanged(const QAccessibleClient::AccessibleObject &object); 0330 0331 private: 0332 Q_DISABLE_COPY(Registry) 0333 RegistryPrivate *d; 0334 friend class RegistryPrivate; 0335 friend class RegistryPrivateCacheApi; 0336 0337 enum CacheType { NoCache, WeakCache}; 0338 QACCESSIBILITYCLIENT_NO_EXPORT CacheType cacheType() const; 0339 QACCESSIBILITYCLIENT_NO_EXPORT void setCacheType(CacheType type); 0340 QACCESSIBILITYCLIENT_NO_EXPORT AccessibleObject clientCacheObject(const QString &id) const; 0341 QACCESSIBILITYCLIENT_NO_EXPORT QStringList clientCacheObjects() const; 0342 QACCESSIBILITYCLIENT_NO_EXPORT void clearClientCache(); 0343 }; 0344 0345 Q_DECLARE_OPERATORS_FOR_FLAGS(Registry::EventListeners) 0346 0347 } 0348 0349 #endif