source: trunk/doc/html/qtranslator.html@ 208

Last change on this file since 208 was 190, checked in by rudi, 14 years ago

reference documentation added

File size: 18.3 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/kernel/qtranslator.cpp:216 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QTranslator Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QTranslator Class Reference</h1>
33
34<p>The QTranslator class provides internationalization support for text
35output.
36<a href="#details">More...</a>
37<p><tt>#include &lt;<a href="qtranslator-h.html">qtranslator.h</a>&gt;</tt>
38<p>Inherits <a href="qobject.html">QObject</a>.
39<p><a href="qtranslator-members.html">List of all member functions.</a>
40<h2>Public Members</h2>
41<ul>
42<li class=fn><a href="#QTranslator"><b>QTranslator</b></a> ( QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
43<li class=fn><a href="#~QTranslator"><b>~QTranslator</b></a> ()</li>
44<li class=fn>QString find ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;char&nbsp;*&nbsp;comment = 0 ) const &nbsp;<em>(obsolete)</em></li>
45<li class=fn>virtual QTranslatorMessage <a href="#findMessage"><b>findMessage</b></a> ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;char&nbsp;*&nbsp;comment = 0 ) const</li>
46<li class=fn>bool <a href="#load"><b>load</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;filename, const&nbsp;QString&nbsp;&amp;&nbsp;directory = QString::null, const&nbsp;QString&nbsp;&amp;&nbsp;search_delimiters = QString::null, const&nbsp;QString&nbsp;&amp;&nbsp;suffix = QString::null )</li>
47<li class=fn>bool <a href="#load-2"><b>load</b></a> ( const&nbsp;uchar&nbsp;*&nbsp;data, int&nbsp;len )</li>
48<li class=fn>void <a href="#clear"><b>clear</b></a> ()</li>
49<li class=fn>enum <a href="#SaveMode-enum"><b>SaveMode</b></a> { Everything, Stripped }</li>
50<li class=fn>bool <a href="#save"><b>save</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;filename, SaveMode&nbsp;mode = Everything )</li>
51<li class=fn>void <a href="#insert"><b>insert</b></a> ( const&nbsp;QTranslatorMessage&nbsp;&amp;&nbsp;message )</li>
52<li class=fn>void insert ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;QString&nbsp;&amp;&nbsp;translation ) &nbsp;<em>(obsolete)</em></li>
53<li class=fn>void <a href="#remove"><b>remove</b></a> ( const&nbsp;QTranslatorMessage&nbsp;&amp;&nbsp;message )</li>
54<li class=fn>void remove ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText ) &nbsp;<em>(obsolete)</em></li>
55<li class=fn>bool <a href="#contains"><b>contains</b></a> ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;char&nbsp;*&nbsp;comment = 0 ) const</li>
56<li class=fn>void <a href="#squeeze"><b>squeeze</b></a> ( SaveMode&nbsp;mode = Everything )</li>
57<li class=fn>void <a href="#unsqueeze"><b>unsqueeze</b></a> ()</li>
58<li class=fn>QValueList&lt;QTranslatorMessage&gt; <a href="#messages"><b>messages</b></a> () const</li>
59<li class=fn>bool <a href="#isEmpty"><b>isEmpty</b></a> () const</li>
60</ul>
61<hr><a name="details"></a><h2>Detailed Description</h2>
62
63
64<p> The QTranslator class provides <a href="i18n.html#internationalization">internationalization</a> support for text
65output.
66<p>
67
68
69<p> An object of this class contains a set of <a href="qtranslatormessage.html">QTranslatorMessage</a>
70objects, each of which specifies a translation from a source
71language to a target language. QTranslator provides functions to
72look up translations, add new ones, remove them, load and save
73them, etc.
74<p> The most common use of QTranslator is to: load a translator file
75created with <a href="linguist-manual.html">Qt Linguist</a>,
76install it using <a href="qapplication.html#installTranslator">QApplication::installTranslator</a>(), and use it via
77<a href="qobject.html#tr">QObject::tr</a>(). For example:
78<p> <pre>
79 int main( int argc, char ** argv )
80 {
81 <a href="qapplication.html">QApplication</a> app( argc, argv );
82
83 QTranslator translator( 0 );
84 translator.<a href="#load">load</a>( "french.qm", "." );
85 app.<a href="qapplication.html#installTranslator">installTranslator</a>( &amp;translator );
86
87 MyWidget m;
88 app.<a href="qapplication.html#setMainWidget">setMainWidget</a>( &amp;m );
89 m.show();
90
91 return app.<a href="qapplication.html#exec">exec</a>();
92 }
93 </pre>
94
95Note that the translator must be created <em>before</em> the
96application's main window.
97<p> Most applications will never need to do anything else with this
98class. The other functions provided by this class are useful for
99applications that work on translator files.
100<p> We call a translation a "messsage". For this reason, translation
101files are sometimes referred to as "message files".
102<p> It is possible to lookup a translation using <a href="#findMessage">findMessage</a>() (as
103<a href="qobject.html#tr">tr</a>() and <a href="qapplication.html#translate">QApplication::translate</a>() do) and <a href="#contains">contains</a>(), to insert a
104new translation messsage using <a href="#insert">insert</a>(), and to remove one using
105<a href="#remove">remove</a>().
106<p> Translation tools often need more information than the bare source
107text and translation, for example, context information to help
108the translator. But end-user programs that are using translations
109usually only need lookup. To cater for these different needs,
110QTranslator can use stripped translator files that use the minimum
111of memory and which support little more functionality than
112findMessage().
113<p> Thus, <a href="#load">load</a>() may not load enough information to make anything more
114than findMessage() work. <a href="#save">save</a>() has an argument indicating
115whether to save just this minimum of information or to save
116everything.
117<p> "Everything" means that for each translation item the following
118information is kept:
119<p> <ul>
120<li> The <em>translated text</em> - the return value from <a href="qobject.html#tr">tr</a>().
121<li> The input key:
122<ul>
123<li> The <em>source text</em> - usually the argument to tr().
124<li> The <em>context</em> - usually the class name for the tr() caller.
125<li> The <em>comment</em> - a comment that helps disambiguate different uses
126of the same text in the same context.
127</ul>
128</ul>
129<p> The minimum for each item is just the information necessary for
130<a href="#findMessage">findMessage</a>() to return the right text. This may include the
131source, context and comment, but usually it is just a hash value
132and the translated text.
133<p> For example, the "Cancel" in a dialog might have "Anuluj" when the
134program runs in Polish (in this case the source text would be
135"Cancel"). The context would (normally) be the dialog's class
136name; there would normally be no comment, and the translated text
137would be "Anuluj".
138<p> But it's not always so simple. The Spanish version of a printer
139dialog with settings for two-sided printing and binding would
140probably require both "Activado" and "Activada" as translations
141for "Enabled". In this case the source text would be "Enabled" in
142both cases, and the context would be the dialog's class name, but
143the two items would have disambiguating comments such as
144"two-sided printing" for one and "binding" for the other. The
145comment enables the translator to choose the appropriate gender
146for the Spanish version, and enables Qt to distinguish between
147translations.
148<p> Note that when QTranslator loads a stripped file, most functions
149do not work. The functions that do work with stripped files are
150explicitly documented as such.
151<p> <p>See also <a href="qtranslatormessage.html">QTranslatorMessage</a>, <a href="qapplication.html#installTranslator">QApplication::installTranslator</a>(), <a href="qapplication.html#removeTranslator">QApplication::removeTranslator</a>(), <a href="qobject.html#tr">QObject::tr</a>(), <a href="qapplication.html#translate">QApplication::translate</a>(), <a href="environment.html">Environment Classes</a>, and <a href="i18n.html">Internationalization with Qt</a>.
152
153<hr><h2>Member Type Documentation</h2>
154<h3 class=fn><a name="SaveMode-enum"></a>QTranslator::SaveMode</h3>
155
156<p> This enum type defines how QTranslator writes translation
157files. There are two modes:
158<ul>
159<li><tt>QTranslator::Everything</tt> - files are saved with all available information
160<li><tt>QTranslator::Stripped</tt> - files are saved with just enough information for
161end-user applications
162</ul><p> Note that when QTranslator loads a stripped file, most functions do
163not work. The functions that do work with stripped files are
164explicitly documented as such.
165
166<hr><h2>Member Function Documentation</h2>
167<h3 class=fn><a name="QTranslator"></a>QTranslator::QTranslator ( <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
168</h3>
169Constructs an empty message file object that is not connected to
170any file. The object is called <em>name</em> with parent <em>parent</em>.
171
172<h3 class=fn><a name="~QTranslator"></a>QTranslator::~QTranslator ()
173</h3>
174Destroys the object and frees any allocated resources.
175
176<h3 class=fn>void <a name="clear"></a>QTranslator::clear ()
177</h3>
178Empties this translator of all contents.
179<p> This function works with stripped translator files.
180
181<h3 class=fn>bool <a name="contains"></a>QTranslator::contains ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;char&nbsp;*&nbsp;comment = 0 ) const
182</h3>
183Returns TRUE if this message file contains a message with the key
184(<em>context</em>, <em>sourceText</em>, <em>comment</em>); otherwise returns FALSE.
185<p> This function works with stripped translator files.
186<p> (This is is a one-liner that calls <a href="#findMessage">findMessage</a>().)
187
188<h3 class=fn><a href="qstring.html">QString</a> <a name="find"></a>QTranslator::find ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;char&nbsp;*&nbsp;comment = 0 ) const
189</h3>
190
191<b>This function is obsolete.</b> It is provided to keep old source working. We strongly advise against using it in new code.
192<p> Please use <a href="#findMessage">findMessage</a>() instead.
193<p> Returns the translation for the key (<em>context</em>, <em>sourceText</em>,
194<em>comment</em>) or <a href="qstring.html#QString-null">QString::null</a> if there is none in this translator.
195
196<h3 class=fn><a href="qtranslatormessage.html">QTranslatorMessage</a> <a name="findMessage"></a>QTranslator::findMessage ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;char&nbsp;*&nbsp;comment = 0 ) const<tt> [virtual]</tt>
197</h3> Returns the <a href="qtranslatormessage.html">QTranslatorMessage</a> for the key
198(<em>context</em>, <em>sourceText</em>, <em>comment</em>). If none is found,
199also tries (<em>context</em>, <em>sourceText</em>, "").
200
201<h3 class=fn>void <a name="insert"></a>QTranslator::insert ( const&nbsp;<a href="qtranslatormessage.html">QTranslatorMessage</a>&nbsp;&amp;&nbsp;message )
202</h3>
203Inserts <em>message</em> into this message file.
204<p> This function does <em>not</em> work with stripped translator files. It
205may appear to, but that is not dependable.
206<p> <p>See also <a href="#remove">remove</a>().
207
208<h3 class=fn>void <a name="insert-2"></a>QTranslator::insert ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;translation )
209</h3>
210
211This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
212<p> <b>This function is obsolete.</b> It is provided to keep old source working. We strongly advise against using it in new code.
213<p>
214<h3 class=fn>bool <a name="isEmpty"></a>QTranslator::isEmpty () const
215</h3>
216Returns TRUE if this translator is empty, otherwise returns FALSE.
217This function works with stripped and unstripped translation files.
218
219<h3 class=fn>bool <a name="load"></a>QTranslator::load ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;filename, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;directory = QString::null, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;search_delimiters = QString::null, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;suffix = QString::null )
220</h3>
221Loads <em>filename</em>, which may be an absolute file name or relative
222to <em>directory</em>. The previous contents of this translator object
223is discarded. Returns TRUE if the file is loaded successfully;
224otherwise returns FALSE.
225<p> If the full file name does not exist, other file names are tried
226in the following order:
227<p> <ol type=1>
228<li> File name with <em>suffix</em> appended (".qm" if the <em>suffix</em> is
229<a href="qstring.html#QString-null">QString::null</a>).
230<li> File name with text after a character in <em>search_delimiters</em>
231stripped ("_." is the default for <em>search_delimiters</em> if it is
232QString::null).
233<li> File name stripped and <em>suffix</em> appended.
234<li> File name stripped further, etc.
235</ol>
236<p> For example, an application running in the fr_CA locale
237(French-speaking Canada) might call <a href="#load">load</a>("foo.fr_ca",
238"/opt/foolib"). load() would then try to open the first existing
239readable file from this list:
240<p> <ol type=1>
241<li> /opt/foolib/foo.fr_ca
242<li> /opt/foolib/foo.fr_ca.qm
243<li> /opt/foolib/foo.fr
244<li> /opt/foolib/foo.fr.qm
245<li> /opt/foolib/foo
246<li> /opt/foolib/foo.qm
247</ol>
248<p> <p>See also <a href="#save">save</a>().
249
250<p>Example: <a href="i18n-example.html#x1950">i18n/main.cpp</a>.
251<h3 class=fn>bool <a name="load-2"></a>QTranslator::load ( const&nbsp;uchar&nbsp;*&nbsp;data, int&nbsp;len )
252</h3>
253This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
254<p>
255<p> Loads the .qm file data <em>data</em> of length <em>len</em> into the
256translator. Returns TRUE if the data is loaded successfully;
257otherwise returns FALSE.
258<p> The data is not copied. The caller must be able to guarantee that <em>data</em>
259will not be deleted or modified.
260
261<h3 class=fn><a href="qvaluelist.html">QValueList</a>&lt;QTranslatorMessage&gt; <a name="messages"></a>QTranslator::messages () const
262</h3>
263Returns a list of the messages in the translator. This function is
264rather slow. Because it is seldom called, it's optimized for
265simplicity and small size, rather than speed.
266<p> If you want to iterate over the list, you should iterate over a
267copy, e.g.
268<pre>
269 <a href="qvaluelist.html">QValueList</a>&lt;QTranslatorMessage&gt; list = myTranslator.messages();
270 QValueList&lt;QTranslatorMessage&gt;::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
271 while ( it != list.<a href="qvaluelist.html#end">end</a>() ) {
272 process_message( *it );
273 ++it;
274 }
275 </pre>
276
277
278<h3 class=fn>void <a name="remove"></a>QTranslator::remove ( const&nbsp;<a href="qtranslatormessage.html">QTranslatorMessage</a>&nbsp;&amp;&nbsp;message )
279</h3>
280Removes <em>message</em> from this translator.
281<p> This function works with stripped translator files.
282<p> <p>See also <a href="#insert">insert</a>().
283
284<h3 class=fn>void <a name="remove-2"></a>QTranslator::remove ( const&nbsp;char&nbsp;*&nbsp;context, const&nbsp;char&nbsp;*&nbsp;sourceText )
285</h3>
286
287This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
288<p> <b>This function is obsolete.</b> It is provided to keep old source working. We strongly advise against using it in new code.
289<p> Removes the translation associated to the key (<em>context</em>, <em>sourceText</em>,
290"") from this translator.
291
292<h3 class=fn>bool <a name="save"></a>QTranslator::save ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;filename, <a href="qtranslator.html#SaveMode-enum">SaveMode</a>&nbsp;mode = Everything )
293</h3>
294Saves this message file to <em>filename</em>, overwriting the previous
295contents of <em>filename</em>. If <em>mode</em> is <a href="#SaveMode-enum">Everything</a> (the
296default), all the information is preserved. If <em>mode</em> is <a href="#SaveMode-enum">Stripped</a>, any information that is not necessary for <a href="#findMessage">findMessage</a>()
297is stripped away.
298<p> <p>See also <a href="#load">load</a>().
299
300<h3 class=fn>void <a name="squeeze"></a>QTranslator::squeeze ( <a href="qtranslator.html#SaveMode-enum">SaveMode</a>&nbsp;mode = Everything )
301</h3>
302Converts this message file to the compact format used to store
303message files on disk.
304<p> You should never need to call this directly; <a href="#save">save</a>() and other
305functions call it as necessary. <em>mode</em> is for internal use.
306<p> <p>See also <a href="#save">save</a>() and <a href="#unsqueeze">unsqueeze</a>().
307
308<h3 class=fn>void <a name="unsqueeze"></a>QTranslator::unsqueeze ()
309</h3>
310Converts this message file into an easily modifiable data
311structure, less compact than the format used in the files.
312<p> You should never need to call this function; it is called by
313<a href="#insert">insert</a>() and friends as necessary.
314<p> <p>See also <a href="#squeeze">squeeze</a>().
315
316<!-- eof -->
317<hr><p>
318This file is part of the <a href="index.html">Qt toolkit</a>.
319Copyright &copy; 1995-2007
320<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
321<table width=100% cellspacing=0 border=0><tr>
322<td>Copyright &copy; 2007
323<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
324<td align=right><div align=right>Qt 3.3.8</div>
325</table></div></address></body>
326</html>
Note: See TracBrowser for help on using the repository browser.