dom/serializers/nsIDocumentEncoder.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIOutputStream;
   9
  10 webidl Document;
  11 webidl Node;
  12 webidl Range;
  13 webidl Selection;
  14
  15 %{ C++
  16 class nsINode;
  17
  18 %}
  19 [ptr] native nsINodePtr(nsINode);
  20
  21 [scriptable, uuid(3d9371d8-a2ad-403e-8b0e-8885ad3562e3)]
  22 interface nsIDocumentEncoderNodeFixup : nsISupports
  23 {
  24   /**
  25    * Create a fixed up version of a node. This method is called before
  26    * each node in a document is about to be persisted. The implementor
  27    * may return a new node with fixed up attributes or null. If null is
  28    * returned the node should be used as-is.
  29    * @param aNode Node to fixup.
  30    * @param [OUT] aSerializeCloneKids True if the document encoder should
  31    * apply recursive serialization to the children of the fixed up node
  32    * instead of the children of the original node.
  33    * @return The resulting fixed up node.
  34    */
  35   Node fixupNode(in Node aNode, out boolean aSerializeCloneKids);
  36 };
  37
  38 [scriptable, uuid(21f112df-d96f-47da-bfcb-5331273003d1)]
  39 interface nsIDocumentEncoder : nsISupports
  40 {
  41   // Output methods flag bits. There are a frightening number of these,
  42   // because everyone wants something a little bit different
  43
  44
  45   /**
  46    * Output only the selection (as opposed to the whole document).
  47    */
  48   const unsigned long OutputSelectionOnly = (1 << 0);
  49
  50   /**
  51     * Plaintext output:
  52     * - Convert html to plaintext that looks like the html.
  53     * - Can't be used in conjunction with `OutputPreformatted`.
  54     * - Implies wrap (except inside <pre>), since html wraps.
  55     * HTML and XHTML output:
  56     * - Do prettyprinting, ignoring existing formatting.
  57     * - Implies wrap (except in attribute values and inside <pre>).
  58     * XML output:
  59     * - Do prettyprinting, ignoring existing formatting.
  60     * - Doesn't implicitly wrap
  61     */
  62   const unsigned long OutputFormatted     = (1 << 1);
  63
  64   /** Don't do prettyprinting. Don't do any wrapping that's not in the existing
  65    * HTML/XML source. This option overrides OutputFormatted if both are set.
  66    * HTML/XHTML output: If neither are set, there won't be prettyprinting too, but
  67    * long lines will be wrapped.
  68    * Supported also in XML and Plaintext output.
  69    * @note This option does not affect entity conversion.
  70    */
  71   const unsigned long OutputRaw           = (1 << 2);
  72
  73   /**
  74    * Do not print html head tags.
  75    * XHTML/HTML output only.
  76    */
  77   const unsigned long OutputBodyOnly      = (1 << 3);
  78
  79   /**
  80    * Output as though the content is preformatted
  81    * (e.g. maybe it's wrapped in a PRE or PRE_WRAP style tag)
  82    * Plaintext output only.
  83    * Can't be used together with `OutputFormatted`/`OutputFormatFlowed`.
  84    * XXXbz How does this interact with OutputRaw?
  85    */
  86   const unsigned long OutputPreformatted  = (1 << 4);
  87
  88   /**
  89    * Wrap even if we're not doing formatted output (e.g. for text fields).
  90    * Supported in XML, XHTML, HTML and Plaintext output.
  91    * Set implicitly in HTML/XHTML output when no OutputRaw.
  92    * Ignored when OutputRaw.
  93    * For XML, XHTML and  HTML: does not wrap values in attributes.
  94    * XXXLJ: set implicitly in HTML/XHTML output, to keep compatible behaviors
  95    *        for old callers of this interface
  96    * XXXbz How does this interact with OutputFormatFlowed?
  97    */
  98   const unsigned long OutputWrap          = (1 << 5);
  99
 100   /**
 101    * Output for format flowed (RFC 2646). This is used when converting
 102    * to text for mail sending. This differs just slightly
 103    * but in an important way from normal formatted, and that is that
 104    * lines are space stuffed. This can't (correctly) be done later.
 105    * PlainText output only.
 106    * If this flag is set, `OutputFormat` has to be set too.
 107    * XXXbz How does this interact with OutputRaw/OutputWrap?
 108    */
 109   const unsigned long OutputFormatFlowed  = (1 << 6);
 110
 111   /**
 112    * Convert links, image src, and script src to absolute URLs when possible.
 113    * XHTML/HTML output only.
 114    */
 115   const unsigned long OutputAbsoluteLinks = (1 << 7);
 116
 117   /**
 118    * LineBreak processing: if this flag is set than CR line breaks will
 119    * be written. If neither this nor OutputLFLineBreak is set, then we
 120    * will use platform line breaks. The combination of the two flags will
 121    * cause CRLF line breaks to be written.
 122    */
 123   const unsigned long OutputCRLineBreak = (1 << 9);
 124
 125   /**
 126    * LineBreak processing: if this flag is set than LF line breaks will
 127    * be written. If neither this nor OutputCRLineBreak is set, then we
 128    * will use platform line breaks. The combination of the two flags will
 129    * cause CRLF line breaks to be written.
 130    */
 131   const unsigned long OutputLFLineBreak = (1 << 10);
 132
 133   /**
 134    * Output the content of noscript elements (only for serializing
 135    * to plaintext).
 136    */
 137   const unsigned long OutputNoScriptContent = (1 << 11);
 138
 139   /**
 140    * Output the content of noframes elements (only for serializing
 141    * to plaintext). (Used only internally in the plain text serializer;
 142    * ignored if passed by the caller.)
 143    */
 144   const unsigned long OutputNoFramesContent = (1 << 12);
 145
 146   /**
 147    * Don't allow any formatting nodes (e.g. <br>, <b>) inside a <pre>.
 148    * This is used primarily by mail. XHTML/HTML output only.
 149    */
 150   const unsigned long OutputNoFormattingInPre = (1 << 13);
 151
 152   /**
 153    * Encode entities when outputting to a string.
 154    * E.g. If set, we'll output &nbsp; if clear, we'll output 0xa0.
 155    * The basic set is just &nbsp; &amp; &lt; &gt; &quot; for interoperability
 156    * with older products that don't support &alpha; and friends.
 157    * HTML output only.
 158    */
 159   const unsigned long OutputEncodeBasicEntities = (1 << 14);
 160
 161   /**
 162    * Normally &nbsp; is replaced with a space character when
 163    * encoding data as plain text, set this flag if that's
 164    * not desired.
 165    * Plaintext output only.
 166    */
 167   const unsigned long OutputPersistNBSP = (1 << 17);
 168
 169   /**
 170    * Normally when serializing the whole document using the HTML or
 171    * XHTML serializer, the encoding declaration is rewritten to match.
 172    * This flag suppresses that behavior.
 173    */
 174   const unsigned long OutputDontRewriteEncodingDeclaration = (1 << 18);
 175
 176   /**
 177    * When using the HTML or XHTML serializer, skip elements that are not
 178    * visible when this flag is set.  Elements are not visible when they
 179    * have CSS style display:none or visibility:collapse, for example.
 180    */
 181   const unsigned long SkipInvisibleContent = (1 << 19);
 182
 183   /**
 184    * Output for delsp=yes (RFC 3676). This is used with OutputFormatFlowed
 185    * when converting to text for mail sending.
 186    * PlainText output only.
 187    */
 188   const unsigned long OutputFormatDelSp  = (1 << 20);
 189
 190   /**
 191    * Drop <br> elements considered "invisible" by the editor. OutputPreformatted
 192    * implies this flag.
 193    */
 194   const unsigned long OutputDropInvisibleBreak = (1 << 21);
 195
 196   /**
 197    * Don't check for _moz_dirty attributes when deciding whether to
 198    * pretty-print if this flag is set (bug 599983).
 199    */
 200   const unsigned long OutputIgnoreMozDirty = (1 << 22);
 201
 202   /**
 203    * Serialize in a way that is suitable for copying a plaintext version of the
 204    * document to the clipboard.  This can for example cause line endings to be
 205    * injected at preformatted block element boundaries.
 206    */
 207   const unsigned long OutputForPlainTextClipboardCopy = (1 << 25);
 208
 209   /**
 210    * Include ruby annotations and ruby parentheses in the output.
 211    * PlainText output only.
 212    */
 213   const unsigned long OutputRubyAnnotation = (1 << 26);
 214
 215   /**
 216    * Disallow breaking of long character strings. This is important
 217    * for serializing e-mail which contains CJK strings. These must
 218    * not be broken just as "normal" longs strings aren't broken.
 219    */
 220   const unsigned long OutputDisallowLineBreaking = (1 << 27);
 221
 222   /**
 223    * Release reference of Document after using encodeTo* method to recycle
 224    * this encoder without holding Document. To use this encoder again,
 225    * we have to call init again.
 226    */
 227   const unsigned long RequiresReinitAfterOutput = (1 << 28);
 228
 229   /**
 230    * Initialize with a pointer to the document and the mime type.
 231    * Resets wrap column to 72 and resets node fixup.
 232    * @param aDocument Document to encode.
 233    * @param aMimeType MimeType to use. May also be set by SetMimeType.
 234    * @param aFlags Flags to use while encoding. May also be set by SetFlags.
 235    */
 236   void init(in Document aDocument,
 237             in AString aMimeType,
 238             in unsigned long aFlags);
 239   [noscript] void nativeInit(in Document aDocument,
 240                              in AString aMimeType,
 241                              in unsigned long aFlags);
 242
 243   /**
 244    *  If the selection is set to a non-null value, then the
 245    *  selection is used for encoding, otherwise the entire
 246    *  document is encoded.
 247    * @param aSelection The selection to encode.
 248    */
 249   void setSelection(in Selection aSelection);
 250
 251   /**
 252    *  If the range is set to a non-null value, then the
 253    *  range is used for encoding, otherwise the entire
 254    *  document or selection is encoded.
 255    * @param aRange The range to encode.
 256    */
 257   void setRange(in Range aRange);
 258
 259   /**
 260    *  If the node is set to a non-null value, then the
 261    *  node is used for encoding, otherwise the entire
 262    *  document or range or selection is encoded.
 263    * @param aNode The node to encode.
 264    */
 265   void setNode(in Node aNode);
 266
 267   /**
 268    *  If the container is set to a non-null value, then its
 269    *  child nodes are used for encoding, otherwise the entire
 270    *  document or range or selection or node is encoded.
 271    *  @param aContainer The node which child nodes will be encoded.
 272    */
 273   void setContainerNode(in Node aContainer);
 274
 275   /**
 276    *  Documents typically have an intrinsic character set,
 277    *  but if no intrinsic value is found, the platform character set
 278    *  is used. This function overrides both the intrinisc and platform
 279    *  charset.
 280    *  @param aCharset Overrides the both the intrinsic or platform
 281    *  character set when encoding the document.
 282    *
 283    *  Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER
 284    */
 285   void setCharset(in ACString aCharset);
 286
 287   /**
 288    *  Set a wrap column.  This may have no effect in some types of encoders.
 289    * @param aWrapColumn Column to which to wrap. If 0, wrapping is disabled.
 290    */
 291   void setWrapColumn(in unsigned long aWrapColumn);
 292
 293   /**
 294    *  The mime type preferred by the encoder.  This piece of api was
 295    *  added because the copy encoder may need to switch mime types on you
 296    *  if you ask it to copy html that really represents plaintext content.
 297    *  Call this AFTER Init() and SetSelection() have both been called.
 298    */
 299   readonly attribute AString mimeType;
 300
 301   /**
 302    *  Encode the document and send the result to the nsIOutputStream.
 303    *
 304    *  Possible result codes are the stream errors which might have
 305    *  been encountered.
 306    * @param aStream Stream into which to encode.
 307    */
 308   void encodeToStream(in nsIOutputStream aStream);
 309
 310   /**
 311    * Encode the document into a string.
 312    *
 313    * @return The document encoded into a string.
 314    */
 315   AString encodeToString();
 316
 317   /**
 318    * Encode the document into a string. Stores the extra context information
 319    * into the two arguments.
 320    * @param [OUT] aContextString The string where the parent hierarchy
 321    *              information will be stored.
 322    * @param [OUT] aInfoString The string where extra context info will
 323    *              be stored.
 324    * @return The document encoded as a string.
 325    *
 326    */
 327   AString encodeToStringWithContext( out AString aContextString,
 328                                      out AString aInfoString);
 329
 330   /**
 331    * Encode the document into a string of limited size.
 332    * @param aMaxLength After aMaxLength characters, the encoder will stop
 333    *                   encoding new data.
 334    *                   Only values > 0 will be considered.
 335    *                   The returned string may be slightly larger than
 336    *                   aMaxLength because some serializers (eg. HTML)
 337    *                   may need to close some tags after they stop
 338    *                   encoding new data, or finish a line (72 columns
 339    *                   by default for the plain text serializer).
 340    *
 341    * @return The document encoded into a string.
 342    */
 343   AString encodeToStringWithMaxLength(in unsigned long aMaxLength);
 344
 345   /**
 346    * Set the fixup object associated with node persistence.
 347    * @param aFixup The fixup object.
 348    */
 349   void setNodeFixup(in nsIDocumentEncoderNodeFixup aFixup);
 350 };
 351
 352 %{ C++
 353 template<class T> struct already_AddRefed;
 354
 355 bool
 356 do_getDocumentTypeSupportedForEncoding(const char* aContentType);
 357 already_AddRefed<nsIDocumentEncoder>
 358 do_createDocumentEncoder(const char* aContentType);
 359 already_AddRefed<nsIDocumentEncoder>
 360 do_createHTMLCopyEncoder();
 361 %}