diff --git a/spec.bs b/spec.bs index b52c7e6..5068fe6 100644 --- a/spec.bs +++ b/spec.bs @@ -108,6 +108,7 @@ partial interface Window { interface DocumentPictureInPicture : EventTarget { [NewObject] Promise<Window> requestWindow( optional DocumentPictureInPictureOptions options = {}); + void show(Window window); readonly attribute Window window; attribute EventHandler onenter; }; @@ -117,6 +118,7 @@ dictionary DocumentPictureInPictureOptions { [EnforceRange] unsigned long long height = 0; boolean disallowReturnToOpener = false; boolean preferInitialWindowPlacement = false; + boolean createHidden = false; }; [Exposed=Window, SecureContext] @@ -231,6 +233,27 @@ previous position or size of any previously closed |pip traversable| window. and is true, the user agent should not display UI affordances on the picture-in-picture window that allow the user to return to the opener window. +15. If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] exists + and is true, the user agent should not show the picture-in-picture + window immediately. Instead, it will wait until either: + 1. {{DocumentPictureInPicture/show()}} is called, with the corresponding + window as its argument. + 2. The UA shows the window automatically after some time has elapsed. + Calls to {{DocumentPictureInPicture/show()}} after the picture-in-picture window + is shown, or after it is closed, will do nothing. A call that provides a window argument + that was not returned by {{DocumentPictureInPicture/requestWindow()}} will throw a + "{{NotAllowedError}}" {{DOMException}}. + If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] does not exist + or is not true, then the picture-in-picture window will be shown immediately after + it is created. +

+The intention to automatically show the window after a timeout is to allow the UA to +prevent a site from waiting indefinitely to show a window. For example, a UA might +choose to use the remaining lifetime of the transient activation that allowed the call to +{{DocumentPictureInPicture/requestWindow()}} to succeed, so that the site cannot show +the window any later than it could by simply waiting to open the picture-in-picture +window. The UA is free to choose any timeout, including "forever". +

For both video and document picture-in-picture, user agents often display a @@ -786,6 +809,18 @@ await documentPictureInPicture.requestWindow({ }); +## Defer showing the picture-in-picture window ## {#example-create-hidden} + +If the site would like to configure the picture-in-picture window contents +before showing the window, it may use the +{{DocumentPictureInPictureOptions/createHidden}} option to do so. + +

+let pip = await documentPictureInPicture.requestWindow({ createHidden: true });
+// Add things to pip.document here!
+documentPictureInPicture.show(pip);
+
+ # Acknowledgments # {#acknowledgments} Many thanks to Frank Liberato, Mark Foltz, Klaus Weidner, François Beaufort,