This blog attempts to be a collection of how-to examples in the Microsoft software stack - things that may take forever to find out, especially for the beginner. I see it as my way to return something to the Microsoft community in exchange for what I learned from it.

14 January 2013

For my Windows Phone 8 game “Pull the Rope” I wrote a utility class to make pairing phones and obtaining a two-way communication channel a little bit easier. I already dabbled into this while developing the game, but now I feel it’s time to show a more comprehensive solution.

I re-use the NavigationEventArgsExtensions and the NavigationMessage from my previous article “Handling Windows Phone 8 NFC startup events using the MVVMLight” without describing them further – I suggest you read this article as a preface to this one if you haven’t done so before. The utility class I describe in this article handles the pairing via tap-to-connect and provides – when that’s done – a method for sending a message and an event for receiving a message. I have peppered the code with debug statements, so can you nicely see in your output windows what’s exactly happening inside of the class when you are debugging on the phone.

Messages are sent and received as strings, therefore the message argument class is not very complex either:

The constructor subscribes this helper class to a message that will need to be fired when the application navigates to it's main page. If it detects the app is started by an NfcRequest - i.e. a tap-to-connect, the PeerFinder is immediately started to allow for the further build-up of the connection. I already described this technique in the article I already mentioned. The method Start can also be called by an the application, for instance the press of a “connect” button. Note that I only allow Bluetooth connections – this is because this class comes from my game, which does not need the highest possible speed, but the lowest possible latency. Ironically Wi-Fi seems to have a little more latency than Bluetooth.

This is kind of nicked from the Bluetooth app to app sample at MSDN, although I made it a bit simpler: only on TriggeredConnectState.Completed I need to do something, i.e. obtain a socket. For the rest of the events, I just pass them to the outside world in case it’s interested.

Next is the part that initiates and performs the actual listening for messages, once the socket is obtained:

The StartListeningForMessages basically enters an endless loop – endless that is, until the “listening” is set to “false” - waiting for GetMessage to return something. The GetMessage is almost 100% nicked from the Bluetooth app to app sample at MSDN. the first four bytes are supposed to contain the message length, the rest is payload, hence the two read actions.

Call SendMessage – and see them appear in the method subscribed to MessageReceived on the other phone.

Oh, and don’t forget to set ID_CAP_PROXIMITY in your WMAppManifest.Xaml.right?

The source code – and a working demo of this component – can be found in the demo solution right here. It’s a very simple chat-application built upon TtcSocketHelper. Of course this is all MVVMLight based, and I start off with the basic viewmodel and its properties:

We have a TtcSocketHelper itself, and two ObservableCollections of strings. ConnectMessages serves is to report the connection progress, and ReceivedMessages hold the messages received by your ‘opponent’ once the connection is established. Then we have three booleans, that basically turn on or off certain parts of the user interface depending on the state:

Initially, IsConnecting is true and CanSend is false. That should show a part of the user interface to show ConnectMessages.

If the app is started by the user, CanInitiateConnect is true as well, so the user can click on some “connect” button as well. If the apps is started by an NFC request, the process of creating a connection is initiated by someone else and the user should not be able to press a “connect” button to prevent the whole process from being south. I my mind I call the instance of the app that has been started by the user “master”, the instance started by the NFC request “slave”.

If the connection has been successfully established, IsConnecting should become false and CanSend true, disabling the controls handling the connection setup, and enabling the controls doing the actual chatting stuff.

And yeah, I know, usually CanSend != IsConnecting so I could replace this with one boolean. But that makes the designer’s job harder, as I will show further on.

Finally we have the Message property, which is where the message the user wants to send. We’ll come to that later. The viewmodel is initialized via a method “Init”, now called in the constructor:

It doesn’t really do that much – apart from initializing the ObservableCollections, creating an instance of TtcSocketHelper and subscribing to its events, and setting the initial status. There are two things to note here – one, in design mode both CanSend and IsConnecting are true so all the parts of the GUI are enabled. This is to remain friends with the designer, who can now shut on or off both the connection part of the GUI and the messaging part when he/she chooses using Blend, making the design process a lot easier - in stead of having to muck around in your code – or worse, by coming to complain to you.

The second thing to note is that this viewmodel also subscribes to NavigationMessage (just as TtcSocketHelper itself) . This is because the viewmodel likes to know as well if it’s in a master or slave app:

That first adds a message to ConnectMessages using a little helper method GetMessageForStatus (I’d suggest loading this from a resource if you do this in a real app) . After that, if it detects a TriggeredConnectState.Completed message coming by, switches from connect mode to chat mode, so to speak. Since all these events are raised outside of the UI thread, say hello to your old friend Dispatcher to prevent cross-thread access exceptions. Oh, and then of course there’s the little matter of enabling the user actually starting the whole connection process:

It adds a message to ConnectMessage (to show “see, I am really doing something!”), disables the connect button (as to prevent an annoying Windows Phone certification tester crashing your program) and then it starts the helper. All this is only needed to handle the build-up of the connection. All that actually handles the chatting is merely this:

As you can see it’s only a command that relays the message to the TtcSocketHelper and then clears the field, and a simple method listening for messages and adding received message contents to ReceivedMessages, once again with the aid of the Dispatcher.

Since this article is already way longer than I planned, I limit myself to the part of the XAML that is actually interesting:

You can see ConnectGrid whose visibility is controlled by IsConnecting, and a MessageGrid whose visibility is controlled by CanSend. Then there is the Connect button that is enabled or disabled by CanInitiateConnect. The two faces of the application look like as showed on the right. On the left image you see the app just after connect has been initiated by the ‘master’ the right shows the app after having received a message from the first phone and the user of the second phone responding.

I will add the classes described in this article to the wp8-specific version of my wp7nl CodePlex library soon. In the mean time, you can find them in the Wp7nl.Contrib project of the demo solution.

For the record, there’s also a ResetCommand in the viewmodel that makes it possible to reset the whole connection process, but that’s currently not bound to a button of sorts. I leave that as exercise for the reader ;-)

A final word: I am aware of the fact that I could also have used the Visual State Manager to turn pieces of the GUI on and off (and animate that, too) but I did not want to add even more complexity to this article.

13 January 2013

In my never-ending quest to preach the gospel of MVVM in general and MVVMLight in particular as the way to make a structured Windows Phone application I show a little part of my my newest Windows Phone app, “Pull the Rope”. It’s a basically a rope pulling contest played on two phones. I think it’s quite fun to play but I am pretty sure it’s even more hilarious to watch other people play it, swiping like maniacs on their phones.

The first version did not even have sounds – I decided to go the “ship early ship often” route this time – so some days ago I submitted a version that does some supportive sound. Of course my game is MVVMLight based and for adding the game sound I pulled a tried-and-tested (at least, by me) out of the hat – the Messenger-Behavior combo.Using the Messenger requires of course a message, so I started off with that:

So this message has only two options – an identifier for the sound that must be started, and a boolean that indicates whether the sound should be started (default) or stopped (this for sounds that are played in a loop).

Then the behavior itself. As usual, I start off with a couple of Dependency Properties, to support data binding:

SoundFileLocation (string) – the location of the sound file to play

SoundName (string) – the sound identifier; if PlaySoundEffectMessage.SoundName has the same value a this property, the behavior will take action.

Repeat (bool) – indicates if the sound should be played in a loop or not.

I hope you will forgive me for not including the Dependency Properties’ code in the this article as it is pretty much run of the mill and takes a lot of space.

The core of the behavior itself is actually pretty simple. It’s meant to be used in conjunction with a MediaElement. First, the setup. I created this as a SafeBehavior to make setup and teardown a little less complex:

So basically this behavior subscribes to the message type we just defined. Then it goes on initializing the MediaElement – disabling hit test and autoplay, actually setting the sound file URI, initializing it to the beginning and initializing repeat (or not).

The method DoPlaySoundFile, which kinda does all the work, isn’t quite rocket science either:

The first method, SetRepeat, enables or disables repeat. As a MediaElement does not support the endless loop by itself, repeat as such is implemented by subscribing the method AssociatedObjectMediaEnded to the MediaEnded event of the MediaElement – that does nothing more than kicking off the sound again. If repeat has to be turned off, the AssociatedObjectMediaEnded is unsubscribed again and the sound automatically ends.

Finally, the last method is called when the behavior is deactivated. It removes the messenger subscription and a possible repeat event subscription.

So how would you go about and use such a behavior? To demonstrate it’s working, I have created a small sample solution with the very exiting *cough* user interface showed to the right. What this app does is, as you click on the go button, is fire off the PlaySoundCommand command in the following, admittedly somewhat contrived view model:

This initializes and starts a DispatcherTimer that will fire every four seconds. So the first four seconds after you click the button absolutely nothing will happen – I wanted to simulate the situation in which an event in the view model, not necessarily directly kicks off the sound. At the first tick – after four seconds – the view model fires a message making the behavior start the “Sad trombone” sound, which runs about four seconds. Then it fires off the “Ping” message, which causes the “Ping” sound to be started and repeated by the behavior. After another four seconds (good for about three ‘pings’) it’s killed again by the second “Ping” message. And then this little app has done all it could. Cue sad trombone indeed ;-)

As to the XAML to make this all work, I’ve outlined in red (and underline for the color blind readers) the interesting parts:

On top we have the DataContext set to our viewmodel, which, by using it this way, is automatically instantiated. The “go!” button is bound to the PlaySoundCommand, and then you see near the bottom the two MediaElement objects which each a PlaySoundEffectBehavior. The first one plays the “Sad trombone" once as the message is received, the second repeatedly (Repeat=”True”) the “ping” sound until it receives a message with “Start” the to “false” indicating it should shut up.

In the sample solution you will find two projects: SoundMvvm (the app itself) and Wpnl.Contrib, which both the behavior and the message class. As you probably understand from this setup, both classes will be soon in the wp7nl CodePlex library.For the record, this is a Windows Phone 8 app, but I think this should work on Windows Phone 7 as well, although on 7 I would still go for the XNA SoundEffect class. The technique used for this behavior comes from my Catch’em Birds for Windows 8 app by the way, where you don’t have XNA at all.

Feedback, comments and tokens of appreciation

If you spot things that are incorrect, or if you don't understand what I mean, please drop a comment on the offending article and I will help you ASAP. You can e-mail me at joostvanschaik at outlook dot com or contact me via twitter.

If you find the information on this blog useful (and apparently some 600+ people per day do on average) please let me know as well, that encourages me to keep doing this. Or do tell others - that made me an MVP; who knows what more it might bring ;-P

Disclaimer and legal stuff

Although I take great care in providing quality samples, all postings, articles and/or files on this site are provided "AS IS" with no warranties, and confer no rights. The views expressed on this blog are strictly my own and do not necessarily reflect the views of my employer, or anyone else on the planet for that matter.

I usually make original content, sometimes building upon other people's work. Sometimes I explain things that can be found elsewhere because I felt what I read was not clear enough for my limited mind so I explain it the way it finally clicked with me. In all cases I take great pains to be sure to link to people or articles who deserve the credit. If you think I have shortchanged you on the credits please let me know.

Please note, I do not work for Microsoft and while I proudly wear the title of "Microsoft Most Valueable Professional", my opinions, files offered, etc. do not represent, are approved of, endorsed by or paid for by Microsoft. The only power behind it is me and my sometimes runaway passion for parts of Microsoft's technology.