diff options
Diffstat (limited to 'dom/serializers/nsIDocumentEncoder.idl')
| -rw-r--r-- | dom/serializers/nsIDocumentEncoder.idl | 361 |
1 files changed, 361 insertions, 0 deletions
diff --git a/dom/serializers/nsIDocumentEncoder.idl b/dom/serializers/nsIDocumentEncoder.idl new file mode 100644 index 0000000000..d909c3989a --- /dev/null +++ b/dom/serializers/nsIDocumentEncoder.idl @@ -0,0 +1,361 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" + +interface nsIOutputStream; + +webidl Document; +webidl Node; +webidl Range; +webidl Selection; + +%{ C++ +class nsINode; + +%} +[ptr] native nsINodePtr(nsINode); + +[scriptable, uuid(3d9371d8-a2ad-403e-8b0e-8885ad3562e3)] +interface nsIDocumentEncoderNodeFixup : nsISupports +{ + /** + * Create a fixed up version of a node. This method is called before + * each node in a document is about to be persisted. The implementor + * may return a new node with fixed up attributes or null. If null is + * returned the node should be used as-is. + * @param aNode Node to fixup. + * @param [OUT] aSerializeCloneKids True if the document encoder should + * apply recursive serialization to the children of the fixed up node + * instead of the children of the original node. + * @return The resulting fixed up node. + */ + Node fixupNode(in Node aNode, out boolean aSerializeCloneKids); +}; + +[scriptable, uuid(21f112df-d96f-47da-bfcb-5331273003d1)] +interface nsIDocumentEncoder : nsISupports +{ + // Output methods flag bits. There are a frightening number of these, + // because everyone wants something a little bit different + + + /** + * Output only the selection (as opposed to the whole document). + */ + const unsigned long OutputSelectionOnly = (1 << 0); + + /** + * Plaintext output: + * - Convert html to plaintext that looks like the html. + * - Can't be used in conjunction with `OutputPreformatted`. + * - Implies wrap (except inside <pre>), since html wraps. + * HTML and XHTML output: + * - Do prettyprinting, ignoring existing formatting. + * - Implies wrap (except in attribute values and inside <pre>). + * XML output: + * - Do prettyprinting, ignoring existing formatting. + * - Doesn't implicitly wrap + */ + const unsigned long OutputFormatted = (1 << 1); + + /** Don't do prettyprinting. Don't do any wrapping that's not in the existing + * HTML/XML source. This option overrides OutputFormatted if both are set. + * HTML/XHTML output: If neither are set, there won't be prettyprinting too, but + * long lines will be wrapped. + * Supported also in XML and Plaintext output. + * @note This option does not affect entity conversion. + */ + const unsigned long OutputRaw = (1 << 2); + + /** + * Do not print html head tags. + * XHTML/HTML output only. + */ + const unsigned long OutputBodyOnly = (1 << 3); + + /** + * Output as though the content is preformatted + * (e.g. maybe it's wrapped in a PRE or PRE_WRAP style tag) + * Plaintext output only. + * Can't be used together with `OutputFormatted`/`OutputFormatFlowed`. + * XXXbz How does this interact with OutputRaw? + */ + const unsigned long OutputPreformatted = (1 << 4); + + /** + * Wrap even if we're not doing formatted output (e.g. for text fields). + * Supported in XML, XHTML, HTML and Plaintext output. + * Set implicitly in HTML/XHTML output when no OutputRaw. + * Ignored when OutputRaw. + * For XML, XHTML and HTML: does not wrap values in attributes. + * XXXLJ: set implicitly in HTML/XHTML output, to keep compatible behaviors + * for old callers of this interface + * XXXbz How does this interact with OutputFormatFlowed? + */ + const unsigned long OutputWrap = (1 << 5); + + /** + * Output for format flowed (RFC 2646). This is used when converting + * to text for mail sending. This differs just slightly + * but in an important way from normal formatted, and that is that + * lines are space stuffed. This can't (correctly) be done later. + * PlainText output only. + * If this flag is set, `OutputFormat` has to be set too. + * XXXbz How does this interact with OutputRaw/OutputWrap? + */ + const unsigned long OutputFormatFlowed = (1 << 6); + + /** + * Convert links, image src, and script src to absolute URLs when possible. + * XHTML/HTML output only. + */ + const unsigned long OutputAbsoluteLinks = (1 << 7); + + /** + * LineBreak processing: if this flag is set than CR line breaks will + * be written. If neither this nor OutputLFLineBreak is set, then we + * will use platform line breaks. The combination of the two flags will + * cause CRLF line breaks to be written. + */ + const unsigned long OutputCRLineBreak = (1 << 9); + + /** + * LineBreak processing: if this flag is set than LF line breaks will + * be written. If neither this nor OutputCRLineBreak is set, then we + * will use platform line breaks. The combination of the two flags will + * cause CRLF line breaks to be written. + */ + const unsigned long OutputLFLineBreak = (1 << 10); + + /** + * Output the content of noscript elements (only for serializing + * to plaintext). + */ + const unsigned long OutputNoScriptContent = (1 << 11); + + /** + * Output the content of noframes elements (only for serializing + * to plaintext). (Used only internally in the plain text serializer; + * ignored if passed by the caller.) + */ + const unsigned long OutputNoFramesContent = (1 << 12); + + /** + * Don't allow any formatting nodes (e.g. <br>, <b>) inside a <pre>. + * This is used primarily by mail. XHTML/HTML output only. + */ + const unsigned long OutputNoFormattingInPre = (1 << 13); + + /** + * Encode entities when outputting to a string. + * E.g. If set, we'll output if clear, we'll output 0xa0. + * The basic set is just & < > " for interoperability + * with older products that don't support α and friends. + * HTML output only. + */ + const unsigned long OutputEncodeBasicEntities = (1 << 14); + + /** + * Normally is replaced with a space character when + * encoding data as plain text, set this flag if that's + * not desired. + * Plaintext output only. + */ + const unsigned long OutputPersistNBSP = (1 << 17); + + /** + * Normally when serializing the whole document using the HTML or + * XHTML serializer, the encoding declaration is rewritten to match. + * This flag suppresses that behavior. + */ + const unsigned long OutputDontRewriteEncodingDeclaration = (1 << 18); + + /** + * When using the HTML or XHTML serializer, skip elements that are not + * visible when this flag is set. Elements are not visible when they + * have CSS style display:none or visibility:collapse, for example. + */ + const unsigned long SkipInvisibleContent = (1 << 19); + + /** + * Output for delsp=yes (RFC 3676). This is used with OutputFormatFlowed + * when converting to text for mail sending. + * PlainText output only. + */ + const unsigned long OutputFormatDelSp = (1 << 20); + + /** + * Drop <br> elements considered "invisible" by the editor. OutputPreformatted + * implies this flag. + */ + const unsigned long OutputDropInvisibleBreak = (1 << 21); + + /** + * Don't check for _moz_dirty attributes when deciding whether to + * pretty-print if this flag is set (bug 599983). + */ + const unsigned long OutputIgnoreMozDirty = (1 << 22); + + /** + * Serialize in a way that is suitable for copying a plaintext version of the + * document to the clipboard. This can for example cause line endings to be + * injected at preformatted block element boundaries. + */ + const unsigned long OutputForPlainTextClipboardCopy = (1 << 25); + + /** + * Include ruby annotations and ruby parentheses in the output. + * PlainText output only. + */ + const unsigned long OutputRubyAnnotation = (1 << 26); + + /** + * Disallow breaking of long character strings. This is important + * for serializing e-mail which contains CJK strings. These must + * not be broken just as "normal" longs strings aren't broken. + */ + const unsigned long OutputDisallowLineBreaking = (1 << 27); + + /** + * Release reference of Document after using encodeTo* method to recycle + * this encoder without holding Document. To use this encoder again, + * we have to call init again. + */ + const unsigned long RequiresReinitAfterOutput = (1 << 28); + + /** + * Initialize with a pointer to the document and the mime type. + * Resets wrap column to 72 and resets node fixup. + * @param aDocument Document to encode. + * @param aMimeType MimeType to use. May also be set by SetMimeType. + * @param aFlags Flags to use while encoding. May also be set by SetFlags. + */ + void init(in Document aDocument, + in AString aMimeType, + in unsigned long aFlags); + [noscript] void nativeInit(in Document aDocument, + in AString aMimeType, + in unsigned long aFlags); + + /** + * If the selection is set to a non-null value, then the + * selection is used for encoding, otherwise the entire + * document is encoded. + * @param aSelection The selection to encode. + */ + void setSelection(in Selection aSelection); + + /** + * If the range is set to a non-null value, then the + * range is used for encoding, otherwise the entire + * document or selection is encoded. + * @param aRange The range to encode. + */ + void setRange(in Range aRange); + + /** + * If the node is set to a non-null value, then the + * node is used for encoding, otherwise the entire + * document or range or selection is encoded. + * @param aNode The node to encode. + */ + void setNode(in Node aNode); + + /** + * If the container is set to a non-null value, then its + * child nodes are used for encoding, otherwise the entire + * document or range or selection or node is encoded. + * @param aContainer The node which child nodes will be encoded. + */ + void setContainerNode(in Node aContainer); + + /** + * Documents typically have an intrinsic character set, + * but if no intrinsic value is found, the platform character set + * is used. This function overrides both the intrinisc and platform + * charset. + * @param aCharset Overrides the both the intrinsic or platform + * character set when encoding the document. + * + * Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER + */ + void setCharset(in ACString aCharset); + + /** + * Set a wrap column. This may have no effect in some types of encoders. + * @param aWrapColumn Column to which to wrap. If 0, wrapping is disabled. + */ + void setWrapColumn(in unsigned long aWrapColumn); + + /** + * The mime type preferred by the encoder. This piece of api was + * added because the copy encoder may need to switch mime types on you + * if you ask it to copy html that really represents plaintext content. + * Call this AFTER Init() and SetSelection() have both been called. + */ + readonly attribute AString mimeType; + + /** + * Encode the document and send the result to the nsIOutputStream. + * + * Possible result codes are the stream errors which might have + * been encountered. + * @param aStream Stream into which to encode. + */ + void encodeToStream(in nsIOutputStream aStream); + + /** + * Encode the document into a string. + * + * @return The document encoded into a string. + */ + AString encodeToString(); + + /** + * Encode the document into a string. Stores the extra context information + * into the two arguments. + * @param [OUT] aContextString The string where the parent hierarchy + * information will be stored. + * @param [OUT] aInfoString The string where extra context info will + * be stored. + * @return The document encoded as a string. + * + */ + AString encodeToStringWithContext( out AString aContextString, + out AString aInfoString); + + /** + * Encode the document into a string of limited size. + * @param aMaxLength After aMaxLength characters, the encoder will stop + * encoding new data. + * Only values > 0 will be considered. + * The returned string may be slightly larger than + * aMaxLength because some serializers (eg. HTML) + * may need to close some tags after they stop + * encoding new data, or finish a line (72 columns + * by default for the plain text serializer). + * + * @return The document encoded into a string. + */ + AString encodeToStringWithMaxLength(in unsigned long aMaxLength); + + /** + * Set the fixup object associated with node persistence. + * @param aFixup The fixup object. + */ + void setNodeFixup(in nsIDocumentEncoderNodeFixup aFixup); +}; + +%{ C++ +template<class T> struct already_AddRefed; + +bool +do_getDocumentTypeSupportedForEncoding(const char* aContentType); +already_AddRefed<nsIDocumentEncoder> +do_createDocumentEncoder(const char* aContentType); +already_AddRefed<nsIDocumentEncoder> +do_createHTMLCopyEncoder(); +%} |