diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h index a3eec23de8..a0b7457f68 100644 --- a/docs/doxygen/mainpages/topics.h +++ b/docs/doxygen/mainpages/topics.h @@ -38,7 +38,7 @@ The following is a basic categorization of them: @li @subpage overview_refcount @li @subpage overview_app @li @subpage overview_unicode -@li @subpage overview_mbconvclasses +@li @subpage overview_mbconv @li @subpage overview_i18n @li @subpage overview_nonenglish @li @subpage overview_debugging diff --git a/docs/doxygen/overviews/log.h b/docs/doxygen/overviews/log.h index 18ab6bbb9b..b02cb5ed1a 100644 --- a/docs/doxygen/overviews/log.h +++ b/docs/doxygen/overviews/log.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: log +// Name: log.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,183 +8,167 @@ /*! - @page log_overview wxLog classes overview +@page overview_log wxLog Classes Overview - Classes: #wxLog, +Classes: +@li wxLog +@li wxLogStderr +@li wxLogStream +@li wxLogTextCtrl +@li wxLogWindow +@li wxLogGui +@li wxLogNull +@li wxLogBuffer +@li wxLogChain +@li wxLogInterposer +@li wxLogInterposerTemp +@li wxStreamToTextRedirector - #wxLogStderr, +This is a general overview of logging classes provided by wxWidgets. The word +logging here has a broad sense, including all of the program output, not only +non-interactive messages. The logging facilities included in wxWidgets provide +the base wxLog class which defines the standard interface for a @e log target +as well as several standard implementations of it and a family of functions to +use with them. - #wxLogStream, +First of all, no knowledge of wxLog classes is needed to use them. For this, +you should only know about @e wxLogXXX() functions. All of them have the same +syntax as @e printf() or @e vprintf() , i.e. they take the format string as the +first argument and respectively a variable number of arguments or a variable +argument list pointer. Here are all of them: - #wxLogTextCtrl, +@li wxLogFatalError which is like wxLogError, but also terminates the program + with the exit code 3 (using @e abort() standard function). Unlike for all + the other logging functions, this function can't be overridden by a log + target. +@li wxLogError is the function to use for error messages, i.e. the messages + that must be shown to the user. The default processing is to pop up a + message box to inform the user about it. +@li wxLogWarning for warnings. They are also normally shown to the user, but + don't interrupt the program work. +@li wxLogMessage is for all normal, informational messages. They also appear in + a message box by default (but it can be changed, see below). +@li wxLogVerbose is for verbose output. Normally, it is suppressed, but might + be activated if the user wishes to know more details about the program + progress (another, but possibly confusing name for the same function is + wxLogInfo). +@li wxLogStatus is for status messages. They will go into the status bar of the + active or specified (as the first argument) wxFrame if it has one. +@li wxLogSysError is mostly used by wxWidgets itself, but might be handy for + logging errors after system call (API function) failure. It logs the + specified message text as well as the last system error code (@e errno or + ::GetLastError() depending on the platform) and the corresponding error + message. The second form of this function takes the error code explicitly + as the first argument. +@li wxLogDebug is @b the right function for debug output. It only does anything + at all in the debug mode (when the preprocessor symbol __WXDEBUG__ is + defined) and expands to nothing in release mode (otherwise). @b Tip: under + Windows, you must either run the program under debugger or use a 3rd party + program such as DebugView to actually see the debug output. + - DebugView: http://www.microsoft.com/technet/sysinternals/Miscellaneous/DebugView.mspx +@li wxLogTrace as wxLogDebug only does something in debug build. The reason for + making it a separate function from it is that usually there are a lot of + trace messages, so it might make sense to separate them from other debug + messages which would be flooded in them. Moreover, the second version of + this function takes a trace mask as the first argument which allows to + further restrict the amount of messages generated. - #wxLogWindow, +The usage of these functions should be fairly straightforward, however it may +be asked why not use the other logging facilities, such as C standard stdio +functions or C++ streams. The short answer is that they're all very good +generic mechanisms, but are not really adapted for wxWidgets, while the log +classes are. Some of advantages in using wxWidgets log functions are: - #wxLogGui, +@li @b Portability: It is a common practice to use @e printf() statements or + cout/cerr C++ streams for writing out some (debug or otherwise) + information. Although it works just fine under Unix, these messages go + strictly nowhere under Windows where the stdout of GUI programs is not + assigned to anything. Thus, you might view wxLogMessage() as a simple + substitute for @e printf(). + You can also redirect the @e wxLogXXX calls to @e cout by just writing: + @code + wxLog* logger = new wxLogStream(&cout); + wxLog::SetActiveTarget(logger); + @endcode + Finally, there is also a possibility to redirect the output sent to @e cout + to a wxTextCtrl by using the wxStreamToTextRedirector class. +@li @b Flexibility: The output of wxLog functions can be redirected or + suppressed entirely based on their importance, which is either impossible + or difficult to do with traditional methods. For example, only error + messages, or only error messages and warnings might be logged, filtering + out all informational messages. +@li @b Completeness: Usually, an error message should be presented to the user + when some operation fails. Let's take a quite simple but common case of a + file error: suppose that you're writing your data file on disk and there is + not enough space. The actual error might have been detected inside + wxWidgets code (say, in wxFile::Write), so the calling function doesn't + really know the exact reason of the failure, it only knows that the data + file couldn't be written to the disk. However, as wxWidgets uses + wxLogError() in this situation, the exact error code (and the corresponding + error message) will be given to the user together with "high level" message + about data file writing error. - #wxLogNull, +After having enumerated all the functions which are normally used to log the +messages, and why would you want to use them we now describe how all this +works. - #wxLogBuffer, +wxWidgets has the notion of a log target: it is just a class deriving +from wxLog. As such, it implements the virtual functions of the base class +which are called when a message is logged. Only one log target is @e active at +any moment, this is the one used by @e wxLogXXX() functions. The normal usage +of a log object (i.e. object of a class derived from wxLog) is to install it as +the active target with a call to @e SetActiveTarget() and it will be used +automatically by all subsequent calls to @e wxLogXXX() functions. - #wxLogChain, +To create a new log target class you only need to derive it from wxLog and +implement one (or both) of @e DoLog() and @e DoLogString() in it. The second +one is enough if you're happy with the standard wxLog message formatting +(prepending "Error:" or "Warning:", timestamping @&c) but just want to send +the messages somewhere else. The first one may be overridden to do whatever +you want but you have to distinguish between the different message types +yourself. - #wxLogInterposer, +There are some predefined classes deriving from wxLog and which might be +helpful to see how you can create a new log target class and, of course, may +also be used without any change. There are: - #wxLogInterposerTemp, +@li wxLogStderr: This class logs messages to a FILE *, using stderr by + default as its name suggests. +@li wxLogStream: This class has the same functionality as wxLogStderr, but uses + @e ostream and cerr instead of FILE * and stderr. +@li wxLogGui: This is the standard log target for wxWidgets applications (it is + used by default if you don't do anything) and provides the most reasonable + handling of all types of messages for given platform. +@li wxLogWindow: This log target provides a "log console" which collects all + messages generated by the application and also passes them to the previous + active log target. The log window frame has a menu allowing user to clear + the log, close it completely or save all messages to file. +@li wxLogBuffer: This target collects all the logged messages in an internal + buffer allowing to show them later to the user all at once. +@li wxLogNull: The last log class is quite particular: it doesn't do anything. + The objects of this class may be instantiated to (temporarily) suppress + output of @e wxLogXXX() functions. As an example, trying to open a + non-existing file will usually provoke an error message, but if for some + reasons it is unwanted, just use this construction: + @code + wxFile file; - #wxStreamToTextRedirector - This is a general overview of logging classes provided by wxWidgets. The word - logging here has a broad sense, including all of the program output, not only - non-interactive messages. The logging facilities included in wxWidgets provide - the base @e wxLog class which defines the standard interface for a @e log - target as well as several standard implementations of it and a family of - functions to use with them. - First of all, no knowledge of @e wxLog classes is needed to use them. For - this, you should only know about @e wxLogXXX() functions. All of them have - the same syntax as @e printf() or @e vprintf() , i.e. they take the - format string as the first argument and respectively a variable number of - arguments or a variable argument list pointer. Here are all of them: + // wxFile.Open() normally complains if file can't be opened, we don't want it + { + wxLogNull logNo; + if ( !file.Open("bar") ) + { + // ... process error ourselves ... + } + } // ~wxLogNull called, old log sink restored + wxLogMessage("..."); // ok + @endcode - @b wxLogFatalError which is like @e wxLogError, but also - terminates the program with the exit code 3 (using @e abort() standard - function). Unlike for all the other logging functions, this function can't be - overridden by a log target. - @b wxLogError is the function to use for error messages, i.e. the - messages that must be shown to the user. The default processing is to pop up a - message box to inform the user about it. - @b wxLogWarning for warnings - they are also normally shown to the - user, but don't interrupt the program work. - @b wxLogMessage is for all normal, informational messages. They also - appear in a message box by default (but it can be changed, see below). - @b wxLogVerbose is for verbose output. Normally, it is suppressed, but - might be activated if the user wishes to know more details about the program - progress (another, but possibly confusing name for the same function is @b wxLogInfo). - @b wxLogStatus is for status messages - they will go into the status - bar of the active or specified (as the first argument) #wxFrame if it has one. - @b wxLogSysError is mostly used by wxWidgets itself, but might be - handy for logging errors after system call (API function) failure. It logs the - specified message text as well as the last system error - code (@e errno or @e ::GetLastError() depending on the platform) and - the corresponding error message. The second form of this function takes the - error code explicitly as the first argument. - @b wxLogDebug is @b the right function for debug output. It only - does anything at all in the debug mode (when the preprocessor symbol - __WXDEBUG__ is defined) and expands to nothing in release mode (otherwise). - @b Tip: under Windows, you must either run the program under debugger or - use a 3rd party program such as #DbgView - to actually see the debug output. - @b wxLogTrace as @b wxLogDebug only does something in debug - build. The reason for making it a separate function from it is that usually - there are a lot of trace messages, so it might make sense to separate them - from other debug messages which would be flooded in them. Moreover, the second - version of this function takes a trace mask as the first argument which allows - to further restrict the amount of messages generated. - - - The usage of these functions should be fairly straightforward, however it may - be asked why not use the other logging facilities, such as C standard stdio - functions or C++ streams. The short answer is that they're all very good - generic mechanisms, but are not really adapted for wxWidgets, while the log - classes are. Some of advantages in using wxWidgets log functions are: - - - @b Portability It is a common practice to use @e printf() - statements or cout/cerr C++ streams for writing out some (debug or otherwise) - information. - Although it works just fine under Unix, these messages go strictly nowhere - under Windows where the stdout of GUI programs is not assigned to anything. - Thus, you might view @e wxLogMessage() as a simple substitute for @e printf(). - You can also redirect the @e wxLogXXX calls to @e cout by just writing: - - - @code - wxLog *logger=new wxLogStream(); - wxLog::SetActiveTarget(logger); - @endcode - - - Finally, there is also a possibility to redirect the output sent to @e cout - to a #wxTextCtrl by using the - #wxStreamToTextRedirector class. - @b Flexibility The output of wxLog functions can be redirected or - suppressed entirely based on their importance, which is either impossible or - difficult to do with traditional methods. For example, only error messages, or - only error messages and warnings might be logged, filtering out all - informational messages. - @b Completeness Usually, an error message should be presented to the user - when some operation fails. Let's take a quite simple but common case of a file - error: suppose that you're writing your data file on disk and there is not - enough space. The actual error might have been detected inside wxWidgets code - (say, in @e wxFile::Write), so the calling function doesn't really know the - exact reason of the failure, it only knows that the data file couldn't be - written to the disk. However, as wxWidgets uses @e wxLogError() in this - situation, the exact error code (and the corresponding error message) will be - given to the user together with "high level" message about data file writing - error. - - - After having enumerated all the functions which are normally used to log the - messages, and why would you want to use them we now describe how all this - works. - wxWidgets has the notion of a @e log target: it is just a class deriving - from #wxLog. As such, it implements the virtual functions of - the base class which are called when a message is logged. Only one log target - is @e active at any moment, this is the one used by @e wxLogXXX() - functions. The normal usage of a log object (i.e. object of a class derived - from wxLog) is to install it as the active target with a call to @e SetActiveTarget() and it will be used automatically by all subsequent calls - to @e wxLogXXX() functions. - To create a new log target class you only need to derive it from wxLog and - implement one (or both) of @e DoLog() and @e DoLogString() in it. The - second one is enough if you're happy with the standard wxLog message - formatting (prepending "Error:" or "Warning:", timestamping c) but just want - to send the messages somewhere else. The first one may be overridden to do - whatever you want but you have to distinguish between the different message - types yourself. - There are some predefined classes deriving from wxLog and which might be - helpful to see how you can create a new log target class and, of course, may - also be used without any change. There are: - - - @b wxLogStderr This class logs messages to a @e FILE *, using - stderr by default as its name suggests. - @b wxLogStream This class has the same functionality as wxLogStderr, - but uses @e ostream and cerr instead of @e FILE * and stderr. - @b wxLogGui This is the standard log target for wxWidgets - applications (it is used by default if you don't do anything) and provides the - most reasonable handling of all types of messages for given platform. - @b wxLogWindow This log target provides a "log console" which - collects all messages generated by the application and also passes them to the - previous active log target. The log window frame has a menu allowing user to - clear the log, close it completely or save all messages to file. - @b wxLogBuffer This target collects all the logged messages in an - internal buffer allowing to show them later to the user all at once. - @b wxLogNull The last log class is quite particular: it doesn't do - anything. The objects of this class may be instantiated to (temporarily) - suppress output of @e wxLogXXX() functions. As an example, trying to open a - non-existing file will usually provoke an error message, but if for some - reasons it is unwanted, just use this construction: - - @code - wxFile file; - - // wxFile.Open() normally complains if file can't be opened, we don't want it - { - wxLogNull logNo; - if ( !file.Open("bar") ) - ... process error ourselves ... - } // ~wxLogNull called, old log sink restored - - wxLogMessage("..."); // ok - @endcode - - - - The log targets can also be combined: for example you may wish to redirect the - messages somewhere else (for example, to a log file) but also process them as - normally. For this the #wxLogChain, #wxLogInterposer and - #wxLogInterposerTemp can be used. - - */ +The log targets can also be combined: for example you may wish to redirect the +messages somewhere else (for example, to a log file) but also process them as +normally. For this the wxLogChain, wxLogInterposer, and wxLogInterposerTemp can +be used. +*/ diff --git a/docs/doxygen/overviews/mbconvclasses.h b/docs/doxygen/overviews/mbconvclasses.h index 28d80c4792..81ac24282e 100644 --- a/docs/doxygen/overviews/mbconvclasses.h +++ b/docs/doxygen/overviews/mbconvclasses.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: mbconvclasses +// Name: mbconvclasses.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,171 +8,184 @@ /*! - @page mbconvclasses_overview wxMBConv classes overview +@page overview_mbconv wxMBConv Classes Overview - Classes: #wxMBConv, wxMBConvLibc, - #wxMBConvUTF7, #wxMBConvUTF8, - #wxCSConv, - #wxMBConvUTF16, #wxMBConvUTF32 - The wxMBConv classes in wxWidgets enable an Unicode-aware application to - easily convert between Unicode and the variety of 8-bit encoding systems still - in use. - @ref needforconversion_overview - @ref conversionandwxstring_overview - @ref mbconvclasses_overview - @ref mbconvobjects_overview - #wxCSConv - @ref convertingstrings_overview - @ref convertingbuffers_overview +Classes: wxMBConv, wxMBConvLibc, wxMBConvUTF7, wxMBConvUTF8, wxCSConv, + wxMBConvUTF16, wxMBConvUTF32 + +The wxMBConv classes in wxWidgets enable an Unicode-aware application to easily +convert between Unicode and the variety of 8-bit encoding systems still in use. + +@li @ref overview_mbconv_need +@li @ref overview_mbconv_string +@li @ref overview_mbconv_classes +@li @ref overview_mbconv_objects +@li @ref overview_mbconv_csconv +@li @ref overview_mbconv_converting +@li @ref overview_mbconv_buffers - @section needforconversion Background: The need for conversion - - As programs are becoming more and more globalized, and users exchange documents - across country boundaries as never before, applications increasingly need to - take into account all the different character sets in use around the world. It - is no longer enough to just depend on the default byte-sized character set that - computers have traditionally used. - A few years ago, a solution was proposed: the Unicode standard. Able to contain - the complete set of characters in use in one unified global coding system, - it would resolve the character set problems once and for all. - But it hasn't happened yet, and the migration towards Unicode has created new - challenges, resulting in "compatibility encodings" such as UTF-8. A large - number of systems out there still depends on the old 8-bit encodings, hampered - by the huge amounts of legacy code still widely deployed. Even sending - Unicode data from one Unicode-aware system to another may need encoding to an - 8-bit multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to - pass unhindered through any traditional transport channels. - - @section conversionandwxstring Background: The wxString class - - If you have compiled wxWidgets in Unicode mode, the wxChar type will become - identical to wchar_t rather than char, and a wxString stores wxChars. Hence, - all wxString manipulation in your application will then operate on Unicode - strings, and almost as easily as working with ordinary char strings (you - just need to remember to use the wxT() macro to encapsulate any string - literals). - But often, your environment doesn't want Unicode strings. You could be sending - data over a network, or processing a text file for some other application. You - need a way to quickly convert your easily-handled Unicode data to and from a - traditional 8-bit encoding. And this is what the wxMBConv classes do. - - @section wxmbconvclasses wxMBConv classes - - The base class for all these conversions is the wxMBConv class (which itself - implements standard libc locale conversion). Derived classes include - wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, which - implement different kinds of conversions. You can also derive your own class - for your own custom encoding and use it, should you need it. All you need to do - is override the MB2WC and WC2MB methods. - - @section wxmbconvobjects wxMBConv objects - - Several of the wxWidgets-provided wxMBConv classes have predefined instances - (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use - these predefined objects directly, or you can instantiate your own objects. - A variable, wxConvCurrent, points to the conversion object that the user - interface is supposed to use, in the case that the user interface is not - Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or - wxConvLocal, depending on which works best on the current platform. - - @section wxcsconvclass wxCSConv - - The wxCSConv class is special because when it is instantiated, you can tell it - which character set it should use, which makes it meaningful to keep many - instances of them around, each with a different character set (or you can - create a wxCSConv instance on the fly). - The predefined wxCSConv instance, wxConvLocal, is preset to use the - default user character set, but you should rarely need to use it directly, - it is better to go through wxConvCurrent. - - @section convertingstrings Converting strings - - Once you have chosen which object you want to use to convert your text, - here is how you would use them with wxString. These examples all assume - that you are using a Unicode build of wxWidgets, although they will still - compile in a non-Unicode build (they just won't convert anything). - Example 1: Constructing a wxString from input in current encoding. - - @code - wxString str(input_data, *wxConvCurrent); - @endcode - - Example 2: Input in UTF-8 encoding. - - @code - wxString str(input_data, wxConvUTF8); - @endcode - - Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly. - - @code - wxString str(input_data, wxCSConv(wxT("koi8-r"))); - @endcode - - Example 4: Printing a wxString to stdout in UTF-8 encoding. - - @code - puts(str.mb_str(wxConvUTF8)); - @endcode - - Example 5: Printing a wxString to stdout in custom encoding. - Using preconstructed wxCSConv instance. - - @code - wxCSConv cust(user_encoding); - printf("Data: %s\n", (const char*) str.mb_str(cust)); - @endcode - - Note: Since mb_str() returns a temporary wxCharBuffer to hold the result - of the conversion, you need to explicitly cast it to const char* if you use - it in a vararg context (like with printf). - - @section convertingbuffers Converting buffers - - If you have specialized needs, or just don't want to use wxString, you - can also use the conversion methods of the conversion objects directly. - This can even be useful if you need to do conversion in a non-Unicode - build of wxWidgets; converting a string from UTF-8 to the current - encoding should be possible by doing this: - - @code - wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent); - @endcode - - Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode - string. The wxString constructor then converts it back to an 8-bit character - set using the passed conversion object, *wxConvCurrent. (In a Unicode build - of wxWidgets, the constructor ignores the passed conversion object and - retains the Unicode data.) - This could also be done by first making a wxString of the original data: - - @code - wxString input_str(input_data); - wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent); - @endcode - - To print a wxChar buffer to a non-Unicode stdout: - - @code - printf("Data: %s\n", (const char*) wxConvCurrent-cWX2MB(unicode_data)); - @endcode - - If you need to do more complex processing on the converted data, you - may want to store the temporary buffer in a local variable: - - @code - const wxWX2MBbuf tmp_buf = wxConvCurrent-cWX2MB(unicode_data); - const char *tmp_str = (const char*) tmp_buf; - printf("Data: %s\n", tmp_str); - process_data(tmp_str); - @endcode - - If a conversion had taken place in cWX2MB (i.e. in a Unicode build), - the buffer will be deallocated as soon as tmp_buf goes out of scope. - (The macro wxWX2MBbuf reflects the correct return value of cWX2MB - (either char* or wxCharBuffer), except for the const.) - - */ +
+@section overview_mbconv_need Background: The Need for Conversion + +As programs are becoming more and more globalized, and users exchange documents +across country boundaries as never before, applications increasingly need to +take into account all the different character sets in use around the world. It +is no longer enough to just depend on the default byte-sized character set that +computers have traditionally used. + +A few years ago, a solution was proposed: the Unicode standard. Able to contain +the complete set of characters in use in one unified global coding system, it +would resolve the character set problems once and for all. + +But it hasn't happened yet, and the migration towards Unicode has created new +challenges, resulting in "compatibility encodings" such as UTF-8. A large +number of systems out there still depends on the old 8-bit encodings, hampered +by the huge amounts of legacy code still widely deployed. Even sending Unicode +data from one Unicode-aware system to another may need encoding to an 8-bit +multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to pass +unhindered through any traditional transport channels. + + +@section overview_mbconv_string Background: The wxString Class + +If you have compiled wxWidgets in Unicode mode, the wxChar type will become +identical to wchar_t rather than char, and a wxString stores wxChars. Hence, +all wxString manipulation in your application will then operate on Unicode +strings, and almost as easily as working with ordinary char strings (you just +need to remember to use the wxT() macro to encapsulate any string literals). + +But often, your environment doesn't want Unicode strings. You could be sending +data over a network, or processing a text file for some other application. You +need a way to quickly convert your easily-handled Unicode data to and from a +traditional 8-bit encoding. And this is what the wxMBConv classes do. + + +@section overview_mbconv_classes wxMBConv Classes + +The base class for all these conversions is the wxMBConv class (which itself +implements standard libc locale conversion). Derived classes include +wxMBConvLibc, several different wxMBConvUTFxxx classes, and wxCSConv, which +implement different kinds of conversions. You can also derive your own class +for your own custom encoding and use it, should you need it. All you need to do +is override the MB2WC and WC2MB methods. + + +@section overview_mbconv_objects wxMBConv Objects + +Several of the wxWidgets-provided wxMBConv classes have predefined instances +(wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use +these predefined objects directly, or you can instantiate your own objects. + +A variable, wxConvCurrent, points to the conversion object that the user +interface is supposed to use, in the case that the user interface is not +Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or +wxConvLocal, depending on which works best on the current platform. + + +@section overview_mbconv_csconv wxCSConv + +The wxCSConv class is special because when it is instantiated, you can tell it +which character set it should use, which makes it meaningful to keep many +instances of them around, each with a different character set (or you can +create a wxCSConv instance on the fly). + +The predefined wxCSConv instance, wxConvLocal, is preset to use the default +user character set, but you should rarely need to use it directly, it is better +to go through wxConvCurrent. + + +@section overview_mbconv_converting Converting Strings + +Once you have chosen which object you want to use to convert your text, here is +how you would use them with wxString. These examples all assume that you are +using a Unicode build of wxWidgets, although they will still compile in a +non-Unicode build (they just won't convert anything). + +Example 1: Constructing a wxString from input in current encoding. + +@code +wxString str(input_data, *wxConvCurrent); +@endcode + +Example 2: Input in UTF-8 encoding. + +@code +wxString str(input_data, wxConvUTF8); +@endcode + +Example 3: Input in KOI8-R. Construction of wxCSConv instance on the fly. + +@code +wxString str(input_data, wxCSConv(wxT("koi8-r"))); +@endcode + +Example 4: Printing a wxString to stdout in UTF-8 encoding. + +@code +puts(str.mb_str(wxConvUTF8)); +@endcode + +Example 5: Printing a wxString to stdout in custom encoding. Using +preconstructed wxCSConv instance. + +@code +wxCSConv cust(user_encoding); +printf("Data: %s\n", (const char*) str.mb_str(cust)); +@endcode + +@note Since mb_str() returns a temporary wxCharBuffer to hold the result of the +conversion, you need to explicitly cast it to const char* if you use it in a +vararg context (like with printf). + + +@section overview_mbconv_buffers Converting Buffers + +If you have specialized needs, or just don't want to use wxString, you can also +use the conversion methods of the conversion objects directly. This can even be +useful if you need to do conversion in a non-Unicode build of wxWidgets; +converting a string from UTF-8 to the current encoding should be possible by +doing this: + +@code +wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent); +@endcode + +Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode +string. The wxString constructor then converts it back to an 8-bit character +set using the passed conversion object, *wxConvCurrent. (In a Unicode build of +wxWidgets, the constructor ignores the passed conversion object and retains the +Unicode data.) + +This could also be done by first making a wxString of the original data: + +@code +wxString input_str(input_data); +wxString str(input_str.wc_str(wxConvUTF8), *wxConvCurrent); +@endcode + +To print a wxChar buffer to a non-Unicode stdout: + +@code +printf("Data: %s\n", (const char*) wxConvCurrent->cWX2MB(unicode_data)); +@endcode + +If you need to do more complex processing on the converted data, you may want +to store the temporary buffer in a local variable: + +@code +const wxWX2MBbuf tmp_buf = wxConvCurrent->cWX2MB(unicode_data); +const char *tmp_str = (const char*) tmp_buf; +printf("Data: %s\n", tmp_str); +process_data(tmp_str); +@endcode + +If a conversion had taken place in cWX2MB (i.e. in a Unicode build), the buffer +will be deallocated as soon as tmp_buf goes out of scope. The macro wxWX2MBbuf +reflects the correct return value of cWX2MB (either char* or wxCharBuffer), +except for the const. + +*/ + diff --git a/docs/doxygen/overviews/nonenglish.h b/docs/doxygen/overviews/nonenglish.h index 4f92f7b1df..fbbd4143ba 100644 --- a/docs/doxygen/overviews/nonenglish.h +++ b/docs/doxygen/overviews/nonenglish.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: nonenglish +// Name: nonenglish.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,156 +8,161 @@ /*! - @page nonenglish_overview Writing non-English applications +@page overview_nonenglish Writing Non-English Applications - This article describes how to write applications that communicate with - the user in a language other than English. Unfortunately many languages use - different charsets under Unix and Windows (and other platforms, to make - the situation even more complicated). These charsets usually differ in so - many characters that it is impossible to use the same texts under all - platforms. - The wxWidgets library provides a mechanism that helps you avoid distributing many - identical, only differently encoded, packages with your application - (e.g. help files and menu items in iso8859-13 and windows-1257). Thanks - to this mechanism you can, for example, distribute only iso8859-13 data - and it will be handled transparently under all systems. - Please read #Internationalization which - describes the locales concept. - In the following text, wherever @e iso8859-2 and @e windows-1250 are - used, any encodings are meant and any encodings may be substituted there. - @b Locales - The best way to ensure correctly displayed texts in a GUI across platforms - is to use locales. Write your in-code messages in English or without - diacritics and put real messages into the message catalog (see - #Internationalization). - A standard .po file begins with a header like this: +This article describes how to write applications that communicate with the user +in a language other than English. Unfortunately many languages use different +charsets under Unix and Windows (and other platforms, to make the situation +even more complicated). These charsets usually differ in so many characters +that it is impossible to use the same texts under all platforms. - @code - # SOME DESCRIPTIVE TITLE. - # Copyright (C) YEAR Free Software Foundation, Inc. - # FIRST AUTHOR EMAIL@ADDRESS, YEAR. - # - msgid "" - msgstr "" - "Project-Id-Version: PACKAGE VERSION\n" - "POT-Creation-Date: 1999-02-19 16:03+0100\n" - "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" - "Last-Translator: FULL NAME EMAIL@ADDRESS\n" - "Language-Team: LANGUAGE LL@li.org\n" - "MIME-Version: 1.0\n" - "Content-Type: text/plain; charset=CHARSET\n" - "Content-Transfer-Encoding: ENCODING\n" - @endcode +The wxWidgets library provides a mechanism that helps you avoid distributing +many identical, only differently encoded, packages with your application (e.g. +help files and menu items in iso8859-13 and windows-1257). Thanks to this +mechanism you can, for example, distribute only iso8859-13 data and it will be +handled transparently under all systems. - Note this particular line: +Please read the @ref overview_i18n which describes the locales concept. - @code - "Content-Type: text/plain; charset=CHARSET\n" - @endcode - - It specifies the charset used by the catalog. All strings in the catalog - are encoded using this charset. - You have to fill in proper charset information. Your .po file may look like this - after doing so: - - @code - # SOME DESCRIPTIVE TITLE. - # Copyright (C) YEAR Free Software Foundation, Inc. - # FIRST AUTHOR EMAIL@ADDRESS, YEAR. - # - msgid "" - msgstr "" - "Project-Id-Version: PACKAGE VERSION\n" - "POT-Creation-Date: 1999-02-19 16:03+0100\n" - "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" - "Last-Translator: FULL NAME EMAIL@ADDRESS\n" - "Language-Team: LANGUAGE LL@li.org\n" - "MIME-Version: 1.0\n" - "Content-Type: text/plain; charset=iso8859-2\n" - "Content-Transfer-Encoding: 8bit\n" - @endcode - - (Make sure that the header is @b not marked as @e fuzzy.) - wxWidgets is able to use this catalog under any supported platform - (although iso8859-2 is a Unix encoding and is normally not understood by - Windows). - How is this done? When you tell the wxLocale class to load a message catalog that - contains a correct header, it checks the charset. The catalog is then converted - to the charset used (see - wxLocale::GetSystemEncoding and - wxLocale::GetSystemEncodingName) by - the user's operating system. This is the default behaviour of the - #wxLocale class; you can disable it by @b not passing - @c wxLOCALE_CONV_ENCODING to wxLocale::Init. - @b Non-English strings or 8-bit characters in the source code - By convention, you should only use characters without diacritics (i.e. 7-bit - ASCII strings) for msgids in the source code and write them in English. - If you port software to wxWindows, you may be confronted with legacy source - code containing non-English string literals. Instead of translating the strings - in the source code to English and putting the original strings into message - catalog, you may configure wxWidgets to use non-English msgids and translate to - English using message catalogs: +In the following text, wherever @e iso8859-2 and @e windows-1250 are used, any +encodings are meant and any encodings may be substituted there. - If you use the program @c xgettext to extract the strings from - the source code, specify the option @c --from-code=source code charset. - Specify the source code language and charset as arguments to - wxLocale::AddCatalog. For example: +@section overview_nonenglish_locales Locales - @code - locale.AddCatalog(_T("myapp"), - wxLANGUAGE_GERMAN, _T("iso-8859-1")); - @endcode +The best way to ensure correctly displayed texts in a GUI across platforms is +to use locales. Write your in-code messages in English or without diacritics +and put real messages into the message catalog (see @ref overview_i18n). + +A standard .po file begins with a header like this: + +@code +# SOME DESCRIPTIVE TITLE. +# Copyright (C) YEAR Free Software Foundation, Inc. +# FIRST AUTHOR , YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"POT-Creation-Date: 1999-02-19 16:03+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=CHARSET\n" +"Content-Transfer-Encoding: ENCODING\n" +@endcode + +Note this particular line: + +@code +"Content-Type: text/plain; charset=CHARSET\n" +@endcode + +It specifies the charset used by the catalog. All strings in the catalog are +encoded using this charset. + +You have to fill in proper charset information. Your .po file may look like +this after doing so: + +@code +# SOME DESCRIPTIVE TITLE. +# Copyright (C) YEAR Free Software Foundation, Inc. +# FIRST AUTHOR , YEAR. +# +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"POT-Creation-Date: 1999-02-19 16:03+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=iso8859-2\n" +"Content-Transfer-Encoding: 8bit\n" +@endcode + +(Make sure that the header is @b not marked as @e fuzzy.) + +wxWidgets is able to use this catalog under any supported platform +(although iso8859-2 is a Unix encoding and is normally not understood by +Windows). + +How is this done? When you tell the wxLocale class to load a message catalog +that contains a correct header, it checks the charset. The catalog is then +converted to the charset used (see wxLocale::GetSystemEncoding and +wxLocale::GetSystemEncodingName) by the user's operating system. This is the +default behaviour of the wxLocale class; you can disable it by @b not passing +@c wxLOCALE_CONV_ENCODING to wxLocale::Init. +@section overview_nonenglish_strings Non-English Strings or 8-bit Characters in Source + +By convention, you should only use characters without diacritics (i.e. 7-bit +ASCII strings) for msgids in the source code and write them in English. + +If you port software to wxWindows, you may be confronted with legacy source +code containing non-English string literals. Instead of translating the strings +in the source code to English and putting the original strings into message +catalog, you may configure wxWidgets to use non-English msgids and translate to +English using message catalogs: + +@li If you use the program @c xgettext to extract the strings from the source + code, specify the option --from-code=@. +@li Specify the source code language and charset as arguments to + wxLocale::AddCatalog. For example: + @code + locale.AddCatalog(_T("myapp"), wxLANGUAGE_GERMAN, _T("iso-8859-1")); + @endcode - @b Font mapping - You can use @ref mbconvclasses_overview and - #wxFontMapper to display text: +@section overview_nonenglish_fontmapping Font Mapping - @code - if (!wxFontMapper::Get()-IsEncodingAvailable(enc, facename)) - { +You can use @ref overview_mbconv and wxFontMapper to display text: + +@code +if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename)) +{ wxFontEncoding alternative; - if (wxFontMapper::Get()-GetAltForEncoding(enc, , - facename, @false)) + if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative, + facename, false)) { - wxCSConv convFrom(wxFontMapper::Get()-GetEncodingName(enc)); - wxCSConv convTo(wxFontMapper::Get()-GetEncodingName(alternative)); + wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc)); + wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative)); text = wxString(text.mb_str(convFrom), convTo); } else ...failure (or we may try iso8859-1/7bit ASCII)... - } - ...display text... - @endcode - - @b Converting data - You may want to store all program data (created documents etc.) in - the same encoding, let's say @c utf-8. You can use - #wxCSConv class to convert data to the encoding used by the - system your application is running on (see - wxLocale::GetSystemEncoding). - @b Help files - If you're using #wxHtmlHelpController there is - no problem at all. You only need to make sure that all the HTML files contain - the META tag, e.g. - - @code - meta http-equiv="Content-Type" content="text/html; charset=iso8859-2" - @endcode - - and that the hhp project file contains one additional line in the @c OPTIONS - section: - - @code - Charset=iso8859-2 - @endcode - - This additional entry tells the HTML help controller what encoding is used - in contents and index tables. - - */ +} +...display text... +@endcode +@section overview_nonenglish_converting Converting Data + +You may want to store all program data (created documents etc.) in the same +encoding, let's say @c utf-8. You can use wxCSConv to convert data to the +encoding used by the system your application is running on (see +wxLocale::GetSystemEncoding). + + +@section overview_nonenglish_help Help Files + +If you're using wxHtmlHelpController there is no problem at all. You only need +to make sure that all the HTML files contain the META tag: + +@code + +@endcode + +Also, the hhp project file needs one additional line in the @c OPTIONS section: + +@code +Charset=iso8859-2 +@endcode + +This additional entry tells the HTML help controller what encoding is used in +contents and index tables. + +*/ +