docs/microwin/readme.txt

   1 wxMicroWindows port
   2 ===================
   3
   4 Julian Smart 2001-12-08
   5
   6 This is a port of wxWindows to MicroWindows, under Linux.
   7 Widgets are supplied by the wxUniversal project, while the
   8 underlying port uses the Windows ports with small modifications
   9 for the MicroWindows API.
  10
  11 There are many things missing from MicroWindows that will
  12 make the port quite limited for the time being. I haven't
  13 worked out how to create bitmaps, though there is a BMP to C
  14 converter. There are no common dialogs (we will use generic ones),
  15 and only one WIN32 app may be run at a time.
  16
  17 Note that you can gain confidence in the WIN32/wxUniversal
  18 combination by compiling wxUniversal under Windows using VC++,
  19 using src/wxvc_universal.dsp. You can compile the minimal
  20 and widgets samples in wxUniversal mode using the
  21 UnivDebug and UnivRelease targets. Most of the code is shared
  22 between this combination, and the wxMicroWindows port.
  23
  24 Installation
  25 ============
  26
  27 MicroWindows:
  28
  29 - unarchive MicroWindows 0.89pre8
  30
  31 - change 'config' to use X11 and any other options you feel fit.
  32   Suggestions for changes to the defaults:
  33
  34   ERASEMOVE=N (otherwise moving windows will look messy)
  35   X11=Y
  36   OPTIMIZE=N
  37   DEBUG=Y
  38   VERBOSE=Y
  39
  40   Note: these are already applied by the patch below.
  41
  42 - apply microwindows.patches (from wxWindows:
  43   docs/microwin/microwindows.patches) to fix PeekMessage
  44   and other issues. If the patch doesn't apply automatically,
  45   you may need to apply it by hand, and the relevant changed
  46   functions are given at the end of this file for convenience.
  47
  48   Example patch command:
  49
  50   % cd microwindows-0.89pre8.orig
  51   % patch -p0 < ~/wx2/docs/microwin/microwindows.patches
  52
  53 - compile by typing 'make' from within the MicroWindows src directory
  54
  55 wxMicroWindows:
  56
  57 - Download wxMSW 2.3.2 or greater, or get it from CVS
  58
  59 - Copy include/wx/msw/setup_microwin.h to include/wx/setup.h if
  60   include/wx/setup.h doesn't exist
  61
  62 - EITHER:
  63
  64   o set the MICROWINDOWS environment variable, e.g.:
  65
  66     % export MICROWINDOWS=/home/julians/local/microwindows/microwindows-0.89pre8/src
  67
  68   OR:
  69
  70   o change the TOP variable at the top of src/msw/makefile.mic
  71     to reflect where MicroWindows is installed
  72
  73 - type 'make -f makefile.mic all' from src/msw. To clean, use
  74   cleanwx and NOT clean since that will clean MicroWindows itself
  75
  76 - to make the sample, cd into samples/minimal, edit the TOP variable
  77   (or set MICROWINDOWS) as before, and type 'make -f makefile.mic all'
  78
  79 Running 'minimal' runs the virtual MicroWindows desktop
  80 and the minimal sample, since in a MicroWindows WIN32 application
  81 they are one and the same binary.
  82
  83 Status
  84 ======
  85
  86 The minimal sample is almost fully-functional, apart from some
  87 presentation issues (no menu borders and status bar in the wrong
  88 place.
  89
  90 The widgets sample is crashing in DeleteObject (see notes below).
  91
  92
  93 Implementation Notes
  94 ====================
  95
  96 wxMicroWindows is essentially the wxMSW port + wxUniversal
  97 widgets. Lots of things in include/wx/univ/setup.h are switched
  98 off to allow the port to compile. There are also #ifdefs
  99 switching off further functionality, such as most wxBitmap
 100 functions, pending proper implementation.
 101
 102 There are some WIN32 API functions not implemented by MicroWindows
 103 that are instead stubbed out in include/wx/msw/microwin.c,
 104 and 'implemented' in src/msw/microwin.c. Some of these functions
 105 are important, some less so. They will need to be implemented
 106 in due course. But implementing missing functionality in this way
 107 is preferably to proliferating many #ifdefs in the
 108 wxMSW/wxMicroWindows port itself.
 109
 110
 111 Things missing from MicroWindows that need to be worked around
 112 ==============================================================
 113
 114 wxImage/inline XPM/::CreateBitmap support
 115 -----------------------------------------
 116
 117 This is the main obstacle to getting a good range
 118 of widgets working, since wxUniversal uses inline XPMs
 119 to implement most of the widgets.
 120
 121 See src/engine/devimage.c for routines for loading JPEGs,
 122 XPMs etc. Unfortunately the XPM routines are also #ifdefed
 123 for FILE_IO, even though for inline XPMs we don't need file I/O.
 124 (Embedded systems tend not to have file I/O, anyway.)
 125
 126 Now, wxWindows has its own XPM decoder, src/common/xpmdecod.cpp,
 127 so in theory we don't need to use MicroWindows' code there.
 128 wxImage can load an inline XPM, _but_ we need to convert to
 129 a wxBitmap since this is what the widgets need.
 130
 131 There is no ::CreateBitmap or BITMAPINFO. (BMPs can be converted
 132 to C using convbmp, then need to use Gr... functions.)
 133
 134 So how can we convert from wxImage to wxBitmap in MicroWindows?
 135
 136 Well, a simple-minded way would be to use CreateCompatibleBitmap
 137 which returns an HBITMAP, select it into an HDC, and draw
 138 the pixels from the wxImage to the HDC one by one with SetPixel.
 139 This is now implemented, but without any mask handling, which will
 140 be needed.
 141
 142 Unfortunately, there's a crash in malloc, within DeleteObject, when
 143 passed a bitmap created by CreateCompatibleBitmap, but only after a few
 144 deletions. This has yet to be tracked down, maybe by trying to create/delete
 145 some wxBitmaps from XPMs, from within e.g. the minimal sample.
 146
 147
 148 Other missing features
 149 ----------------------
 150
 151 No ::GetKeyState (see include/wx/msw/private.h). Should probably use
 152 GdOpenKeyboard/GdCloseKeyboard/GdReadKeyboard. Could perhaps emulate
 153 GetKeyState this way.
 154
 155 No ::DestroyIcon, ::DestroyCursor - use ::DestroyObject instead?
 156 Also no LoadCursor, LoadImage. So how do we make cursors? No ::SetCursor.
 157
 158 wxDC: no ::GetTextColor, ::GetBkColor, ::IntersectClipRect,
 159 ::GetClipBox
 160
 161 No ::SetMenu, so no menus or menubars (now implemented by
 162 wxUniversal).
 163
 164 No ::GetObject so we can't get LOGFONT from an HFONT
 165 in wxSystemSettings (worked around by passing HFONT to
 166 the wxFont constructor).
 167
 168
 169 Applying patches by hand
 170 ========================
 171
 172 The full altered functions are given below in case you have
 173 to apply them by hand.
 174
 175 src/mwin/winevent.c
 176 -------------------
 177
 178 A second test has been added to this line:
 179
 180         if(hittest == HTCLIENT || hwnd == GetCapture()) {
 181
 182 in MwTranslateMouseMessage below. This corrects a mouse message
 183 bug.
 184
 185 /*
 186  * Translate and deliver hardware mouse message to proper window.
 187  */
 188 void
 189 MwTranslateMouseMessage(HWND hwnd,UINT msg,int hittest)
 190 {
 191         POINT           pt;
 192         DWORD           tick;
 193         static UINT     lastmsg = 0;
 194         static HWND     lasthwnd;
 195         static DWORD    lasttick;
 196         static int      lastx, lasty;
 197
 198         /* determine double click eligibility*/
 199         if(msg == WM_LBUTTONDOWN || msg == WM_RBUTTONDOWN) {
 200                 tick = GetTickCount();
 201                 if((hwnd->pClass->style & CS_DBLCLKS) &&
 202                     msg == lastmsg && hwnd == lasthwnd &&
 203                     tick - lasttick < DBLCLICKSPEED &&
 204                     abs(cursorx-lastx) < mwSYSMETRICS_CXDOUBLECLK &&
 205                     abs(cursory-lasty) < mwSYSMETRICS_CYDOUBLECLK)
 206                         msg += (WM_LBUTTONDBLCLK - WM_LBUTTONDOWN);
 207                 lastmsg = msg;
 208                 lasthwnd = hwnd;
 209                 lasttick = tick;
 210                 lastx = cursorx;
 211                 lasty = cursory;
 212         }
 213
 214         /*
 215          * We always send nc mouse message
 216          * unlike Windows, for HTCLIENT default processing
 217          */
 218         PostMessage(hwnd, msg + (WM_NCMOUSEMOVE-WM_MOUSEMOVE), hittest,
 219                 MAKELONG(cursorx, cursory));
 220
 221         /* then possibly send user mouse message*/
 222         if(hittest == HTCLIENT || hwnd == GetCapture()) {
 223                 pt.x = cursorx;
 224                 pt.y = cursory;
 225                 ScreenToClient(hwnd, &pt);
 226                 PostMessage(hwnd, msg, 0, MAKELONG(pt.x, pt.y));
 227         }
 228 }
 229
 230 winuser.c
 231 ---------
 232
 233 Part of PeekMessage has been factored out into PeekMessageHelper,
 234 and used in PeekMessage and GetMessage. The three relevant functions
 235 are:
 236
 237 /*
 238  * A helper function for sharing code between PeekMessage and GetMessage
 239  */
 240
 241 BOOL WINAPI
 242 PeekMessageHelper(LPMSG lpMsg, HWND hwnd, UINT uMsgFilterMin, UINT uMsgFilterMax,
 243         UINT wRemoveMsg, BOOL returnIfEmptyQueue)
 244 {
 245         HWND    wp;
 246         PMSG    pNxtMsg;
 247
 248         /* check if no messages in queue*/
 249         if(mwMsgHead.head == NULL) {
 250                 /* Added by JACS so it doesn't reach MwSelect */
 251                 if (returnIfEmptyQueue)
 252                     return FALSE;
 253
 254 #if PAINTONCE
 255                 /* check all windows for pending paint messages*/
 256                 for(wp=listwp; wp; wp=wp->next) {
 257                         if(!(wp->style & WS_CHILD)) {
 258                                 if(chkPaintMsg(wp, lpMsg))
 259                                         return TRUE;
 260                         }
 261                 }
 262                 for(wp=listwp; wp; wp=wp->next) {
 263                         if(wp->style & WS_CHILD) {
 264                                 if(chkPaintMsg(wp, lpMsg))
 265                                         return TRUE;
 266                         }
 267                 }
 268 #endif
 269                 MwSelect();
 270         }
 271
 272         if(mwMsgHead.head == NULL)
 273                 return FALSE;
 274
 275         pNxtMsg = (PMSG)mwMsgHead.head;
 276         if(wRemoveMsg & PM_REMOVE)
 277                 GdListRemove(&mwMsgHead, &pNxtMsg->link);
 278         *lpMsg = *pNxtMsg;
 279         if(wRemoveMsg & PM_REMOVE)
 280                 GdItemFree(pNxtMsg);
 281         return TRUE;
 282 }
 283
 284 BOOL WINAPI
 285 PeekMessage(LPMSG lpMsg, HWND hwnd, UINT uMsgFilterMin, UINT uMsgFilterMax,
 286         UINT wRemoveMsg)
 287 {
 288         /* Never wait in MwSelect: pass TRUE */
 289         return PeekMessageHelper(lpMsg, hwnd, uMsgFilterMin, uMsgFilterMax, wRemoveMsg, TRUE);
 290 }
 291
 292 BOOL WINAPI
 293 GetMessage(LPMSG lpMsg,HWND hwnd,UINT wMsgFilterMin,UINT wMsgFilterMax)
 294 {
 295         /*
 296          * currently MwSelect() must poll for VT switch reasons,
 297          * so this code will work
 298          */
 299         /* Always wait in MwSelect if there are messages: pass FALSE */
 300         while(!PeekMessageHelper(lpMsg, hwnd, wMsgFilterMin, wMsgFilterMax,PM_REMOVE, FALSE))
 301                 continue;
 302         return lpMsg->message != WM_QUIT;
 303 }