content/base/public/nsIDocumentEncoder.idl@8bccb770b82d
content/base/public/nsIDocumentEncoder.idl
Wed, 31 Dec 2014 13:27:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 13:27:57 +0100
- branch
- TOR_BUG_3246
- changeset 6
- 8bccb770b82d
- permissions
- -rw-r--r--
Ignore runtime configuration files generated during quality assurance.
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 nsIDOMDocument;
9 interface nsIDOMRange;
10 interface nsISelection;
11 interface nsIDOMNode;
12 interface nsIOutputStream;
14 %{ C++
15 class nsINode;
16 class nsIDocument;
17 %}
18 [ptr] native nsINodePtr(nsINode);
19 [ptr] native nsIDocumentPtr(nsIDocument);
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 nsIDOMNode fixupNode(in nsIDOMNode aNode, out boolean aSerializeCloneKids);
36 };
38 [scriptable, uuid(1158bd7e-a08b-4ff6-9417-6f99144cfccc)]
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
45 /**
46 * Output only the selection (as opposed to the whole document).
47 */
48 const unsigned long OutputSelectionOnly = (1 << 0);
50 /** Plaintext output: Convert html to plaintext that looks like the html.
51 * Implies wrap (except inside <pre>), since html wraps.
52 * HTML, XHTML and XML output: do prettyprinting, ignoring existing formatting.
53 * XML output : it doesn't implicitly wrap
54 */
55 const unsigned long OutputFormatted = (1 << 1);
57 /** Don't do prettyprinting. Don't do any wrapping that's not in the existing
58 * HTML/XML source. This option overrides OutputFormatted if both are set.
59 * HTML/XHTML output: If neither are set, there won't be prettyprinting too, but
60 * long lines will be wrapped.
61 * Supported also in XML and Plaintext output.
62 * @note This option does not affect entity conversion.
63 */
64 const unsigned long OutputRaw = (1 << 2);
66 /**
67 * Do not print html head tags.
68 * XHTML/HTML output only.
69 */
70 const unsigned long OutputBodyOnly = (1 << 3);
72 /**
73 * Output as though the content is preformatted
74 * (e.g. maybe it's wrapped in a PRE or PRE_WRAP style tag)
75 * Plaintext output only.
76 * XXXbz How does this interact with
77 * OutputFormatted/OutputRaw/OutputPreformatted/OutputFormatFlowed?
78 */
79 const unsigned long OutputPreformatted = (1 << 4);
81 /**
82 * Wrap even if we're not doing formatted output (e.g. for text fields).
83 * Supported in XML, XHTML, HTML and Plaintext output.
84 * Set implicitly in HTML/XHTML output when no OutputRaw.
85 * Ignored when OutputRaw.
86 * XXXLJ: set implicitly in HTML/XHTML output, to keep compatible behaviors
87 * for old callers of this interface
88 * XXXbz How does this interact with OutputFormatFlowed?
89 */
90 const unsigned long OutputWrap = (1 << 5);
92 /**
93 * Output for format flowed (RFC 2646). This is used when converting
94 * to text for mail sending. This differs just slightly
95 * but in an important way from normal formatted, and that is that
96 * lines are space stuffed. This can't (correctly) be done later.
97 * PlainText output only.
98 * XXXbz How does this interact with
99 * OutputFormatted/OutputRaw/OutputPreformatted/OutputWrap?
100 */
101 const unsigned long OutputFormatFlowed = (1 << 6);
103 /**
104 * Convert links, image src, and script src to absolute URLs when possible.
105 * XHTML/HTML output only.
106 */
107 const unsigned long OutputAbsoluteLinks = (1 << 7);
109 /**
110 * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
111 * This is a catch-all flag for documents with mixed contents. Beware of
112 * interoperability issues. See below for other flags which might likely
113 * do what you want.
114 * HTML output only.
115 */
116 const unsigned long OutputEncodeW3CEntities = (1 << 8);
118 /**
119 * LineBreak processing: if this flag is set than CR line breaks will
120 * be written. If neither this nor OutputLFLineBreak is set, then we
121 * will use platform line breaks. The combination of the two flags will
122 * cause CRLF line breaks to be written.
123 */
124 const unsigned long OutputCRLineBreak = (1 << 9);
126 /**
127 * LineBreak processing: if this flag is set than LF line breaks will
128 * be written. If neither this nor OutputCRLineBreak is set, then we
129 * will use platform line breaks. The combination of the two flags will
130 * cause CRLF line breaks to be written.
131 */
132 const unsigned long OutputLFLineBreak = (1 << 10);
134 /**
135 * Output the content of noscript elements (only for serializing
136 * to plaintext).
137 */
138 const unsigned long OutputNoScriptContent = (1 << 11);
140 /**
141 * Output the content of noframes elements (only for serializing
142 * to plaintext). (Used only internally in the plain text serializer;
143 * ignored if passed by the caller.)
144 */
145 const unsigned long OutputNoFramesContent = (1 << 12);
147 /**
148 * Don't allow any formatting nodes (e.g. <br>, <b>) inside a <pre>.
149 * This is used primarily by mail. XHTML/HTML output only.
150 */
151 const unsigned long OutputNoFormattingInPre = (1 << 13);
153 /**
154 * Encode entities when outputting to a string.
155 * E.g. If set, we'll output if clear, we'll output 0xa0.
156 * The basic set is just & < > " for interoperability
157 * with older products that don't support α and friends.
158 * HTML output only.
159 */
160 const unsigned long OutputEncodeBasicEntities = (1 << 14);
162 /**
163 * Encode entities when outputting to a string.
164 * The Latin1 entity set additionally includes 8bit accented letters
165 * between 128 and 255.
166 * HTML output only.
167 */
168 const unsigned long OutputEncodeLatin1Entities = (1 << 15);
170 /**
171 * Encode entities when outputting to a string.
172 * The HTML entity set additionally includes accented letters, greek
173 * letters, and other special markup symbols as defined in HTML4.
174 * HTML output only.
175 */
176 const unsigned long OutputEncodeHTMLEntities = (1 << 16);
178 /**
179 * Normally is replaced with a space character when
180 * encoding data as plain text, set this flag if that's
181 * not desired.
182 * Plaintext output only.
183 */
184 const unsigned long OutputPersistNBSP = (1 << 17);
186 /**
187 * Normally when serializing the whole document using the HTML or
188 * XHTML serializer, the encoding declaration is rewritten to match.
189 * This flag suppresses that behavior.
190 */
191 const unsigned long OutputDontRewriteEncodingDeclaration = (1 << 18);
193 /**
194 * When using the HTML or XHTML serializer, skip elements that are not
195 * visible when this flag is set. Elements are not visible when they
196 * have CSS style display:none or visibility:collapse, for example.
197 */
198 const unsigned long SkipInvisibleContent = (1 << 19);
200 /**
201 * Output for delsp=yes (RFC 3676). This is used with OutputFormatFlowed
202 * when converting to text for mail sending.
203 * PlainText output only.
204 */
205 const unsigned long OutputFormatDelSp = (1 << 20);
207 /**
208 * Drop <br> elements considered "invisible" by the editor. OutputPreformatted
209 * implies this flag.
210 */
211 const unsigned long OutputDropInvisibleBreak = (1 << 21);
213 /**
214 * Don't check for _moz_dirty attributes when deciding whether to
215 * pretty-print if this flag is set (bug 599983).
216 */
217 const unsigned long OutputIgnoreMozDirty = (1 << 22);
219 /**
220 * Output the content of non-text elements as the placehodler character
221 * U+FFFC (OBJECT REPLACEMENT CHARACTER, only for serializing to plaintext).
222 */
223 const unsigned long OutputNonTextContentAsPlaceholder = (1 << 23);
225 /**
226 * Don't Strip ending spaces from a line (only for serializing to plaintext).
227 */
228 const unsigned long OutputDontRemoveLineEndingSpaces = (1 << 24);
230 /**
231 * Initialize with a pointer to the document and the mime type.
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 nsIDOMDocument aDocument,
237 in AString aMimeType,
238 in unsigned long aFlags);
239 [noscript] void nativeInit(in nsIDocumentPtr aDocument,
240 in AString aMimeType,
241 in unsigned long aFlags);
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 nsISelection aSelection);
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 nsIDOMRange aRange);
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 nsIDOMNode aNode);
266 [noscript] void setNativeNode(in nsINodePtr aNode);
268 /**
269 * If the container is set to a non-null value, then its
270 * child nodes are used for encoding, otherwise the entire
271 * document or range or selection or node is encoded.
272 * @param aContainer The node which child nodes will be encoded.
273 */
274 void setContainerNode(in nsIDOMNode aContainer);
275 [noscript] void setNativeContainerNode(in nsINodePtr aContainer);
277 /**
278 * Documents typically have an intrinsic character set,
279 * but if no intrinsic value is found, the platform character set
280 * is used. This function overrides both the intrinisc and platform
281 * charset.
282 * @param aCharset Overrides the both the intrinsic or platform
283 * character set when encoding the document.
284 *
285 * Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER
286 */
287 void setCharset(in ACString aCharset);
289 /**
290 * Set a wrap column. This may have no effect in some types of encoders.
291 * @param aWrapColumn Column to which to wrap.
292 */
293 void setWrapColumn(in unsigned long aWrapColumn);
295 /**
296 * The mime type preferred by the encoder. This piece of api was
297 * added because the copy encoder may need to switch mime types on you
298 * if you ask it to copy html that really represents plaintext content.
299 * Call this AFTER Init() and SetSelection() have both been called.
300 */
301 readonly attribute AString mimeType;
303 /**
304 * Encode the document and send the result to the nsIOutputStream.
305 *
306 * Possible result codes are the stream errors which might have
307 * been encountered.
308 * @param aStream Stream into which to encode.
309 */
310 void encodeToStream(in nsIOutputStream aStream);
312 /**
313 * Encode the document into a string.
314 *
315 * @return The document encoded into a string.
316 */
317 AString encodeToString();
319 /**
320 * Encode the document into a string. Stores the extra context information
321 * into the two arguments.
322 * @param [OUT] aContextString The string where the parent hierarchy
323 * information will be stored.
324 * @param [OUT] aInfoString The string where extra context info will
325 * be stored.
326 * @return The document encoded as a string.
327 *
328 */
329 AString encodeToStringWithContext( out AString aContextString,
330 out AString aInfoString);
332 /**
333 * Encode the document into a string of limited size.
334 * @param aMaxLength After aMaxLength characters, the encoder will stop
335 * encoding new data.
336 * Only values > 0 will be considered.
337 * The returned string may be slightly larger than
338 * aMaxLength because some serializers (eg. HTML)
339 * may need to close some tags after they stop
340 * encoding new data, or finish a line (72 columns
341 * by default for the plain text serializer).
342 *
343 * @return The document encoded into a string.
344 */
345 AString encodeToStringWithMaxLength(in unsigned long aMaxLength);
347 /**
348 * Set the fixup object associated with node persistence.
349 * @param aFixup The fixup object.
350 */
351 void setNodeFixup(in nsIDocumentEncoderNodeFixup aFixup);
352 };
