Adapt to Orca 47

The screen reader Orca has seen some fundamental changes between
Orca 46 and Orca 47. While they are improvements overall, they do
require changes to Dolphin to preserve the intended user
experience for Orca users.

The biggest change is perhaps that Orca will now not only announce
changes to the currently focused item, but also of its parent,
which means we do not need to pass focus around between file items
and the main view within Dolphin, but can keep focus on the file
items most of the time. This commit implements this.

The only exception of when we cannot have focus on the items within
the main view is when the current location is empty or not loaded
yet. Only then is the focus moved to the view itself and the
placeholderMessage is announced.

This commit worsens the UX for users of Orca 46 or older, so this
should only be merged once most users are on Orca 47 or later.

1 files changed, 50 insertions, 10 deletions

diff --git a/src/kitemviews/accessibility/kitemlistviewaccessible.h b/src/kitemviews/accessibility/kitemlistviewaccessible.h
index 4c44b18ad..db2832435 100644
--- a/src/kitemviews/accessibility/kitemlistviewaccessible.h
+++ b/src/kitemviews/accessibility/kitemlistviewaccessible.h
@@ -96,21 +96,35 @@ public:
     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
+     * Called by KItemListContainer when it passes on focus to the view. Accessible focus is then meant to go towards this accessible interface and a detailed
+     * announcement of the current view state (current item and overall location state) should be triggered.
+     */
+    void setAccessibleFocusAndAnnounceAll();
+
+    /**
+     * Called multiple times while a new location is loading. A timer is restarted, and if this method has not been called for a split second, the newly loaded
+     * location is finally announced.
+     * Either the @p placeholderMessage is announced when there are no items in the view (yet), or the current item is announced together with the view state.
+     *
+     * @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().
+     *
+     * If there are items in the view and the placeholderMessage is therefore not visible, the current item and location is announced instead.
      */
-    void announceOverallViewState(const QString &placeholderMessage);
+    void announceNewlyLoadedLocation(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.
+     * Starts a timer that will trigger an announcement of the current item. The timer makes sure that quick changes to the current item will only lead to a
+     * singular announcement. This way when a new folder is loaded we only trigger a single announcement even if the items quickly change.
+     *
+     * When m_shouldAnnounceLocation is true, the current location will be announced following the announcement of the current item.
+     *
+     * If the current item is invalid, only the current location is announced, which has the responsibility of then telling why there is no valid item in the
+     * view.
      */
-    void announceDescriptionChange();
+    void announceCurrentItem();
 
-protected:
-    virtual void modelReset();
+private:
     /**
      * @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.
@@ -120,11 +134,37 @@ protected:
 
     KItemListSelectionManager *selectionManager() const;
 
+private Q_SLOTS:
+    /**
+     * Is run in response to announceCurrentItem(). If the current item exists, it is announced. Otherwise the view is announced.
+     * Also announces some general information about the current location if it has changed recently.
+     */
+    void slotAnnounceCurrentItemTimerTimeout();
+
 private:
     /** @see setPlaceholderMessage(). */
     QString m_placeholderMessage;
 
-    QTimer *m_announceDescriptionChangeTimer;
+    /**
+     * Is started by announceCurrentItem().
+     * If we announce the current item as soon as it changes, we would announce multiple items while loading a folder.
+     * This timer makes sure we only announce the singular currently focused item when things have settled down.
+     */
+    QTimer *m_announceCurrentItemTimer;
+
+    /**
+     * If we want announceCurrentItem() to always announce the current item, we must be aware if this is equal to the previous current item, because
+     * - if the accessibility focus moves to a new item, it is automatically announced, but
+     * - if the focus is still on the item at the same index, the focus does not technically move to a new item even if the file at that index changed, so we
+     *   need to instead send change events for the accessible name and accessible description.
+     */
+    int m_lastAnnouncedIndex = -1;
+
+    /**
+     * Is set to true in response to announceDescriptionChange(). When true, the next time slotAnnounceCurrentItemTimerTimeout() is called the description is
+     * also announced. Then this bool is set to false.
+     */
+    bool m_shouldAnnounceLocation = true;
 
     class AccessibleIdWrapper
     {