| // Copyright 2019 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.text; |
| |
| /// Lists the Positions for selection and other related ranges, at a particular |
| /// revision number. Any time the revision number is incremented, all these Positions |
| /// become invalid, and a new TextFieldState is sent through OnUpdate. |
| table TextFieldState { |
| /// (required) The start and end of the entire text field. |
| 1: Range document; |
| |
| /// (required) The currently selected range of text. |
| 2: Selection selection; |
| |
| /// The range that indicates the text that is being composed, or currently |
| /// receiving suggestions from the keyboard. It should be displayed in some |
| /// distinct way, such as underlined. |
| 3: Range composition; |
| |
| /// Some keyboards, notably Japanese, give the user buttons to highlight just a |
| /// subset of the composition string for suggestions. It must be equal to or a subset |
| /// of the composition range. If the composition range changes, the TextField may |
| /// discard this and require the keyboard to create a new one. |
| 4: Range composition_highlight; |
| |
| /// A dead key is a key combination you press before another key to add diacritical |
| /// marks, accents, or other changes to the second key. After the first key, a |
| /// highlighted character indicates that the next character will be different. This |
| /// range is that highlighted character. If the selection moves away from this |
| /// highlight range, or if the contents of the highlight range change, the TextField |
| /// may discard this and require the keyboard to create a new one. |
| 5: Range dead_key_highlight; |
| |
| /// (required) This number is increased any time content in the text field is changed, |
| /// if the selection is changed, or if anything else about the state is changed. |
| 6: uint64 revision; |
| }; |
| |
| /// Indicates errors that can occur with various TextField methods. Until FIDL supports |
| /// result return types, if Error has any value except OK, the client must ignore |
| /// all other return data from that method. |
| enum Error { |
| // Once FIDL supports Result return types, this option can be removed. |
| OK = 0; |
| |
| /// Indicates the revision number passed to the method is no longer valid. |
| BAD_REVISION = 1; |
| |
| /// Indicates an edit would be valid, but custom text field code does not allow that change |
| /// to be made, like inserting number into a text field. |
| INVALID_EDIT = 2; |
| |
| /// Bad request entirely, like an unknown position that doesn't match the edits revision. |
| /// Indicates a bug with client code. |
| BAD_REQUEST = 3; |
| |
| /// For a contents() request, indicates there is no text between the two position that is known. |
| /// (If only a substring is known, it should be returned, with the `start` Position set |
| /// appropriately). For a distance() request, indicates the number of characters between the |
| /// two position is unknowably large. |
| UNKNOWABLE = 4; |
| }; |
| |
| |
| /// Represents a text field or other kind of editing interface that wants to receive text input |
| /// from the operating system. This interface is also what is passed to a keyboard to allow it |
| /// to read state and make changes to text fields. |
| /// |
| /// All editing methods must happen within an edit transaction. The edits aren't |
| /// applied until CommitEdit is called. **This isn't a lock!** The TextField |
| /// can still apply edits on its side, which would increase the current revision |
| /// number. When CommitEdit is called, the edits are only run if the revision |
| /// number passed to BeginEdit is still valid. TextField implementations can |
| /// assume that there will only be one client at a time; they don't need to |
| /// keep track of a separate transaction list for each client. |
| protocol TextField { |
| /// Any time the revision number increments, this event fires, with the latest version of |
| /// the state. It also fires when a new client connects to the service, so it can get an |
| /// initial state without waiting for an edit. |
| -> OnUpdate(TextFieldState state); |
| |
| // READ METHODS |
| |
| /// Returns a new position that is `offset` unicode code points away from `old_position` |
| PositionOffset(Position old_position, int64 offset, uint64 revision) -> (Position new_position, Error error); |
| |
| /// Returns number of unicode code points between two positions. If the position range.start is after |
| /// range.end, then the range is considered `inverted` and distance will be negative. |
| /// For all positions A and B, PositionOffset(A, Distance(A, B)) == B |
| Distance(Range range, uint64 revision) -> (int64 distance, Error error); |
| |
| /// Returns string of unicode code points between two positions |
| Contents(Range range, uint64 revision) -> (string contents, Position start, Error error); |
| |
| // TRANSACTION METHODS |
| |
| /// Starts a transaction. If it's called a second time with no CommitEdit() |
| /// call, the changes from the first uncommitted transaction are discarded as |
| /// though AbortEdit() was called. |
| BeginEdit(uint64 revision); |
| |
| /// If the transaction's revision number (from BeginEdit) is still current, |
| /// runs all edit commands queued in this transaction. If not, returns |
| /// BAD_REVISION. |
| CommitEdit() -> (Error error); |
| |
| /// Discards the current transaction. |
| AbortEdit(); |
| |
| // EDITING METHODS — used within a transaction |
| |
| /// Replaces text in the range with new_text. It's the client's |
| /// responsibility to make sure new_text isn't too long for a FIDL message; |
| /// if it is, the client should break up the string into separate replace |
| /// calls. |
| Replace(Range range, string new_text); |
| |
| /// Sets the selection range. |
| SetSelection(Selection selection); |
| |
| /// Sets the composition range and the composition highlight range. For more info, |
| /// see TextState's comments. |
| SetComposition(Range composition_range, Range? highlight_range); |
| |
| /// Clears both the composition range, and the composition highlight range. |
| ClearComposition(); |
| |
| /// Sets the dead key highlight range. For more info, see TextState's comments. |
| SetDeadKeyHighlight(Range range); |
| |
| /// Clears the dead key highlight range. |
| ClearDeadKeyHighlight(); |
| }; |