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