<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /home/gvatteka/dev/qtjambi/4.3/scripts/../doc/src/qtjambi-generator.qdoc -->
<head>
<title>The Qt Jambi Generator</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1 align="center">The Qt Jambi Generator<br /><small></small></h1>
<p>The generator is a Qt application which can be used to map C++ based APIs onto equivalent Java APIs, enabling C++ programmers to easily integrate their own Qt code with Java.</p>
<p>The generator supports a selected subset of C++, covering the most common constructs in Qt. It creates the Java Api by parsing the C++ header files and generating Java source files. It also generates code to tie the Java classes to the C++ classes. Based on the Java Native Interface (JNI), this code ensures that method calls made in Java are redirected to the corresponding functions in the C++ library.</p>
<p align="center"><img src="images/generator.png" /></p><p>The Qt Jambi generator is a command line tool accepting a header file and a type system specification as arguments:</p>
<pre> ./generator [options] header-file typesystem-file</pre>
<p>The header file should include the relevant modules of the C++ based library. The type system specification is a handwritten XML document listing the types that will be made available in the generated Java API (see the <a href="qtjambi-typesystem.html">type system</tt></a> documentation for details).</p>
<p>See also: <a href="qtjambi-generatorexample.html">Qt Jambi Generator Example</tt></a></p>
<p><table width="100 %" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th colspan="2">Command Line Options</th></tr></thead>
<tr valign="top" class="odd"><td>--debug-level=sparse | medium | full</td><td>Specifies the debug level of the generator which, for example, is useful to understand how the type system is loaded.</td></tr>
<tr valign="top" class="even"><td>--dump-object-tree</td><td>Dumps the parsed object tree as plain text which can be helpful when debugging the type system.</td></tr>
<tr valign="top" class="odd"><td>--juic-file</td><td>Specifies the location of the information file that is used together with Qt Jambi's implementation of UIC (<tt>juic</tt>) to generate code for custom libraries.</td></tr>
<tr valign="top" class="even"><td>--convert-to-jui=[uifile]</td><td>Converts the given <tt>.ui</tt> file to a Java user interface file (<tt>.jui</tt>). The <tt>.jui</tt> file format's datastructure is based on Java syntax.</td></tr>
<tr valign="top" class="odd"><td>--no-cpp-h</td><td>The generator will not generate any C++ header files.</td></tr>
<tr valign="top" class="even"><td>--no-cpp-impl</td><td>The generator will not generate any C++ source files.</td></tr>
<tr valign="top" class="odd"><td>--no-java</td><td>The generator will not generate any Java source files.</td></tr>
<tr valign="top" class="even"><td>--no-metainfo</td><td>The generator will not generate any meta-info files.</td></tr>
<tr valign="top" class="odd"><td>--no-suppress-warnings</td><td>All warnings are shown even if they are suppressed by the type system specification (see the <a href="qtjambi-typesystem.html#suppress-warning">type system</tt></a> documentation for details).</td></tr>
<tr valign="top" class="even"><td>--output-directory</td><td>Specifies the output directory for the generated code.</td></tr>
</table></p>
<p>When running the generator, the header files are preprocessed (i.e., all macros and type definitions are expanded). Then enums, namespaces and classes are mapped according to the <a href="qtjambi-typesystem.html">type system</tt></a> specification. For each C++ class that is encountered, the generator creates a Java source file and a set of C++ implementation files.</p>
<p><b>Warning:</b> The Qt Jambi generator is written to handle Qt- based source code, and is not intended for mapping C++ libraries in general.</p>
<ul><li><a href="#the-java-source-file">The Java Source File</a></li>
<li><a href="#the-c-implementation-files">The C++ Implementation Files</a></li>
</ul>
<a name="the-java-source-file"></a>
<h2>The Java Source File</h2>
<p>The Java source file contains one public class with the same name as the original C++ class.</p>
<p>All public and protected members of the C++ class are included in the Java class. For each C++ function, the generator creates a native Java method, and each original member variable generates a set and get method pair since JNI only provides access to native resources through methods. For example, the C++ member variable:</p>
<pre> QString text;</pre>
<p>generates</p>
<pre> String text();
void setText(String text);</pre>
<p>in the Java API.</p>
<p>Using the <a href="qtjambi-typesystem.html">type system</tt></a> specification, it is also possible to rename or remove functions when generating the Java API, as well as changing the access privileges. It is even possible to use the type system to inject arbitrary code into the Java source file, such as an extra member method.</p>
<a name="the-c-implementation-files"></a>
<h2>The C++ Implementation Files</h2>
<p>The C++ source file contain two different parts: a shell class and the implementation of the functions declared in the Java source file.</p>
<p>The shell class inherits the original class in the C++ based Qt library, and makes it possible to reimplement virtual functions in Java and to call protected functions in the C++ based library from Java. Whenever an instance of a class is constructed in Java, a corresponding object of the shell class is constructed. If a class has been extended by a user's custom Java class, and one or more of the virtual functions in the class have been reimplemented, the shell class ensures that it is the reimplemented Java implementations that are called.</p>
<p>As with the generated Java source file, it is possible to inject code in the reimplemented virtual functions in the shell classes using the type system specification.</p>
<p>The C++ header file is primarily an implementation detail and can in most cases be ignored.</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Jambi </div></td>
</tr></table></div></address></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6711891ce757817bba854bf3f25205a
>
files
>
2360
