summaryrefslogtreecommitdiff
path: root/docs/start.doc
Unidiff
Diffstat (limited to 'docs/start.doc') (more/less context) (ignore whitespace changes)
-rw-r--r--docs/start.doc191
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 @@
1/*!
2
3\page start.html
4
5\title Getting Started
6
7<html>
8<title>Qtopia - The Qt palmtop environment</title>
9
10<body>
11<h1><i>Qtopia</i> - The Qt palmtop environment</h1>
12
13<p>
14<i>Qtopia</i> is a windowing system for handheld devices. It offers
15developers the powerful Qt API, and provides users with fast and
16intuitive interaction.
17
18<h2>Developing for <i>Qtopia</i></h2>
19
20<p>
21The Qt API includes rich GUI functionality, and is suitable for
22both large and small applications.
23
24<p>
25Since <i>Qtopia</i> offers the complete Qt API, you can do much of
26your development on any of the other platforms for which Qt is
27available - Windows, Unix/X11, or Mac OS X. However, for optimal
28tailoring of your application to the smaller screen and other
29demands of a handheld environment, you should use the <i>Qtopia
30SDK</i>.
31
32<p>
33The <i>Qtopia SDK</i> allows you to develop <i>Qtopia</i>
34applications under the Linux desktop environment using the Qt Virtual
35Framebuffer, which completely emulates the handheld <i>Qtopia</i>
36environment. It also includes cross-compiler software so that you can
37compile your application to run on the target handheld device.
38If you do not already have the Qtopia SDK (this document is normally
39part of the SDK), contact info@trolltech.com, or see the
40<a href=http://www.trolltech.com>Trolltech</a> web site.
41
42<p>To build applications for the SHARP SL5000 or similar StrongARM-based devices,
43you will also need a StrongARM cross compiler. Entrants in the programming
44contest for this device will have received both the SDK and a cross-compiler.
45
46<p>
47The SDK includes an example program. We recommend that you compile and
48run this example to learn how things work, before tackling your own
49projects.
50
51<p>
52To compile the example program for running on the Linux desktop:
53
54<ol>
55 <li>
56 <p>
57 Check the environment is correct:
58
59 <p>
60<pre>
61 export QPEDIR=/opt/Qtopia
62 export QTDIR=/opt/Qtopia
63 export PATH=$QTDIR/bin:$PATH
64 export TMAKEPATH=/opt/Qtopia/tmake/lib/qws/linux-generic-g++
65 export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
66</pre>
67
68 <li> Take a copy of the example:
69
70<pre>
71 cd somewhere
72 cp -r $QPEDIR/example .
73 cd example
74</pre>
75
76 <li> Generate a Makefile:
77
78<pre>
79 tmake -o Makefile example.pro
80</pre>
81
82 <li> Build the example:
83
84<pre>
85 make
86</pre>
87
88 <li> Install it:
89
90<pre>
91 su # root privileges required to install
92 cp example.desktop $QPEDIR/apps/Applications
93 cp Example.png $QPEDIR/pics
94 cp example $QPEDIR/bin
95 exit # no need to be root anymore
96</pre>
97
98 <li> To run it, first run the Qt Virtual Framebuffer:
99
100<pre>
101 qvfb &amp;
102</pre>
103
104 <li> Then run the <i>Qtopia</i> environment:
105
106<pre>
107 qpe
108</pre>
109
110<p>
111 Your application should be available in the Applications tab visible
112inside the Qt Virtual Framebuffer window.
113</p>
114
115 <li> If you want to distribute your applications to others, build an RPM package, e.g.:
116<pre>
117 mkipks -rpm -arch i386 example.control
118</pre>
119</ol>
120
121<p>
122To make your own application, use the example program as a model. Make sure that
123when you add files to your project, you also add them
124to your project file (e.g. <tt>example.pro</tt>) and rerun the
125<tt>tmake</tt> command to update the <tt>Makefile</tt>.
126
127<p>
128To build you application for the SHARP SL5000 rather than just running
129on the desktop, the process is similar:
130
131<ol>
132 <li>
133 <p>
134 Check the environment is correctly set for the SHARP SL5000:
135
136 <p>
137<pre>
138 export QPEDIR=/opt/Qtopia/sharp
139 export QTDIR=/opt/Qtopia/sharp
140 export PATH=$QTDIR/bin:/usr/local/arm/bin:$PATH
141 export TMAKEPATH=/opt/Qtopia/tmake/lib/qws/linux-sharp-g++
142</pre>
143
144 <li> Build and install exactly the same as you did for the desktop
145 (note that the generated Makefile is different):
146<pre>
147 make clean
148 tmake -o Makefile example.pro
149 ... <i>etc.</i>
150</pre>
151
152 <li> To install it on a device, build an ipk package file (you should be root
153 to do this, since then it will strip the executable for you):
154<pre>
155 mkipks example.control
156</pre>
157
158<p>
159 The resulting <tt>example-1.0.0.ipk</tt> can be installed on the
160SL5000 by using <i>Qtopia Desktop</i>.
161</p>
162
163</ol>
164
165<h3>Building Your Own Applications</h3>
166
167Once you have built the example, you can proceed with writing
168your own applicatons. If you are not familiar with Qt, you should
169consult the Qt documentation by pointing your web browser at
170<a href=file:/opt/Qtopia/doc/html/index.html><tt>/opt/Qtopia/doc/html/index.html</tt></a>
171when you have installed the SDK, or use the online
172<a href=http://doc.trolltech.com/>Trolltech Documentation Site</a>.
173The <a href="http://www.trolltech.com/products/qt/whitepaper.html">Qt
174Whitepaper</a> provides a good overview of, and introduction to, the
175Qt API.
176
177<p>
178When you add more files to your application, just edit the project
179file (e.g. <tt>example.pro</tt>) and rerun the <tt>tmake</tt>
180command.
181
182<p>
183The <tt>.ui</tt> files are <i>Qt Designer</i> user interface files.
184You can create and edit these using <i>Qt Designer</i>:
185<pre>
186 designer example.ui
187</pre>
188<i>Qt Designer</i>'s online documentation includes a complete
189tutorial.
190
191*/