| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
|---|
| 2 | <?xml-stylesheet type="text/css"
|
|---|
| 3 | href="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 type="text/css"
|
|---|
| 10 | href="eclipseos2.css"
|
|---|
| 11 | rel="stylesheet" />
|
|---|
| 12 |
|
|---|
| 13 | <title>Eclipse for OS/2 Transitional Project Notes</title>
|
|---|
| 14 | </head>
|
|---|
| 15 |
|
|---|
| 16 | <body>
|
|---|
| 17 | <h1>SWT Step 1. Initial moves</h1>
|
|---|
| 18 |
|
|---|
| 19 | <h2>Objective</h2>
|
|---|
| 20 |
|
|---|
| 21 | <p>Start our work by setting up a working environment (cvs) and creating a
|
|---|
| 22 | skeleton of the SWT with the least possible functionality, that can be
|
|---|
| 23 | successfully compiled and tested with the simplest dummy example (creation
|
|---|
| 24 | of the <code>Display</code> object).</p>
|
|---|
| 25 |
|
|---|
| 26 | <h2>Task notes</h2>
|
|---|
| 27 |
|
|---|
| 28 | <p>The one of the basics of SWT is <code>o.e.swt.widgets.Display</code>
|
|---|
| 29 | class that represents an SWT session. It represents a connection between
|
|---|
| 30 | SWT an the underlying platform's GUI and manages the platform event
|
|---|
| 31 | loop. It is created by the application's main thread (UI thread) which
|
|---|
| 32 | runs the event loop and dispatches events directly from it. Every (?) SWT
|
|---|
| 33 | program creates a <code>Display</code> object so it's a good place to
|
|---|
| 34 | begin. The minimum functionality to implement is the message queue
|
|---|
| 35 | creation/deletion, <code>readAndDispatch()</code> method and <code>internal_new_GC()</code>,
|
|---|
| 36 | <code>intermal_dispose_GC()</code> methods (including their native
|
|---|
| 37 | representations) which leads to a partial implementation of <code>o.e.swt.OS</code>
|
|---|
| 38 | class and also few others (see checklist). All other stuff should be
|
|---|
| 39 | temporarily commented. Of course, without any visible window (which is
|
|---|
| 40 | represented by the <code>Shell</code> class) we cannot get keyboard and
|
|---|
| 41 | mouse messages from the system but there should be a couple of system
|
|---|
| 42 | events that we can get and write their info to the log file. As a criteria
|
|---|
| 43 | of the step completion will be a simplified SWT example <kbd>HelloWorld1</kbd>
|
|---|
| 44 | (with the <code>Shell</code> code ripped off).</p>
|
|---|
| 45 |
|
|---|
| 46 | <h2>Step checklist</h2>
|
|---|
| 47 |
|
|---|
| 48 | <table>
|
|---|
| 49 | <col width="40%" />
|
|---|
| 50 |
|
|---|
| 51 | <col />
|
|---|
| 52 |
|
|---|
| 53 | <col width="50%" />
|
|---|
| 54 |
|
|---|
| 55 | <thead>
|
|---|
| 56 | <tr>
|
|---|
| 57 | <th>Operation</th>
|
|---|
| 58 |
|
|---|
| 59 | <th>Status</th>
|
|---|
| 60 |
|
|---|
| 61 | <th>Remarks</th>
|
|---|
| 62 | </tr>
|
|---|
| 63 | </thead>
|
|---|
| 64 |
|
|---|
| 65 | <tr>
|
|---|
| 66 | <td>Create the initial directory structure in cvs, initially checkin
|
|---|
| 67 | common SWT parts as <kbd>rel-2-0-1</kbd> on the <kbd>eclipse-team</kbd>
|
|---|
| 68 | branch</td>
|
|---|
| 69 |
|
|---|
| 70 | <td>Done [dmik]</td>
|
|---|
| 71 |
|
|---|
| 72 | <td>Common native C code from [Base] (<kbd>\src\plugins\org.eclipse.swt\Eclipse
|
|---|
| 73 | SWT\common\library</kbd>) and <code>o.e.swt.internal.Library</code>
|
|---|
| 74 | [PI] are checked in.</td>
|
|---|
| 75 | </tr>
|
|---|
| 76 |
|
|---|
| 77 | <tr>
|
|---|
| 78 | <td>Include <code>o.e.swt.Drawable</code> [Base] in compilation</td>
|
|---|
| 79 |
|
|---|
| 80 | <td>Done [dmik]</td>
|
|---|
| 81 |
|
|---|
| 82 | <td></td>
|
|---|
| 83 | </tr>
|
|---|
| 84 |
|
|---|
| 85 | <tr>
|
|---|
| 86 | <td>Add <code>o.e.swt.graphics.<b>Device, DeviceData, GCData</b></code>
|
|---|
| 87 | [Base] and comment all unnecessary parts</td>
|
|---|
| 88 |
|
|---|
| 89 | <td>Done [dmik]</td>
|
|---|
| 90 |
|
|---|
| 91 | <td><br /></td>
|
|---|
| 92 | </tr>
|
|---|
| 93 |
|
|---|
| 94 | <tr>
|
|---|
| 95 | <td>Create <code>o.e.swt.internal.pm.<b>QMSG</b></code> [PI]</td>
|
|---|
| 96 |
|
|---|
| 97 | <td>Done [eli]</td>
|
|---|
| 98 |
|
|---|
| 99 | <td><a href="swt.html#o.e.swt.internal.pm.QMSG">[QMSG]</a></td>
|
|---|
| 100 | </tr>
|
|---|
| 101 |
|
|---|
| 102 | <tr>
|
|---|
| 103 | <td>Create <code>o.e.swt.internal.pm.<b>MPARAM</b></code> [PI]</td>
|
|---|
| 104 |
|
|---|
| 105 | <td>Done [eli]</td>
|
|---|
| 106 |
|
|---|
| 107 | <td>Now it's uncomplete and not used.</td>
|
|---|
| 108 | </tr>
|
|---|
| 109 |
|
|---|
| 110 | <tr>
|
|---|
| 111 | <td>Create <code>o.e.swt.internal.pm.<b>POINTL</b></code> [PI]</td>
|
|---|
| 112 |
|
|---|
| 113 | <td>Done [eli]</td>
|
|---|
| 114 |
|
|---|
| 115 | <td>Now it's not used.</td>
|
|---|
| 116 | </tr>
|
|---|
| 117 |
|
|---|
| 118 | <tr>
|
|---|
| 119 | <td>Add <code>o.e.swt.widgets.<b>Display</b></code> [PI] and comment
|
|---|
| 120 | unnecessary parts</td>
|
|---|
| 121 |
|
|---|
| 122 | <td>Done [dmik]</td>
|
|---|
| 123 |
|
|---|
| 124 | <td></td>
|
|---|
| 125 | </tr>
|
|---|
| 126 |
|
|---|
| 127 | <tr>
|
|---|
| 128 | <td>Create <code>o.e.swt.internal.pm.<b>OS</b></code> [PI]</td>
|
|---|
| 129 |
|
|---|
| 130 | <td>Done [dmik]</td>
|
|---|
| 131 |
|
|---|
| 132 | <td></td>
|
|---|
| 133 | </tr>
|
|---|
| 134 |
|
|---|
| 135 | <tr>
|
|---|
| 136 | <td>Port <code>o.e.swt.internal.Library</code> [PI]</td>
|
|---|
| 137 |
|
|---|
| 138 | <td>Done [dmik]</td>
|
|---|
| 139 |
|
|---|
| 140 | <td>OS/2 (or Java under OS/2) is unable to handle DLL files with long
|
|---|
| 141 | names, only 8.3 format is allowed (see Q&A #2). So, SWT DLL file
|
|---|
| 142 | name will be constructed as <kbd>swtpNNNN.dll</kbd> (where NNNN is the
|
|---|
| 143 | SWT version number). Revision number will be ignored.</td>
|
|---|
| 144 | </tr>
|
|---|
| 145 |
|
|---|
| 146 | <tr>
|
|---|
| 147 | <td>Create dummy (empty) C natives [PI], port <kbd>callback.h</kbd>
|
|---|
| 148 | [Base] and setup VAC4 compilation</td>
|
|---|
| 149 |
|
|---|
| 150 | <td>Done [dmik]</td>
|
|---|
| 151 |
|
|---|
| 152 | <td>At this moment the build of natives is done by <kbd>\src\plugins\org.eclipse.swt\Eclipse
|
|---|
| 153 | SWT PI\pm\library\build.cmd</kbd> (later will be called from the main
|
|---|
| 154 | build file). The native callback stuff seems to be compiled ok. Not
|
|---|
| 155 | properly tested, but <code>o.e.swt.SWT.getPlatform()</code> (that uses
|
|---|
| 156 | <code>o.e.swt.internal.Callback.getPlatform()</code>) works.</td>
|
|---|
| 157 | </tr>
|
|---|
| 158 |
|
|---|
| 159 | <tr>
|
|---|
| 160 | <td>Implement <code>OS.WinAlarm()</code> (<kbd>swt.c</kbd>) as an
|
|---|
| 161 | example of native mappings and <code>OS.WA_*</code> constants for it;
|
|---|
| 162 | implement <code>Display.beep()</code></td>
|
|---|
| 163 |
|
|---|
| 164 | <td>Done [dmik]</td>
|
|---|
| 165 |
|
|---|
| 166 | <td>This is an analogue of Win32's <code>MessageBeep()</code>. <a
|
|---|
| 167 | href="swt.html#o.e.swt.internal.pm.OS.WinAlarm">[WinAlarm]</a> (see
|
|---|
| 168 | Q&A #6).</td>
|
|---|
| 169 | </tr>
|
|---|
| 170 |
|
|---|
| 171 | <tr>
|
|---|
| 172 | <td>Add <code>OS.HWND_DESKTOP</code> (=1) and <code>OS.NULLHANDLE</code>
|
|---|
| 173 | (=0) constants.</td>
|
|---|
| 174 |
|
|---|
| 175 | <td>Done [dmik]</td>
|
|---|
| 176 |
|
|---|
| 177 | <td>See Q&A #6.</td>
|
|---|
| 178 | </tr>
|
|---|
| 179 |
|
|---|
| 180 | <tr>
|
|---|
| 181 | <td>Implement <code>OS.WinGetLastError()</code> for debugging purposes</td>
|
|---|
| 182 |
|
|---|
| 183 | <td>Done [dmik]</td>
|
|---|
| 184 |
|
|---|
| 185 | <td></td>
|
|---|
| 186 | </tr>
|
|---|
| 187 |
|
|---|
| 188 | <tr>
|
|---|
| 189 | <td>Add <code>Display.hab</code> field (together with <code>hmq</code>)
|
|---|
| 190 | and add its initialization and cleanup (<code>OS.WinInitialize()</code>
|
|---|
| 191 | and <code><code>OS</code>.WinTerminate()</code>, <code><code>OS</code>.WinCreateMsgQueue()</code>
|
|---|
| 192 | and <code><code>OS</code>.WinDestroyMsgQueue()</code>) to
|
|---|
| 193 | <code>init()</code> and <code>release()</code> (actually <code>releaseDisplay()</code>)
|
|---|
| 194 | methods</td>
|
|---|
| 195 |
|
|---|
| 196 | <td>Done [dmik]</td>
|
|---|
| 197 |
|
|---|
| 198 | <td>See O&A #7. An attempt to create a msg queue in the program
|
|---|
| 199 | started by <kbd>java.exe</kbd> will lead to <code>PMERR_NOT_IN_A_PM_SESSION</code>
|
|---|
| 200 | (0x1051) error. Execution under <kbd>javaw.exe</kbd> is ok => see
|
|---|
| 201 | O&A #8.</td>
|
|---|
| 202 | </tr>
|
|---|
| 203 |
|
|---|
| 204 | <tr>
|
|---|
| 205 | <td>Implement <code>OS.DosGetInfoBlocks()</code> to make it possible
|
|---|
| 206 | to get the current thread and process id and create wrapper classes
|
|---|
| 207 | for the corresponding structures: <code>o.e.swt.internal.pm.<b>TIB</b></code>,
|
|---|
| 208 | <code>o.e.swt.internal.pm.<b>TIB2</b></code>, <code>o.e.swt.internal.pm.<b>PIB</b></code>,
|
|---|
| 209 | and getters/setters for them (<kbd>structs.h</kbd>/<kbd>structs.c</kbd>).</td>
|
|---|
| 210 |
|
|---|
| 211 | <td>Done [dmik]</td>
|
|---|
| 212 |
|
|---|
| 213 | <td>Curently, <code>PIB.pib_pchcmd</code> and <code>PIB.pib_pchenv</code>
|
|---|
| 214 | are not implemented. <br /><b>Note</b>: Useful information about the
|
|---|
| 215 | implementation of native methods can be found <a
|
|---|
| 216 | href="swt.html#native.methods">here</a>.</td>
|
|---|
| 217 | </tr>
|
|---|
| 218 |
|
|---|
| 219 | <tr>
|
|---|
| 220 | <td>Change <code>OS.DosGetInfoBlocks()</code> implementation.</td>
|
|---|
| 221 |
|
|---|
| 222 | <td>Done [dmik]</td>
|
|---|
| 223 |
|
|---|
| 224 | <td>Since <code>DosGetInfoBlocks()</code>returns pointers to its
|
|---|
| 225 | internal data rather than fills structures provided by the caller and
|
|---|
| 226 | since we need the direct access to that data from Java, it will be
|
|---|
| 227 | more "native" and useful to change arguments of the wrapper to
|
|---|
| 228 | arrays of int with one element to return this pointers to Java caller
|
|---|
| 229 | and then use <code>OS.objcpy</code> to excahge data between the memory
|
|---|
| 230 | they point to and Java TIB/PIB structure wrappers.</td>
|
|---|
| 231 | </tr>
|
|---|
| 232 |
|
|---|
| 233 | <tr>
|
|---|
| 234 | <td>Implement <code>OS.DosQuerySysInfo()</code> and <code>OS.QSV_*</code>
|
|---|
| 235 | constants to get the OS/2 version and revision, define <code>OS.IsWarp3</code>,
|
|---|
| 236 | <code>OS.IsWarp4</code>, <code>OS.IsAurora</code> constants.</td>
|
|---|
| 237 |
|
|---|
| 238 | <td>Done [dmik]</td>
|
|---|
| 239 |
|
|---|
| 240 | <td></td>
|
|---|
| 241 | </tr>
|
|---|
| 242 |
|
|---|
| 243 | <tr>
|
|---|
| 244 | <td>Implement <code>OS.PSZ</code> wrapper and C helpers for it to
|
|---|
| 245 | handle ASCIIZ strings.</td>
|
|---|
| 246 |
|
|---|
| 247 | <td>Done [dmik]</td>
|
|---|
| 248 |
|
|---|
| 249 | <td>See <a href="swt.html#native.methods">conventions</a> about ASCIIZ
|
|---|
| 250 | strings.</td>
|
|---|
| 251 | </tr>
|
|---|
| 252 |
|
|---|
| 253 | <tr>
|
|---|
| 254 | <td>Finish the preliminary <code>Display</code> imlementation to get a
|
|---|
| 255 | working message queue and add the following <code>OS</code> natives
|
|---|
| 256 | for this:<ul><li><code>WinRegisterClass</code> (and <code>CS_* </code>constants)</li><li><code>WinCreateWindow
|
|---|
| 257 | </code>(and <code>WS_* </code>constants)</li><li><code>WinDestroyWindow</code></li><li><code>WinDefWinProc</code></li><li><code>WinPeekMsg</code></li><li><code>WinDispatchMsg</code></li><li><code>WinPostQueueMsg</code></li><li><code>WinWaitMsg</code></li></ul>Also
|
|---|
| 258 | include some common classes in compilation (see <kbd>classes.inc</kbd>).</td>
|
|---|
| 259 |
|
|---|
| 260 | <td>Done [dmik]</td>
|
|---|
| 261 |
|
|---|
| 262 | <td>The last objective in the test example (<kbd>SWT001.java</kbd>)
|
|---|
| 263 | shows the same behavior as its C equvivalent. Nonvisible message-only
|
|---|
| 264 | window receives <code>WM_CREATE</code> upon creation, then
|
|---|
| 265 | <code>WM_ADJUSTWINDOWPOS</code>, then a locale message, then the
|
|---|
| 266 | message loop terminates and the window receives a <code>WM_CLOSE</code>
|
|---|
| 267 | message upon destroying. This behavior does not depend on whether the
|
|---|
| 268 | test is run in PM mode or in VIO. Everything seems to be working
|
|---|
| 269 | correctly.</td>
|
|---|
| 270 | </tr>
|
|---|
| 271 | </table>
|
|---|
| 272 | </body>
|
|---|
| 273 | </html>
|
|---|
