qtextcodec.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QTextCodec 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QTextCodec \- Conversion between text encodings
.SH SYNOPSIS
Almost all the functions in this class are reentrant when Qt is built with thread support. The exceptions are \fB~QTextCodec\fR(), \fBsetCodecForTr\fR(), \fBsetCodecForCStrings\fR(), and \fBQTextCodec\fR().</p>
.PP
\fC#include <qtextcodec.h>\fR
.PP
Inherited by QBig5Codec, QBig5hkscsCodec, QEucJpCodec, QEucKrCodec, QGb18030Codec, QJisCodec, QHebrewCodec, QSjisCodec, and QTsciiCodec.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "virtual \fB~QTextCodec\fR ()"
.br
.ti -1c
.BI "virtual const char * \fBname\fR () const = 0"
.br
.ti -1c
.BI "virtual const char * \fBmimeName\fR () const"
.br
.ti -1c
.BI "virtual int \fBmibEnum\fR () const = 0"
.br
.ti -1c
.BI "virtual QTextDecoder * \fBmakeDecoder\fR () const"
.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 "virtual QCString \fBfromUnicode\fR ( const QString & uc, int & lenInOut ) const"
.br
.ti -1c
.BI "QCString \fBfromUnicode\fR ( const QString & uc ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const QByteArray & a, int len ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const QByteArray & a ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const QCString & a, int len ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const QCString & a ) const"
.br
.ti -1c
.BI "QString \fBtoUnicode\fR ( const char * chars ) const"
.br
.ti -1c
.BI "virtual bool \fBcanEncode\fR ( QChar ch ) const"
.br
.ti -1c
.BI "virtual bool \fBcanEncode\fR ( const QString & s ) const"
.br
.ti -1c
.BI "virtual int \fBheuristicContentMatch\fR ( const char * chars, int len ) const = 0"
.br
.ti -1c
.BI "virtual int \fBheuristicNameMatch\fR ( const char * hint ) const"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "QTextCodec * \fBloadCharmap\fR ( QIODevice * iod )"
.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 * name, 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 \fBsetCodecForLocale\fR ( QTextCodec * c )"
.br
.ti -1c
.BI "QTextCodec * \fBcodecForTr\fR ()"
.br
.ti -1c
.BI "void \fBsetCodecForTr\fR ( QTextCodec * c )"
.br
.ti -1c
.BI "QTextCodec * \fBcodecForCStrings\fR ()"
.br
.ti -1c
.BI "void \fBsetCodecForCStrings\fR ( QTextCodec * c )"
.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
The QTextCodec class provides conversion between text encodings.
.PP
Qt uses Unicode to store, draw and manipulate strings. In many situations you may wish to deal with data that uses a different encoding. For example, most japanese documents are still stored in Shift-JIS or ISO2022, while Russian users often have their documents in KOI8-R or CP1251.
.PP
Qt provides a set of QTextCodec classes to help with converting non-Unicode formats to and from Unicode. You can also create your own codec classes (see later).
.PP
The supported encodings are:
.TP
Latin1
.TP
Big5 -- Chinese
.TP
Big5-HKSCS -- Chinese
.TP
eucJP -- Japanese
.TP
eucKR -- Korean
.TP
GB2312 -- Chinese
.TP
GBK -- Chinese
.TP
GB18030 -- Chinese
.TP
JIS7 -- Japanese
.TP
Shift-JIS -- Japanese
.TP
TSCII -- Tamil
.TP
utf8 -- Unicode, 8-bit
.TP
utf16 -- Unicode
.TP
KOI8-R -- Russian
.TP
KOI8-U -- Ukrainian
.TP
ISO8859-1 -- Western
.TP
ISO8859-2 -- Central European
.TP
ISO8859-3 -- Central European
.TP
ISO8859-4 -- Baltic
.TP
ISO8859-5 -- Cyrillic
.TP
ISO8859-6 -- Arabic
.TP
ISO8859-7 -- Greek
.TP
ISO8859-8 -- Hebrew, visually ordered
.TP
ISO8859-8-i -- Hebrew, logically ordered
.TP
ISO8859-9 -- Turkish
.TP
ISO8859-10
.TP
ISO8859-13
.TP
ISO8859-14
.TP
ISO8859-15 -- Western
.TP
IBM 850
.TP
IBM 866
.TP
CP874
.TP
CP1250 -- Central European
.TP
CP1251 -- Cyrillic
.TP
CP1252 -- Western
.TP
CP1253 -- Greek
.TP
CP1254 -- Turkish
.TP
CP1255 -- Hebrew
.TP
CP1256 -- Arabic
.TP
CP1257 -- Baltic
.TP
CP1258
.TP
Apple Roman
.TP
TIS-620 -- Thai
.PP
QTextCodecs can be used as follows to convert some locally encoded string to Unicode. Suppose you have some string encoded in Russian KOI8-R encoding, and want to convert it to Unicode. The simple way to do this is:
.PP
.nf
.br
  QCString locallyEncoded = "..."; // text to convert
.br
  QTextCodec *codec = QTextCodec::codecForName("KOI8-R"); // get the codec for KOI8-R
.br
  QString unicodeString = codec->toUnicode( locallyEncoded );
.br
.fi
.PP
After this, \fCunicodeString\fR holds the text converted to Unicode. Converting a string from Unicode to the local encoding is just as easy:
.PP
.nf
.br
  QString unicodeString = "..."; // any Unicode text
.br
  QTextCodec *codec = QTextCodec::codecForName("KOI8-R"); // get the codec for KOI8-R
.br
  QCString locallyEncoded = codec->fromUnicode( unicodeString );
.br
.fi
.PP
Some care must be taken when trying to convert the data in chunks, for example, when receiving it over a network. In such cases it is possible that a multi-byte character will be split over two chunks. At best this might result in the loss of a character and at worst cause the entire conversion to fail.
.PP
The approach to use in these situations is to create a QTextDecoder object for the codec and use this QTextDecoder for the whole decoding process, as shown below:
.PP
.nf
.br
  QTextCodec *c = QTextCodec::codecForName( "Shift-JIS" );
.br
  QTextDecoder *decoder = c->makeDecoder();
.br
.br
  QString unicodeString;
.br
  while( receiving_data ) {
.br
      QByteArray chunk = new_data;
.br
      unicodeString += decoder->toUnicode( chunk.data(), chunk.length() );
.br
  }
.br
.fi
.PP
The QTextDecoder object maintains state between chunks and therefore works correctly even if a multi-byte character is split between chunks.
.SH "Creating your own Codec class"
By making objects of subclasses of QTextCodec, support for new text encodings can be added to Qt.
.PP
More recently created QTextCodec objects take precedence over earlier ones.
.PP
You may find it more convenient to make your codec class available as a plugin; see the plugin documentation for more details.
.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 by QTextStream, and under X11, for the locale-specific character input and output.
.PP
To add support for another 8-bit encoding to Qt, make a subclass of QTextCodec and implement at least the following methods:
.PP
.nf
.br
   const char* name() const
.br
.fi
Return the official name for the encoding.
.PP
.nf