sdk/fidl/fuchsia.ui.test.input/registry.fidl

// Copyright 2022 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.test.input;

/// Indicates the units used to specify spatial event parameters (unless otherwise
/// noted).
@available(added=11)
type CoordinateUnit = flexible enum {
    /// The physical display is mapped to a coordinate space spanning [-1000, 1000]
    /// on both the x and y axes, where positive x extends rightward and positive y
    /// extends downward.
    ///
    /// Example: (500, -500) in the default coordinate space maps to the center of
    /// the top-right quadrant of the physical display.
    DEFAULT = 0;

    /// The physical display is mapped to a coordinate space spanning (0, 0) -
    /// (dispaly width, display height), where positive x extends rightward and
    /// positive y extends downward.
    ///
    /// Test writers should use `fuchsia.ui.display.singleton.Info` to retrieve
    /// the physical dimensions of the display.
    ///
    /// Note that this space matches both the size AND orientation of the physical
    /// display, so it will NOT mirror any rotations applied to the scene graph.
    ///
    /// In general, test writers should NOT assume that a particular view's logical
    /// coordinate space matches the physical coordinate space.
    PHYSICAL_PIXELS = 1;

    /// The physical display is mapped to a coordinate space from argument of
    /// RegisterTouchScreen.
    @available(added=29)
    REGISTERED_DIMENSIONS = 2;
};

@available(added=29)
type DisplayDimensions = struct {
    /// min_x of the display.
    min_x int64;
    /// min_y of the display.
    min_y int64;
    /// max_x of the display. max_x should be larger than min_x.
    max_x int64;
    /// max_y of the display. max_y should be larger than min_y.
    max_y int64;
};

/// *** This protocol must not be used in production. ***
///
/// Enables clients to register fake input devices, which can be used to
/// inject input events directly into Input Pipeline.
@discoverable(client="platform", server="platform")
closed protocol Registry {

    /// Enables the client to inject touch events using the corresponding
    /// client end to `device`.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.TouchScreen` channel will remain open even
    /// if the `Registry` connection closes.
    strict RegisterTouchScreen(resource table {
        1: device server_end:TouchScreen;

        /// Indicates the coordinate space in which to describe touch events.
        @available(added=11)
        2: coordinate_unit CoordinateUnit;

        /// the dimensions of the display, only used when coordinate_unit is
        /// `REGISTERED_DIMENSIONS`.
        @available(added=29)
        3: display_dimensions DisplayDimensions;
    }) -> ();

    /// Enables the client to inject touch events using the corresponding
    /// client end to `device`. Returns device_id of the created device.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.TouchScreen` channel will remain open even
    /// if the `Registry` connection closes.
    @available(added=24)
    strict RegisterTouchScreenAndGetDeviceInfo(resource table {
        1: device server_end:TouchScreen;

        /// Indicates the coordinate space in which to describe touch events.
        2: coordinate_unit CoordinateUnit;

        /// the dimensions of the display, only used when coordinate_unit is
        /// `REGISTERED_DIMENSIONS`.
        @available(added=29)
        3: display_dimensions DisplayDimensions;
    }) -> (resource table {
        1: device_id uint32;
    });

    /// Enables the client to inject media buttons events using the
    /// corresponding client end to `device`.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.MediaButtonsDevice` channel will remain open
    /// even if the `Registry` connection closes.
    strict RegisterMediaButtonsDevice(resource table {
        1: device server_end:MediaButtonsDevice;
    }) -> ();

    /// Enables the client to inject media buttons events using the
    /// corresponding client end to `device`. Returns device_id of the created device.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.MediaButtonsDevice` channel will remain open
    /// even if the `Registry` connection closes.
    @available(added=24)
    strict RegisterMediaButtonsDeviceAndGetDeviceInfo(resource table {
        1: device server_end:MediaButtonsDevice;
    }) -> (resource table {
        1: device_id uint32;
    });

    /// Enables the client to inject keyboard events using the corresponding
    /// client end to `device`.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.Keyboard` channel will remain open even
    /// if the `Registry` connection closes.
    strict RegisterKeyboard(resource table {
        1: device server_end:Keyboard;
    }) -> ();

    /// Enables the client to inject keyboard events using the corresponding
    /// client end to `device`. Returns device_id of the created device.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.Keyboard` channel will remain open even
    /// if the `Registry` connection closes.
    @available(added=24)
    strict RegisterKeyboardAndGetDeviceInfo(resource table {
        1: device server_end:Keyboard;
    }) -> (resource table {
        1: device_id uint32;
    });

    /// Enables the client to inject mouse events using the corresponding
    /// client end to `device`.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.Mouse` channel will remain open even
    /// if the `Registry` connection closes.
    strict RegisterMouse(resource table {
        1: device server_end:Mouse;
    }) -> ();

    /// Enables the client to inject mouse events using the corresponding
    /// client end to `device`. Returns device_id of the created device.
    ///
    /// Clients are allowed at most one in-flight call at a time. Subsequent
    /// calls must wait until the acknowledgment returns. Non-compliance
    /// results in channel closure.
    ///
    /// The `fuchsia.ui.test.input.Mouse` channel will remain open even
    /// if the `Registry` connection closes.
    @available(added=24)
    strict RegisterMouseAndGetDeviceInfo(resource table {
        1: device server_end:Mouse;
    }) -> (resource table {
        1: device_id uint32;
    });
};