// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.ui.input;

/// Whether a TextPosition is visually upstream or downstream of its offset.
///
/// For example, when a text position exists at a line break, a single offset has
/// two visual positions, one prior to the line break (at the end of the first
/// line) and one after the line break (at the start of the second line). A text
/// affinity disambiguates between those cases. (Something similar happens with
/// between runs of bidirectional text.)
enum TextAffinity {
    /// The position has affinity for the upstream side of the text position.
    ///
    /// For example, if the offset of the text position is a line break, the
    /// position represents the end of the first line.
    UPSTREAM = 0;

    /// The position has affinity for the downstream side of the text position.
    ///
    /// For example, if the offset of the text position is a line break, the
    /// position represents the start of the second line.
    DOWNSTREAM = 1;
};

/// A range of characters in a string of text. Although strings in FIDL's wire
/// format are UTF-8 encoded, these indices are measured in UTF-16 code units
/// for legacy reasons. These text input APIs will eventually be replaced by
/// fuchsia.ui.text, which uses code points instead.
struct TextRange {
    /// The index of the first UTF-16 code unit in the range.
    ///
    /// If `start` and `end` are both -1, the text range is empty.
    int64 start = -1;

    /// The next index after the last UTF-16 code unit in this range.
    ///
    /// If `start` and `end` are both -1, the text range is empty.
    int64 end = -1;
};

/// A range of text that represents a selection. Although strings in FIDL's wire
/// format are UTF-8 encoded, these indices are measured in UTF-16 code units
/// for legacy reasons. These text input APIs will eventually be replaced by
/// fuchsia.ui.text, which uses code points instead.
///
/// Text selection is always directional. Direction should be determined by
/// comparing base and extent.
struct TextSelection {
    /// The offset at which the selection originates, as measured in UTF-16 code units.
    ///
    /// Might be larger than, smaller than, or equal to extent.
    int64 base;

    /// The offset at which the selection terminates, as measured in UTF-16 code units.
    ///
    /// When the user uses the arrow keys to adjust the selection, this is the
    /// value that changes. Similarly, if the current theme paints a caret on one
    /// side of the selection, this is the location at which to paint the caret.
    ///
    /// Might be larger than, smaller than, or equal to base.
    int64 extent;

    /// If the text range is collapsed and has more than one visual location
    /// (e.g., occurs at a line break), which of the two locations to use when
    /// painting the caret.
    TextAffinity affinity;
};