Jump to content

IDL draft for Option II

From Second Screen Presentation Community Group

The following IDL definitions is a draft of the constructor-based approach with using a boolean flag to indicate the scree availability.

[Constructor(in DOMString url)]
interface Presentation : EventTarget {
  readonly attribute URL url;

  // The presentation is ready for showing on external screen.
  const unsigned short READY = 0;
  // The presentation is showing on the external screen after show() is invoked.
  const unsigned short SHOWING = 1;
  // The presentation is closed, 1) no available screen for show(); or 2) close()
  // method is invoked, or 3) fatal error is detected by UA when showing.
  const unsigned short CLOSED = 2;

  // The presentation state.
  readonly attribute unsigned short state;
  readonly attribute PresentationOption option;

  // Fired when state is changed.
  attribute EventHandler onstatechange;
  
  // Messaging port used to communicate with the browsing context identified by |url|.
  // Only valid when the |state| is SHOWING.
  MessagePort port;
 
  // Request UA to show the presentation on the external screen. UA may popup a permission dialog
  // to ask user for screen selection if have:
  // 1) If it is in READY state and no available screen for presentation, the state is transited to CLOSED.
  // 2) If it is in CLOSED state and no available screen for presentation, do nothing.
  // 3) If it is in SHOWING state, do nothing;
  // 4) If it is in READY or CLOSED state, and there is at least one available external screen for presentation,
  //    a) if the url is not showing on the selected screen yet, UA will show it on the selected screen,
  //       and the state is transited to SHOWING, the port can be used to communicate with presentation
  //       browsing context;
  //    b) if the url is already showing on the selected screen, but UA detects the messaging channel to the
  //       presentation browsing context is not established yet, UA will establish such a channel for communication
  //       and the state is transited to SHOWING. Otherwise, says UA detects the messaging channel is already
  //       established, do nothing.
  void show(PresentationOption option);

  // Request UA to close the presentation:
  // 1) If it is in READY state, the state is transited to CLOSED;
  // 2) If it is in SHOWING state, the state will be transited to CLOSED, and the presentation browsing context
  //    will receive onclose event. If the presentation doesn't have 'persistent:true' option, UA will close the
  //    presentation browsing context, otherwise, only the messaging channel will be closed.
  // 3) If it is already in CLOSED state, do nothing.
  void close();
};

interface NavigatorPresentation : EventTarget {
  // Fired when this browsing context is showed as a Presentation on external screen, or resumed as a
  // Presentation again. The event type of onshow is MessageEvent.
  attribute EventHandler onshow;

  // Fired when the opener browsing context requests closing this Presentation. Once
  // onclose event is fired, the message port received from onshow event becomes invalid.
  attribute EventHandler onclose;

  // Fired when the first available screen is arrived, or the last available screen is removed.
  attribute EventHandler onscreenavailable;

  // Asynchronously check the screen availability.
  void checkScreenAvailable(callback);
};

partial interface Navigator {
  readonly attribute NavigatorPresentation presentation;
};