@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
/////////////////////////////////////////////////////////////////////////////
-// Name: log
+// Name: log.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page log_overview wxLog classes overview
-
- Classes: #wxLog,
-
- #wxLogStderr,
-
- #wxLogStream,
-
- #wxLogTextCtrl,
-
- #wxLogWindow,
-
- #wxLogGui,
-
- #wxLogNull,
-
- #wxLogBuffer,
-
- #wxLogChain,
-
- #wxLogInterposer,
-
- #wxLogInterposerTemp,
-
- #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:
-
-
- @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.
-
- */
-
+@page overview_log wxLog Classes Overview
+
+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
+
+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.
+
+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:
+
+@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.
+
+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:
+
+@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.
+
+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 <em>log target</em>: 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:
+
+@li wxLogStderr: This class logs messages to a <tt>FILE *</tt>, 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 <tt>FILE *</tt> 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;
+
+ // 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.
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: mbconvclasses
+// Name: mbconvclasses.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page mbconvclasses_overview 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
-
-
- @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:
+@page overview_mbconv wxMBConv Classes Overview
- @code
- printf("Data: %s\n", (const char*) wxConvCurrent-cWX2MB(unicode_data));
- @endcode
+Classes: wxMBConv, wxMBConvLibc, wxMBConvUTF7, wxMBConvUTF8, wxCSConv,
+ wxMBConvUTF16, wxMBConvUTF32
- If you need to do more complex processing on the converted data, you
- may want to store the temporary buffer in a local variable:
+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.
- @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
+@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
- 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.)
- */
+<hr>
+@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.
+
+*/
+
/////////////////////////////////////////////////////////////////////////////
-// Name: nonenglish
+// Name: nonenglish.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page nonenglish_overview 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:
-
- @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
-
- 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 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:
-
-
- 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:
-
- @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:
-
- @code
- if (!wxFontMapper::Get()-IsEncodingAvailable(enc, facename))
- {
+@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 the @ref overview_i18n 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.
+
+
+@section overview_nonenglish_locales 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 @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 <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
+
+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 <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.
+
+
+@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 <tt>--from-code=@<source code charset@></tt>.
+@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
+
+
+@section overview_nonenglish_fontmapping Font Mapping
+
+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
+}
+...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
+@section overview_nonenglish_converting Converting Data
- and that the hhp project file contains one additional line in the @c OPTIONS
- section:
+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).
- @code
- Charset=iso8859-2
- @endcode
- This additional entry tells the HTML help controller what encoding is used
- in contents and index tables.
+@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
+<meta http-equiv="Content-Type" content="text/html; charset=iso8859-2">
+@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.
+
+*/
projects / wxWidgets.git / commitdiff
