1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * the Mozilla Foundation.
19 * Portions created by the Initial Developer are Copyright (C) 2006
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Josh Lurz <jlurz24@gmail.com>
24 *
25 * Alternatively, the contents of this file may be used under the terms of
26 * either of the GNU General Public License Version 2 or later (the "GPL"),
27 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 * in which case the provisions of the GPL or the LGPL are applicable instead
29 * of those above. If you wish to allow use of your version of this file only
30 * under the terms of either the GPL or the LGPL, and not to allow others to
31 * use your version of this file under the terms of the MPL, indicate your
32 * decision by deleting the provisions above and replace them with the notice
33 * and other provisions required by the GPL or the LGPL. If you do not delete
34 * the provisions above, a recipient may use your version of this file under
35 * the terms of any one of the MPL, the GPL or the LGPL.
36 *
37 * ***** END LICENSE BLOCK ***** */
38
39 #include "nsISupports.idl"
40
41 interface nsIDOMDocument;
42 interface nsIDOMRange;
43 interface nsISelection;
44 interface nsIDOMNode;
45 interface nsIOutputStream;
46
47 [scriptable, uuid(e770c650-b3d3-11da-a94d-0800200c9a66)]
48 interface nsIDocumentEncoderNodeFixup : nsISupports
49 {
50 /**
51 * Create a fixed up version of a node. This method is called before
52 * each node in a document is about to be persisted. The implementor
53 * may return a new node with fixed up attributes or null. If null is
54 * returned the node should be used as-is.
55 * @param aNode Node to fixup.
56 * @return The resulting fixed up node.
57 */
58 nsIDOMNode fixupNode(in nsIDOMNode aNode);
59 };
60
61 [scriptable, uuid(f85c5a20-258d-11db-a98b-0800200c9a66)]
62 interface nsIDocumentEncoder : nsISupports
63 {
64 // Output methods flag bits. There are a frightening number of these,
65 // because everyone wants something a little bit different
66
67
68 /**
69 * Output only the selection (as opposed to the whole document).
70 */
71 const unsigned long OutputSelectionOnly = (1 << 0);
72
73 /** Plaintext output: Convert html to plaintext that looks like the html.
74 * Implies wrap (except inside <pre>), since html wraps.
75 * HTML output: always do prettyprinting, ignoring existing formatting.
76 * (Probably not well tested for HTML output.)
77 */
78 const unsigned long OutputFormatted = (1 << 1);
79
80 /** Don't do prettyprinting of HTML. Don't do any wrapping that's not in
81 * the existing HTML source. This option overrides OutputFormatted if both
82 * are set.
83 * @note This option does not affect entity conversion.
84 */
85 const unsigned long OutputRaw = (1 << 2);
86
87 /**
88 * Do not print html head tags.
89 */
90 const unsigned long OutputBodyOnly = (1 << 3);
91
92 /**
93 * Wrap even if we're not doing formatted output (e.g. for text fields)
94 * XXXbz this doesn't seem to be used by all serializers... document? How
95 * does this interact with
96 * OutputFormatted/OutputRaw/OutputWrap/OutputFormatFlowed?
97 */
98 const unsigned long OutputPreformatted = (1 << 4);
99
100 /**
101 * Output as though the content is preformatted
102 * (e.g. maybe it's wrapped in a MOZ_PRE or MOZ_PRE_WRAP style tag)
103 * XXXbz this doesn't seem to be used by all serializers... document? How
104 * does this interact with
105 * OutputFormatted/OutputRaw/OutputPreformatted/OutputFormatFlowed?
106 */
107 const unsigned long OutputWrap = (1 << 5);
108
109 /**
110 * Output for format flowed (RFC 2646). This is used when converting
111 * to text for mail sending. This differs just slightly
112 * but in an important way from normal formatted, and that is that
113 * lines are space stuffed. This can't (correctly) be done later.
114 * XXXbz this doesn't seem to be used by all serializers... document? How
115 * does this interact with
116 * OutputFormatted/OutputRaw/OutputPreformatted/OutputWrap?
117 */
118 const unsigned long OutputFormatFlowed = (1 << 6);
119
120 /**
121 * Convert links, image src, and script src to absolute URLs when possible
122 */
123 const unsigned long OutputAbsoluteLinks = (1 << 7);
124
125 /**
126 * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
127 * This is a catch-all flag for documents with mixed contents. Beware of
128 * interoperability issues. See below for other flags which might likely
129 * do what you want.
130 */
131 const unsigned long OutputEncodeW3CEntities = (1 << 8);
132
133 /**
134 * LineBreak processing: if this flag is set than CR line breaks will
135 * be written. If neither this nor OutputLFLineBreak is set, then we
136 * will use platform line breaks. The combination of the two flags will
137 * cause CRLF line breaks to be written.
138 */
139 const unsigned long OutputCRLineBreak = (1 << 9);
140
141 /**
142 * LineBreak processing: if this flag is set than LF line breaks will
143 * be written. If neither this nor OutputCRLineBreak is set, then we
144 * will use platform line breaks. The combination of the two flags will
145 * cause CRLF line breaks to be written.
146 */
147 const unsigned long OutputLFLineBreak = (1 << 10);
148
149 /**
150 * Output the content of noscript elements (only for serializing
151 * to plaintext).
152 */
153 const unsigned long OutputNoScriptContent = (1 << 11);
154
155 /**
156 * Output the content of noframes elements (only for serializing
157 * to plaintext).
158 */
159 const unsigned long OutputNoFramesContent = (1 << 12);
160
161 /**
162 * Don't allow any formatting nodes (e.g. <br>, <b>) inside a <pre>.
163 * This is used primarily by mail.
164 */
165 const unsigned long OutputNoFormattingInPre = (1 << 13);
166
167 /**
168 * Encode entities when outputting to a string.
169 * E.g. If set, we'll output if clear, we'll output 0xa0.
170 * The basic set is just & < > " for interoperability
171 * with older products that don't support α and friends.
172 */
173 const unsigned long OutputEncodeBasicEntities = (1 << 14);
174
175 /**
176 * Encode entities when outputting to a string.
177 * The Latin1 entity set additionally includes 8bit accented letters
178 * between 128 and 255.
179 */
180 const unsigned long OutputEncodeLatin1Entities = (1 << 15);
181
182 /**
183 * Encode entities when outputting to a string.
184 * The HTML entity set additionally includes accented letters, greek
185 * letters, and other special markup symbols as defined in HTML4.
186 */
187 const unsigned long OutputEncodeHTMLEntities = (1 << 16);
188
189 /**
190 * Normally is replaced with a space character when
191 * encoding data as plain text, set this flag if that's
192 * not desired.
193 */
194 const unsigned long OutputPersistNBSP = (1 << 17);
195
196 /**
197 * Initialize with a pointer to the document and the mime type.
198 * @param aDocument Document to encode.
199 * @param aMimeType MimeType to use. May also be set by SetMimeType.
200 * @param aFlags Flags to use while encoding. May also be set by SetFlags.
201 */
202 void init(in nsIDOMDocument aDocument,
203 in AString aMimeType,
204 in unsigned long aFlags);
205
206 /**
207 * If the selection is set to a non-null value, then the
208 * selection is used for encoding, otherwise the entire
209 * document is encoded.
210 * @param aSelection The selection to encode.
211 */
212 void setSelection(in nsISelection aSelection);
213
214 /**
215 * If the range is set to a non-null value, then the
216 * range is used for encoding, otherwise the entire
217 * document or selection is encoded.
218 * @param aRange The range to encode.
219 */
220 void setRange(in nsIDOMRange aRange);
221
222 /**
223 * If the node is set to a non-null value, then the
224 * node is used for encoding, otherwise the entire
225 * document or range or selection is encoded.
226 * @param aNode The node to encode.
227 */
228 void setNode(in nsIDOMNode aNode);
229
230 /**
231 * If the container is set to a non-null value, then its
232 * child nodes are used for encoding, otherwise the entire
233 * document or range or selection or node is encoded.
234 * @param aContainer The node which child nodes will be encoded.
235 */
236 void setContainerNode(in nsIDOMNode aContainer);
237
238 /**
239 * Documents typically have an intrinsic character set,
240 * but if no intrinsic value is found, the platform character set
241 * is used. This function overrides both the intrinisc and platform
242 * charset.
243 * @param aCharset Overrides the both the intrinsic or platform
244 * character set when encoding the document.
245 *
246 * Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER
247 */
248 void setCharset(in ACString aCharset);
249
250 /**
251 * Set a wrap column. This may have no effect in some types of encoders.
252 * @param aWrapColumn Column to which to wrap.
253 */
254 void setWrapColumn(in unsigned long aWrapColumn);
255
256 /**
257 * The mime type preferred by the encoder. This piece of api was
258 * added because the copy encoder may need to switch mime types on you
259 * if you ask it to copy html that really represents plaintext content.
260 * Call this AFTER Init() and SetSelection() have both been called.
261 */
262 readonly attribute AString mimeType;
263
264 /**
265 * Encode the document and send the result to the nsIOutputStream.
266 *
267 * Possible result codes are the stream errors which might have
268 * been encountered.
269 * @param aStream Stream into which to encode.
270 */
271 void encodeToStream(in nsIOutputStream aStream);
272
273 /**
274 * Encode the document into a string.
275 *
276 * @return The document encoded into a string.
277 */
278 AString encodeToString();
279
280 /**
281 * Encode the document into a string. Stores the extra context information
282 * into the two arguments.
283 * @param [OUT] aContextString The string where the parent heirarchy
284 * information will be stored.
285 * @param [OUT] aInfoString The string where extra context info will
286 * be stored.
287 * @return The document encoded as a string.
288 *
289 */
290 AString encodeToStringWithContext( out AString aContextString,
291 out AString aInfoString);
292
293 /**
294 * Set the fixup object associated with node persistence.
295 * @param aFixup The fixup object.
296 */
297 void setNodeFixup(in nsIDocumentEncoderNodeFixup aFixup);
298 };