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,