sdk/fidl/fuchsia.ui.policy/presentation.fidl

// 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.policy;

using fuchsia.ui.gfx;
using fuchsia.ui.input;

/// `Presentation.CaptureKeyboardEvent` will consume this listener interface and
/// call `OnEvent` when the registered keyboard event occurs.
protocol KeyboardCaptureListenerHACK {
    OnEvent(fuchsia.ui.input.KeyboardEvent event);
};

/// `Presentation.CapturePointerEvent` will consume this listener interface and
/// call `OnEvent` when a pointer event occurs.
protocol PointerCaptureListenerHACK {
    OnPointerEvent(fuchsia.ui.input.PointerEvent event);
};

/// `Presentation.RegisterMediaButtonsListener` will consume this listener interface
/// and call `OnMediaButtonsEvent` when the registered media buttons event occurs.
protocol MediaButtonsListener {
    OnMediaButtonsEvent(fuchsia.ui.input.MediaButtonsEvent event);
};

/// Allows clients of Presenter.Present() to control a presentation.
/// Experimental.
[Discoverable]
protocol Presentation {
    /// Enable or disable clipping for the Scenic renderer associated with the
    /// presentation.
    EnableClipping(bool enabled);

    UseOrthographicView();
    UsePerspectiveView();

    /// Set parameters such as the shadow algorithm used to render the scene.
    /// NOTE: a single param would be better than an array; see TO-529.
    SetRendererParams(vector<fuchsia.ui.gfx.RendererParam> params);

    /// Override the intended usage of the display.
    SetDisplayUsage(DisplayUsage usage);

    /// Rotates the display.
    SetDisplayRotation(float32 display_rotation_degrees, bool animate);

    /// Override the dimensions of the display. Values must be less than the actual
    /// size of the display. If either of the values are 0, then they are ignored
    /// and the actual size of the display is used.
    SetDisplaySizeInMm(float32 width_in_mm, float32 height_in_mm);

    /// This call exists so that base shell can capture hotkeys and do special
    /// things with it (e.g., switch a session shell). Phase and modifiers are always
    /// matched, and valid (non-zero) code points are matched. If there is no
    /// valid code point, the filter will match against the hid usage value.
    /// The full KeyboardEvent is supplied to `listener`'s OnEvent.
    // TODO: Figure out the feasibility of this feature and the best place to put
    // it.
    CaptureKeyboardEventHACK(fuchsia.ui.input.KeyboardEvent event_to_capture,
                             KeyboardCaptureListenerHACK listener);

    /// This call exists so that base shell can capture pointer events.
    // TODO: Figure out the feasibility of this feature and the best place to put
    // it. This call will be replaced by gesture disambiguation system in future.
    CapturePointerEventsHACK(PointerCaptureListenerHACK listener);

    // TODO(SCN-650): Determine better place for PresentationMode API.
    GetPresentationMode() -> (PresentationMode mode);
    SetPresentationModeListener(PresentationModeListener listener);

    /// Registers a listener for media buttons events.
    RegisterMediaButtonsListener(MediaButtonsListener listener);

    /// EXPERIMENTAL. Inject pointer events into input stream. This WILL go
    /// away. Used exclusively by Session Shells to test focus navigation.
    // TODO(SCN-1186): Delete when RequestFocus is available.
    [Transitional]
    InjectPointerEventHACK(fuchsia.ui.input.PointerEvent event);
};

/// Screen modes that can be detected via sensor data.
/// N.B. We use accelerometers to measure gravity when at rest, so detection is
/// limited to earth-relative orientations.
enum PresentationMode {
    CLOSED = 0;
    LAPTOP = 1;
    TABLET = 2;
    TENT = 3;
};

/// Tell client that the screen mode has changed, according to sensors.
/// N.B. There can be a race where the actual mode continues to change, after
/// the listener has been notified. The client must call GetPresentationMode(),
/// which will return the latest detected mode.
protocol PresentationModeListener {
    OnModeChanged();
};