1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/base/public/nsIDocumentEncoder.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,352 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIDOMDocument;
1.12 +interface nsIDOMRange;
1.13 +interface nsISelection;
1.14 +interface nsIDOMNode;
1.15 +interface nsIOutputStream;
1.16 +
1.17 +%{ C++
1.18 +class nsINode;
1.19 +class nsIDocument;
1.20 +%}
1.21 +[ptr] native nsINodePtr(nsINode);
1.22 +[ptr] native nsIDocumentPtr(nsIDocument);
1.23 +
1.24 +[scriptable, uuid(3d9371d8-a2ad-403e-8b0e-8885ad3562e3)]
1.25 +interface nsIDocumentEncoderNodeFixup : nsISupports
1.26 +{
1.27 + /**
1.28 + * Create a fixed up version of a node. This method is called before
1.29 + * each node in a document is about to be persisted. The implementor
1.30 + * may return a new node with fixed up attributes or null. If null is
1.31 + * returned the node should be used as-is.
1.32 + * @param aNode Node to fixup.
1.33 + * @param [OUT] aSerializeCloneKids True if the document encoder should
1.34 + * apply recursive serialization to the children of the fixed up node
1.35 + * instead of the children of the original node.
1.36 + * @return The resulting fixed up node.
1.37 + */
1.38 + nsIDOMNode fixupNode(in nsIDOMNode aNode, out boolean aSerializeCloneKids);
1.39 +};
1.40 +
1.41 +[scriptable, uuid(1158bd7e-a08b-4ff6-9417-6f99144cfccc)]
1.42 +interface nsIDocumentEncoder : nsISupports
1.43 +{
1.44 + // Output methods flag bits. There are a frightening number of these,
1.45 + // because everyone wants something a little bit different
1.46 +
1.47 +
1.48 + /**
1.49 + * Output only the selection (as opposed to the whole document).
1.50 + */
1.51 + const unsigned long OutputSelectionOnly = (1 << 0);
1.52 +
1.53 + /** Plaintext output: Convert html to plaintext that looks like the html.
1.54 + * Implies wrap (except inside <pre>), since html wraps.
1.55 + * HTML, XHTML and XML output: do prettyprinting, ignoring existing formatting.
1.56 + * XML output : it doesn't implicitly wrap
1.57 + */
1.58 + const unsigned long OutputFormatted = (1 << 1);
1.59 +
1.60 + /** Don't do prettyprinting. Don't do any wrapping that's not in the existing
1.61 + * HTML/XML source. This option overrides OutputFormatted if both are set.
1.62 + * HTML/XHTML output: If neither are set, there won't be prettyprinting too, but
1.63 + * long lines will be wrapped.
1.64 + * Supported also in XML and Plaintext output.
1.65 + * @note This option does not affect entity conversion.
1.66 + */
1.67 + const unsigned long OutputRaw = (1 << 2);
1.68 +
1.69 + /**
1.70 + * Do not print html head tags.
1.71 + * XHTML/HTML output only.
1.72 + */
1.73 + const unsigned long OutputBodyOnly = (1 << 3);
1.74 +
1.75 + /**
1.76 + * Output as though the content is preformatted
1.77 + * (e.g. maybe it's wrapped in a PRE or PRE_WRAP style tag)
1.78 + * Plaintext output only.
1.79 + * XXXbz How does this interact with
1.80 + * OutputFormatted/OutputRaw/OutputPreformatted/OutputFormatFlowed?
1.81 + */
1.82 + const unsigned long OutputPreformatted = (1 << 4);
1.83 +
1.84 + /**
1.85 + * Wrap even if we're not doing formatted output (e.g. for text fields).
1.86 + * Supported in XML, XHTML, HTML and Plaintext output.
1.87 + * Set implicitly in HTML/XHTML output when no OutputRaw.
1.88 + * Ignored when OutputRaw.
1.89 + * XXXLJ: set implicitly in HTML/XHTML output, to keep compatible behaviors
1.90 + * for old callers of this interface
1.91 + * XXXbz How does this interact with OutputFormatFlowed?
1.92 + */
1.93 + const unsigned long OutputWrap = (1 << 5);
1.94 +
1.95 + /**
1.96 + * Output for format flowed (RFC 2646). This is used when converting
1.97 + * to text for mail sending. This differs just slightly
1.98 + * but in an important way from normal formatted, and that is that
1.99 + * lines are space stuffed. This can't (correctly) be done later.
1.100 + * PlainText output only.
1.101 + * XXXbz How does this interact with
1.102 + * OutputFormatted/OutputRaw/OutputPreformatted/OutputWrap?
1.103 + */
1.104 + const unsigned long OutputFormatFlowed = (1 << 6);
1.105 +
1.106 + /**
1.107 + * Convert links, image src, and script src to absolute URLs when possible.
1.108 + * XHTML/HTML output only.
1.109 + */
1.110 + const unsigned long OutputAbsoluteLinks = (1 << 7);
1.111 +
1.112 + /**
1.113 + * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
1.114 + * This is a catch-all flag for documents with mixed contents. Beware of
1.115 + * interoperability issues. See below for other flags which might likely
1.116 + * do what you want.
1.117 + * HTML output only.
1.118 + */
1.119 + const unsigned long OutputEncodeW3CEntities = (1 << 8);
1.120 +
1.121 + /**
1.122 + * LineBreak processing: if this flag is set than CR line breaks will
1.123 + * be written. If neither this nor OutputLFLineBreak is set, then we
1.124 + * will use platform line breaks. The combination of the two flags will
1.125 + * cause CRLF line breaks to be written.
1.126 + */
1.127 + const unsigned long OutputCRLineBreak = (1 << 9);
1.128 +
1.129 + /**
1.130 + * LineBreak processing: if this flag is set than LF line breaks will
1.131 + * be written. If neither this nor OutputCRLineBreak is set, then we
1.132 + * will use platform line breaks. The combination of the two flags will
1.133 + * cause CRLF line breaks to be written.
1.134 + */
1.135 + const unsigned long OutputLFLineBreak = (1 << 10);
1.136 +
1.137 + /**
1.138 + * Output the content of noscript elements (only for serializing
1.139 + * to plaintext).
1.140 + */
1.141 + const unsigned long OutputNoScriptContent = (1 << 11);
1.142 +
1.143 + /**
1.144 + * Output the content of noframes elements (only for serializing
1.145 + * to plaintext). (Used only internally in the plain text serializer;
1.146 + * ignored if passed by the caller.)
1.147 + */
1.148 + const unsigned long OutputNoFramesContent = (1 << 12);
1.149 +
1.150 + /**
1.151 + * Don't allow any formatting nodes (e.g. <br>, <b>) inside a <pre>.
1.152 + * This is used primarily by mail. XHTML/HTML output only.
1.153 + */
1.154 + const unsigned long OutputNoFormattingInPre = (1 << 13);
1.155 +
1.156 + /**
1.157 + * Encode entities when outputting to a string.
1.158 + * E.g. If set, we'll output if clear, we'll output 0xa0.
1.159 + * The basic set is just & < > " for interoperability
1.160 + * with older products that don't support α and friends.
1.161 + * HTML output only.
1.162 + */
1.163 + const unsigned long OutputEncodeBasicEntities = (1 << 14);
1.164 +
1.165 + /**
1.166 + * Encode entities when outputting to a string.
1.167 + * The Latin1 entity set additionally includes 8bit accented letters
1.168 + * between 128 and 255.
1.169 + * HTML output only.
1.170 + */
1.171 + const unsigned long OutputEncodeLatin1Entities = (1 << 15);
1.172 +
1.173 + /**
1.174 + * Encode entities when outputting to a string.
1.175 + * The HTML entity set additionally includes accented letters, greek
1.176 + * letters, and other special markup symbols as defined in HTML4.
1.177 + * HTML output only.
1.178 + */
1.179 + const unsigned long OutputEncodeHTMLEntities = (1 << 16);
1.180 +
1.181 + /**
1.182 + * Normally is replaced with a space character when
1.183 + * encoding data as plain text, set this flag if that's
1.184 + * not desired.
1.185 + * Plaintext output only.
1.186 + */
1.187 + const unsigned long OutputPersistNBSP = (1 << 17);
1.188 +
1.189 + /**
1.190 + * Normally when serializing the whole document using the HTML or
1.191 + * XHTML serializer, the encoding declaration is rewritten to match.
1.192 + * This flag suppresses that behavior.
1.193 + */
1.194 + const unsigned long OutputDontRewriteEncodingDeclaration = (1 << 18);
1.195 +
1.196 + /**
1.197 + * When using the HTML or XHTML serializer, skip elements that are not
1.198 + * visible when this flag is set. Elements are not visible when they
1.199 + * have CSS style display:none or visibility:collapse, for example.
1.200 + */
1.201 + const unsigned long SkipInvisibleContent = (1 << 19);
1.202 +
1.203 + /**
1.204 + * Output for delsp=yes (RFC 3676). This is used with OutputFormatFlowed
1.205 + * when converting to text for mail sending.
1.206 + * PlainText output only.
1.207 + */
1.208 + const unsigned long OutputFormatDelSp = (1 << 20);
1.209 +
1.210 + /**
1.211 + * Drop <br> elements considered "invisible" by the editor. OutputPreformatted
1.212 + * implies this flag.
1.213 + */
1.214 + const unsigned long OutputDropInvisibleBreak = (1 << 21);
1.215 +
1.216 + /**
1.217 + * Don't check for _moz_dirty attributes when deciding whether to
1.218 + * pretty-print if this flag is set (bug 599983).
1.219 + */
1.220 + const unsigned long OutputIgnoreMozDirty = (1 << 22);
1.221 +
1.222 + /**
1.223 + * Output the content of non-text elements as the placehodler character
1.224 + * U+FFFC (OBJECT REPLACEMENT CHARACTER, only for serializing to plaintext).
1.225 + */
1.226 + const unsigned long OutputNonTextContentAsPlaceholder = (1 << 23);
1.227 +
1.228 + /**
1.229 + * Don't Strip ending spaces from a line (only for serializing to plaintext).
1.230 + */
1.231 + const unsigned long OutputDontRemoveLineEndingSpaces = (1 << 24);
1.232 +
1.233 + /**
1.234 + * Initialize with a pointer to the document and the mime type.
1.235 + * @param aDocument Document to encode.
1.236 + * @param aMimeType MimeType to use. May also be set by SetMimeType.
1.237 + * @param aFlags Flags to use while encoding. May also be set by SetFlags.
1.238 + */
1.239 + void init(in nsIDOMDocument aDocument,
1.240 + in AString aMimeType,
1.241 + in unsigned long aFlags);
1.242 + [noscript] void nativeInit(in nsIDocumentPtr aDocument,
1.243 + in AString aMimeType,
1.244 + in unsigned long aFlags);
1.245 +
1.246 + /**
1.247 + * If the selection is set to a non-null value, then the
1.248 + * selection is used for encoding, otherwise the entire
1.249 + * document is encoded.
1.250 + * @param aSelection The selection to encode.
1.251 + */
1.252 + void setSelection(in nsISelection aSelection);
1.253 +
1.254 + /**
1.255 + * If the range is set to a non-null value, then the
1.256 + * range is used for encoding, otherwise the entire
1.257 + * document or selection is encoded.
1.258 + * @param aRange The range to encode.
1.259 + */
1.260 + void setRange(in nsIDOMRange aRange);
1.261 +
1.262 + /**
1.263 + * If the node is set to a non-null value, then the
1.264 + * node is used for encoding, otherwise the entire
1.265 + * document or range or selection is encoded.
1.266 + * @param aNode The node to encode.
1.267 + */
1.268 + void setNode(in nsIDOMNode aNode);
1.269 + [noscript] void setNativeNode(in nsINodePtr aNode);
1.270 +
1.271 + /**
1.272 + * If the container is set to a non-null value, then its
1.273 + * child nodes are used for encoding, otherwise the entire
1.274 + * document or range or selection or node is encoded.
1.275 + * @param aContainer The node which child nodes will be encoded.
1.276 + */
1.277 + void setContainerNode(in nsIDOMNode aContainer);
1.278 + [noscript] void setNativeContainerNode(in nsINodePtr aContainer);
1.279 +
1.280 + /**
1.281 + * Documents typically have an intrinsic character set,
1.282 + * but if no intrinsic value is found, the platform character set
1.283 + * is used. This function overrides both the intrinisc and platform
1.284 + * charset.
1.285 + * @param aCharset Overrides the both the intrinsic or platform
1.286 + * character set when encoding the document.
1.287 + *
1.288 + * Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER
1.289 + */
1.290 + void setCharset(in ACString aCharset);
1.291 +
1.292 + /**
1.293 + * Set a wrap column. This may have no effect in some types of encoders.
1.294 + * @param aWrapColumn Column to which to wrap.
1.295 + */
1.296 + void setWrapColumn(in unsigned long aWrapColumn);
1.297 +
1.298 + /**
1.299 + * The mime type preferred by the encoder. This piece of api was
1.300 + * added because the copy encoder may need to switch mime types on you
1.301 + * if you ask it to copy html that really represents plaintext content.
1.302 + * Call this AFTER Init() and SetSelection() have both been called.
1.303 + */
1.304 + readonly attribute AString mimeType;
1.305 +
1.306 + /**
1.307 + * Encode the document and send the result to the nsIOutputStream.
1.308 + *
1.309 + * Possible result codes are the stream errors which might have
1.310 + * been encountered.
1.311 + * @param aStream Stream into which to encode.
1.312 + */
1.313 + void encodeToStream(in nsIOutputStream aStream);
1.314 +
1.315 + /**
1.316 + * Encode the document into a string.
1.317 + *
1.318 + * @return The document encoded into a string.
1.319 + */
1.320 + AString encodeToString();
1.321 +
1.322 + /**
1.323 + * Encode the document into a string. Stores the extra context information
1.324 + * into the two arguments.
1.325 + * @param [OUT] aContextString The string where the parent hierarchy
1.326 + * information will be stored.
1.327 + * @param [OUT] aInfoString The string where extra context info will
1.328 + * be stored.
1.329 + * @return The document encoded as a string.
1.330 + *
1.331 + */
1.332 + AString encodeToStringWithContext( out AString aContextString,
1.333 + out AString aInfoString);
1.334 +
1.335 + /**
1.336 + * Encode the document into a string of limited size.
1.337 + * @param aMaxLength After aMaxLength characters, the encoder will stop
1.338 + * encoding new data.
1.339 + * Only values > 0 will be considered.
1.340 + * The returned string may be slightly larger than
1.341 + * aMaxLength because some serializers (eg. HTML)
1.342 + * may need to close some tags after they stop
1.343 + * encoding new data, or finish a line (72 columns
1.344 + * by default for the plain text serializer).
1.345 + *
1.346 + * @return The document encoded into a string.
1.347 + */
1.348 + AString encodeToStringWithMaxLength(in unsigned long aMaxLength);
1.349 +
1.350 + /**
1.351 + * Set the fixup object associated with node persistence.
1.352 + * @param aFixup The fixup object.
1.353 + */
1.354 + void setNodeFixup(in nsIDocumentEncoderNodeFixup aFixup);
1.355 +};
