qtextcodec.3qt

Trolltech公司发布的基于C++图形开发环境

'\" t
.TH QTextCodec 3qt "24 January 2005" "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 \- Provides conversion between text encodings
.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 const char* \fBname\fR () const"
.br
.ti -1c
.BI "virtual int \fBmibEnum\fR () const"
.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 &, 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
.ti -1c
.BI "virtual int \fBheuristicContentMatch\fR ( const char * " "chars" ", int len ) const"
.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 * ) "
.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.