| // 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.views; |
| |
| /// Problematic situations that occur on Focuser.RequestFocus. |
| type Error = strict enum { |
| /// Value returned when RequestFocus is denied. |
| DENIED = 1; |
| }; |
| |
| @available(added=9) |
| type AutoFocusError = flexible enum {}; |
| |
| /// A method of programmatically transferring View focus. |
| /// |
| /// The protocol client has implicit access to a requestor ViewRef, which is |
| /// used as the basis for request authority. |
| closed protocol Focuser { |
| /// Asks the server to transfer focus to the View specified by `view_ref`, |
| /// with the authority of the requestor ViewRef. Such a request may be |
| /// honored or denied. |
| /// |
| /// If the request was honored, and it triggers a focus change, a FocusEvent |
| /// (with focused=true) is issued to the newly-focused View, and a |
| /// FocusEvent (with focused=false) is issued to the previous View. |
| /// |
| /// The result callback indicates that the request was received and honored. |
| /// It does not guarantee that the requested View actually received a |
| /// FocusEvent in time. |
| /// |
| /// The request may be denied for many reasons, for example: |
| /// - if `view_ref` is invalid |
| /// - if there is no View backed by `view_ref` |
| /// - if there is no requestor ViewRef accessible to Focuser |
| /// - if the requestor ViewRef lacks authority over `view_ref`'s View |
| /// - if `view_ref`'s View is not hittable or may not receive focus |
| /// etc. A denied request is indicated with a Error. |
| strict RequestFocus(resource struct { |
| view_ref ViewRef; |
| }) -> () error Error; |
| |
| /// Sets the auto focus target to the View specified by `view_ref`. |
| /// To unset the target, pass in an empty table. |
| /// |
| /// If a target has been set, then whenever the caller's View would receive |
| /// focus, an attempt is made to transfer focus immediately to the target |
| /// instead. If the target is unfocusable, the new target is the first |
| /// focusable ancestor of the target instead. Setting an auto focus target |
| /// places no limitations on simultaneous use of RequestFocus(). |
| /// |
| /// An auto focus target is "valid" only while it is a descendant of the |
| /// caller's View in the ViewTree. Specifying an invalid auto focus target is |
| /// allowed, since it may become valid later. |
| /// It is the client's responsibility to ensure the target is a valid |
| /// receiver of auto focus. |
| /// |
| /// If the target is invalid when the auto focus behavior would trigger, then |
| /// the attempt to move focus will silently fail and focus will remain with |
| /// the caller's View. |
| /// A target may become invalid and then become valid again any number of |
| /// times; auto focus will continue to function whenever the target is |
| /// in a valid state, and will continue to ignore the target while it's in an |
| /// invalid state. |
| /// |
| /// If the focus would by some further automatic mechanism return to the |
| /// caller's View (e.g. if the target is unfocusable), then focus will |
| /// remain with the caller's View. |
| /// |
| /// AutoFocusError is currently never returned, and is reserved for possible |
| /// future use. |
| @available(added=9) |
| strict SetAutoFocus(resource table { |
| 1: view_ref ViewRef; |
| }) -> () error AutoFocusError; |
| }; |