chromium/chrome/renderer/accessibility/read_aloud_traversal_utils.h

// Copyright 2024 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CHROME_RENDERER_ACCESSIBILITY_READ_ALOUD_TRAVERSAL_UTILS_H_
#define CHROME_RENDERER_ACCESSIBILITY_READ_ALOUD_TRAVERSAL_UTILS_H_

#include <string>

#include "ui/accessibility/ax_enums.mojom.h"
#include "ui/accessibility/ax_node_position.h"

// Utilities for traversing the accessibility tree for Read Aloud.
// TODO(crbug.com/346612365): Rename to util instead of utils.

// A current segment of text that will be consumed by Read Aloud.
struct ReadAloudTextSegment { … };

namespace a11y {

// During text traversal when adding new text to the current speech segment,
// this is used to indicate the next traversal steps.
enum class TraversalState { … };

// A representation of multiple ReadAloudTextSegments that are processed
// by Read Aloud at a single moment. For example, when using sentence
// granularity, the list of ReadAloudTextSegments in a
// ReadAloudCurrentGranularity will include all ReadAloudTextSegments
// necessary to represent a single sentence.
struct ReadAloudCurrentGranularity { … };
}  // namespace a11y

// Returns the index of the next sentence of the given text, such that the
// next sentence is equivalent to text.substr(0, <returned_index>).
int GetNextSentence(const std::u16string& text, bool is_pdf);

// Returns the index of the next word of the given text, such that the
// next word is equivalent to text.substr(0, <returned_index>).
int GetNextWord(const std::u16string& text);

// Returns true if both positions are non-null and equal.
bool ArePositionsEqual(const ui::AXNodePosition::AXPositionInstance& position,
                       const ui::AXNodePosition::AXPositionInstance& other);

// Returns the correct anchor node from an AXPositionInstance that should be
// used by Read Aloud. AXPosition can sometimes return leaf nodes that don't
// actually correspond to the AXNodes we're using in Reading Mode, so we need
// to get a parent node from the AXPosition's returned anchor.
ui::AXNode* GetAnchorNode(
    const ui::AXNodePosition::AXPositionInstance& position);

// Uses the given AXNodePosition to return the next node that should be spoken
// by Read Aloud.
ui::AXNode* GetNextNodeFromPosition(
    const ui::AXNodePosition::AXPositionInstance& ax_position);

// Returns if the given character can be considered opening puncutation.
// This is used to ensure we're not reading out opening punctuation
// as a separate segment.
bool IsOpeningPunctuation(char& c);

// Returns whether we should split the current utterance at a paragraph
// boundary.
bool ShouldSplitAtParagraph(
    const ui::AXNodePosition::AXPositionInstance& position,
    const a11y::ReadAloudCurrentGranularity current_granularity);

#endif  // CHROME_RENDERER_ACCESSIBILITY_READ_ALOUD_TRAVERSAL_UTILS_H_