added interface headers with latest discussed changes

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
2008-03-08 13:52:38 +00:00
parent 5d713a7574
commit 23324ae1c7
272 changed files with 92200 additions and 9 deletions
--- a/interface/encconv.h
+++ b/interface/encconv.h
@@ -0,0 +1,129 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        encconv.h
+// Purpose:     documentation for wxEncodingConverter class
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    @class wxEncodingConverter
+    @wxheader{encconv.h}
+    
+    This class is capable of converting strings between two
+    8-bit encodings/charsets. It can also convert from/to Unicode (but only
+    if you compiled wxWidgets with wxUSE_WCHAR_T set to 1). Only a limited subset
+    of encodings is supported by wxEncodingConverter:
+    @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and 
+    @c wxFONTENCODING_KOI8.
+    
+    @library{wxbase}
+    @category{misc}
+    
+    @seealso
+    wxFontMapper, wxMBConv, @ref overview_nonenglishoverview "Writing non-English
+    applications"
+*/
+class wxEncodingConverter : public wxObject
+{
+public:
+    /**
+        Constructor.
+    */
+    wxEncodingConverter();
+
+    /**
+        Return @true if (any text in) multibyte encoding @e encIn can be converted to
+        another one (@e encOut) losslessly.
+        
+        Do not call this method with @c wxFONTENCODING_UNICODE as either
+        parameter, it doesn't make sense (always works in one sense and always depends
+        on the text to convert in the other).
+    */
+    static bool CanConvert(wxFontEncoding encIn,
+                           wxFontEncoding encOut);
+
+    //@{
+    /**
+        Convert wxString and return new wxString object.
+    */
+    bool Convert(const char* input, char* output);
+        bool Convert(const wchar_t* input, wchar_t* output);
+        bool Convert(const char* input, wchar_t* output);
+        bool Convert(const wchar_t* input, char* output);
+        bool Convert(char* str);
+        bool Convert(wchar_t* str);
+        wxString Convert(const wxString& input);
+    //@}
+
+    /**
+        Similar to 
+        GetPlatformEquivalents(), 
+        but this one will return ALL 
+        equivalent encodings, regardless of the platform, and including itself.
+        
+        This platform's encodings are before others in the array. And again, if @e enc
+        is in the array,
+        it is the very first item in it.
+    */
+    static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc);
+
+    /**
+        Return equivalents for given font that are used
+        under given platform. Supported platforms:
+        
+         wxPLATFORM_UNIX
+         wxPLATFORM_WINDOWS
+         wxPLATFORM_OS2
+         wxPLATFORM_MAC
+         wxPLATFORM_CURRENT
+        
+        wxPLATFORM_CURRENT means the platform this binary was compiled for.
+        
+        Examples:
+        Equivalence is defined in terms of convertibility:
+        two encodings are equivalent if you can convert text between
+        then without losing information (it may - and will - happen
+        that you lose special chars like quotation marks or em-dashes
+        but you shouldn't lose any diacritics and language-specific
+        characters when converting between equivalent encodings).
+        
+        Remember that this function does @b NOT check for presence of
+        fonts in system. It only tells you what are most suitable
+        encodings. (It usually returns only one encoding.)
+    */
+    static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc,
+                                                      int platform = wxPLATFORM_CURRENT);
+
+    /**
+        Initialize conversion. Both output or input encoding may
+        be wxFONTENCODING_UNICODE, but only if wxUSE_ENCODING is set to 1.
+        All subsequent calls to Convert() 
+        will interpret its argument
+        as a string in @e input_enc encoding and will output string in 
+        @e output_enc encoding.
+        You must call this method before calling Convert. You may call 
+        it more than once in order to switch to another conversion.
+        @e Method affects behaviour of Convert() in case input character
+        cannot be converted because it does not exist in output encoding:
+        
+        @b wxCONVERT_STRICT
+        
+        
+        follow behaviour of GNU Recode -
+        just copy unconvertible  characters to output and don't change them 
+        (its integer value will stay the same)
+        
+        @b wxCONVERT_SUBSTITUTE
+        
+        
+        try some (lossy) substitutions 
+        - e.g. replace unconvertible latin capitals with acute by ordinary
+        capitals, replace en-dash or em-dash by '-' etc.
+        
+        Both modes guarantee that output string will have same length
+        as input string.
+    */
+    bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc,
+              int method = wxCONVERT_STRICT);
+};