wxMSW is a port of wxWidgets for the Windows platforms including Windows 95, 98, ME, 2000, NT, XP in ANSI and Unicode mode (for Windows 95 through the MSLU extension library). wxMSW ensures native look and feel for XP as well when using wxWidgets version 2.3.3 or higher. wxMSW can be compile with a great variety of compilers including MS VC++, Borland 5.5, MinGW32, Cygwin and Watcom as well as cross-compilation with a Linux hosted MinGW32 tool chain.
For further information, please see the files in docs/msw in the distribution.
wxWinCE is the name given to wxMSW when compiled on Windows CE devices; most of wxMSW is common to Win32 and Windows CE but there are some simplifications, enhancements, and differences in behaviour.
For building instructions, see docs/msw/wince in the distribution, also the section about Visual Studio 2005 project files below. The rest of this section documents issues you need to be aware of when programming for Windows CE devices.
Mobile applications generally have fewer features and simpler user interfaces. Simply omit whole sizers, static lines and controls in your dialogs, and use comboboxes instead of listboxes where appropriate. You also need to reduce the amount of spacing used by sizers, for which you can use a macro such as this:
#if defined(__WXWINCE__)
#define wxLARGESMALL(large,small) small
#else
#define wxLARGESMALL(large,small) large
#endif
// Usage
topsizer->Add( CreateTextSizer( message ), 0, wxALL, wxLARGESMALL(10,0) );
There is only ever one instance of a Windows CE application running,
and wxWidgets will take care of showing the current instance and
shutting down the second instance if necessary.You can test the return value of wxSystemSettings::GetScreenType() for a qualitative assessment of what kind of display is available, or use wxGetDisplaySize() if you need more information.
You can also use wxGetOsVersion to test for a version of Windows CE at run-time (see the next section). However, because different builds are currently required to target different kinds of device, these values are hard-wired according to the build, and you cannot dynamically adapt the same executable for different major Windows CE platforms. This would require a different approach to the way wxWidgets adapts its behaviour (such as for menubars) to suit the style of device.
See the "Life!" example (demos/life) for an example of an application that has been tailored for PocketPC and Smartphone use.
Note: don't forget to have this line in your .rc file, as for desktop Windows applications:
#include "wx/msw/wx.rc"
Use these preprocessor symbols to test for the different types of device or SDK:
| __SMARTPHONE__ | Generic mobile devices with phone buttons and a small display |
| __PDA__ | Generic mobile devices with no phone |
| __HANDHELDPC__ | Generic mobile device with a keyboard |
| __WXWINCE__ | Microsoft-powered Windows CE devices, whether PocketPC, Smartphone or Standard SDK |
| WIN32_PLATFORM_WFSP | Microsoft-powered smartphone |
| __POCKETPC__ | Microsoft-powered PocketPC devices with touch-screen |
| __WINCE_STANDARDSDK__ | Microsoft-powered Windows CE devices, for generic Windows CE applications |
| __WINCE_NET__ | Microsoft-powered Windows CE .NET devices (_WIN32_WCE is 400 or greater) |
wxGetOsVersion will return these values:
| wxWINDOWS_POCKETPC | The application is running under PocketPC. |
| wxWINDOWS_SMARTPHONE | The application is running under Smartphone. |
| wxWINDOWS_CE | The application is running under Windows CE (built with the Standard SDK). |
Top level windows (dialogs, frames) are created always full-screen. Fit() of sizers will not rescale top level windows but instead will scale window content.
If the screen orientation changes, the windows will automatically be resized so no further action needs to be taken (unless you want to change the layout according to the orientation, which you could detect in idle time, for example). When input panel (SIP) is shown, top level windows (frames and dialogs) resize accordingly (see wxTopLevelWindow::HandleSettingChange).
You won't get a wxCloseEvent when the user clicks on the X in the titlebar on Smartphone and PocketPC; the window is simply hidden instead. However the system may send the event to force the application to close down.
Smartphone and PocketPC will send a wxEVT_HIBERNATE to the application object in low memory conditions. Your application should release memory and close dialogs, and wake up again when the next wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP message is received. (wxEVT_ACTIVATE_APP is generated whenever a wxEVT_ACTIVATE event is received in Smartphone and PocketPC, since these platforms do not support WM_ACTIVATEAPP.)
Special hardware buttons are sent to a window via the wxEVT_HOTKEY event under Smartphone and PocketPC. You should first register each required button with wxWindow::RegisterHotKey, and unregister the button when you're done with it. For example:
win->RegisterHotKey(0, wxMOD_WIN, WXK_SPECIAL1); win->UnregisterHotKey(0);You may have to register the buttons in a wxEVT_ACTIVATE event handler since other applications will grab the buttons.
There is currently no method of finding out the names of the special buttons or how many there are.
PocketPC dialogs have an OK button on the caption, and so you should generally not repeat an OK button on the dialog. You can add a Cancel button if necessary, but some dialogs simply don't offer you the choice (the guidelines recommend you offer an Undo facility to make up for it). When the user clicks on the OK button, your dialog will receive a wxID_OK event by default. If you wish to change this, call wxDialog::SetAffirmativeId with the required identifier to be used. Or, override wxDialog::DoOK (return false to have wxWidgets simply call Close to dismiss the dialog).
Smartphone dialogs do not have an OK button on the caption, and are closed using one of the two menu buttons. You need to assign these using wxTopLevelWindow::SetLeftMenu and wxTopLevelWindow::SetRightMenu, for example:
#ifdef __SMARTPHONE__
SetLeftMenu(wxID_OK);
SetRightMenu(wxID_CANCEL, _("Cancel"));
#elif defined(__POCKETPC__)
// No OK/Cancel buttons on PocketPC, OK on caption will close
#else
topsizer->Add( CreateButtonSizer( wxOK|wxCANCEL ), 0, wxEXPAND | wxALL, 10 );
#endif
For implementing property sheets (flat tabs), use a wxNotebook with wxNB_FLAT|wxNB_BOTTOM
and have the notebook left, top and right sides overlap the dialog by about 3 pixels
to eliminate spurious borders. You can do this by using a negative spacing in your
sizer Add() call. The cross-platform property sheet dialog wxPropertySheetDialog is
provided, to show settings in the correct style on PocketPC and on other platforms.Notifications (bubble HTML text with optional buttons and links) will also be implemented in the future for PocketPC.
Modeless dialogs probably don't make sense for PocketPC and Smartphone, since frames and dialogs are normally full-screen, and a modeless dialog is normally intended to co-exist with the main application frame.
Menubars and toolbars in PocketPC
On PocketPC, a frame must always have a menubar, even if it's empty. An empty menubar/toolbar is automatically provided for dialogs, to hide any existing menubar for the duration of the dialog.
Menubars and toolbars are implemented using a combined control, but you can use essentially the usual wxWidgets API; wxWidgets will combine the menubar and toolbar. However, there are some restrictions:
Unlike in all other ports, a wxDialog has a wxToolBar, automatically created for you. You may either leave it blank, or access it with wxDialog::GetToolBar and add buttons, then calling wxToolBar::Realize. You cannot set or recreate the toolbar.
Menubars and toolbars in Smartphone
On Smartphone, there are only two menu buttons, so a menubar is simulated using a nested menu on the right menu button. Any toolbars are simply ignored on Smartphone.
The guidelines state that applications should not have a Quit menu item, since the user should not have to know whether an application is in memory or not. The close button on a window does not call the window's close handler; it simply hides the window. However, the guidelines say that the Ctrl+Q accelerator can be used to quit the application, so wxWidgets defines this accelerator by default and if your application handles wxID_EXIT, it will do the right thing.
To enable context menus in PocketPC, you currently need to call wxWindow::EnableContextMenu, a wxWinCE-only function. Otherwise the context menu event (wxContextMenuEvent) will never be sent. This API is subject to change.
Context menus are not supported in Smartphone.
These controls and styles are specific to wxWinCE:
These controls are missing from wxWinCE:
Tooltips are not currently supported for controls, since on PocketPC controls with tooltips are distinct controls, and it will be hard to add dynamic tooltip support.
Control borders on PocketPC and Smartphone should normally be specified with wxSIMPLE_BORDER instead of wxSUNKEN_BORDER. Controls will usually adapt appropriately by virtue of their GetDefaultBorder() function, but if you wish to specify a style explicitly you can use wxDEFAULT_CONTROL_BORDER which will give a simple border on PocketPC and Smartphone, and the sunken border on other platforms.
You can use the help controller wxWinceHelpController which controls simple .htm files, usually installed in the Windows directory. See the Windows CE reference for how to format the HTML files.
To install your application, you need to build a CAB file using the parameters defined in a special .inf file. The CabWiz program in your SDK will compile the CAB file from the .inf file and files that it specifies.
For delivery, you can simply ask the user to copy the CAB file to the device and execute the CAB file using File Explorer. Or, you can write a program for the desktop PC that will find the ActiveSync Application Manager and install the CAB file on the device, which is obviously much easier for the user.
Here are some links that may help.
You may also check out demos/life/setup/wince which contains scripts to create a PocketPC installation for ARM-based devices. In particular, build.bat builds the distribution and copies it to a directory called Deliver.
Allowing the user to access files on memory cards, or on arbitrary parts of the filesystem, is a pain; the standard file dialog only shows folders under My Documents or folders on memory cards (not the system or card root directory, for example). This is a known problem for PocketPC developers.
If you need a file dialog that allows access to all folders, you can use wxGenericFileDialog instead. You will need to include wx/generic/filedlgg.h.
Run-time type information
If you wish to use runtime type information (RTTI) with eVC++ 4, you need to download an extra library, ccrtrtti.lib, and link with it. At the time of writing you can get it from here:
http://support.microsoft.com/kb/830482/en-usOtherwise you will get linker errors similar to this:
wxwince26d.lib(control.obj) : error LNK2001: unresolved external symbol "const type_info::`vftable'" (??_7type_info@@6B@)Windows Mobile 5.0 emulator
Note that there is no separate emulator configuration for Windows Mobile 5.0: the emulator runs the ARM code directly.
Visual Studio 2005 project files
Unfortunately, Visual Studio 2005, required to build Windows Mobile 5.0 applications, doesn't do a perfect job of converting the project files from eVC++ format.
When you have converted the wxWidgets workspace, edit the configuration properties for each configuration and in the Librarian, add a relative path ..\..\lib to each library path. For example: ..\$(PlatformName)\$(ConfigurationName)\wx_mono.lib.
Then, for a sample you want to compile, edit the configuration properties and make sure ..\..\lib\$(PlatformName)\$(ConfigurationName) is in the Linker/General/Additional Library Directories property. Also change the Linker/Input/Additional Dependencies property to something like coredll.lib wx_mono.lib wx_wxjpeg.lib wx_wxpng.lib wx_wxzlib.lib wx_wxexpat.lib commctrl.lib winsock.lib wininet.lib (since the library names in the wxWidgets workspace were changed by VS 2005).
Alternately, you could could edit all the names to be identical to the original eVC++ names, but this will probably be more fiddly.
These are some of the remaining problems to be sorted out, and features to be supported.