The targeted audience for the article is people who would like to get started with Pocket Windows development. I assume that you have prior knowledge of Windows programming with MFC, and you have played around with the Pocket Windows operating system enough to know what it’s limitations are.
Before starting make sure that you have the following:
- A fast PC with Windows2000 or NT4 *
- Microsoft Embedded Visual C++ (includes MSDN and the Platform SDK for Windows CE 3.0)
- A Pocket PC for testing the result.
- Lots of coffee
* You can use Windows 98 but it is not recommended since it will not support emulation. I don’t know about Windows ME. If you decide to use Windows NT 4, you should at least have Service Pack 5 installed.
By the end of this article you will be able to Install the Embedded VC environment and set it up for your particular device. You will also be able to understand what the limitations are when porting existing applications.
Obtaining Microsoft Embedded Visual C++ (EVC)
EVC is offered from Microsoft for free, and
can be downloaded from the Pocket PC website.
If you don’t want to wait for the 300Mb download to complete, you
can get it from a MSDN subscription or order the CD’s.
Installing EVC
The following guide is based on the installation process using the CD’s. The installation process should be similar when using the download. Make sure that you have obtained a valid registration key.
Completing the installation is not hard. It is completely wizard driven, and whenever you’re in doubt you should be able to get away with choosing the defaults. When asked which parts you want to install, you should choose the ‘Windows CE Platform SDK for Palm size PC 1.2’. You will not need support for the ‘H/PC Pro’ to follow the exercises in this article.
After you have installed the application three new folders has been created in Start Menu > Programs. Don’t worry about all the different programs. You will only need to use the Embedded Visual C++ Development Environment.
Creating an application with EVC
In this introduction I will tell you how to get started with a simple project.
Many MFC programmers has started their career by following the famed Scribble tutorial which takes you through the entire process of building a workable drawing application with Visual Studio and MFC.
If you’re not familiar with MFC and Windows development you should follow the Scribble tutorial or buy one of the many excellent books on the subject, before going into the exercises in this article.
I think the Scribble app is a perfect starting point for a Pocket PC application, since what could be more suitable for a pen driven application than a drawing program.
The scribble application does not come with EVC, and you will need to download it
from the
Microsoft MSDN Web site or, if you have Visual Studio, get it from the MSDN disks.
The scribble tutorial is separated into seven parts each delving into different aspects of Windows development. We will port Scribble step 6 in this article. I won’t even try to port step 7 since it teaches you how to do COM (OLE) programming with MFC. I will not do that for two reasons. COM is not implemented in such a degree on Pocket Windows, that it can be ported directly, and many interfaces (like the one dealing with embedding) is not even implemented. The other reason is that using MFC for doing COM development is just too hard. You have to jump to many hoops to get even the simplest things done. Use ATL instead or code directly to the COM API (is isn’t as hard as you might expect – but that’s another story).
The screenshot above shows the normal Windows version of Scribble. When looking at my feeble sketches above, done with a standard mouse, you might get an idea of why I think that Scribble should be converted to a pen driven application.
Pocket Windows Limitations
Before starting the porting process, we should take a minute going through all the stuff that we will not port to Pocket Scribble, simply because it is not possible, or because it will take to much work.
Many of the things that we take for granted when doing Windows development with MFC are not implemented in MFC for the Pocket Windows platform. The most prominent which are included in the PC version of Scribble but won’t be in the Pocket Windows version are:
- Online help in the form of Win Help files.
- Context sensitive help (the ? on the toolbar or in the corner of dialog boxes)
- Multiple Document Interface
- Splitter Windows
- Printing
Creating the starter files for the application
Well, it’s time to get our feet wet.
We will start by creating a Pocket PC application using the built-in wizards. This application will form the basis of the porting process, and should also serve as a short introduction to the development environment.
- Start the Embedded Visual C++ IDE as shown in the screen shot.
- When the IDE has loaded you should be greeted with an empty workspace. As you can see the EVC workspace is almost indistinguishable from Visual Studio, and you should feel at home immediately, if you have worked with Visual Studio before.
- From the File menu, select New. In the wizard that follows you will need to provide a name for the application, for instance Pocket Scribble.
- The type of project should be a ‘WCE Pocket PC MFC AppWizard (exe)’. Make sure that the build targets are properly configured. It is done in the ‘CPUs’ list box. You should always use the Win32 (WCE x86em) “CPU” – since it is the build target for the Windows CE simulator, which are necessary if you want to debug.
- You will need to select the other targets according to the type of CPU used in the particular device you want to make the application for.
- Click OK to start the wizard, which will create the application in four easy steps. In the first step you will choose which type of application you want to create. The type most suitable for Pocket Scribble is the ‘Single document with Doc List’. If you choose this option the ‘Document/View architecture’ check box is disabled. This is because Document/View is always enabled in this type of application. When done, just click Finish to begin the generation of the starter files for the project.
You might wonder what a ‘Doc List’ is and why you should choose it for this project. A ‘Doc List’ is a class specialised for dealing with file types on Pocket Windows. It has become the standard, more or less, for creating file-based applications. Pocket Word and Pocket Excel that come with Pocket Windows are both examples of ‘Doc List’ based applications.
Configuring EVC for use with the Scribble workspace
Now we should have a working, albeit useless, Pocket PC application. We will use the next few minutes to set up the environment and get familiar with the user interface architecture of a simple application.
We will start by running the application in the emulator. On the ‘WCE Configuration’ toolbar make sure that it is set up like this:
This will make us able to compile and run out project in the emulator, which is a lot easier than downloading to the Pocket PC after each recompile.
When done, hit F7 and watch the magic happen! If everything goes well, you should get some messages in the output window declaring that the file PocketScribble.exe has been downloaded to the emulator, and you should be able to see a hideous blue thing with a Pocket Windows user interface. Get used to it – you will use much of your time with it while testing.
To see what you starter application looks like, click on the start menu (in the emulator window) and launch it.
As you can see from the screenshot nothing much happens when you launch a ‘Doc List’ application. That is because it starts by asking you to open an existing file. Click the file that you want to open or, if you want to create a new file, choose ‘New’ from the bottom menu. This is known as the ‘Shared New’ in the application wizard.
When you choose ‘New’ you will see the user interface for the application. The standard AppWizard generated application features a menu bar, a toolbar and a build-in about box. Now we will try to actually make it do something by porting the Scribble application.
Porting Scribble for PC/Windows to Pocket Windows
There are some things involved in porting the Scribble application to Pocket Windows. First you must look at the source code, to see if you can use the original files as they are, or if it will take so much time that an actual rewrite would be faster. Next you will have to go through the original files, that you decided to keep, removing all the stuff not supported on Pocket Windows. At last you have to recompile it and test it to see if it behaves satisfactory.
Go to the PocketScribble workspace and remove the following files from the project:
- PocketScribbleDoc.h
- PocketScribbleDoc.cpp
- PocketScribbleView.h
- PocketScribbleView.cpp
Next copy the following files from the MSDN Scribble sample to the PocketScribble directory.
- Scribdoc.h
- Scribdoc.cpp
- Scribvw.h
- Scribvw.cpp
- Pendlg.h
- Pendlg.cpp
Here are the steps that are necessary to complete before it is possible to compile the project. Make sure that you complete each one.
- Add all the files listed above to the workspace and replace all instances of “#include “Scribble.h” to #include “PocketScribble.h”. Replace all instances of #include “PocketScribbleDoc.h” and #include “PocketScribbleView.h” with #include “scribdoc.h” and #include “scribvw.h”
- In CPocketScribbleApp::InitInstance() you should replace the references to CPocketScribbleDoc and CPocketScribbleView in the creation of the document template, with their CScribbleDoc and CscribbleView counterparts.
- The class CScribbleDoc uses MFC template collection classes, so you will also have to add the line #include
to Stdafx.h. - Remove everything that has to do with printing from scribvw.cpp and scribvw.h. The functions that should be removed are OnPreparePrinting, OnBeginPrinting, OnEndPrinting, OnPrint, PrintTitlePage and PrintPageHeader. Be sure that you remove the command handlers too.
- Copy some of the resources from the “Scribble Step 6 “application to the PocketScribble resource file. To do that, open the file scribble.rc in the PocketScribble project, and drag the resources into the PocketScribble resource file. Some of the resources does not match the look and feel of Pocket Windows, and will be changed later.
- Modify the dialog template. The look and feel of dialogs on Pocket Windows are different from the dialogs on Win32, due to its smaller screen size and lack of OK and Cancel buttons. There is only one dialog in the Scribble project that you will need to modify. You should delete the OK and Cancel buttons and resize the template and its controls to look something like that below.
- is everything I have drawn gone when the main window has been covered?
- can I save the files with the ‘.scb’ extension so I can open existing files?
- the file format compatible with the PC version of Scribble?
- do I save my work? There is no OK button in the corner of the window. I can only choose ‘Save As’
The only resource that should be copied directly is the dialog IDD_PEN_WIDTHS. You should not copy the menu bar resource directly, but merely delete some items from the existing menu and add some others. Start by copying the entire ‘Pen’ dropdown menu from the original IDR_SCRIBBTYPE menu bar to PocketScribble IDR_SCRIBBTYPE menu bar. Next copy the ‘Clear All’ menu item from the ‘Edit Menu’. You can, if you want to, delete the menu items that are not in use: Undo, Cut, Copy, Paste. By now you menu should look like this:
After the menu has been updated you should copy the ‘Pen Widths’ button to the toolbar. The Cut, Copy and Paste buttons can be deleted, so that you end up with a toolbar with a single menu item.
Regarding the size of the dialog you shouldn’t worry too much about the size. The operating system will resize the dialog to fit the screen anyway. I have found out that a size of 139 by 154 dialog units works fine for me.
The ‘Pen Widths’ dialog on PocketWindows
Now it is time to compile the project. Hit F7 and see what happens. Well, nothing much actually. The compiler aborts with an “undeclared identifier error”, because the constant MM_LOENGLISH is not defined. This is because the GDI in Pocket Windows are a lot simpler than the GDI layer in its bigger brothers. Go to CScribbleView::OnInitialUpdate() and remove the line that the compiler is complaining about. Now hit F7 again and it should compile without problems.
Moving into the Real World
Now it is time to move PocketScribble from the emulator environment to the ‘real world’ – that is your Pocket PC.
Change the build settings so the generated executable will be compatible with the CPU on your device. Which CPU you should target for which device should be documented in you users manual. To change the build settings use the WCE configuration toolbar and choose the right target. For my device (Cassiopeia E-115) it is the MIPS CPU. You should also choose the release build version, if you plan to distribute your executable.
You can move the executable into ‘My PocketPC\Windows\Start Menu\Programs’ to have it appear in the programs folder along with your other programs.
Below is the ported version of Scribble. As you can see from my beautiful artwork it actually works as expected.
You can download your own copy to try it out. Make sure that you download the version for the right CPU.
What’s Next?
Even though I boldly state that PocketScribble is almost done, a lot is still missing.
In my next article in this series, I will answer all of the above questions, and maybe throw in a few features into PocketScribble that will demonstrate some of the more advanced stuff you can do with the Pocket Windows API.
If you have suggestions or comment, please don’t hesitate to
contact me. If you can’t
wait for the next article and want to know more, take a look
at another article about Pocket Windows development I’ve written
that shows the creation of a
PocketWine database application.
