diff options
Diffstat (limited to 'src/kitemviews/accessibility/kitemlistviewaccessible.h')
| -rw-r--r-- | src/kitemviews/accessibility/kitemlistviewaccessible.h | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/src/kitemviews/accessibility/kitemlistviewaccessible.h b/src/kitemviews/accessibility/kitemlistviewaccessible.h new file mode 100644 index 000000000..4c44b18ad --- /dev/null +++ b/src/kitemviews/accessibility/kitemlistviewaccessible.h @@ -0,0 +1,146 @@ +/* + * SPDX-FileCopyrightText: 2012 Amandeep Singh <[email protected]> + * SPDX-FileCopyrightText: 2024 Felix Ernst <[email protected]> + * + * SPDX-License-Identifier: GPL-2.0-or-later + */ + +#ifndef KITEMLISTVIEWACCESSIBLE_H +#define KITEMLISTVIEWACCESSIBLE_H + +#include "dolphin_export.h" + +#include <QAccessible> +#include <QAccessibleObject> +#include <QAccessibleWidget> +#include <QPointer> + +class KItemListView; +class KItemListContainer; +class KItemListContainerAccessible; +class KItemListSelectionManager; + +/** + * The main class for making the main view accessible. + * + * Such a class is necessary because the KItemListView is a mostly custom entity. This class provides a lot of the functionality to make it possible to + * interact with the view using accessibility tools. It implements various interfaces mostly to generally allow working with the view as a whole. However, + * actually interacting with singular items within the view is implemented in KItemListDelegateAccessible. + * + * @note For documentation of most of the methods within this class, check out the documentation of the methods which are being overriden here. + */ +class DOLPHIN_EXPORT KItemListViewAccessible : public QAccessibleObject, + public QAccessibleSelectionInterface, + public QAccessibleTableInterface, + public QAccessibleActionInterface +{ +public: + explicit KItemListViewAccessible(KItemListView *view, KItemListContainerAccessible *parent); + ~KItemListViewAccessible() override; + + // QAccessibleObject + void *interface_cast(QAccessible::InterfaceType type) override; + + QAccessible::Role role() const override; + QAccessible::State state() const override; + QString text(QAccessible::Text t) const override; + QRect rect() const override; + + QAccessibleInterface *child(int index) const override; + int childCount() const override; + int indexOfChild(const QAccessibleInterface *) const override; + QAccessibleInterface *childAt(int x, int y) const override; + QAccessibleInterface *parent() const override; + + // Table interface + QAccessibleInterface *cellAt(int row, int column) const override; + QAccessibleInterface *caption() const override; + QAccessibleInterface *summary() const override; + QString columnDescription(int column) const override; + QString rowDescription(int row) const override; + int columnCount() const override; + int rowCount() const override; + + // Selection + int selectedCellCount() const override; + int selectedColumnCount() const override; + int selectedRowCount() const override; + QList<QAccessibleInterface *> selectedCells() const override; + QList<int> selectedColumns() const override; + QList<int> selectedRows() const override; + bool isColumnSelected(int column) const override; + bool isRowSelected(int row) const override; + bool selectRow(int row) override; + bool selectColumn(int column) override; + bool unselectRow(int row) override; + bool unselectColumn(int column) override; + void modelChange(QAccessibleTableModelChangeEvent *) override; + + // Selection interface + /** Clear selection */ + bool clear() override; + bool isSelected(QAccessibleInterface *childItem) const override; + bool select(QAccessibleInterface *childItem) override; + bool selectAll() override; + QAccessibleInterface *selectedItem(int selectionIndex) const override; + int selectedItemCount() const override; + QList<QAccessibleInterface *> selectedItems() const override; + bool unselect(QAccessibleInterface *childItem) override; + + // Action interface + QStringList actionNames() const override; + void doAction(const QString &actionName) override; + QStringList keyBindingsForAction(const QString &actionName) const override; + + // Custom non-interface methods + KItemListView *view() const; + + /** + * Moves the focus to the list view itself so an overview over the state can be given. + * @param placeholderMessage the message that should be announced when no items are visible (yet). This message is mostly identical to + * DolphinView::m_placeholderLabel in both content and purpose. @see DolphinView::updatePlaceHolderLabel(). + */ + void announceOverallViewState(const QString &placeholderMessage); + + /** + * Announces that the description of the view has changed. The changed description will only be announced if the view has focus (from an accessibility + * point of view). This method ensures that multiple calls to this method within a small time frame will only lead to a singular announcement instead of + * multiple or already outdated ones, so calling this method instead of manually sending accessibility events for this view is preferred. + */ + void announceDescriptionChange(); + +protected: + virtual void modelReset(); + /** + * @returns a KItemListDelegateAccessible representing the file or folder at the @index. Returns nullptr for invalid indices. + * If a KItemListDelegateAccessible for an index does not yet exist, it will be created. + * Index is 0-based. + */ + inline QAccessibleInterface *accessibleDelegate(int index) const; + + KItemListSelectionManager *selectionManager() const; + +private: + /** @see setPlaceholderMessage(). */ + QString m_placeholderMessage; + + QTimer *m_announceDescriptionChangeTimer; + + class AccessibleIdWrapper + { + public: + AccessibleIdWrapper(); + bool isValid; + QAccessible::Id id; + }; + /** + * A list that maps the indices of the children of this KItemListViewAccessible to the accessible ids of the matching KItemListDelegateAccessible objects. + * For example: m_accessibleDelegates.at(2) would be the AccessibleIdWrapper with an id which can be used to retrieve the QAccessibleObject that represents + * the third file in this view. + */ + mutable QVector<AccessibleIdWrapper> m_accessibleDelegates; + + KItemListContainerAccessible *m_parent; +}; + +#endif |