First attempt to document raw bitmap access

[wxWidgets.git] / interface / encconv.h

diff --git a/interface/encconv.h b/interface/encconv.h
index b72f8478178b5d41d803fc17bb8e0f4b8958d210..a7821321ced14c435c37f8cc06d602bb278edf0e 100644 (file)
--- a/interface/encconv.h
+++ b/interface/encconv.h
@@ -10,18 +10,25 @@
     @class wxEncodingConverter
     @wxheader{encconv.h}
 
     @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:
+    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.
 
     @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and
     @c wxFONTENCODING_KOI8.
 

+    @note
+
+    Please use wxMBConv classes instead if possible. wxCSConv has much better
+    support for various encodings than wxEncodingConverter.
+    wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode
+    of operation (see wxEncodingConverter::Init()).
+

     @library{wxbase}
     @category{misc}
 
     @library{wxbase}
     @category{misc}
 

-    @see wxFontMapper, wxMBConv, @ref overview_nonenglishoverview "Writing
-    non-English applications"
+    @see wxFontMapper, wxMBConv, @ref overview_nonenglish

 */
 class wxEncodingConverter : public wxObject
 {
 */
 class wxEncodingConverter : public wxObject
 {


@@ -33,88 +40,146 @@ public:
 
     /**
         Return @true if (any text in) multibyte encoding @a encIn can be converted to
 
     /**
         Return @true if (any text in) multibyte encoding @a 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
+        another one (@a 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);
 
         on the text to convert in the other).
     */
     static bool CanConvert(wxFontEncoding encIn,
                            wxFontEncoding encOut);
 

-    //@{

     /**
     /**

-        Convert wxString and return new wxString object.
+        @name Conversion functions
+
+        @{
+    */
+    /**
+        Convert input string according to settings passed to Init() and writes
+        the result to output.
+
+        All the Convert() function overloads return @true if the conversion was
+        lossless and @false if at least one of the characters couldn't be converted
+        was and replaced with '?' in the output.
+
+        Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is
+        considered a lossless operation.
+
+        @note You must call Init() before using this method!
+
+        @note wchar_t versions of the method are not available if wxWidgets was
+              compiled with @c wxUSE_WCHAR_T set to 0.

     */
     bool Convert(const char* input, char* output) const;
     */
     bool Convert(const char* input, char* output) const;

-    const bool Convert(const wchar_t* input, wchar_t* output) const;
-    const bool Convert(const char* input, wchar_t* output) const;
-    const bool Convert(const wchar_t* input, char* output) const;
-    const bool Convert(char* str) const;
-    const bool Convert(wchar_t* str) const;
-    const wxString  Convert(const wxString& input) const;
+    bool Convert(const wchar_t* input, wchar_t* output) const;
+    bool Convert(const char* input, wchar_t* output) const;
+    bool Convert(const wchar_t* input, char* output) const;
+
+    /**
+        Convert input string according to settings passed to Init() in-place,
+        i.e. write the result to the same memory area.
+
+        See the Convert(const char*,char*) const overload for more info.
+    */
+    bool Convert(char* str) const;
+    bool Convert(wchar_t* str) const;
+
+    /**
+        Convert a wxString and return a new wxString object.
+
+        See the Convert(const char*,char*) const overload for more info.
+    */
+    wxString Convert(const wxString& input) const;

     //@}
 
     //@}
 

+

     /**
     /**

-        Similar to
-        GetPlatformEquivalents(),
-        but this one will return ALL
+        Similar to GetPlatformEquivalents(), but this one will return ALL

         equivalent encodings, regardless of the platform, and including itself.
         equivalent encodings, regardless of the platform, and including itself.

-        This platform's encodings are before others in the array. And again, if @a enc
-        is in the array,
-        it is the very first item in it.
+
+        This platform's encodings are before others in the array.
+        And again, if @a enc is in the array, it is the very first item in it.

     */
     static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc);
 
     /**
     */
     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
+        Return equivalents for given font that are used under given platform.
+
+        Supported platforms:
+        @li wxPLATFORM_UNIX
+        @li wxPLATFORM_WINDOWS
+        @li wxPLATFORM_OS2
+        @li wxPLATFORM_MAC
+        @li wxPLATFORM_CURRENT
+

         wxPLATFORM_CURRENT means the platform this binary was compiled for.
         wxPLATFORM_CURRENT means the platform this binary was compiled for.

+

         Examples:
         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).
+
+        @verbatim
+        current platform   enc          returned value
+        ----------------------------------------------
+        unix            CP1250             {ISO8859_2}
+        unix         ISO8859_2             {ISO8859_2}
+        windows      ISO8859_2                {CP1250}
+        unix            CP1252  {ISO8859_1,ISO8859_15}
+        @endverbatim
+
+        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.)
         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.)

+
+        @note Note that argument enc itself may be present in the returned array,
+              so that you can, as a side-effect, detect whether the encoding is
+              native for this platform or not.
+
+        @note Convert() is not limited to converting between equivalent encodings,
+              it can convert between two arbitrary encodings.
+
+        @note If @a enc is present in the returned array, then it is always the first
+              item of it.
+
+        @note Please note that the returned array may contain no items at all.

     */
     static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc,
     */
     static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc,

-            int platform = wxPLATFORM_CURRENT);
+                                                      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
+        Initialize the 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 @a input_enc encoding and will output string in
         @a output_enc encoding.
         as a string in @a input_enc encoding and will output string in
         @a 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.
         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
+
+        @a method affects behaviour of Convert() in case input character

         cannot be converted because it does not exist in output encoding:
         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.
-        
+
+        @li @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)
+        @li @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.
         Both modes guarantee that output string will have same length
         as input string.

+
+        @return @false if given conversion is impossible, @true otherwise
+                (conversion may be impossible either if you try to convert
+                to Unicode with non-Unicode build of wxWidgets or if input
+                or output encoding is not supported).

     */
     bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc,
               int method = wxCONVERT_STRICT);
     */
     bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc,
               int method = wxCONVERT_STRICT);