qtextcodec.3qt

Qt/Embedded是一个多平台的C++图形用户界面应用程序框架

.TH QTextCodec 3qt "3 September 2000" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2000 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QTextCodec \- Provides conversion between text encodings
.SH SYNOPSIS
.br
.PP
\fC#include <qtextcodec.h>\fR
.PP
Inherited by QEucJpCodec, QEucKrCodec, QGbkCodec, QJisCodec, QSjisCodec and QTsciiCodec.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "virtual \fB~QTextCodec\fR () "
.br
.ti -1c
.BI "virtual QTextEncoder* \fBmakeEncoder\fR () const"
.br
.ti -1c
.BI "virtual QString \fBtoUnicode\fR ( const char * " "chars" ", int len ) const"
.br
.ti -1c
.BI "QCString \fBfromUnicode\fR ( const QString & uc ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const QByteArray &, int len ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const QByteArray & ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const char * chars ) const"
.br
.ti -1c
.BI "virtual bool \fBcanEncode\fR ( QChar ) const"
.br
.ti -1c
.BI "virtual bool \fBcanEncode\fR ( const QString & ) const"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "QTextCodec* \fBloadCharmap\fR ( QIODevice * ) "
.br
.ti -1c
.BI "QTextCodec* \fBloadCharmapFile\fR ( QString filename ) "
.br
.ti -1c
.BI "QTextCodec* \fBcodecForMib\fR ( int mib ) "
.br
.ti -1c
.BI "QTextCodec* \fBcodecForName\fR ( const char * " "hint" ", int " "accuracy" "=0 ) "
.br
.ti -1c
.BI "QTextCodec* \fBcodecForContent\fR ( const char * " "chars" ", int len ) "
.br
.ti -1c
.BI "QTextCodec* \fBcodecForIndex\fR ( int i ) "
.br
.ti -1c
.BI "QTextCodec* \fBcodecForLocale\fR () "
.br
.ti -1c
.BI "void \fBdeleteAllCodecs\fR () "
.br
.ti -1c
.BI "const char* \fBlocale\fR () "
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "\fBQTextCodec\fR () "
.br
.in -1c
.SS "Static Protected Members"
.in +1c
.ti -1c
.BI "int \fBsimpleHeuristicNameMatch\fR ( const char * " "name" ", const char * hint ) "
.br
.in -1c
.SH DESCRIPTION
Provides conversion between text encodings.
.PP
By making objects of subclasses of QTextCodec, support for new text encodings can be added to Qt.
.PP
The abstract virtual functions describe the encoder to the system and the coder is used as required in the different text file formats supported QTextStream and, under X11 for the locale-specific character input and output (under Windows NT codecs are not needed for GUI I/O since the system works with Unicode already, and Windows 95/98 has built-in convertors for the 8-bit local encoding).
.PP
More recently created QTextCodec objects take precedence over earlier ones.
.PP
To add support for another 8-bit encoding to Qt, make a subclass or QTextCodec and implement at least the following methods:
.IP "\fCconst\fR char* name() const" 1c
Return the official name for the encoding.
.IP "\fCint\fR mibEnum() const" 1c
Return the MIB enum for the encoding if it is listed in the IANA character-sets encoding file.
.PP
If the encoding is multi-byte then it will have "state"; that is, the interpretation of some bytes will be dependent on some preceding bytes. For such an encoding, you will need to implement
.IP "\fCQTextDecoder*\fR makeDecoder() const" 1c
Return a QTextDecoder that remembers incomplete multibyte sequence prefixes or other required state.
.PP
If the encoding does \fInot\fR require state, you should implement:
.IP "\fCQString\fR toUnicode(const char* chars, int len) const" 1c
Converts \fIlen\fR characters from \fIchars\fR to Unicode.
.PP
The base QTextCodec class has default implementations of the above two functions, \fIbut they are mutually recursive\fR, so you must re-implement at least one of them, or both for improved efficiency.
.PP
For conversion from Unicode to 8-bit encodings, it is rarely necessary to maintain state. However, two functions similar to the two above are used for encoding:
.IP "\fCQTextEncoder*\fR makeEncoder() const" 1c
Return a QTextDecoder.
.IP "\fCQCString\fR fromUnicode(const QString& uc, int& lenInOut ) const;" 1c
Converts \fIlenInOut\fR characters (of type QChar) from the start of the string \fIuc,\fR returning a QCString result, and also returning the length of the result in lenInOut.
.PP
Again, these are mutually recursive so only one needs to be implemented, or both if better efficiency is possible.
.PP
Finally, you must implement:
.IP "\fCint\fR heuristicContentMatch(const char* chars, int len) const" 1c
Gives a value indicating how likely it is that \fIlen\fR characters from \fIchars\fR are in the encoding.
.PP
A good model for this function is the QWindowsLocalCodec::heuristicContentMatch function found in the Qt sources.
.PP
A QTextCodec subclass might have improved performance if you also re-implement:
.IP "\fCbool\fR canEncode( QChar ) const" 1c
Test if a Unicode character can be encoded.
.IP "\fCbool\fR canEncode( const QString& ) const" 1c
Test if a string of Unicode characters can be encoded.
.IP "\fCint\fR heuristicNameMatch(const char* hint) const" 1c
Test if a possibly non-standard name is referring to the codec.
.PP
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QTextCodec::QTextCodec () \fC[protected]\fR"
Constructs a QTextCodec, making it of highest precedence. The QTextCodec should always be constructed on the heap (with new), and once constructed it becomes the responsibility of Qt to delete it (which is done at QApplication destruction).
.SH "QTextCodec::~QTextCodec () \fC[virtual]\fR"
Destructs the QTextCodec. Note that you should not delete codecs yourself - once created they become the responsibility of Qt to delete.
.SH "bool QTextCodec::canEncode ( QChar ch ) const \fC[virtual]\fR"
Returns TRUE if the unicode character \fIch\fR can be fully encoded with this codec. The default implementation tests if the result of toUnicode(fromUnicode(ch)) is the original \fIch.\fR Subclasses may be able to improve the efficiency.
.SH "bool QTextCodec::canEncode ( const QString & s ) const \fC[virtual]\fR"
Returns TRUE if the unicode string \fIs\fR can be fully encoded with this codec. The default implementation tests if the result of toUnicode(fromUnicode(s)) is the original \fIs.\fR Subclasses may be able to improve the efficiency.
.SH "QTextCodec* QTextCodec::codecForContent ( const char * chars, int len ) \fC[static]\fR"
Searches all installed QTextCodec objects, returning the one which most recognizes the given content. May return 0.
.PP
Note that this is often a poor choice, since character encodings often use most of the available character sequences, and so only by linguistic analysis could a true match be made.
.PP
See also heuristicContentMatch().
.SH "QTextCodec* QTextCodec::codecForIndex ( int i ) \fC[static]\fR"
Returns the QTextCodec \fIi\fR places from the more recently inserted, or NULL if there is no such QTextCodec. Thus, codecForIndex(0) returns the most recently created QTextCodec.
.SH "QTextCodec* QTextCodec::codecForLocale () \fC[static]\fR"
Returns a pointer to the codec most suitable for this locale.
.SH "QTextCodec* QTextCodec::codecForMib ( int mib ) \fC[static]\fR"
Returns the QTextCodec which matches the MIBenum \fImib.\fR
.SH "QTextCodec* QTextCodec::codecForName ( const char * hint, int accuracy=0 ) \fC[static]\fR"
Searches all installed QTextCodec objects, returning the one which best matches given name. Returns NULL if no codec has a match closeness above \fIaccuracy.\fR
.PP
See also heuristicNameMatch().
.SH "void QTextCodec::deleteAllCodecs () \fC[static]\fR"
Deletes all the created codecs.
.PP
\fBWarning:\fR Do not call this function.
.PP
QApplication calls this just before exiting, to delete any QTextCodec objects that may be lying around. Since various other classes hold pointers to QTextCodec objects, it is not safe to call this function earlier.
.PP
If you are using the utility classes (like QString) but not using QApplication, calling this function at the very end of your application can be helpful to chasing down memory leaks, as QTextCodec objects will not show up.
.SH "QCString QTextCodec::fromUnicode ( const QString & uc ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QTextCodec* QTextCodec::loadCharmap ( QIODevice * iod ) \fC[static]\fR"
Reads a POSIX2 charmap definition from \fIiod.\fR The parser recognizes the following lines:
.PP
.nf
.br
   <code_set_name> \fIname\fR
.br
   <escape_char> \fIcharacter\fR
.br
   % alias \fIalias\fR
.br
   CHARMAP
.br
   <\fItoken\fR> /x\fIhexbyte\fR <U\fIunicode\fR> ...
.br
   <\fItoken\fR> /d\fIdecbyte\fR <U\fIunicode\fR> ...
.br
   <\fItoken\fR> /\fIoctbyte\fR <U\fIunicode\fR> ...
.br
   <\fItoken\fR> /\fIany\fR/\fIany\fR... <U\fIunicode\fR> ...
.br
   END CHARMAP
.fi
.PP
The resulting QTextCodec is returned (and also added to the global list of codecs). The name() of the result is taken from the code_set_name.
.PP
Note that a codec constructed in this way uses much more memory and is slower than a hand-written QTextCodec subclass, since tables in code are in memory shared by all applications simultaneously using Qt.
.PP
See also loadCharmapFile().
.SH "QTextCodec* QTextCodec::loadCharmapFile ( QString filename ) \fC[static]\fR"
A convenience function for loadCharmap().
.SH "const char* QTextCodec::locale () \fC[static]\fR"
Returns a string representing the current language.
.SH "QTextEncoder* QTextCodec::makeEncoder () const \fC[virtual]\fR"
Creates a QTextEncoder which stores enough state to encode chunks of Unicode data as char* data. The default implementation creates a stateless encoder, which is sufficient for only the simplest encodings where each Unicode character corresponds to exactly one char.
.PP
The caller is responsible for deleting the returned object.
.SH "int QTextCodec::simpleHeuristicNameMatch ( const char * name, const char * hint ) \fC[static protected]\fR"
A simple utility function for heuristicNameMatch() - it does some very minor character-skipping so that almost-exact matches score high.
.SH "QString QTextCodec::toUnicode ( const char * chars, int len ) const \fC[virtual]\fR"
Subclasses of QTextCodec must reimplement this function or makeDecoder(). It converts the first \fIlen\fR characters of \fIchars\fR to Unicode.
.PP
The default implementation makes a decoder with makeDecoder() and converts the input with that. Note that the default makeDecoder() implementation makes a decoder that simply calls this function, hence subclasses \fImust\fR reimplement one function or the other to avoid infinite recursion.
.PP
Reimplemented in QEucJpCodec, QEucKrCodec, QJisCodec, QSjisCodec, QGbkCodec and QTsciiCodec.
.SH "QString QTextCodec::toUnicode ( const QByteArray & a ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QString QTextCodec::toUnicode ( const QByteArray & a, int len ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QString QTextCodec::toUnicode ( const char * chars ) const"
This is an overloaded member function, provided for convenience.  It differs from the above function only in what argument(s) it accepts.
.SH "SEE ALSO"
.BR http://doc.trolltech.com/qtextcodec.html
.SH COPYRIGHT
Copyright 1992-2000 Trolltech AS, http://www.trolltech.com/.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.