diff --git a/spec.bs b/spec.bs index e1a9e43..92321e1 100644 --- a/spec.bs +++ b/spec.bs @@ -114,6 +114,7 @@ interface DocumentPictureInPicture : EventTarget { dictionary DocumentPictureInPictureOptions { [EnforceRange] unsigned long long width = 0; [EnforceRange] unsigned long long height = 0; + boolean allowReturnToOpener = true; }; [Exposed=Window, SecureContext] @@ -218,16 +219,32 @@ problems. window such that the distance between the top and bottom edges of the viewport are |options|["{{DocumentPictureInPictureOptions/height}}"] pixels. -14. Configure |pip traversable|'s active browsing context's window to +14. If |options|["{{DocumentPictureInPictureOptions/allowReturnToOpener}}"] exists + and is false, the user agent should not display UI affordances + on the picture-in-picture window that allow the user to return to the + opener window. + +

+For both video and document picture-in-picture, user agents often display a +button for the user to return to the original page and close the +picture-in-picture window. While this action makes sense in most cases +(especially for a video picture-in-picture window that returns the video to the +main document), it does not always make sense for document picture-in-picture +windows. {{DocumentPictureInPictureOptions/allowReturnToOpener}} is a hint to the +user agent from the website as to whether that action makes sense for their +particular document picture-in-picture experience. +

+ +15. Configure |pip traversable|'s active browsing context's window to float on top of other windows. -15. Set this's last-opened window to |pip traversable|'s active window. -16. Queue a global task on the +16. Set this's last-opened window to |pip traversable|'s active window. +17. Queue a global task on the DOM manipulation task source given this's relevant global object to fire an event named {{enter}} using {{DocumentPictureInPictureEvent}} on this with its {{DocumentPictureInPictureEvent/window}} attribute initialized to |pip traversable|'s active window. -17. Return |pip traversable|'s active window. +18. Return |pip traversable|'s active window. @@ -640,6 +657,18 @@ content in question inside the PiP window: } +## Hide return-to-opener button ## {#example-hide-return-to-opener} + +While user agents often display a button on their video and document +picture-in-picture windows to return to the opener and close the window, +this button doesn't always make sense for some websites' document +picture-in-picture experience. Use the +{{DocumentPictureInPictureOptions/allowReturnToOpener}} option to hide the button. + +
+documentPictureInPicture.requestWindow({ allowReturnToOpener: false });
+
+ # Acknowledgments # {#acknowledgments} Many thanks to Frank Liberato, Mark Foltz, Klaus Weidner, François Beaufort,