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/. */
6 #include
"nsISupports.idl"
8 interface nsIOutputStream
;
19 [ptr] native nsINodePtr
(nsINode
);
21 [scriptable
, uuid(3d9371d8
-a2ad
-403e-8b0e
-8885ad3562e3
)]
22 interface nsIDocumentEncoderNodeFixup
: nsISupports
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.
35 Node fixupNode
(in Node aNode
, out boolean aSerializeCloneKids
);
38 [scriptable
, uuid(21f112df
-d96f
-47da
-bfcb
-5331273003d1
)]
39 interface nsIDocumentEncoder
: nsISupports
41 // Output methods flag bits. There are a frightening number of these,
42 // because everyone wants something a little bit different
46 * Output only the selection (as opposed to the whole document).
48 const unsigned long OutputSelectionOnly
= (1 << 0);
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>).
59 * - Do prettyprinting, ignoring existing formatting.
60 * - Doesn't implicitly wrap
62 const unsigned long OutputFormatted
= (1 << 1);
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.
71 const unsigned long OutputRaw
= (1 << 2);
74 * Do not print html head tags.
75 * XHTML/HTML output only.
77 const unsigned long OutputBodyOnly
= (1 << 3);
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?
86 const unsigned long OutputPreformatted
= (1 << 4);
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?
98 const unsigned long OutputWrap
= (1 << 5);
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?
109 const unsigned long OutputFormatFlowed
= (1 << 6);
112 * Convert links, image src, and script src to absolute URLs when possible.
113 * XHTML/HTML output only.
115 const unsigned long OutputAbsoluteLinks
= (1 << 7);
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.
123 const unsigned long OutputCRLineBreak
= (1 << 9);
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.
131 const unsigned long OutputLFLineBreak
= (1 << 10);
134 * Output the content of noscript elements (only for serializing
137 const unsigned long OutputNoScriptContent
= (1 << 11);
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.)
144 const unsigned long OutputNoFramesContent
= (1 << 12);
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.
150 const unsigned long OutputNoFormattingInPre
= (1 << 13);
153 * Encode entities when outputting to a string.
154 * E.g. If set, we'll output if clear, we'll output 0xa0.
155 * The basic set is just & < > " for interoperability
156 * with older products that don't support α and friends.
159 const unsigned long OutputEncodeBasicEntities
= (1 << 14);
162 * Normally is replaced with a space character when
163 * encoding data as plain text, set this flag if that's
165 * Plaintext output only.
167 const unsigned long OutputPersistNBSP
= (1 << 17);
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.
174 const unsigned long OutputDontRewriteEncodingDeclaration
= (1 << 18);
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.
181 const unsigned long SkipInvisibleContent
= (1 << 19);
184 * Output for delsp=yes (RFC 3676). This is used with OutputFormatFlowed
185 * when converting to text for mail sending.
186 * PlainText output only.
188 const unsigned long OutputFormatDelSp
= (1 << 20);
191 * Drop <br> elements considered "invisible" by the editor. OutputPreformatted
194 const unsigned long OutputDropInvisibleBreak
= (1 << 21);
197 * Don't check for _moz_dirty attributes when deciding whether to
198 * pretty-print if this flag is set (bug 599983).
200 const unsigned long OutputIgnoreMozDirty
= (1 << 22);
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.
207 const unsigned long OutputForPlainTextClipboardCopy
= (1 << 25);
210 * Include ruby annotations and ruby parentheses in the output.
211 * PlainText output only.
213 const unsigned long OutputRubyAnnotation
= (1 << 26);
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.
220 const unsigned long OutputDisallowLineBreaking
= (1 << 27);
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.
227 const unsigned long RequiresReinitAfterOutput
= (1 << 28);
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.
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
);
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.
249 void setSelection
(in Selection aSelection
);
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.
257 void setRange
(in Range aRange
);
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.
265 void setNode
(in Node aNode
);
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.
273 void setContainerNode
(in Node aContainer
);
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
280 * @param aCharset Overrides the both the intrinsic or platform
281 * character set when encoding the document.
283 * Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER
285 void setCharset
(in ACString aCharset
);
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.
291 void setWrapColumn
(in unsigned long aWrapColumn
);
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.
299 readonly attribute AString mimeType
;
302 * Encode the document and send the result to the nsIOutputStream.
304 * Possible result codes are the stream errors which might have
306 * @param aStream Stream into which to encode.
308 void encodeToStream
(in nsIOutputStream aStream
);
311 * Encode the document into a string.
313 * @return The document encoded into a string.
315 AString encodeToString
();
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
324 * @return The document encoded as a string.
327 AString encodeToStringWithContext
( out AString aContextString
,
328 out AString aInfoString
);
331 * Encode the document into a string of limited size.
332 * @param aMaxLength After aMaxLength characters, the encoder will stop
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).
341 * @return The document encoded into a string.
343 AString encodeToStringWithMaxLength
(in unsigned long aMaxLength
);
346 * Set the fixup object associated with node persistence.
347 * @param aFixup The fixup object.
349 void setNodeFixup
(in nsIDocumentEncoderNodeFixup aFixup
);
353 template
<class T
> struct already_AddRefed
;
356 do_getDocumentTypeSupportedForEncoding
(const char* aContentType
);
357 already_AddRefed
<nsIDocumentEncoder
>
358 do_createDocumentEncoder
(const char* aContentType
);
359 already_AddRefed
<nsIDocumentEncoder
>
360 do_createHTMLCopyEncoder
();