content/base/public/nsIDocumentEncoder.idl

   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(3c556e41-0f73-4e1d-b724-1474884fe2e3)]
  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    * @param [OUT] aSerializeCloneKids True if the document encoder should
  57    * apply recursive serialization to the children of the fixed up node
  58    * instead of the children of the original node.
  59    * @return The resulting fixed up node.
  60    */
  61   nsIDOMNode fixupNode(in nsIDOMNode aNode, out boolean aSerializeCloneKids);
  62 };
  63
  64 [scriptable, uuid(f85c5a20-258d-11db-a98b-0800200c9a66)]
  65 interface nsIDocumentEncoder : nsISupports
  66 {
  67   // Output methods flag bits. There are a frightening number of these,
  68   // because everyone wants something a little bit different
  69
  70
  71   /**
  72    * Output only the selection (as opposed to the whole document).
  73    */
  74   const unsigned long OutputSelectionOnly = (1 << 0);
  75
  76   /** Plaintext output: Convert html to plaintext that looks like the html.
  77     * Implies wrap (except inside <pre>), since html wraps.
  78     * HTML output: always do prettyprinting, ignoring existing formatting.
  79     * (Probably not well tested for HTML output.)
  80     * XML output: unsupported
  81     */
  82   const unsigned long OutputFormatted     = (1 << 1);
  83
  84   /** Don't do prettyprinting of HTML.  Don't do any wrapping that's not in
  85    * the existing HTML source.  This option overrides OutputFormatted if both
  86    * are set.
  87    * Plaintext and HTML output only.
  88    * @note This option does not affect entity conversion.
  89    */
  90   const unsigned long OutputRaw           = (1 << 2);
  91
  92   /**
  93    * Do not print html head tags.
  94    * HTML output only.
  95    */
  96   const unsigned long OutputBodyOnly      = (1 << 3);
  97
  98   /**
  99    * Wrap even if we're not doing formatted output (e.g. for text fields).
 100    * Plaintext output only.
 101    * XXXbz How does this interact with
 102    * OutputFormatted/OutputRaw/OutputWrap/OutputFormatFlowed?
 103    */
 104   const unsigned long OutputPreformatted  = (1 << 4);
 105
 106   /**
 107    * Output as though the content is preformatted
 108    * (e.g. maybe it's wrapped in a PRE or PRE_WRAP style tag)
 109    * Plaintext output only.
 110    * XXXbz How does this interact with
 111    * OutputFormatted/OutputRaw/OutputPreformatted/OutputFormatFlowed?
 112    */
 113   const unsigned long OutputWrap          = (1 << 5);
 114
 115   /**
 116    * Output for format flowed (RFC 2646). This is used when converting
 117    * to text for mail sending. This differs just slightly
 118    * but in an important way from normal formatted, and that is that
 119    * lines are space stuffed. This can't (correctly) be done later.
 120    * PlainText output only.
 121    * XXXbz How does this interact with
 122    * OutputFormatted/OutputRaw/OutputPreformatted/OutputWrap?
 123    */
 124   const unsigned long OutputFormatFlowed  = (1 << 6);
 125
 126   /**
 127    * Convert links, image src, and script src to absolute URLs when possible.
 128    * HTML output only.
 129    */
 130   const unsigned long OutputAbsoluteLinks = (1 << 7);
 131
 132   /**
 133    * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
 134    * This is a catch-all flag for documents with mixed contents. Beware of
 135    * interoperability issues. See below for other flags which might likely
 136    * do what you want.
 137    * HTML output only.
 138    */
 139   const unsigned long OutputEncodeW3CEntities = (1 << 8);
 140
 141   /**
 142    * LineBreak processing: if this flag is set than CR line breaks will
 143    * be written. If neither this nor OutputLFLineBreak 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 OutputCRLineBreak = (1 << 9);
 148
 149   /**
 150    * LineBreak processing: if this flag is set than LF line breaks will
 151    * be written. If neither this nor OutputCRLineBreak is set, then we
 152    * will use platform line breaks. The combination of the two flags will
 153    * cause CRLF line breaks to be written.
 154    */
 155   const unsigned long OutputLFLineBreak = (1 << 10);
 156
 157   /**
 158    * Output the content of noscript elements (only for serializing
 159    * to plaintext).
 160    */
 161   const unsigned long OutputNoScriptContent = (1 << 11);
 162
 163   /**
 164    * Output the content of noframes elements (only for serializing
 165    * to plaintext).
 166    */
 167   const unsigned long OutputNoFramesContent = (1 << 12);
 168
 169   /**
 170    * Don't allow any formatting nodes (e.g. <br>, <b>) inside a <pre>.
 171    * This is used primarily by mail. HTML output only.
 172    */
 173   const unsigned long OutputNoFormattingInPre = (1 << 13);
 174
 175   /**
 176    * Encode entities when outputting to a string.
 177    * E.g. If set, we'll output &nbsp; if clear, we'll output 0xa0.
 178    * The basic set is just &nbsp; &amp; &lt; &gt; &quot; for interoperability
 179    * with older products that don't support &alpha; and friends.
 180    * HTML output only.
 181    */
 182   const unsigned long OutputEncodeBasicEntities = (1 << 14);
 183
 184   /**
 185    * Encode entities when outputting to a string.
 186    * The Latin1 entity set additionally includes 8bit accented letters
 187    * between 128 and 255.
 188    * HTML output only.
 189    */
 190   const unsigned long OutputEncodeLatin1Entities = (1 << 15);
 191
 192   /**
 193    * Encode entities when outputting to a string.
 194    * The HTML entity set additionally includes accented letters, greek
 195    * letters, and other special markup symbols as defined in HTML4.
 196    * HTML output only.
 197    */
 198   const unsigned long OutputEncodeHTMLEntities = (1 << 16);
 199
 200   /**
 201    * Normally &nbsp; is replaced with a space character when
 202    * encoding data as plain text, set this flag if that's
 203    * not desired.
 204    * Plaintext output only.
 205    */
 206   const unsigned long OutputPersistNBSP = (1 << 17);
 207
 208   /**
 209    * Initialize with a pointer to the document and the mime type.
 210    * @param aDocument Document to encode.
 211    * @param aMimeType MimeType to use. May also be set by SetMimeType.
 212    * @param aFlags Flags to use while encoding. May also be set by SetFlags.
 213    */
 214   void init(in nsIDOMDocument aDocument,
 215             in AString aMimeType,
 216             in unsigned long aFlags);
 217
 218   /**
 219    *  If the selection is set to a non-null value, then the
 220    *  selection is used for encoding, otherwise the entire
 221    *  document is encoded.
 222    * @param aSelection The selection to encode.
 223    */
 224   void setSelection(in nsISelection aSelection);
 225
 226   /**
 227    *  If the range is set to a non-null value, then the
 228    *  range is used for encoding, otherwise the entire
 229    *  document or selection is encoded.
 230    * @param aRange The range to encode.
 231    */
 232   void setRange(in nsIDOMRange aRange);
 233
 234   /**
 235    *  If the node is set to a non-null value, then the
 236    *  node is used for encoding, otherwise the entire
 237    *  document or range or selection is encoded.
 238    * @param aNode The node to encode.
 239    */
 240   void setNode(in nsIDOMNode aNode);
 241
 242   /**
 243    *  If the container is set to a non-null value, then its
 244    *  child nodes are used for encoding, otherwise the entire
 245    *  document or range or selection or node is encoded.
 246    *  @param aContainer The node which child nodes will be encoded.
 247    */
 248   void setContainerNode(in nsIDOMNode aContainer);
 249
 250   /**
 251    *  Documents typically have an intrinsic character set,
 252    *  but if no intrinsic value is found, the platform character set
 253    *  is used. This function overrides both the intrinisc and platform
 254    *  charset.
 255    *  @param aCharset Overrides the both the intrinsic or platform
 256    *  character set when encoding the document.
 257    *
 258    *  Possible result codes: NS_ERROR_NO_CHARSET_CONVERTER
 259    */
 260   void setCharset(in ACString aCharset);
 261
 262   /**
 263    *  Set a wrap column.  This may have no effect in some types of encoders.
 264    * @param aWrapColumn Column to which to wrap.
 265    */
 266   void setWrapColumn(in unsigned long aWrapColumn);
 267
 268   /**
 269    *  The mime type preferred by the encoder.  This piece of api was
 270    *  added because the copy encoder may need to switch mime types on you
 271    *  if you ask it to copy html that really represents plaintext content.
 272    *  Call this AFTER Init() and SetSelection() have both been called.
 273    */
 274   readonly attribute AString mimeType;
 275
 276   /**
 277    *  Encode the document and send the result to the nsIOutputStream.
 278    *
 279    *  Possible result codes are the stream errors which might have
 280    *  been encountered.
 281    * @param aStream Stream into which to encode.
 282    */
 283   void encodeToStream(in nsIOutputStream aStream);
 284
 285   /**
 286    * Encode the document into a string.
 287    *
 288    * @return The document encoded into a string.
 289    */
 290   AString encodeToString();
 291
 292   /**
 293    * Encode the document into a string. Stores the extra context information
 294    * into the two arguments.
 295    * @param [OUT] aContextString The string where the parent heirarchy
 296    *              information will be stored.
 297    * @param [OUT] aInfoString The string where extra context info will
 298    *              be stored.
 299    * @return The document encoded as a string.
 300    *
 301    */
 302   AString encodeToStringWithContext( out AString aContextString,
 303                                      out AString aInfoString);
 304
 305   /**
 306    * Set the fixup object associated with node persistence.
 307    * @param aFixup The fixup object.
 308    */
 309   void setNodeFixup(in nsIDocumentEncoderNodeFixup aFixup);
 310 };