// 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;
using fuchsia.ui.input3;

/// Requests a specific keyboard type from the text editing subsystem.
///
/// This is most relevant for virtual keyboards which have some leeway in how
/// the keyboard is presented to the user, as well as which input is acceptable.
///
/// For example, a `NUMBER` keyboard type may only allow decimal numbers to be
/// entered.  In addition, a virtual keyboard might only show a numeric keypad
/// for text entry.
type KeyboardType = flexible enum {
    /// Single-line text fields only.  Use MULTILINE below for multiline text.
    @unknown
    TEXT = 0;
    /// A text field intended for entering numbers only.
    NUMBER = 1;
    /// A text field for entering phone numbers only (e.g. digits, limited
    /// punctuation, perhaps some validation).
    PHONE = 2;
    /// A text field for entering date and time. For example, may have a
    /// calendar widget on the side, to aid in date time entry.
    DATETIME = 3;
    /// Multi-line text.
    @available(added=8)
    MULTILINE = 4;
};

/// Determines what happens if the "action" key is pressed on the keyboard,
/// typically would either be the "Enter" key on a physical keyboard, or an
/// action button on a virtual keyboard, which is usually placed where Enter
/// would be, but with a custom label.
type InputMethodAction = flexible enum {
    /// The method action was not specified at all.
    @unknown
    UNSPECIFIED = 0;
    /// No special action is requested.
    NONE = 1;
    /// The action is "Go", e.g. execute a command.
    GO = 2;
    /// The action is to invoke a search.
    SEARCH = 3;
    /// The action is to invoke "send", e.g. if this is an email or a SMS
    /// message.
    SEND = 4;
    /// The action is to move to the next field in the focus sequence.
    NEXT = 5;
    /// The action is to end the text editing.
    DONE = 6;
    /// The action is to move to the previous field in the focus sequence.
    PREVIOUS = 7;
    /// Pressing the action key inserts a new line into the text field. In
    /// contrast to other values, which all stop editing and invoke a specific
    /// action.
    @available(added=8)
    NEWLINE = 8;
};

/// The current text, selection, and composing state for editing a run of text.
type TextInputState = struct {
    /// Current state revision to avoid race conditions.
    revision uint32;

    /// The current text being edited.
    text string;

    /// The range of text that is currently selected.
    selection TextSelection;

    /// The range of text that is still being composed.
    composing TextRange;
};

/// A interface for interacting with a text input control.
closed protocol InputMethodEditor {
    strict SetKeyboardType(struct {
        keyboard_type KeyboardType;
    });
    strict SetState(struct {
        state TextInputState;
    });

    // TODO(https://fxbug.dev/42152248)
    @available(deprecated=8, note="Instead, use `fuchsia.ui.input3.KeyEventInjector`")
    strict InjectInput(struct {
        event InputEvent;
    });

    // TODO(https://fxbug.dev/42152248)
    @available(deprecated=8, note="Instead, use `fuchsia.ui.input3.KeyEventInjector`")
    strict DispatchKey3(struct {
        event fuchsia.ui.input3.KeyEvent;
    }) -> (struct {
        handled bool;
    });

    // TODO(https://fxbug.dev/42101179): remove these in a later change, after PlatformView has been
    // switched over to open/close on the input_connection_ instead.
    @available(deprecated=13)
    strict Show();

    @available(deprecated=13)
    strict Hide();
};

/// An interface to receive information from `TextInputService`.
closed protocol InputMethodEditorClient {
    strict DidUpdateState(struct {
        state TextInputState;
        event InputEvent:optional;
    });
    strict OnAction(struct {
        action InputMethodAction;
    });
};