michael@0: /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: /**
michael@0:   Description: Currently only functions to enhance plain text with HTML tags.
michael@0:   <p>
michael@0:   Wrapper class for various parsing routines, that convert plain text to HTML.
michael@0:   They try to recognize cites, URLs, plain text formattting like *bold* etc.
michael@0:   See <http://www.bucksch.org/1/projects/mozilla/16507/> for a description.
michael@0:  */
michael@0: 
michael@0: #include "nsIStreamConverter.idl"
michael@0: 
michael@0: %{C++
michael@0: // {77c0e42a-1dd2-11b2-8ebf-edc6606f2f4b}
michael@0: #define MOZITXTTOHTMLCONV_CID \
michael@0:     { 0x77c0e42a, 0x1dd2, 0x11b2, \
michael@0:     { 0x8e, 0xbf, 0xed, 0xc6, 0x60, 0x6f, 0x2f, 0x4b } }
michael@0: 	
michael@0: #define MOZ_TXTTOHTMLCONV_CONTRACTID \
michael@0:   "@mozilla.org/txttohtmlconv;1"
michael@0: 
michael@0: %}
michael@0: 
michael@0: [scriptable, uuid(77c0e42a-1dd2-11b2-8ebf-edc6606f2f4b)]
michael@0: interface mozITXTToHTMLConv : nsIStreamConverter {
michael@0:   const unsigned long kEntities = 0;  // just convert < & > to &lt; &amp; and &gt;
michael@0:   const unsigned long kURLs = 1 << 1;
michael@0:   const unsigned long kGlyphSubstitution = 1 << 2;  // Smilies, &reg; etc.
michael@0:   const unsigned long kStructPhrase = 1 << 3;       // E.g. *bold* -> <strong>
michael@0: 
michael@0: /**
michael@0:   @param text: plain text to scan. May be a line, paragraph (recommended)
michael@0:                or just a substring.<p>
michael@0:                Must be non-escaped, pure unicode.<p>
michael@0:                <em>Note:</em> ScanTXT(a, o) + ScanTXT(b, o) may be !=
michael@0:                Scan(a + b, o)
michael@0:   @param whattodo: Bitfield describing the modes of operation
michael@0:   @result      "<", ">" and "&" are escaped and HTML tags are inserted where
michael@0:                appropriate.
michael@0:  */
michael@0:   wstring   scanTXT(in wstring text, in unsigned long whattodo);
michael@0: 
michael@0: /**
michael@0:   Adds additional formatting to user edited text, that the user was too lazy
michael@0:   or "unknowledged" (DELETEME: is that a word?) to make.
michael@0:   <p>
michael@0:   <em>Note:</em> Don't use kGlyphSubstitution with this function. This option
michael@0:   generates tags, that are unuseable for UAs other than Mozilla. This would
michael@0:   be a data loss bug.
michael@0: 
michael@0:   @param text: HTML source to scan. May be a line, paragraph (recommended)
michael@0:                or just a substring.<p>
michael@0:                Must be correct HTML. "<", ">" and "&" must be escaped,
michael@0:                other chars must be pure unicode.<p>
michael@0:                <em>Note:</em> ScanTXT(a, o) + ScanTXT(b, o) may be !=
michael@0:                Scan(a + b, o)
michael@0:   @param whattodo: Bitfield describing the modes of operation
michael@0:   @result      Additional HTML tags are inserted where appropriate.
michael@0:  */
michael@0:   wstring   scanHTML(in wstring text, in unsigned long whattodo);
michael@0: 
michael@0: /**
michael@0:   @param line: line in original msg, possibly starting starting with
michael@0:                txt quote tags like ">"
michael@0:   @param logLineStart: pos in line, where the real content (logical line)
michael@0:                begins, i.e. pos after all txt quote tags.
michael@0:                E.g. position of "t" in "> > text".
michael@0:                Initial value must be 0, unless line is not real line.
michael@0:   @return      Cite Level, i.e. number of txt quote tags found, i.e. number of
michael@0:                nested quotes.
michael@0:  */
michael@0:   unsigned long   citeLevelTXT(in wstring line,
michael@0:                                out unsigned long logLineStart);
michael@0: 
michael@0: /** 
michael@0:  @param a wide string to scan for the presence of a URL.
michael@0:  @param aLength --> the length of the buffer to be scanned
michael@0:  @param aPos --> the position in the buffer to start scanning for a url
michael@0: 
michael@0:  aStartPos --> index into the start of a url (-1 if no url found)
michael@0:  aEndPos --> index of the last character in the url (-1 if no url found)
michael@0:  */
michael@0: 
michael@0:   void findURLInPlaintext(in wstring text, in long aLength, in long aPos, out long aStartPos, out long aEndPos);
michael@0: };