michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
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 nsIDOMDocument;
michael@0: interface nsIDOMRange;
michael@0: interface nsISelection;
michael@0: interface nsIDOMNode;
michael@0: interface nsIOutputStream;
michael@0: 
michael@0: %{ C++
michael@0: class nsINode;
michael@0: class nsIDocument;
michael@0: %}
michael@0: [ptr] native nsINodePtr(nsINode);
michael@0: [ptr] native nsIDocumentPtr(nsIDocument);
michael@0: 
michael@0: [scriptable, uuid(3d9371d8-a2ad-403e-8b0e-8885ad3562e3)]
michael@0: interface nsIDocumentEncoderNodeFixup : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Create a fixed up version of a node. This method is called before
michael@0:    * each node in a document is about to be persisted. The implementor
michael@0:    * may return a new node with fixed up attributes or null. If null is
michael@0:    * returned the node should be used as-is.
michael@0:    * @param aNode Node to fixup.
michael@0:    * @param [OUT] aSerializeCloneKids True if the document encoder should
michael@0:    * apply recursive serialization to the children of the fixed up node
michael@0:    * instead of the children of the original node.
michael@0:    * @return The resulting fixed up node.
michael@0:    */
michael@0:   nsIDOMNode fixupNode(in nsIDOMNode aNode, out boolean aSerializeCloneKids);
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(1158bd7e-a08b-4ff6-9417-6f99144cfccc)]
michael@0: interface nsIDocumentEncoder : nsISupports
michael@0: {
michael@0:   // Output methods flag bits. There are a frightening number of these,
michael@0:   // because everyone wants something a little bit different
michael@0:    
michael@0: 
michael@0:   /** 
michael@0:    * Output only the selection (as opposed to the whole document).
michael@0:    */
michael@0:   const unsigned long OutputSelectionOnly = (1 << 0);
michael@0: 
michael@0:   /** Plaintext output: Convert html to plaintext that looks like the html.
michael@0:     * Implies wrap (except inside <pre>), since html wraps.
michael@0:     * HTML, XHTML and XML output: do prettyprinting, ignoring existing formatting.
michael@0:     * XML output : it doesn't implicitly wrap
michael@0:     */
michael@0:   const unsigned long OutputFormatted     = (1 << 1);
michael@0: 
michael@0:   /** Don't do prettyprinting. Don't do any wrapping that's not in the existing
michael@0:    * HTML/XML source. This option overrides OutputFormatted if both are set.
michael@0:    * HTML/XHTML output: If neither are set, there won't be prettyprinting too, but
michael@0:    * long lines will be wrapped.
michael@0:    * Supported also in XML and Plaintext output.
michael@0:    * @note This option does not affect entity conversion.
michael@0:    */
michael@0:   const unsigned long OutputRaw           = (1 << 2);
michael@0: 
michael@0:   /** 
michael@0:    * Do not print html head tags.
michael@0:    * XHTML/HTML output only.
michael@0:    */
michael@0:   const unsigned long OutputBodyOnly      = (1 << 3);
michael@0: 
michael@0:   /**
michael@0:    * Output as though the content is preformatted
michael@0:    * (e.g. maybe it's wrapped in a PRE or PRE_WRAP style tag)
michael@0:    * Plaintext output only.
michael@0:    * XXXbz How does this interact with
michael@0:    * OutputFormatted/OutputRaw/OutputPreformatted/OutputFormatFlowed?
michael@0:    */
michael@0:   const unsigned long OutputPreformatted  = (1 << 4);
michael@0: 
michael@0:   /**
michael@0:    * Wrap even if we're not doing formatted output (e.g. for text fields).
michael@0:    * Supported in XML, XHTML, HTML and Plaintext output.
michael@0:    * Set implicitly in HTML/XHTML output when no OutputRaw.
michael@0:    * Ignored when OutputRaw.
michael@0:    * XXXLJ: set implicitly in HTML/XHTML output, to keep compatible behaviors
michael@0:    *        for old callers of this interface
michael@0:    * XXXbz How does this interact with OutputFormatFlowed?
michael@0:    */
michael@0:   const unsigned long OutputWrap          = (1 << 5);
michael@0: 
michael@0:   /**
michael@0:    * Output for format flowed (RFC 2646). This is used when converting
michael@0:    * to text for mail sending. This differs just slightly
michael@0:    * but in an important way from normal formatted, and that is that
michael@0:    * lines are space stuffed. This can't (correctly) be done later.
michael@0:    * PlainText output only.
michael@0:    * XXXbz How does this interact with
michael@0:    * OutputFormatted/OutputRaw/OutputPreformatted/OutputWrap?
michael@0:    */
michael@0:   const unsigned long OutputFormatFlowed  = (1 << 6);
michael@0: 
michael@0:   /**
michael@0:    * Convert links, image src, and script src to absolute URLs when possible.
michael@0:    * XHTML/HTML output only.
michael@0:    */
michael@0:   const unsigned long OutputAbsoluteLinks = (1 << 7);
michael@0: 
michael@0:   /**
michael@0:    * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
michael@0:    * This is a catch-all flag for documents with mixed contents. Beware of
michael@0:    * interoperability issues. See below for other flags which might likely
michael@0:    * do what you want.
michael@0:    * HTML output only.
michael@0:    */
michael@0:   const unsigned long OutputEncodeW3CEntities = (1 << 8);
michael@0: 
michael@0:   /** 
michael@0:    * LineBreak processing: if this flag is set than CR line breaks will
michael@0:    * be written. If neither this nor OutputLFLineBreak is set, then we
michael@0:    * will use platform line breaks. The combination of the two flags will
michael@0:    * cause CRLF line breaks to be written.
michael@0:    */
michael@0:   const unsigned long OutputCRLineBreak = (1 << 9);
michael@0: 
michael@0:   /** 
michael@0:    * LineBreak processing: if this flag is set than LF line breaks will
michael@0:    * be written. If neither this nor OutputCRLineBreak is set, then we
michael@0:    * will use platform line breaks. The combination of the two flags will
michael@0:    * cause CRLF line breaks to be written.
michael@0:    */
michael@0:   const unsigned long OutputLFLineBreak = (1 << 10);
michael@0: 
michael@0:   /**
michael@0:    * Output the content of noscript elements (only for serializing
michael@0:    * to plaintext).
michael@0:    */
michael@0:   const unsigned long OutputNoScriptContent = (1 << 11);
michael@0: 
michael@0:   /**
michael@0:    * Output the content of noframes elements (only for serializing
michael@0:    * to plaintext). (Used only internally in the plain text serializer;
michael@0:    * ignored if passed by the caller.)
michael@0:    */
michael@0:   const unsigned long OutputNoFramesContent = (1 << 12);
michael@0: 
michael@0:   /**
michael@0:    * Don't allow any formatting nodes (e.g. <br>, <b>) inside a <pre>.
michael@0:    * This is used primarily by mail. XHTML/HTML output only.
michael@0:    */
michael@0:   const unsigned long OutputNoFormattingInPre = (1 << 13);
michael@0: 
michael@0:   /**
michael@0:    * Encode entities when outputting to a string.
michael@0:    * E.g. If set, we'll output &nbsp; if clear, we'll output 0xa0.
michael@0:    * The basic set is just &nbsp; &amp; &lt; &gt; &quot; for interoperability
michael@0:    * with older products that don't support &alpha; and friends.
michael@0:    * HTML output only.
michael@0:    */
michael@0:   const unsigned long OutputEncodeBasicEntities = (1 << 14);
michael@0:     
michael@0:   /**
michael@0:    * Encode entities when outputting to a string.
michael@0:    * The Latin1 entity set additionally includes 8bit accented letters
michael@0:    * between 128 and 255.
michael@0:    * HTML output only.
michael@0:    */
michael@0:   const unsigned long OutputEncodeLatin1Entities = (1 << 15);
michael@0:   
michael@0:   /**
michael@0:    * Encode entities when outputting to a string.
michael@0:    * The HTML entity set additionally includes accented letters, greek
michael@0:    * letters, and other special markup symbols as defined in HTML4.
michael@0:    * HTML output only.
michael@0:    */
michael@0:   const unsigned long OutputEncodeHTMLEntities = (1 << 16);
michael@0: 
michael@0:   /**
michael@0:    * Normally &nbsp; is replaced with a space character when
michael@0:    * encoding data as plain text, set this flag if that's
michael@0:    * not desired.
michael@0:    * Plaintext output only.
michael@0:    */
michael@0:   const unsigned long OutputPersistNBSP = (1 << 17);
michael@0: 
michael@0:   /**
michael@0:    * Normally when serializing the whole document using the HTML or 
michael@0:    * XHTML serializer, the encoding declaration is rewritten to match.
michael@0:    * This flag suppresses that behavior.
michael@0:    */
michael@0:   const unsigned long OutputDontRewriteEncodingDeclaration = (1 << 18);
michael@0:  
michael@0:   /**
michael@0:    * When using the HTML or XHTML serializer, skip elements that are not
michael@0:    * visible when this flag is set.  Elements are not visible when they
michael@0:    * have CSS style display:none or visibility:collapse, for example.
michael@0:    */
michael@0:   const unsigned long SkipInvisibleContent = (1 << 19);
michael@0:   
michael@0:   /**
michael@0:    * Output for delsp=yes (RFC 3676). This is used with OutputFormatFlowed
michael@0:    * when converting to text for mail sending.
michael@0:    * PlainText output only.
michael@0:    */
michael@0:   const unsigned long OutputFormatDelSp  = (1 << 20);
michael@0:  
michael@0:   /**
michael@0:    * Drop <br> elements considered "invisible" by the editor. OutputPreformatted
michael@0:    * implies this flag.
michael@0:    */
michael@0:   const unsigned long OutputDropInvisibleBreak = (1 << 21);
michael@0: 
michael@0:   /**
michael@0:    * Don't check for _moz_dirty attributes when deciding whether to
michael@0:    * pretty-print if this flag is set (bug 599983).
michael@0:    */
michael@0:   const unsigned long OutputIgnoreMozDirty = (1 << 22);
michael@0: 
michael@0:   /**
michael@0:    * Output the content of non-text elements as the placehodler character
michael@0:    * U+FFFC (OBJECT REPLACEMENT CHARACTER, only for serializing to plaintext).
michael@0:    */
michael@0:   const unsigned long OutputNonTextContentAsPlaceholder = (1 << 23);
michael@0: 
michael@0:   /**
michael@0:    * Don't Strip ending spaces from a line (only for serializing to plaintext).
michael@0:    */
michael@0:   const unsigned long OutputDontRemoveLineEndingSpaces = (1 << 24);
michael@0: 
michael@0:   /**
michael@0:    * Initialize with a pointer to the document and the mime type.
michael@0:    * @param aDocument Document to encode.
michael@0:    * @param aMimeType MimeType to use. May also be set by SetMimeType.
michael@0:    * @param aFlags Flags to use while encoding. May also be set by SetFlags.
michael@0:    */
michael@0:   void init(in nsIDOMDocument aDocument,
michael@0:             in AString aMimeType,
michael@0:             in unsigned long aFlags);
michael@0:   [noscript] void nativeInit(in nsIDocumentPtr aDocument,
michael@0:                              in AString aMimeType,
michael@0:                              in unsigned long aFlags);
michael@0: 
michael@0:   /**
michael@0:    *  If the selection is set to a non-null value, then the
michael@0:    *  selection is used for encoding, otherwise the entire
michael@0:    *  document is encoded.
michael@0:    * @param aSelection The selection to encode.
michael@0:    */
michael@0:   void setSelection(in nsISelection aSelection);
michael@0: 
michael@0:   /**
michael@0:    *  If the range is set to a non-null value, then the
michael@0:    *  range is used for encoding, otherwise the entire
michael@0:    *  document or selection is encoded.
michael@0:    * @param aRange The range to encode.
michael@0:    */
michael@0:   void setRange(in nsIDOMRange aRange);
michael@0: 
michael@0:   /**
michael@0:    *  If the node is set to a non-null value, then the
michael@0:    *  node is used for encoding, otherwise the entire
michael@0:    *  document or range or selection is encoded.
michael@0:    * @param aNode The node to encode.
michael@0:    */
michael@0:   void setNode(in nsIDOMNode aNode);
michael@0:   [noscript] void setNativeNode(in nsINodePtr aNode);
michael@0: 
michael@0:   /**
michael@0:    *  If the container is set to a non-null value, then its
michael@0:    *  child nodes are used for encoding, otherwise the entire
michael@0:    *  document or range or selection or node is encoded.
michael@0:    *  @param aContainer The node which child nodes will be encoded.
michael@0:    */
michael@0:   void setContainerNode(in nsIDOMNode aContainer);
michael@0:   [noscript] void setNativeContainerNode(in nsINodePtr aContainer);
michael@0: 
michael@0:   /**
michael@0:    *  Documents typically have an intrinsic character set,
michael@0:    *  but if no intrinsic value is found, the platform character set
michael@0:    *  is used. This function overrides both the intrinisc and platform
michael@0:    *  charset.
michael@0:    *  @param aCharset Overrides the both the intrinsic or platform
michael@0:    *  character set when encoding the document.
michael@0:    *
michael@0:    *  Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER
michael@0:    */
michael@0:   void setCharset(in ACString aCharset);
michael@0: 
michael@0:   /**
michael@0:    *  Set a wrap column.  This may have no effect in some types of encoders.
michael@0:    * @param aWrapColumn Column to which to wrap.
michael@0:    */
michael@0:   void setWrapColumn(in unsigned long aWrapColumn);
michael@0: 
michael@0:   /**
michael@0:    *  The mime type preferred by the encoder.  This piece of api was
michael@0:    *  added because the copy encoder may need to switch mime types on you
michael@0:    *  if you ask it to copy html that really represents plaintext content.
michael@0:    *  Call this AFTER Init() and SetSelection() have both been called.
michael@0:    */
michael@0:   readonly attribute AString mimeType;
michael@0:   
michael@0:   /**
michael@0:    *  Encode the document and send the result to the nsIOutputStream.
michael@0:    *
michael@0:    *  Possible result codes are the stream errors which might have
michael@0:    *  been encountered.
michael@0:    * @param aStream Stream into which to encode.
michael@0:    */
michael@0:   void encodeToStream(in nsIOutputStream aStream);
michael@0: 
michael@0:   /**
michael@0:    * Encode the document into a string.
michael@0:    *
michael@0:    * @return The document encoded into a string.
michael@0:    */
michael@0:   AString encodeToString();
michael@0: 
michael@0:   /**
michael@0:    * Encode the document into a string. Stores the extra context information
michael@0:    * into the two arguments.
michael@0:    * @param [OUT] aContextString The string where the parent hierarchy
michael@0:    *              information will be stored.
michael@0:    * @param [OUT] aInfoString The string where extra context info will
michael@0:    *              be stored.
michael@0:    * @return The document encoded as a string.
michael@0:    * 
michael@0:    */
michael@0:   AString encodeToStringWithContext( out AString aContextString,
michael@0:                                      out AString aInfoString);
michael@0: 
michael@0:   /**
michael@0:    * Encode the document into a string of limited size.
michael@0:    * @param aMaxLength After aMaxLength characters, the encoder will stop
michael@0:    *                   encoding new data.
michael@0:    *                   Only values > 0 will be considered.
michael@0:    *                   The returned string may be slightly larger than
michael@0:    *                   aMaxLength because some serializers (eg. HTML)
michael@0:    *                   may need to close some tags after they stop
michael@0:    *                   encoding new data, or finish a line (72 columns
michael@0:    *                   by default for the plain text serializer).
michael@0:    *
michael@0:    * @return The document encoded into a string.
michael@0:    */
michael@0:   AString encodeToStringWithMaxLength(in unsigned long aMaxLength);
michael@0: 
michael@0:   /**
michael@0:    * Set the fixup object associated with node persistence.
michael@0:    * @param aFixup The fixup object.
michael@0:    */
michael@0:   void setNodeFixup(in nsIDocumentEncoderNodeFixup aFixup);
michael@0: };