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