michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIDOMHTMLElement;
michael@0: interface nsIWebVTTListener;
michael@0: interface nsIDOMWindow;
michael@0: interface nsIVariant;
michael@0: 
michael@0: /**
michael@0:  * Interface for a wrapper of a JS WebVTT parser (vtt.js).
michael@0:  */
michael@0: [scriptable, uuid(acf6e493-0092-4b26-b172-241e375c57ab)]
michael@0: interface nsIWebVTTParserWrapper : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Loads the JS WebVTTParser and sets it to use the passed window to create
michael@0:    * VTTRegions and VTTCues. This function must be called before calling
michael@0:    * parse, flush, or watch.
michael@0:    *
michael@0:    * @param window The window that the parser will use to create VTTCues and
michael@0:    *               VTTRegions.
michael@0:    *
michael@0:    */
michael@0:   void loadParser(in nsIDOMWindow window);
michael@0: 
michael@0:   /**
michael@0:    * Attempts to parse the stream's data as WebVTT format. When it successfully
michael@0:    * parses a WebVTT region or WebVTT cue it will create a VTTRegion or VTTCue
michael@0:    * object and pass it back to the callee through its callbacks.
michael@0:    *
michael@0:    * @param data   The buffer that contains the WebVTT data received by the
michael@0:    *               Necko consumer so far.
michael@0:    */
michael@0:   void parse(in ACString data);
michael@0: 
michael@0:   /**
michael@0:    * Flush indicates that no more data is expected from the stream. As such the
michael@0:    * parser should try to parse any kind of partial data it has.
michael@0:    */
michael@0:   void flush();
michael@0: 
michael@0:   /**
michael@0:    * Set this parser object to use an nsIWebVTTListener object for its onCue
michael@0:    * and onRegion callbacks.
michael@0:    *
michael@0:    * @param callback The nsIWebVTTListener object that exposes onCue and
michael@0:    *                 onRegion callbacks for the parser.
michael@0:    */
michael@0:   void watch(in nsIWebVTTListener callback);
michael@0: 
michael@0:   /**
michael@0:    * Convert the text content of a WebVTT cue to a document fragment so that
michael@0:    * we can display it on the page.
michael@0:    *
michael@0:    * @param window A window object with which the document fragment will be
michael@0:    *               created.
michael@0:    * @param cue    The cue whose content will be converted to a document
michael@0:    *               fragment.
michael@0:    */
michael@0:   nsIDOMHTMLElement convertCueToDOMTree(in nsIDOMWindow window,
michael@0:                                         in nsISupports cue);
michael@0: 
michael@0: 
michael@0:   /**
michael@0:    * Compute the display state of the VTTCues in cues along with any VTTRegions
michael@0:    * that they might be in. First, it computes the positioning and styling of
michael@0:    * the cues and regions passed and converts them into a DOM tree rooted at
michael@0:    * a containing HTMLDivElement. It then adjusts those computed divs for
michael@0:    * overlap avoidance using the dimensions of 'overlay'. Finally, it adds the
michael@0:    * computed divs to the VTTCues display state property for use later.
michael@0:    *
michael@0:    * @param window  A window object with which it will create the DOM tree
michael@0:    *                and containing div element.
michael@0:    * @param cues    An array of VTTCues who need there display state to be
michael@0:    *                computed.
michael@0:    * @param overlay The HTMLElement that the cues will be displayed within.
michael@0:    */
michael@0:   void processCues(in nsIDOMWindow window, in nsIVariant cues,
michael@0:                    in nsISupports overlay);
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: #define NS_WEBVTTPARSERWRAPPER_CONTRACTID "@mozilla.org/webvttParserWrapper;1"
michael@0: %}