src/kitemviews/accessibility/kitemlistviewaccessible.h

   1 /*
   2  * SPDX-FileCopyrightText: 2012 Amandeep Singh <aman.dedman@gmail.com>
   3  * SPDX-FileCopyrightText: 2024 Felix Ernst <felixernst@kde.org>
   4  *
   5  * SPDX-License-Identifier: GPL-2.0-or-later
   6  */
   7
   8 #ifndef KITEMLISTVIEWACCESSIBLE_H
   9 #define KITEMLISTVIEWACCESSIBLE_H
  10
  11 #include "dolphin_export.h"
  12
  13 #include <QAccessible>
  14 #include <QAccessibleObject>
  15 #include <QAccessibleWidget>
  16 #include <QPointer>
  17
  18 class KItemListView;
  19 class KItemListContainer;
  20 class KItemListContainerAccessible;
  21 class KItemListSelectionManager;
  22
  23 /**
  24  * The main class for making the main view accessible.
  25  *
  26  * 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
  27  * interact with the view using accessibility tools. It implements various interfaces mostly to generally allow working with the view as a whole. However,
  28  * actually interacting with singular items within the view is implemented in KItemListDelegateAccessible.
  29  *
  30  * @note For documentation of most of the methods within this class, check out the documentation of the methods which are being overriden here.
  31  */
  32 class DOLPHIN_EXPORT KItemListViewAccessible : public QAccessibleObject,
  33                                                public QAccessibleSelectionInterface,
  34                                                public QAccessibleTableInterface,
  35                                                public QAccessibleActionInterface
  36 {
  37 public:
  38     explicit KItemListViewAccessible(KItemListView *view, KItemListContainerAccessible *parent);
  39     ~KItemListViewAccessible() override;
  40
  41     // QAccessibleObject
  42     void *interface_cast(QAccessible::InterfaceType type) override;
  43
  44     QAccessible::Role role() const override;
  45     QAccessible::State state() const override;
  46     QString text(QAccessible::Text t) const override;
  47     QRect rect() const override;
  48
  49     QAccessibleInterface *child(int index) const override;
  50     int childCount() const override;
  51     int indexOfChild(const QAccessibleInterface *) const override;
  52     QAccessibleInterface *childAt(int x, int y) const override;
  53     QAccessibleInterface *parent() const override;
  54
  55     // Table interface
  56     QAccessibleInterface *cellAt(int row, int column) const override;
  57     QAccessibleInterface *caption() const override;
  58     QAccessibleInterface *summary() const override;
  59     QString columnDescription(int column) const override;
  60     QString rowDescription(int row) const override;
  61     int columnCount() const override;
  62     int rowCount() const override;
  63
  64     // Selection
  65     int selectedCellCount() const override;
  66     int selectedColumnCount() const override;
  67     int selectedRowCount() const override;
  68     QList<QAccessibleInterface *> selectedCells() const override;
  69     QList<int> selectedColumns() const override;
  70     QList<int> selectedRows() const override;
  71     bool isColumnSelected(int column) const override;
  72     bool isRowSelected(int row) const override;
  73     bool selectRow(int row) override;
  74     bool selectColumn(int column) override;
  75     bool unselectRow(int row) override;
  76     bool unselectColumn(int column) override;
  77     void modelChange(QAccessibleTableModelChangeEvent *) override;
  78
  79     // Selection interface
  80     /** Clear selection */
  81     bool clear() override;
  82     bool isSelected(QAccessibleInterface *childItem) const override;
  83     bool select(QAccessibleInterface *childItem) override;
  84     bool selectAll() override;
  85     QAccessibleInterface *selectedItem(int selectionIndex) const override;
  86     int selectedItemCount() const override;
  87     QList<QAccessibleInterface *> selectedItems() const override;
  88     bool unselect(QAccessibleInterface *childItem) override;
  89
  90     // Action interface
  91     QStringList actionNames() const override;
  92     void doAction(const QString &actionName) override;
  93     QStringList keyBindingsForAction(const QString &actionName) const override;
  94
  95     // Custom non-interface methods
  96     KItemListView *view() const;
  97
  98     /**
  99      * Moves the focus to the list view itself so an overview over the state can be given.
 100      * @param placeholderMessage   the message that should be announced when no items are visible (yet). This message is mostly identical to
 101      *                              DolphinView::m_placeholderLabel in both content and purpose. @see DolphinView::updatePlaceHolderLabel().
 102      */
 103     void announceOverallViewState(const QString &placeholderMessage);
 104
 105     /**
 106      * Announces that the description of the view has changed. The changed description will only be announced if the view has focus (from an accessibility
 107      * 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
 108      * multiple or already outdated ones, so calling this method instead of manually sending accessibility events for this view is preferred.
 109      */
 110     void announceDescriptionChange();
 111
 112 protected:
 113     virtual void modelReset();
 114     /**
 115      * @returns a KItemListDelegateAccessible representing the file or folder at the @index. Returns nullptr for invalid indices.
 116      * If a KItemListDelegateAccessible for an index does not yet exist, it will be created.
 117      * Index is 0-based.
 118      */
 119     inline QAccessibleInterface *accessibleDelegate(int index) const;
 120
 121     KItemListSelectionManager *selectionManager() const;
 122
 123 private:
 124     /** @see setPlaceholderMessage(). */
 125     QString m_placeholderMessage;
 126
 127     QTimer *m_announceDescriptionChangeTimer;
 128
 129     class AccessibleIdWrapper
 130     {
 131     public:
 132         AccessibleIdWrapper();
 133         bool isValid;
 134         QAccessible::Id id;
 135     };
 136     /**
 137      * A list that maps the indices of the children of this KItemListViewAccessible to the accessible ids of the matching KItemListDelegateAccessible objects.
 138      * For example: m_accessibleDelegates.at(2) would be the AccessibleIdWrapper with an id which can be used to retrieve the QAccessibleObject that represents
 139      *              the third file in this view.
 140      */
 141     mutable QVector<AccessibleIdWrapper> m_accessibleDelegates;
 142
 143     KItemListContainerAccessible *m_parent;
 144 };
 145
 146 #endif