Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More doxygen topic overview cleanup.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52211 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-03-01 09:49:25 +00:00
parent 077a28282e
commit 9715cf42b3
4 changed files with 466 additions and 464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/doxygen/mainpages/topics.h
View File

@@ -38,7 +38,7 @@ The following is a basic categorization of them:
@li @subpage overview_refcount @li @subpage overview_refcount
@li @subpage overview_app @li @subpage overview_app
@li @subpage overview_unicode @li @subpage overview_unicode
@li @subpage overview_mbconvclasses @li @subpage overview_mbconv
@li @subpage overview_i18n @li @subpage overview_i18n
@li @subpage overview_nonenglish @li @subpage overview_nonenglish
@li @subpage overview_debugging @li @subpage overview_debugging

250
docs/doxygen/overviews/log.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: log // Name: log.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,79 +8,70 @@
/*! /*!
@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,
#wxLogStream,
#wxLogTextCtrl,
#wxLogWindow,
#wxLogGui,
#wxLogNull,
#wxLogBuffer,
#wxLogChain,
#wxLogInterposer,
#wxLogInterposerTemp,
#wxStreamToTextRedirector
This is a general overview of logging classes provided by wxWidgets. The word 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 logging here has a broad sense, including all of the program output, not only
non-interactive messages. The logging facilities included in wxWidgets provide non-interactive messages. The logging facilities included in wxWidgets provide
the base @e wxLog class which defines the standard interface for a @e log the base wxLog class which defines the standard interface for a @e log target
target as well as several standard implementations of it and a family of as well as several standard implementations of it and a family of functions to
functions to use with them. 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:
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:
@b wxLogFatalError which is like @e wxLogError, but also @li wxLogFatalError which is like wxLogError, but also terminates the program
terminates the program with the exit code 3 (using @e abort() standard with the exit code 3 (using @e abort() standard function). Unlike for all
function). Unlike for all the other logging functions, this function can't be the other logging functions, this function can't be overridden by a log
overridden by a log target. target.
@b wxLogError is the function to use for error messages, i.e. the @li wxLogError is the function to use for error messages, i.e. the messages
messages that must be shown to the user. The default processing is to pop up a that must be shown to the user. The default processing is to pop up a
message box to inform the user about it. message box to inform the user about it.
@b wxLogWarning for warnings - they are also normally shown to the @li wxLogWarning for warnings. They are also normally shown to the user, but
user, but don't interrupt the program work. don't interrupt the program work.
@b wxLogMessage is for all normal, informational messages. They also @li wxLogMessage is for all normal, informational messages. They also appear in
appear in a message box by default (but it can be changed, see below). a message box by default (but it can be changed, see below).
@b wxLogVerbose is for verbose output. Normally, it is suppressed, but @li wxLogVerbose is for verbose output. Normally, it is suppressed, but might
might be activated if the user wishes to know more details about the program 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). progress (another, but possibly confusing name for the same function is
@b wxLogStatus is for status messages - they will go into the status wxLogInfo).
bar of the active or specified (as the first argument) #wxFrame if it has one. @li wxLogStatus is for status messages. They will go into the status bar of the
@b wxLogSysError is mostly used by wxWidgets itself, but might be active or specified (as the first argument) wxFrame if it has one.
handy for logging errors after system call (API function) failure. It logs the @li wxLogSysError is mostly used by wxWidgets itself, but might be handy for
specified message text as well as the last system error logging errors after system call (API function) failure. It logs the
code (@e errno or @e ::GetLastError() depending on the platform) and specified message text as well as the last system error code (@e errno or
the corresponding error message. The second form of this function takes the ::GetLastError() depending on the platform) and the corresponding error
error code explicitly as the first argument. message. The second form of this function takes the error code explicitly
@b wxLogDebug is @b the right function for debug output. It only as the first argument.
does anything at all in the debug mode (when the preprocessor symbol @li wxLogDebug is @b the right function for debug output. It only does anything
__WXDEBUG__ is defined) and expands to nothing in release mode (otherwise). at all in the debug mode (when the preprocessor symbol __WXDEBUG__ is
@b Tip: under Windows, you must either run the program under debugger or defined) and expands to nothing in release mode (otherwise). @b Tip: under
use a 3rd party program such as #DbgView Windows, you must either run the program under debugger or use a 3rd party
to actually see the debug output. program such as DebugView to actually see the debug output.
@b wxLogTrace as @b wxLogDebug only does something in debug - DebugView: http://www.microsoft.com/technet/sysinternals/Miscellaneous/DebugView.mspx
build. The reason for making it a separate function from it is that usually @li wxLogTrace as wxLogDebug only does something in debug build. The reason for
there are a lot of trace messages, so it might make sense to separate them making it a separate function from it is that usually there are a lot of
from other debug messages which would be flooded in them. Moreover, the second trace messages, so it might make sense to separate them from other debug
version of this function takes a trace mask as the first argument which allows messages which would be flooded in them. Moreover, the second version of
to further restrict the amount of messages generated. 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 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 be asked why not use the other logging facilities, such as C standard stdio
@@ -88,83 +79,77 @@
generic mechanisms, but are not really adapted for wxWidgets, while the log generic mechanisms, but are not really adapted for wxWidgets, while the log
classes are. Some of advantages in using wxWidgets log functions are: 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
@b Portability It is a common practice to use @e printf() cout/cerr C++ streams for writing out some (debug or otherwise)
statements or cout/cerr C++ streams for writing out some (debug or otherwise) information. Although it works just fine under Unix, these messages go
information. strictly nowhere under Windows where the stdout of GUI programs is not
Although it works just fine under Unix, these messages go strictly nowhere assigned to anything. Thus, you might view wxLogMessage() as a simple
under Windows where the stdout of GUI programs is not assigned to anything. substitute for @e printf().
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: You can also redirect the @e wxLogXXX calls to @e cout by just writing:
@code @code
wxLog *logger=new wxLogStream(); wxLog* logger = new wxLogStream(&cout);
wxLog::SetActiveTarget(logger); wxLog::SetActiveTarget(logger);
@endcode @endcode
Finally, there is also a possibility to redirect the output sent to @e cout Finally, there is also a possibility to redirect the output sent to @e cout
to a #wxTextCtrl by using the to a wxTextCtrl by using the wxStreamToTextRedirector class.
#wxStreamToTextRedirector class. @li @b Flexibility: The output of wxLog functions can be redirected or
@b Flexibility The output of wxLog functions can be redirected or suppressed entirely based on their importance, which is either impossible
suppressed entirely based on their importance, which is either impossible or or difficult to do with traditional methods. For example, only error
difficult to do with traditional methods. For example, only error messages, or messages, or only error messages and warnings might be logged, filtering
only error messages and warnings might be logged, filtering out all out all informational messages.
informational messages. @li @b Completeness: Usually, an error message should be presented to the user
@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
when some operation fails. Let's take a quite simple but common case of a file file error: suppose that you're writing your data file on disk and there is
error: suppose that you're writing your data file on disk and there is not not enough space. The actual error might have been detected inside
enough space. The actual error might have been detected inside wxWidgets code wxWidgets code (say, in wxFile::Write), so the calling function doesn't
(say, in @e wxFile::Write), so the calling function doesn't really know the really know the exact reason of the failure, it only knows that the data
exact reason of the failure, it only knows that the data file couldn't be file couldn't be written to the disk. However, as wxWidgets uses
written to the disk. However, as wxWidgets uses @e wxLogError() in this wxLogError() in this situation, the exact error code (and the corresponding
situation, the exact error code (and the corresponding error message) will be error message) will be given to the user together with "high level" message
given to the user together with "high level" message about data file writing about data file writing error.
error.
After having enumerated all the functions which are normally used to log the 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 messages, and why would you want to use them we now describe how all this
works. 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 wxWidgets has the notion of a <em>log target</em>: it is just a class deriving
the base class which are called when a message is logged. Only one log target from wxLog. As such, it implements the virtual functions of the base class
is @e active at any moment, this is the one used by @e wxLogXXX() which are called when a message is logged. Only one log target is @e active at
functions. The normal usage of a log object (i.e. object of a class derived any moment, this is the one used by @e wxLogXXX() functions. The normal usage
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 of a log object (i.e. object of a class derived from wxLog) is to install it as
to @e wxLogXXX() functions. 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 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 implement one (or both) of @e DoLog() and @e DoLogString() in it. The second
second one is enough if you're happy with the standard wxLog message one is enough if you're happy with the standard wxLog message formatting
formatting (prepending "Error:" or "Warning:", timestamping c) but just want (prepending "Error:" or "Warning:", timestamping @&c) but just want to send
to send the messages somewhere else. The first one may be overridden to do the messages somewhere else. The first one may be overridden to do whatever
whatever you want but you have to distinguish between the different message you want but you have to distinguish between the different message types
types yourself. yourself.
There are some predefined classes deriving from wxLog and which might be 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 helpful to see how you can create a new log target class and, of course, may
also be used without any change. There are: also be used without any change. There are:
@li wxLogStderr: This class logs messages to a <tt>FILE *</tt>, using stderr by
@b wxLogStderr This class logs messages to a @e FILE *, using default as its name suggests.
stderr by default as its name suggests. @li wxLogStream: This class has the same functionality as wxLogStderr, but uses
@b wxLogStream This class has the same functionality as wxLogStderr, @e ostream and cerr instead of <tt>FILE *</tt> and stderr.
but uses @e ostream and cerr instead of @e FILE * and stderr. @li wxLogGui: This is the standard log target for wxWidgets applications (it is
@b wxLogGui This is the standard log target for wxWidgets used by default if you don't do anything) and provides the most reasonable
applications (it is used by default if you don't do anything) and provides the handling of all types of messages for given platform.
most reasonable handling of all types of messages for given platform. @li wxLogWindow: This log target provides a "log console" which collects all
@b wxLogWindow This log target provides a "log console" which messages generated by the application and also passes them to the previous
collects all messages generated by the application and also passes them to the active log target. The log window frame has a menu allowing user to clear
previous active log target. The log window frame has a menu allowing user to the log, close it completely or save all messages to file.
clear the log, close it completely or save all messages to file. @li wxLogBuffer: This target collects all the logged messages in an internal
@b wxLogBuffer This target collects all the logged messages in an buffer allowing to show them later to the user all at once.
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.
@b wxLogNull The last log class is quite particular: it doesn't do The objects of this class may be instantiated to (temporarily) suppress
anything. The objects of this class may be instantiated to (temporarily) output of @e wxLogXXX() functions. As an example, trying to open a
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 non-existing file will usually provoke an error message, but if for some
reasons it is unwanted, just use this construction: reasons it is unwanted, just use this construction:
@code @code
wxFile file; wxFile file;
@@ -172,19 +157,18 @@
{ {
wxLogNull logNo; wxLogNull logNo;
if ( !file.Open("bar") ) if ( !file.Open("bar") )
... process error ourselves ... {
// ... process error ourselves ...
}
} // ~wxLogNull called, old log sink restored } // ~wxLogNull called, old log sink restored
wxLogMessage("..."); // ok wxLogMessage("..."); // ok
@endcode @endcode
The log targets can also be combined: for example you may wish to redirect the 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 messages somewhere else (for example, to a log file) but also process them as
normally. For this the #wxLogChain, #wxLogInterposer and normally. For this the wxLogChain, wxLogInterposer, and wxLogInterposerTemp can
#wxLogInterposerTemp can be used. be used.
*/ */

135
docs/doxygen/overviews/mbconvclasses.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: mbconvclasses // Name: mbconvclasses.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,56 +8,62 @@
/*! /*!
@page mbconvclasses_overview wxMBConv classes overview @page overview_mbconv wxMBConv Classes Overview
Classes: #wxMBConv, wxMBConvLibc, Classes: wxMBConv, wxMBConvLibc, wxMBConvUTF7, wxMBConvUTF8, wxCSConv,
#wxMBConvUTF7, #wxMBConvUTF8, wxMBConvUTF16, wxMBConvUTF32
#wxCSConv,
#wxMBConvUTF16, #wxMBConvUTF32 The wxMBConv classes in wxWidgets enable an Unicode-aware application to easily
The wxMBConv classes in wxWidgets enable an Unicode-aware application to convert between Unicode and the variety of 8-bit encoding systems still in use.
easily convert between Unicode and the variety of 8-bit encoding systems still
in use. @li @ref overview_mbconv_need
@ref needforconversion_overview @li @ref overview_mbconv_string
@ref conversionandwxstring_overview @li @ref overview_mbconv_classes
@ref mbconvclasses_overview @li @ref overview_mbconv_objects
@ref mbconvobjects_overview @li @ref overview_mbconv_csconv
#wxCSConv @li @ref overview_mbconv_converting
@ref convertingstrings_overview @li @ref overview_mbconv_buffers
@ref convertingbuffers_overview
@section needforconversion Background: The need for conversion <hr>
@section overview_mbconv_need Background: The Need for Conversion
As programs are becoming more and more globalized, and users exchange documents As programs are becoming more and more globalized, and users exchange documents
across country boundaries as never before, applications increasingly need to across country boundaries as never before, applications increasingly need to
take into account all the different character sets in use around the world. It 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 is no longer enough to just depend on the default byte-sized character set that
computers have traditionally used. computers have traditionally used.
A few years ago, a solution was proposed: the Unicode standard. Able to contain 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, the complete set of characters in use in one unified global coding system, it
it would resolve the character set problems once and for all. would resolve the character set problems once and for all.
But it hasn't happened yet, and the migration towards Unicode has created new 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 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 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 by the huge amounts of legacy code still widely deployed. Even sending Unicode
Unicode data from one Unicode-aware system to another may need encoding to an data from one Unicode-aware system to another may need encoding to an 8-bit
8-bit multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to multibyte encoding (UTF-7 or UTF-8 is typically used for this purpose), to pass
pass unhindered through any traditional transport channels. unhindered through any traditional transport channels.
@section conversionandwxstring Background: The wxString class
@section overview_mbconv_string Background: The wxString Class
If you have compiled wxWidgets in Unicode mode, the wxChar type will become 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, identical to wchar_t rather than char, and a wxString stores wxChars. Hence,
all wxString manipulation in your application will then operate on Unicode all wxString manipulation in your application will then operate on Unicode
strings, and almost as easily as working with ordinary char strings (you strings, and almost as easily as working with ordinary char strings (you just
just need to remember to use the wxT() macro to encapsulate any string need to remember to use the wxT() macro to encapsulate any string literals).
literals).
But often, your environment doesn't want Unicode strings. You could be sending 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 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 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. traditional 8-bit encoding. And this is what the wxMBConv classes do.
@section wxmbconvclasses wxMBConv classes
@section overview_mbconv_classes wxMBConv Classes
The base class for all these conversions is the wxMBConv class (which itself The base class for all these conversions is the wxMBConv class (which itself
implements standard libc locale conversion). Derived classes include implements standard libc locale conversion). Derived classes include
@@ -66,32 +72,38 @@
for your own custom encoding and use it, should you need it. All you need to do for your own custom encoding and use it, should you need it. All you need to do
is override the MB2WC and WC2MB methods. is override the MB2WC and WC2MB methods.
@section wxmbconvobjects wxMBConv objects
@section overview_mbconv_objects wxMBConv Objects
Several of the wxWidgets-provided wxMBConv classes have predefined instances Several of the wxWidgets-provided wxMBConv classes have predefined instances
(wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use (wxConvLibc, wxConvFileName, wxConvUTF7, wxConvUTF8, wxConvLocal). You can use
these predefined objects directly, or you can instantiate your own objects. these predefined objects directly, or you can instantiate your own objects.
A variable, wxConvCurrent, points to the conversion object that the user 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 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 Unicode-based (like with GTK+ 1.2). By default, it points to wxConvLibc or
wxConvLocal, depending on which works best on the current platform. wxConvLocal, depending on which works best on the current platform.
@section wxcsconvclass wxCSConv
@section overview_mbconv_csconv wxCSConv
The wxCSConv class is special because when it is instantiated, you can tell it 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 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 instances of them around, each with a different character set (or you can
create a wxCSConv instance on the fly). 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 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).
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. Example 1: Constructing a wxString from input in current encoding.
@code @code
@@ -116,25 +128,26 @@
puts(str.mb_str(wxConvUTF8)); puts(str.mb_str(wxConvUTF8));
@endcode @endcode
Example 5: Printing a wxString to stdout in custom encoding. Example 5: Printing a wxString to stdout in custom encoding. Using
Using preconstructed wxCSConv instance. preconstructed wxCSConv instance.
@code @code
wxCSConv cust(user_encoding); wxCSConv cust(user_encoding);
printf("Data: %s\n", (const char*) str.mb_str(cust)); printf("Data: %s\n", (const char*) str.mb_str(cust));
@endcode @endcode
Note: Since mb_str() returns a temporary wxCharBuffer to hold the result @note Since mb_str() returns a temporary wxCharBuffer to hold the result of the
of the conversion, you need to explicitly cast it to const char* if you use conversion, you need to explicitly cast it to const char* if you use it in a
it in a vararg context (like with printf). vararg context (like with printf).
@section convertingbuffers Converting buffers
If you have specialized needs, or just don't want to use wxString, you @section overview_mbconv_buffers Converting Buffers
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 If you have specialized needs, or just don't want to use wxString, you can also
build of wxWidgets; converting a string from UTF-8 to the current use the conversion methods of the conversion objects directly. This can even be
encoding should be possible by doing this: 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 @code
wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent); wxString str(wxConvUTF8.cMB2WC(input_data), *wxConvCurrent);
@@ -142,9 +155,10 @@
Here, cMB2WC of the UTF8 object returns a wxWCharBuffer containing a Unicode 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 string. The wxString constructor then converts it back to an 8-bit character
set using the passed conversion object, *wxConvCurrent. (In a Unicode build set using the passed conversion object, *wxConvCurrent. (In a Unicode build of
of wxWidgets, the constructor ignores the passed conversion object and wxWidgets, the constructor ignores the passed conversion object and retains the
retains the Unicode data.) Unicode data.)
This could also be done by first making a wxString of the original data: This could also be done by first making a wxString of the original data:
@code @code
@@ -155,24 +169,23 @@
To print a wxChar buffer to a non-Unicode stdout: To print a wxChar buffer to a non-Unicode stdout:
@code @code
printf("Data: %s\n", (const char*) wxConvCurrent-cWX2MB(unicode_data)); printf("Data: %s\n", (const char*) wxConvCurrent->cWX2MB(unicode_data));
@endcode @endcode
If you need to do more complex processing on the converted data, you If you need to do more complex processing on the converted data, you may want
may want to store the temporary buffer in a local variable: to store the temporary buffer in a local variable:
@code @code
const wxWX2MBbuf tmp_buf = wxConvCurrent-cWX2MB(unicode_data); const wxWX2MBbuf tmp_buf = wxConvCurrent->cWX2MB(unicode_data);
const char *tmp_str = (const char*) tmp_buf; const char *tmp_str = (const char*) tmp_buf;
printf("Data: %s\n", tmp_str); printf("Data: %s\n", tmp_str);
process_data(tmp_str); process_data(tmp_str);
@endcode @endcode
If a conversion had taken place in cWX2MB (i.e. in a Unicode build), If a conversion had taken place in cWX2MB (i.e. in a Unicode build), the buffer
the buffer will be deallocated as soon as tmp_buf goes out of scope. will be deallocated as soon as tmp_buf goes out of scope. The macro wxWX2MBbuf
(The macro wxWX2MBbuf reflects the correct return value of cWX2MB reflects the correct return value of cWX2MB (either char* or wxCharBuffer),
(either char* or wxCharBuffer), except for the const.) except for the const.
*/ */

147
docs/doxygen/overviews/nonenglish.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: nonenglish // Name: nonenglish.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,42 +8,46 @@
/*! /*!
@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 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).
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: A standard .po file begins with a header like this:
@code @code
# SOME DESCRIPTIVE TITLE. # SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR Free Software Foundation, Inc. # Copyright (C) YEAR Free Software Foundation, Inc.
# FIRST AUTHOR EMAIL@ADDRESS, YEAR. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
# #
msgid "" msgid ""
msgstr "" msgstr ""
"Project-Id-Version: PACKAGE VERSION\n" "Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 1999-02-19 16:03+0100\n" "POT-Creation-Date: 1999-02-19 16:03+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME EMAIL@ADDRESS\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE LL@li.org\n" "Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n" "MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n" "Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: ENCODING\n" "Content-Transfer-Encoding: ENCODING\n"
@@ -55,76 +59,76 @@
"Content-Type: text/plain; charset=CHARSET\n" "Content-Type: text/plain; charset=CHARSET\n"
@endcode @endcode
It specifies the charset used by the catalog. All strings in the catalog It specifies the charset used by the catalog. All strings in the catalog are
are encoded using this charset. encoded using this charset.
You have to fill in proper charset information. Your .po file may look like this
after doing so: You have to fill in proper charset information. Your .po file may look like
this after doing so:
@code @code
# SOME DESCRIPTIVE TITLE. # SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR Free Software Foundation, Inc. # Copyright (C) YEAR Free Software Foundation, Inc.
# FIRST AUTHOR EMAIL@ADDRESS, YEAR. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
# #
msgid "" msgid ""
msgstr "" msgstr ""
"Project-Id-Version: PACKAGE VERSION\n" "Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 1999-02-19 16:03+0100\n" "POT-Creation-Date: 1999-02-19 16:03+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME EMAIL@ADDRESS\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE LL@li.org\n" "Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n" "MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=iso8859-2\n" "Content-Type: text/plain; charset=iso8859-2\n"
"Content-Transfer-Encoding: 8bit\n" "Content-Transfer-Encoding: 8bit\n"
@endcode @endcode
(Make sure that the header is @b not marked as @e fuzzy.) (Make sure that the header is @b not marked as @e fuzzy.)
wxWidgets is able to use this catalog under any supported platform wxWidgets is able to use this catalog under any supported platform
(although iso8859-2 is a Unix encoding and is normally not understood by (although iso8859-2 is a Unix encoding and is normally not understood by
Windows). 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 How is this done? When you tell the wxLocale class to load a message catalog
to the charset used (see that contains a correct header, it checks the charset. The catalog is then
wxLocale::GetSystemEncoding and converted to the charset used (see wxLocale::GetSystemEncoding and
wxLocale::GetSystemEncodingName) by wxLocale::GetSystemEncodingName) by the user's operating system. This is the
the user's operating system. This is the default behaviour of the default behaviour of the wxLocale class; you can disable it by @b not passing
#wxLocale class; you can disable it by @b not passing
@c wxLOCALE_CONV_ENCODING to wxLocale::Init. @c wxLOCALE_CONV_ENCODING to wxLocale::Init.
@b Non-English strings or 8-bit characters in the source code
@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 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. 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 If you port software to wxWindows, you may be confronted with legacy source
code containing non-English string literals. Instead of translating the strings code containing non-English string literals. Instead of translating the strings
in the source code to English and putting the original strings into message 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 catalog, you may configure wxWidgets to use non-English msgids and translate to
English using message catalogs: English using message catalogs:
@li If you use the program @c xgettext to extract the strings from the source
If you use the program @c xgettext to extract the strings from code, specify the option <tt>--from-code=@<source code charset@></tt>.
the source code, specify the option @c --from-code=source code charset. @li Specify the source code language and charset as arguments to
Specify the source code language and charset as arguments to
wxLocale::AddCatalog. For example: wxLocale::AddCatalog. For example:
@code @code
locale.AddCatalog(_T("myapp"), locale.AddCatalog(_T("myapp"), wxLANGUAGE_GERMAN, _T("iso-8859-1"));
wxLANGUAGE_GERMAN, _T("iso-8859-1"));
@endcode @endcode
@section overview_nonenglish_fontmapping Font Mapping
You can use @ref overview_mbconv and wxFontMapper to display text:
@b Font mapping
You can use @ref mbconvclasses_overview and
#wxFontMapper to display text:
@code @code
if (!wxFontMapper::Get()-IsEncodingAvailable(enc, facename)) if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
{ {
wxFontEncoding alternative; wxFontEncoding alternative;
if (wxFontMapper::Get()-GetAltForEncoding(enc, , if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
facename, @false)) facename, false))
{ {
wxCSConv convFrom(wxFontMapper::Get()-GetEncodingName(enc)); wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
wxCSConv convTo(wxFontMapper::Get()-GetEncodingName(alternative)); wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
text = wxString(text.mb_str(convFrom), convTo); text = wxString(text.mb_str(convFrom), convTo);
} }
else else
@@ -133,31 +137,32 @@
...display text... ...display text...
@endcode @endcode
@b Converting data
You may want to store all program data (created documents etc.) in @section overview_nonenglish_converting Converting Data
the same encoding, let's say @c utf-8. You can use
#wxCSConv class to convert data to the encoding used by the You may want to store all program data (created documents etc.) in the same
system your application is running on (see 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). 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 @section overview_nonenglish_help Help Files
the META tag, e.g.
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 @code
meta http-equiv="Content-Type" content="text/html; charset=iso8859-2" <meta http-equiv="Content-Type" content="text/html; charset=iso8859-2">
@endcode @endcode
and that the hhp project file contains one additional line in the @c OPTIONS Also, the hhp project file needs one additional line in the @c OPTIONS section:
section:
@code @code
Charset=iso8859-2 Charset=iso8859-2
@endcode @endcode
This additional entry tells the HTML help controller what encoding is used This additional entry tells the HTML help controller what encoding is used in
in contents and index tables. contents and index tables.
*/ */