source: trunk/doc/swt.html

Last change on this file was 9, checked in by lpino, 18 years ago
  • Initial commit
File size: 20.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<?xml-stylesheet type="text/css"
3href="eclipseos2-xxe.css"
4?>
5<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
6"xhtml1-strict.dtd">
7<html>
8 <head>
9 <link href="eclipseos2.css" rel="stylesheet" type="text/css" />
10
11 <title>Eclipse for OS/2 Transitional Project Notes</title>
12 </head>
13
14 <body>
15 <h1>Standard Widget Toolkit</h1>
16
17 <p>The main idea of the SWT library is such that its internal
18 implementation on the certain platform is made in the terms of that
19 platform, directly using its native API through the JNI interface, so the
20 look'n'feel comes close to the regular platform applications (i.e.
21 usability; other important benefits of such approach are: easiness,
22 stability, performance). This means that there is a different
23 implementation of the basics of SWT for each supported platform; only the
24 public interface of SWT classes is, of course, the same. So the term
25 "porting" in this case means rewriting the most part of the internal logic
26 from scratch (sometimes including the whole classes) rather than just
27 correcting it for the specific OS. Therefore we have chosen to start from
28 the very beginning and go possibly like original Eclipse developers did,
29 from the basics (the top of the class hierarchy) to details, creating the
30 java and the native code in parallel. The best way to do it is to divide
31 our work into little steps (tasks): every of them is the next level of the
32 implementation and can be tested regardless of other parts that are to be
33 implemented on the next levels.</p>
34
35 <h2>Brief description of SWT parts</h2>
36
37 <p>Technically, SWT sources consist of two parts: one is written in Java,
38 another is written in C and contains native methods that communicate with
39 Java code through JNI.</p>
40
41 <p>The table below represents basic subcomponents of SWT as they were
42 defined by the original developers. There's a separate directory for each
43 subcomponent in the structure of the Eclipse sources. Packages with names
44 in <b>bold</b> are platform specific (i.e. have their own implementation
45 on each platform), other are common for all platforms (but may require
46 some adaptation for a certain OS). <code>o.e.swt</code> here and further
47 is a short form of <code>org.eclipse.swt</code>, for convenience.</p>
48
49 <table>
50 <thead>
51 <tr>
52 <th>Name</th>
53
54 <th>Description</th>
55
56 <th>Packages</th>
57
58 <th>Prognosis</th>
59 </tr>
60 </thead>
61
62 <tr>
63 <td>SWT Base</td>
64
65 <td>SWT Base. Contains the major part of all public classes and
66 interfaces. Implementations of many basic classes (Display, Widget
67 etc.) are individual for each supported platform.</td>
68
69 <td>o.e.swt.events<br />o.e.swt.graphics<br />o.e.swt.internal<br />o.e.swt.internal.image<br />o.e.swt.layout<br />o.e.swt.widgetsefwef<br /><b>o.e.swt.graphics</b><br /><b>o.e.swt.internal</b><br /><b>o.e.swt.widgets</b></td>
70
71 <td>Platform dependent parts need to be almost fully rewritten for
72 OS/2</td>
73 </tr>
74
75 <tr>
76 <td>SWT PI</td>
77
78 <td>SWT Platform Implementation. Contains platform dependent internal
79 implementations of SWT interface, including Java wrappers for platform
80 native API data structures.</td>
81
82 <td>o.e.swt.internal<br /><b>o.e.swt.internal.&lt;xxx&gt;</b></td>
83
84 <td>Needs to be almost fully rewritten for OS/2</td>
85 </tr>
86
87 <tr>
88 <td>SWT AWT</td>
89
90 <td>It's an experimental class (works currently only on Win32 and has
91 some limitations) to make it possible to embed AWT widgets to SWT
92 layout.</td>
93
94 <td><b>o.e.s.internal.awt.&lt;xxx&gt;</b></td>
95
96 <td>Can be implemented in the future?</td>
97 </tr>
98
99 <tr>
100 <td>SWT Accessibility</td>
101
102 <td>Accessibility support.</td>
103
104 <td>o.s.swt.accessibility<br /><b>o.s.swt.accessibility</b></td>
105
106 <td>Is it supported natively by OS/2 or should be emulated?</td>
107 </tr>
108
109 <tr>
110 <td>SWT Custom Widgets</td>
111
112 <td>Standard custom widgets library</td>
113
114 <td>o.e.swt.custom</td>
115
116 <td>Does not contain any platform dependent code?</td>
117 </tr>
118
119 <tr>
120 <td>SWT Drag and Drop</td>
121
122 <td>Public interface for D'n'D support</td>
123
124 <td>o.e.swt.dnd<br /><b>o.e.swt.dnd</b></td>
125
126 <td>Platform dependent implementations need to be rewritten (partially
127 ported from Win32?) for OS/2</td>
128 </tr>
129
130 <tr>
131 <td>SWT Printing</td>
132
133 <td>SWT printing capabilities</td>
134
135 <td><b>o.e.swt.printing</b><br />o.e.swt.printing</td>
136
137 <td>Needs to be almost fully rewritten for OS/2 (not a lot of work to
138 do)</td>
139 </tr>
140
141 <tr>
142 <td>SWT Program</td>
143
144 <td>OS specific program launching aspects</td>
145
146 <td><b>o.e.swt.program</b></td>
147
148 <td>Just one single class &lt;)</td>
149 </tr>
150
151 <tr>
152 <td>SWT OLE</td>
153
154 <td>OLE support</td>
155
156 <td><b>o.e.swt.ole.win32</b><br /><b>o.e.swt.internal.ole.win32</b></td>
157
158 <td>Can the similar one be implemented for OS/2 in the future?</td>
159 </tr>
160 </table>
161
162 <h3><a name="native.methods">Native methods [uncomplete]</a></h3>
163
164 <p>C sources of native methods are organized in the following way:</p>
165
166 <ul>
167 <li><kbd>swt.h</kbd> -- contains some definitions common for all C
168 code.</li>
169
170 <li><kbd>callback.h</kbd>, <kbd>callback.c</kbd> -- contain native
171 methods and helpers for <code>org.eclipse.swt.internal.Callback</code>
172 class, that allows using regular Java methods as callback functions by
173 the platform native API.</li>
174
175 <li><kbd>structs.h</kbd>, <kbd>structs.c</kbd> -- contain getter/setter
176 functions to convert data from platform native API structures to their
177 Java wrappers and back. These functions are used by native methods.</li>
178
179 <li><kbd>swt.c</kbd> -- contains definitions of native methods.</li>
180 </ul>
181
182 <p>Native methods serve as a bridge between SWT and underlying platform
183 API. One of Eclipse principles is that such mapping should be transparent
184 as much as it possible. It means that Java methods have exactly the same
185 name and behavior as their native counterparts, including the type and the
186 list of arguments and the return value. For that purposes there are Java
187 wrappers exist for native structures used by platform API functions to
188 exchange information with the application. These wrapper classes are
189 defined in the SWT PI part as well as the <code>o.e.swt.internal.OS</code>
190 class containing (almost?) all of native API-to-Java mappers. But due to
191 the fact that Java semantics differ from C there cannot be the full
192 equivalence between C and Java types, so some considerations about mapping
193 should be taken into account.</p>
194
195 <h4>Primitive types</h4>
196
197 <ul>
198 <li>C 32-bit integer types (<code>[unsigned] int</code>,
199 <code>[unsigned] long</code> and derived) are mapped to Java
200 <code>int</code> type.</li>
201
202 <li>In some cases 32-bit types that logically are boolean, can be mapped
203 to Java <code>boolean</code> type.</li>
204
205 <li>C 16-bit integer type <code>[unsigned] short</code> (and derived) is
206 mapped to Java <code>short</code> type.</li>
207
208 <li>C 8-bit integer type <code>[unsigned] char</code> (and derived) is
209 mapped to Java <code>byte</code> type.</li>
210 </ul>
211
212 <h4>Arrays</h4>
213
214 <p>...</p>
215
216 <h4>Pointers</h4>
217
218 <ul>
219 <li>Pointer to an array of primitive type is mapped to a Java reference
220 to an array of the corresponding primitive type (i.e., <code>int*</code>
221 is mapped to <code>int[]</code>). There's one exception with ASCIIZ
222 strings (see below).</li>
223
224 <li>Pointer to a C structure that have the corresponding Java wrapper is
225 mapped to a Java reference to that wrapper class (see below about
226 structures).</li>
227
228 <li>Pointer to a function and pointers to other types that are not
229 directly used by the Java code (and therefore do not have wrappers) are
230 mapped to Java <code>int</code> type.</li>
231
232 <li>Pointer to an array of C structures is mapped to Java
233 <code>int</code> array (see below).</li>
234 </ul>
235
236 <p>There's a special case with pointers to arrays and ASCIIZ strings,
237 which are <i>returned</i> by some platform API calls to represent some
238 data of variable length. There are few situations when such data is not
239 copied to the storage area provided by the caller, but the pointer to the
240 internal storage area is returned. In these situations we cannot allocate
241 the storage for that data in Java before a call to a native method,
242 because we don't know its size. The solution can be to create the
243 corresponding Java array object inside of the C implementation of the
244 native method after an API call (when we already know the size of the data
245 returned) fill it and return the reference to this object to the Java
246 caller.</p>
247
248 <p>Also there are sutiations when an API call returns a pointer to a
249 structure from its internal storage and the user should be able to access
250 this data directly to change some value (the good example is
251 <code>DosGetInfoBlocks()</code>). Since a Java structure wrapper class
252 contains a copy of the original data it doesn't make sence to use it as a
253 parameter to call such API -- it's better to return a pointer to the
254 caller "as is" using a reference to one-element array of <code>int</code>
255 type to use it for the direct access. But Java cannot read/write directly
256 to the specified memory address, so we need some helper functions to copy
257 data from a wrapper class directly to a given memory location and back.
258 These functions are overloaded versions of
259 <code>o.e.swt.internal.pm.OS.objcpy()</code>. They take two arguments: the
260 destination (the first one) and the source (the second one) of data to be
261 copied. One of them is a reference to a wrapper class and another is an
262 <code>int</code> value containing the address of (the pointer to) the
263 corresponding C structure. So, to the sequence of operations to get the
264 required result can be:</p>
265
266 <ol>
267 <li>Call API function to get the "real" pointer through an one-element
268 <code>int</code> array</li>
269
270 <li>Use it in <code>OS.objcpy()</code> to copy data to the object of the
271 wrapper class</li>
272
273 <li>Change object's nesessary fields</li>
274
275 <li>Use <code>OS.objcpy()</code> to copy data back from the object to
276 the memory</li>
277 </ol>
278
279 <p><b>Note.</b> These helper functions are potentionally dangerous and
280 should be used very carefully since there's no way to check whether a
281 given pointer really points to the structure of the appropriate type or
282 not. However, if zero or <code>null</code> is passed as one of arguments,
283 an <code>SWTError</code> exception will be thrown (this behavior depends
284 on the <code>DEBUG_CHECK_NULL_EXCEPTIONS</code> macro definition during
285 compilation of the SWT DLL).</p>
286
287 <h4>ASCIIZ strings</h4>
288
289 <p>ASCIIZ strings are mapped using references to the special Java wrapper
290 class: <code>o.e.swt.internal.pm.PSZ</code>. String data is actually
291 stored in its <code>bytes</code> field which is of <code>byte[]</code>
292 type. This class provides automatic appending of zero byte to the array
293 when constructed from Java <code>String</code> type and removing that byte
294 when converted back to <code>String</code>. Convertion between Unicode and
295 8-byte ASCII characters is done using the default system codepage. There
296 are helper functions to handle this wrapper in C:
297 <code>getPSZArray()</code>, <code>getPSZBytes()</code> and
298 <code>releasePSZBytes()</code>, see their description at the top of
299 <kbd>structs.h</kbd>.</p>
300
301 <h4>Structures</h4>
302
303 <p>C structures are mapped to Java classes (wrappers) with the same name
304 and fields (their order and names). Primitive fields' types are mapped
305 according to the rules above. For every structure the following C helper
306 functions are defined: <code>cacheXXXFids()</code> (and the correspondig
307 <code>XXX_FID_CACHE</code> structure) to cache Java field IDs,
308 <code>getXXXFields()</code> to fill the native C structure with values
309 from the Java wrapper structure before a call to platform API routine and
310 <code>setXXXFields()</code> for backward operation after a call.</p>
311
312 <p>If some field of the structure is itself a structure or a pointer to a
313 structure, there are two ways to handle this situation:</p>
314
315 <ul>
316 <li>The first way is to "unfold" such nested structure into regular
317 fields of the parent structure with names constructed according to the
318 following scheme: <code>xxx_yyy</code>, where <code>xxx</code> is the
319 name of the field representing the nested structure and <code>yyy</code>
320 is substituted with field names of that nested structure. It's useful
321 when the structure has few fields. As an example, see the
322 <code>o.e.swt.internal.pm.QMSG</code> wrapper class.</li>
323
324 <li>The second way can be used when there's a need to operate the nested
325 structure whth many fields as a whole (using a reference to it) rather
326 than accessing its fields directly. Such nested structure must have its
327 own Java wrapper (as descrbed above) and be mapped to a reference to
328 that type, and <code>getXXXFields()</code> and
329 <code>setXXXFields()</code> must correctly handle this case. For
330 example, see <code>TIB</code> and <code>TIB2</code> wrappers and their
331 getters/setters (though <code>TIB2</code> does not actually need to be
332 used as a whole, it was done so for clarity). Note that such nested
333 wrapper is newed (via the initializer expression) in the parent
334 wrapper's implicit constructor.</li>
335 </ul>
336
337 <p>Some structures have the special field (<code>cb</code> or
338 <code>cbFix</code>) that should be set to the length of the structure
339 before passing it to a function. In Win32 version this is achieved by
340 adding an extra field (<code>sizeof</code>) to Java wrapper of every
341 structure and then assigning its value to the length field when using the
342 structure from Java code. In OS/2, this is done not at the Java level, but
343 in the code of the structure's getter function. Therefore, the need in the
344 <code>sizeof</code> field is eliminated (tough,some strucrures will have
345 this field because there are some cases when arrays of that structures are
346 given us as a pointer from the C code and we need to know the address of
347 the particular structure in the array). Also, Java wrappers in OS/2 do not
348 contain the <code>cb</code> or <code>cbFix</code> field since it's useless
349 from the point of view of data the structure represents.</p>
350
351 <h4>Pointers to structures</h4>
352
353 <p>Since it's too complicated (in particular, requires two transformations
354 and two times more memory) to convert arrays of C structures to arrays of
355 their Java wrappers and back, such arrays are mapped to arrays of Java
356 <code>int</code> type, where every one or more elements of that array
357 correspond to a field from the structure, consequtively. Of course, it's
358 suitable only for structure types where all fields have the size which is
359 multiple of 32-bit <code>int</code> type, such as <code>POINTL</code> and
360 <code>RECTL</code>. This is primarily used in <code>Gpi*</code> API calls.
361 Hopefully, at the present time there is no need to work with other types
362 of structures.</p>
363
364 <p>For convenience, parameter names in the declaration (in Java) and in
365 the definition (in C) of native methods should be the same as in the
366 toolkit documentation.</p>
367
368 <h2>SWT compilation notes</h2>
369
370 <p>SWT compilation is driven by the <kbd>build.xml</kbd> located in the
371 <kbd>src\plugins\org.eclipse.swt.pm</kbd> directory of the repository. It
372 should not be used directly since there are some prerequisites that are
373 set up from the main build file.</p>
374
375 <p>Ant includes in compilation every <kbd>.java</kbd> file it finds in the
376 specified source directory. Since we go class by class, but use complete
377 common source directories from the original distribution, we need a way to
378 narrow a list of files to compile. Otherwise we will get many errors
379 because of missing platform dependent classes (which are not yet ready)
380 referenced from common sources during compilation. To exclude temporarily
381 the whole common directory is not a good idea because we might need some
382 classes from there. So, there is a special file called
383 <kbd>classes.inc</kbd> in the same directory as the SWT build file that
384 contains a list of all files to be compiled. Paths there are relative to
385 the source directories, so every entry there is just a full name of a
386 class but with dots replaced by slashes in the package name. Although file
387 masks can be used there it should be done carefully because file mask will
388 apply to every source directory (we cannot change this behavior in Ant)
389 and unnecessary files can be included.</p>
390
391 <h2>SWT porting roadmap</h2>
392
393 <p>Below is the plan and the progress of the SWT porting process. Each
394 step number and objective is a link to the corresponding step description.
395 The names of classes here, in the step descriptions and in some other
396 places follow the rule: the text in [square brackets] after the class name
397 shows the name of the SWT part the class belongs to (according to the
398 table above) and the sharp (#) sign before it means that the class is
399 platform specific, otherwise it is common.</p>
400
401 <table>
402 <thead>
403 <tr>
404 <th>#</th>
405
406 <th>Objective</th>
407
408 <th>Started</th>
409
410 <th>To be done</th>
411
412 <th>Actually done</th>
413 </tr>
414 </thead>
415
416 <tr>
417 <td><a href="swt001.html">1</a></td>
418
419 <td><a href="swt001.html">Initial moves</a>. CVS setup, dummy
420 <code>Device</code> [#Base] implementation.</td>
421
422 <td>2002-10-21</td>
423
424 <td>2003-01-15</td>
425
426 <td>2003-01-21</td>
427 </tr>
428
429 <tr>
430 <td><a href="swt002.html">2</a></td>
431
432 <td><a href="swt002.html">Basics of GUI, part 1</a>. Partially
433 implement the basic hierarchy from the <code>Widget</code> to
434 <code>Shell</code>.</td>
435
436 <td>2003-01-24</td>
437
438 <td>2003-02-24</td>
439
440 <td>2003-03-11</td>
441 </tr>
442
443 <tr>
444 <td><a href="swt003.html">3</a></td>
445
446 <td><a href="swt003.html">Basics of GUI, part 2</a>. Implement drawing
447 facilities</td>
448
449 <td>2003-03-12</td>
450
451 <td>2003-04-15</td>
452
453 <td>2003-07-11</td>
454 </tr>
455
456 <tr>
457 <td><a href="swt004.html">4</a></td>
458
459 <td><a href="swt004.html">Layout basics</a>. Implement the basics of
460 the layout management.</td>
461
462 <td>2003-03-12</td>
463
464 <td>2003-04-15</td>
465
466 <td>2003-07-11</td>
467 </tr>
468
469 <tr>
470 <td><a href="swt005.html">5</a></td>
471
472 <td><a href="swt005.html">Font handling</a>. Implement font
473 handling.</td>
474
475 <td>2003-07-12</td>
476
477 <td>2003-08-01</td>
478
479 <td>2004-02-29</td>
480 </tr>
481
482 <tr>
483 <td><a href="swt006.html">6</a></td>
484
485 <td><a href="swt006.html">Image handling</a>. Implement Image
486 handling</td>
487
488 <td>2003-07-22</td>
489
490 <td>2003-08-15</td>
491
492 <td>2003-11-24</td>
493 </tr>
494
495 <tr>
496 <td><a href="swt007.html">7</a></td>
497
498 <td><a href="swt007.html">Buttons</a>. Finish the implementation of
499 the <code>Button</code> widget</td>
500
501 <td>2004-03-01</td>
502
503 <td>2004-03-10</td>
504
505 <td>2004-10-31</td>
506 </tr>
507
508 <tr>
509 <td><a href="swt008.html">8</a></td>
510
511 <td><a href="swt008.html">Standard dialogs</a>. Implement standard
512 dialogs (<code>Dialog</code> derivants).</td>
513
514 <td>2004-12-09</td>
515
516 <td>??</td>
517
518 <td></td>
519 </tr>
520
521 <tr>
522 <td><a href="swt009.html">9</a></td>
523
524 <td><a href="swt009.html">Labels</a>. Implement the <code>Label</code>
525 class.</td>
526
527 <td>2004-12-09</td>
528
529 <td>??</td>
530
531 <td></td>
532 </tr>
533 </table>
534 </body>
535</html>
Note: See TracBrowser for help on using the repository browser.