Getting started with the .NET Compact Framework
This article explains the basics of building a simple but useful application using the .NET Compact Framework where we’ll go beyond “Hello World” but not so far that you’ll get lost in the process. We accomplish this by focusing on building our application while starting to realize some of the limitations and workarounds Compact Framework developers face.
By the end of the article you’ll have a clear understanding of just how easy it can be to get started developing your own Compact Framework applications. If you’ve been coding along with the article, you’ll also have built a template for future development projects.
Part 1 – Background Info
Section 1 – A Short Time Ago at a Code Camp Near You…
The Theo And Lou Show
In September 2006 Theo Moore and I co-presented a fun Code Camp session on .NET Compact Framework Game Development. We had quite a few people show up across the entire 3+ hour session (with breaks of course!) and the interaction with the developers who were there was great.
One of the things that I think surprised me the most was that there seemed to be an overwhelming notion (among those viewing our session) that .NET Compact Framework was going to be waaaaay different than programming the “full” .NET Framework. I even had guys come up to me afterwards and mention that one thing that had kept them from exploring the Compact Framework was they thought they might have to re-learn a bunch of stuff. Now, without getting into lengthy discussions about specifics, for a good number of basic apps, the code can remain the same although your interface design will need some changes to accommodate smaller screens, etc.
7000 downloads and counting!
To illustrate this point I often use my wildly popular Tip Calculator/Bill Splitter which uses the same code base in the full .NET Framework and the .NET Compact Framework. In fact, I developed it first in the full framework and then copied/pasted it into my CF project when I was ready. I did all this because I wanted to get started developing CF applications but wanted something a little more robust than “Hello World!”
Here’s a shot of what the finished program looks like on PocketGear.com:
If you’re interested in downloading the program for yourself, you can do so free of charge at PocketGear.com with the following link: http://classic.pocketgear.com/software_detail.asp?id=17954
I had no idea when I released this little application that it would become so widely used.
It’s even been featured in PC Today magazine as one of their Mobile Tips in the February 2006 issue. ( http://www.pctoday.com/editorial/article.asp?article=articles%2F2006%2Ft0402%2F19t02%2F19t02.asp )
Part 2 – Not your average “Hello World”
Section 2 – Getting Started
Required Software
So how do we start? First things first – the Visual Basic and C# Express Editions do not support Compact Framework. If you have Visual Studio 2003, you can follow along just fine, though the screen shots will look different, none of the code (I’m pretty sure!) I’m using in this demo is .NET 2.0 specific. If you’re not fortunate enough to have Visual Studio 2005 Professional there’s hope – attending your local Microsoft Sponsored User Events like local .NET User Groups, MSDN Code Camps, etc. often result in one or more lucky persons walking away with that as a prize…in fact at the September 2006 South Carolina Code Camp, 2 people won Visual Studio 2005 Professional and we’ve given away a few copies as prizes to our Greater Charleston .NET User Group members…just one more reason to get involved in your local developer community!
Working with your project in the IDE
So that said, let’s fire up Visual Studio 2005 Professional and start a new project as shown in the screen below:
So here we’re creating a project that targets a Pocket PC 2003 device (only because I don’t own a Windows Mobile 5 device myself) and we’re also targeting a project for 2.0 framework. Incidentally if you want to create a 1.0 Compact Framework project in VS 2005 you still can. The project icon right underneath the one I’ve selected above is for a 1.0 project.
Once we’ve created the project we’re presented with a screenshot showing an emulator background where we can begin development of our application. See the screenshot below:
If you’re following along with us using Visual Studio 2003, you won’t see the emulator image in the background, but instead see a much smaller (and probably more familiar) Windows Form. I personally think the emulator image in the background is a nice touch added in VS 2005 and was pretty stoked to learn about some of the other nice things that come with that, but that’s a topic for a later lesson.
In looking at this form you can see it’s not so radically different than standard Windows forms (except for the background image of a Pocket PC). Interacting with the form, setting properties, etc. all remains the same. That said; let’s get some things set up so we can write some code!
Some helpful advice
Alright – if you look at the screenshot below you’ll notice a few things have changed. To help illustrate the changes, I’ve added color coding to bring focus to the changes I’ve made.
The first thing I want to draw your attention to is the Yellow-Bordered box both on the form itself and the Form1 Properties window. This is where I’ve set the caption for my Pocket PC application. That in and of itself isn’t too much different than what you’d do with a Windows form, but one thing to keep in mind is that there is limited real estate for your entire app, to include the form’s caption bar which is shared on the Pocket PC by notifications. You’ll see as we progress with this project that my current choice of text for the form caption is not a good idea as the “Bill Splitter” part stands to be covered up by those notifications.
A Mini-Rant about Smart Minimize
The next thing I’ll point out is one of my standard modifications I make to most Pocket PC applications I build. If you look at the Green-bordered box around the “OK” button in the top right corner of the Pocket PC form and the Form 1 properties window you might wonder “OK, what’s the big deal?” Microsoft has very good reasons for making the default action of a Compact Framework application to be “Smart Minimize versus closing the application outright, but my biggest gripe with it has always been the fact they use an “X” to denote “Smart Minimize” in the Compact Framework while everyone who’s used to WinForms knows that “X” is “Close”. Enough with my mini-rant, if you want to read more about “Smart Minimize versus Close” then check out the following blog entry on the Windows Mobile Team blog called “The Emperor has no Close”.
The reason I chose to override Smart Minimize and force a form closure is because the apps I’m building are mostly for entertainment purposes…not exactly something that needs to be running all the time waiting around to be disposed. That said – at least now you have a better idea of what’s going on with that and why I made the choice I did.
The Big Red Panel
Another item that stands out in the screen above is the big red rectangle at the bottom of the form. Let’s take a closer look at this in the IDE screen shot below:
The size is exactly 80 pixels high which also (not by accident!) happens to be the size of the SIP (Soft Input Panel) when it’s activated and visible on screen. The reason I put the “Big Red Panel” in place is to remind me of that when designing the form in the IDE so as not to place controls there which would be hidden by the SIP when active. It’s a lazy way around the problem in reality, but again for the type of application this is, it works just fine. See the screenshots below to compare having the SIP hidden and then active (also a live shot of a production app after the big red panel):
Of course two things are worth noting here…
1) When I’m done with development and ready to deploy the project I get rid of the “Big Red Panel” and replace it with something else, usually a banner of something else that isn’t critical to the program operation (see above).
2) This is just a simple hack, what I should be doing is to resize/and or re-position my controls as needed.
What brought about this in the first place? When I first read the Microsoft guide to getting your software “Windows Logo Certified” this was one of the requirements, that nothing could be blocked by the SIP when active. I’m a long way from being “Windows Logo Certified” but this little tidbit of info stuck with me.
Finishing the “Template”
At this point we have our basic form layout finished. We’ve chosen to override Smart-Minimize and we’ve created our “Big Red Panel” SIP placeholder. Something you might do at this point is save the project, close it all and copy the project folder to a new folder named “Pocket PC Project Template” (or something similar) and even go as far as to ZIP that new folder so that in the future it’s easy to get started with future Compact Framework project. I’ve actually saved off several such “template” folders for different development needs which I can pull out as needed. Is this a hard and fast requirement to be an effective Compact Framework developer? Nah – but it sure has helped me out since I’ve been doing it.
Section 3 – The Visual Interface
Working with limited screen real estate
We’ll finish off adding the visual elements to our form before we plug in the code. In all actuality this is the exact same as you’d do for a Windows Forms project, just find your control, drag-n-drop it on the form and then set properties on it. OK – so the purists out there are saying that I’m leaving something out…well yes. You’ll notice that because this is the Compact Framework that there are some controls missing, but for our purposes right now, we have everything we need. The screenshot below illustrates the project with the rest of the visual elements added:
As you can see we’ve simply added an image, a few label controls, a text box, a button and a few numeric up-downs. The reason this is worth mentioning is because after we cover this next part you can go to a Windows Forms app and add the same items with the same names and you’ll see the code work just the same!
Part 3 – Core Code
Section 4 – Just some math
Main Code Listing (in VB.NET)
Let’s get to the code! See the code screen shot below for what we’ll begin working with:
Alright – a few disclaimers about the code…could it be written better? Sure. I went for readability here versus elegance. So let’s focus more on function versus fashion for the time being J
Wiring the button
Once you plug that code in and call the sub from the Button_Click event you’ve got a functioning application! That wasn’t so hard was it? Of course not…and now you have a basic functioning Compact Framework application. Wasn’t that more fun than “Hello World”? I thought so too. One of the things I encourage you to do is to go ahead and test this same code in a WinForms application, after all it’s just a simple math operation after all.
The main reason I picked this application to illustrate basic development under the Compact Framework is because of what I mentioned at the start of this article. I’ve had developers come to me after I’ve given a presentation on Compact Framework to either a user group or a Code Camp audience and they’ve told me they thought developing these projects were much harder than I’ve made it out to be here. Does that mean I’m trying to say that developing real world applications for the Compact Framework will be easy? Nope. We’ve got resource constraints, chief among them processing power, network connectivity, screen real estate and user input methods to contend with if you want to develop an elegant and functional mobile application. What I hope to accomplish by providing this information is to show how easy it is to get started and also show you some of the things I’ve discovered along the way that will hopefully get you thinking about ways to tackle these problems as they relate to your development projects.
Section 5 – This program sucks, let’s improve it.
Making our program more user friendly
Let’s look next at how we can improve this project to make it a little more bearable for users other than ourselves. For example, if someone enters the numbers in the Meal Cost box using the SIP, then shouldn’t it auto-hide when they hit “Calculate”? What about going a step further and hiding the SIP if/when they hit the ENTER key on the SIP? These are perfectly valid operations and along the lines of the type of thing you might handle on a web form or Windows form so it makes sense to handle these here as well.
Additionally what happens if the user wants to figure changes in the tip by toggling up or down the Tip Percentage number? What about if the guest split option changes? For example if there are four in the party and then one person says they’ll pick up another person’s tab? Now the four becomes three. Shouldn’t our application handle these changes on-the-fly without requiring further clicks or input after toggling the up/down options? Good – I’m glad you think so because you can call it feature creep if you want, but that’s what we’re doing next!
Here’s the functionality we’re going to add:
- Auto-Hide the SIP when ENTER key on SIP is pressed
- Auto-Hide the SIP when “Calculate” button is pressed
- Auto-Convert the display of “Meal Cost”, “Tip Amount”, “Price per Guest”, and “Total Meal Cost” to currency format.
- Auto-Recalculate “Tip Amount”, and “Price per Guest” when the Tip Percentage number is toggled either up or down.
- Auto-Recalculate “Tip Amount”, and “Price per Guest” when the “# of Guests” is toggled either up or down.
Implementing the changes-Auto Hide the SIP when ENTER key is pressed
The first change we’ll tackle is Auto-Hiding the SIP when the ENTER key is pressed on the SIP. This is basically going to improve the user experience and get the SIP out of the way when we presume it’s no longer needed, (i.e., they’ve finished entering information).
Those of you who have been programming any length of time may recall capturing such events are rather easy – perhaps the thought of interacting with this SIP has you wondering if it’s more complex. The simple answer is “no”. Check it out:
First the public function to convert the key pressed into it’s ASCII number and then wire the text box key-press event to watch for the ENTER Key (ASCII 13).
Now some of you might be thinking – “Hey where’s the SIP code there?” – I confess…I got sneaky and introduced another “fix” by handling the SIP Hide as part of my TipCalc sub. If you noticed in the VB.NET code listing previously there was a Sip.Hide line of code commented out. Here’s the block of code that handles hiding the SIP:
This way of hiding the SIP is purposefully more “complex” than it needs to be because this was also part of me learning how to use PInvoke, (Platform Invoke) which is how you can call Win32 or unmanaged APIs using the .NET framework (which is of course, managed code).
A lesson I learned from a goofy mistake I made
The simpler way to handle this would have been to drop an InputPanel control on my form and handle hiding and showing it (along with resizing the form, etc.) via code that way. Way back when I was first experimenting with the Compact Framework and reading about increasing performance by limiting the number of controls you load on the form, I thought to myself “Great – I can have one less control by using PInvoke instead of dropping the InputPanel control on my form” Those of you who know better are laughing right now because you know (as I have since learned) how expensive PInvoke is! In any case this was my first introduction to PInvoke and I’ve included it ever since as a short and simple way to introduce others to it. Would you use this in a real world application? Probably not. But hopefully you’ll take away the basic concept and do some additional research on your own to determine if and when PInvoke might be a good idea for your application. Also - since you brought it up, now’s a good time to look at the PInvoke sample we’re using here.
A Gentle Introduction to PInvoke
I mentioned just a moment ago a little bit about what PInvoke is so let’s take a look at what it looks like in our code sample. Note that this is a separate class I’m using in my project. If you were going to use a lot of PInvoke code, it might make sense to build a class library of this stuff.
There is so much one could write about PInvoke, it could be a whole chapter or book in itself, much farther beyond the scope of this lesson. If you want to find out more you can get started by reading An Introduction to P/Invoke and Marshaling on the Microsoft .NET Compact Framework on MSDN. For some pre-written PInvoke signatures, check out the samples provided at http://www.pinvoke.net/
Implementing the changes-Auto Hide the SIP when CALCULATE button is pressed
The good news is that this change was implemented auto-magically when I decided to incorporate the SIP.HIDE functionality as part of the TipCalc subroutine. So hey – that was easy…every time the Calculate Button is pressed it’s wired up to call TipCalc() and the SIP goes away. Hurray!
Coming later – Packaging and Deploying your application…that’s all for now folks!