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
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.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.
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 EVCIn 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.
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
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.
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.
Next copy the following files from the MSDN Scribble sample to the PocketScribble directory.
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
- 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.
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 WorldNow 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.
Even though I boldly state that PocketScribble is almost done, a lot is still missing.
- 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'
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.