| -rw-r--r-- | docs/start.doc | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/docs/start.doc b/docs/start.doc new file mode 100644 index 0000000..9745d9a --- a/dev/null +++ b/docs/start.doc @@ -0,0 +1,191 @@ +/*! + +\page start.html + +\title Getting Started + +<html> +<title>Qtopia - The Qt palmtop environment</title> + +<body> +<h1><i>Qtopia</i> - The Qt palmtop environment</h1> + +<p> +<i>Qtopia</i> is a windowing system for handheld devices. It offers +developers the powerful Qt API, and provides users with fast and +intuitive interaction. + +<h2>Developing for <i>Qtopia</i></h2> + +<p> +The Qt API includes rich GUI functionality, and is suitable for +both large and small applications. + +<p> +Since <i>Qtopia</i> offers the complete Qt API, you can do much of +your development on any of the other platforms for which Qt is +available - Windows, Unix/X11, or Mac OS X. However, for optimal +tailoring of your application to the smaller screen and other +demands of a handheld environment, you should use the <i>Qtopia +SDK</i>. + +<p> +The <i>Qtopia SDK</i> allows you to develop <i>Qtopia</i> +applications under the Linux desktop environment using the Qt Virtual +Framebuffer, which completely emulates the handheld <i>Qtopia</i> +environment. It also includes cross-compiler software so that you can +compile your application to run on the target handheld device. +If you do not already have the Qtopia SDK (this document is normally +part of the SDK), contact info@trolltech.com, or see the +<a href=http://www.trolltech.com>Trolltech</a> web site. + +<p>To build applications for the SHARP SL5000 or similar StrongARM-based devices, +you will also need a StrongARM cross compiler. Entrants in the programming +contest for this device will have received both the SDK and a cross-compiler. + +<p> +The SDK includes an example program. We recommend that you compile and +run this example to learn how things work, before tackling your own +projects. + +<p> +To compile the example program for running on the Linux desktop: + +<ol> + <li> + <p> + Check the environment is correct: + + <p> +<pre> + export QPEDIR=/opt/Qtopia + export QTDIR=/opt/Qtopia + export PATH=$QTDIR/bin:$PATH + export TMAKEPATH=/opt/Qtopia/tmake/lib/qws/linux-generic-g++ + export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH +</pre> + + <li> Take a copy of the example: + +<pre> + cd somewhere + cp -r $QPEDIR/example . + cd example +</pre> + + <li> Generate a Makefile: + +<pre> + tmake -o Makefile example.pro +</pre> + + <li> Build the example: + +<pre> + make +</pre> + + <li> Install it: + +<pre> + su # root privileges required to install + cp example.desktop $QPEDIR/apps/Applications + cp Example.png $QPEDIR/pics + cp example $QPEDIR/bin + exit # no need to be root anymore +</pre> + + <li> To run it, first run the Qt Virtual Framebuffer: + +<pre> + qvfb & +</pre> + + <li> Then run the <i>Qtopia</i> environment: + +<pre> + qpe +</pre> + +<p> + Your application should be available in the Applications tab visible +inside the Qt Virtual Framebuffer window. +</p> + + <li> If you want to distribute your applications to others, build an RPM package, e.g.: +<pre> + mkipks -rpm -arch i386 example.control +</pre> +</ol> + +<p> +To make your own application, use the example program as a model. Make sure that +when you add files to your project, you also add them +to your project file (e.g. <tt>example.pro</tt>) and rerun the +<tt>tmake</tt> command to update the <tt>Makefile</tt>. + +<p> +To build you application for the SHARP SL5000 rather than just running +on the desktop, the process is similar: + +<ol> + <li> + <p> + Check the environment is correctly set for the SHARP SL5000: + + <p> +<pre> + export QPEDIR=/opt/Qtopia/sharp + export QTDIR=/opt/Qtopia/sharp + export PATH=$QTDIR/bin:/usr/local/arm/bin:$PATH + export TMAKEPATH=/opt/Qtopia/tmake/lib/qws/linux-sharp-g++ +</pre> + + <li> Build and install exactly the same as you did for the desktop + (note that the generated Makefile is different): +<pre> + make clean + tmake -o Makefile example.pro + ... <i>etc.</i> +</pre> + + <li> To install it on a device, build an ipk package file (you should be root + to do this, since then it will strip the executable for you): +<pre> + mkipks example.control +</pre> + +<p> + The resulting <tt>example-1.0.0.ipk</tt> can be installed on the +SL5000 by using <i>Qtopia Desktop</i>. +</p> + +</ol> + +<h3>Building Your Own Applications</h3> + +Once you have built the example, you can proceed with writing +your own applicatons. If you are not familiar with Qt, you should +consult the Qt documentation by pointing your web browser at +<a href=file:/opt/Qtopia/doc/html/index.html><tt>/opt/Qtopia/doc/html/index.html</tt></a> +when you have installed the SDK, or use the online +<a href=http://doc.trolltech.com/>Trolltech Documentation Site</a>. +The <a href="http://www.trolltech.com/products/qt/whitepaper.html">Qt +Whitepaper</a> provides a good overview of, and introduction to, the +Qt API. + +<p> +When you add more files to your application, just edit the project +file (e.g. <tt>example.pro</tt>) and rerun the <tt>tmake</tt> +command. + +<p> +The <tt>.ui</tt> files are <i>Qt Designer</i> user interface files. +You can create and edit these using <i>Qt Designer</i>: +<pre> + designer example.ui +</pre> +<i>Qt Designer</i>'s online documentation includes a complete +tutorial. + +*/ |