/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIWebVTTListener;
interface mozIDOMWindow;
interface nsIVariant;

webidl DocumentFragment;

/**
 * Interface for a wrapper of a JS WebVTT parser (vtt.js).
 */
[scriptable, uuid(8dfe016e-1701-4618-9f5e-9a6154e853f0)]
interface nsIWebVTTParserWrapper : nsISupports
{
  /**
   * Loads the JS WebVTTParser and sets it to use the passed window to create
   * VTTRegions and VTTCues. This function must be called before calling
   * parse, flush, or watch.
   *
   * @param window The window that the parser will use to create VTTCues and
   *               VTTRegions.
   *
   */
  void loadParser(in mozIDOMWindow window);

  /**
   * Attempts to parse the stream's data as WebVTT format. When it successfully
   * parses a WebVTT region or WebVTT cue it will create a VTTRegion or VTTCue
   * object and pass it back to the callee through its callbacks.
   *
   * @param data   The buffer that contains the WebVTT data received by the
   *               Necko consumer so far.
   */
  void parse(in ACString data);

  /**
   * Flush indicates that no more data is expected from the stream. As such the
   * parser should try to parse any kind of partial data it has.
   */
  void flush();

  /**
   * Set this parser object to use an nsIWebVTTListener object for its onCue
   * and onRegion callbacks.
   *
   * @param callback The nsIWebVTTListener object that exposes onCue and
   *                 onRegion callbacks for the parser.
   */
  void watch(in nsIWebVTTListener callback);

  /**
   * Cancel watching notifications which parser would send.
   */
  void cancel();

  /**
   * Convert the text content of a WebVTT cue to a document fragment so that
   * we can display it on the page.
   *
   * @param window A window object with which the document fragment will be
   *               created.
   * @param cue    The cue whose content will be converted to a document
   *               fragment.
   */
  DocumentFragment convertCueToDOMTree(in mozIDOMWindow window,
                                       in nsISupports cue);


  /**
   * Compute the display state of the VTTCues in cues along with any VTTRegions
   * that they might be in. First, it computes the positioning and styling of
   * the cues and regions passed and converts them into a DOM tree rooted at
   * a containing HTMLDivElement. It then adjusts those computed divs for
   * overlap avoidance using the dimensions of 'overlay'. Finally, it adds the
   * computed divs to the VTTCues display state property for use later.
   *
   * @param window  A window object with which it will create the DOM tree
   *                and containing div element.
   * @param cues    An array of VTTCues who need there display state to be
   *                computed.
   * @param overlay The HTMLElement that the cues will be displayed within.
   * @param controls The video control element that will affect cues position.
   */
  void processCues(in mozIDOMWindow window, in nsIVariant cues,
                   in nsISupports overlay, in nsISupports controls);
};

%{C++
#define NS_WEBVTTPARSERWRAPPER_CONTRACTID "@mozilla.org/webvttParserWrapper;1"
%}