netwerk/streamconv/public/mozITXTToHTMLConv.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 the Mozilla Text to HTML converter code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Ben Bucksch <http://www.bucksch.org>.
  19  * Portions created by the Initial Developer are Copyright (C) 1999, 2000
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /**
  39   Description: Currently only functions to enhance plain text with HTML tags.
  40   <p>
  41   Wrapper class for various parsing routines, that convert plain text to HTML.
  42   They try to recognize cites, URLs, plain text formattting like *bold* etc.
  43   See <http://www.bucksch.org/1/projects/mozilla/16507/> for a description.
  44  */
  45
  46 #include "nsIStreamConverter.idl"
  47 #include "nsrootidl.idl"
  48
  49 %{C++
  50 // {77c0e42a-1dd2-11b2-8ebf-edc6606f2f4b}
  51 #define MOZITXTTOHTMLCONV_CID \
  52     { 0x77c0e42a, 0x1dd2, 0x11b2, \
  53     { 0x8e, 0xbf, 0xed, 0xc6, 0x60, 0x6f, 0x2f, 0x4b } }
  54
  55 #define MOZ_TXTTOHTMLCONV_CONTRACTID \
  56   "@mozilla.org/txttohtmlconv;1"
  57
  58 %}
  59
  60 [scriptable, uuid(77c0e42a-1dd2-11b2-8ebf-edc6606f2f4b)]
  61 interface mozITXTToHTMLConv : nsIStreamConverter {
  62   const unsigned long kEntities = 0;  // just convert < & > to &lt; &amp; and &gt;
  63   const unsigned long kURLs = 1 << 1;
  64   const unsigned long kGlyphSubstitution = 1 << 2;  // Smilies, &reg; etc.
  65   const unsigned long kStructPhrase = 1 << 3;       // E.g. *bold* -> <strong>
  66
  67 /**
  68   @param text: plain text to scan. May be a line, paragraph (recommended)
  69                or just a substring.<p>
  70                Must be non-escaped, pure unicode.<p>
  71                <em>Note:</em> ScanTXT(a, o) + ScanTXT(b, o) may be !=
  72                Scan(a + b, o)
  73   @param whattodo: Bitfield describing the modes of operation
  74   @result      "<", ">" and "&" are escaped and HTML tags are inserted where
  75                appropriate.
  76  */
  77   wstring   scanTXT(in wstring text, in unsigned long whattodo);
  78
  79 /**
  80   Adds additional formatting to user edited text, that the user was too lazy
  81   or "unknowledged" (DELETEME: is that a word?) to make.
  82   <p>
  83   <em>Note:</em> Don't use kGlyphSubstitution with this function. This option
  84   generates tags, that are unuseable for UAs other than Mozilla. This would
  85   be a data loss bug.
  86
  87   @param text: HTML source to scan. May be a line, paragraph (recommended)
  88                or just a substring.<p>
  89                Must be correct HTML. "<", ">" and "&" must be escaped,
  90                other chars must be pure unicode.<p>
  91                <em>Note:</em> ScanTXT(a, o) + ScanTXT(b, o) may be !=
  92                Scan(a + b, o)
  93   @param whattodo: Bitfield describing the modes of operation
  94   @result      Additional HTML tags are inserted where appropriate.
  95  */
  96   wstring   scanHTML(in wstring text, in unsigned long whattodo);
  97
  98 /**
  99   @param line: line in original msg, possibly starting starting with
 100                txt quote tags like ">"
 101   @param logLineStart: pos in line, where the real content (logical line)
 102                begins, i.e. pos after all txt quote tags.
 103                E.g. position of "t" in "> > text".
 104                Initial value must be 0, unless line is not real line.
 105   @return      Cite Level, i.e. number of txt quote tags found, i.e. number of
 106                nested quotes.
 107  */
 108   unsigned long   citeLevelTXT(in wstring line,
 109                                out unsigned long logLineStart);
 110
 111 /**
 112  @param a wide string to scan for the presence of a URL.
 113  @param aLength --> the length of the buffer to be scanned
 114  @param aPos --> the position in the buffer to start scanning for a url
 115
 116  aStartPos --> index into the start of a url (-1 if no url found)
 117  aEndPos --> index of the last character in the url (-1 if no url found)
 118  */
 119
 120   void findURLInPlaintext(in wstring text, in long aLength, in long aPos, out long aStartPos, out long aEndPos);
 121 };