The Visual Basic Team : VB2005

Spot the Bug! – The Key to using Anonymous Types (Jonathan Aneja)

VBTeam — Tue, 17 Nov 2009 07:54:00 GMT

This one’s going to be long, but for those of you who’ve felt the first 3 in this series were too easy I promise this one’s tougher J.

Let’s say you want to list all the customers from a table in a ComboBox, and update the UI based on which one is selected. To do this we’ll need to bring back two fields from the database – the customer’s name and the customer’s ID. When a customer is selected we want the ComboBox’s SelectedValue property to equal the customer’s ID.

Here’s some quick code that gets us up and running (using Northwind and LINQ to SQL):

Dim db As New NorthwindDataContext

Dim query = From row In db.Customers _

Select row.CompanyName, row.CustomerID

ComboBox1.DataSource = query.ToList()

ComboBox1.DisplayMember = "CompanyName"

ComboBox1.ValueMember = "CustomerID"

But now let’s say your boss looks at the app and says “I want you to add an ‘All Customers’ option as the first item in the list.” How would you do that? You’d need to insert an anonymous type into an existing sequence of anonymous types, which is tricky given that you can never actually use the type’s name.

Thankfully there’s a trick that uses generic parameter inference that allows us to do this (it relies on the fact that the compiler will share (or “unify”) the definition of multiple anonymous types when they have the same number of members, in the same order, of the same type, with the same names, and the same mutability):

Dim db As New NorthwindDataContext

Dim query = From row In db.Customers _

Select row.CompanyName, row.CustomerID

Dim allOption = New With {.CompanyName = "All Customers", _

.CustomerID = "-1"}

ComboBox1.DataSource = AddOptionForAll(query, allOption).ToList()

ComboBox1.DisplayMember = "CompanyName"

ComboBox1.ValueMember = "CustomerID"

...

Function AddOptionForAll(Of T)(ByVal sequence As IEnumerable(Of T), _

ByVal allOption As T) As IEnumerable(Of T)

'wrap individual element in an array and then union the two sequences

Return (New T() {allOption}).Union(sequence)

End Function

As long as we have an anonymous type that’s compatible with the anonymous type that the query generated, the compiler will determine that sequence and allOption are actually the same type and this should work fine.

Ok so let’s get to the bug – well in this case spotting it is pretty simple (it doesn’t compile J), but fixing it is tricky (though I’ve already given two pretty big hints). Here’s the text of the compiler error (it’s on the line that calls AddOptionForAll):

Data type(s) of the type parameter(s) in method 'Public Function AddOptionForAll(Of T)(sequence As System.Collections.Generic.IEnumerable(Of T), allOption As T) As System.Collections.Generic.IEnumerable(Of T)' cannot be inferred from these arguments because they do not convert to the same type. Specifying the data type(s) explicitly might correct this error.

What’s wrong and how do we fix it?

Answer: We actually told the compiler to generate two different anonymous type definitions, and thus it can’t unify them because the types really are different.

From earlier: “…the compiler will share (or “unify”) the definition of multiple anonymous types when they have the same number of members, in the same order, with the same names, and the same mutability”

The anonymous type that the query generates will have ReadOnly properties, whereas the anonymous type that we generated (allOption) will have Read/Write properties. The fix is to allOption immutable so that its structure will match the result of the query:

Dim allOption = New With {Key .CompanyName = "All Customers", _

Key .CustomerID = "-1"}

The “Key” modifier tells the compiler to make those properties ReadOnly and to override Equals and GetHashCode such that they only consider “Key” properties when deciding if two instances of the same anonymous type are equal. (the other hint was in the title J). For the query above, the compiler automatically inserts the “Key” modifier - i.e. what we wrote is exactly equivalent to this:

Dim query = From row In db.Customers _

Select New With {Key row.CompanyName, Key row.CustomerID}

So with a simple fix to the allOption line we’re now using the same anonymous type definition and everything works fine.

VB’s anonymous type syntax is very flexible and provides three different options: immutable, fully mutable, or partially mutable (i.e. some fields are ReadOnly while others are not). Even for a simple scenario like adding an option to a list, the better you understand how things work under the covers the easier it’ll be to debug problems later J.

Spot the Bug! – Is it in VB or XAML? (Jonathan Aneja)

VBTeam — Fri, 13 Nov 2009 03:39:00 GMT

What’s wrong with the following WPF code?

Class Window1

Sub OK_Click(sender As Object, e As RoutedEventArgs) Handles OK.Click

MsgBox("Button Clicked")

End Sub

End Class

<Window x:Class="Window1"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

Title="Window1" Height="300" Width="300">

<Grid>

</Grid>

</Window>

Answer: The message box will be displayed twice! To understand why, open up the project in Reflector, and in the System_Windows_Mark_IComponentConnector_Connect method you’ll see these two lines:

    Me.OK = DirectCast(target, Button)

    AddHandler Me.OK.Click, New RoutedEventHandler(AddressOf Me.OK_Click)

Ok so we’re adding one handler here, but click the link to navigate to “OK”. You’ll see this is actually a property of type Button (that’s what the compiler does for WithEvents/Handles – the full story of how WithEvents works is its own blog entry…). In the Setter you’ll see this code:

    If (Not Me._OK Is Nothing) Then

        AddHandler Me._OK.Click, handler

    End If

So now we can clearly see there’s two AddHandler calls and thus the event gets handled multiple times by the same method (which is perfectly legal). One of them came from Handles OKButton.Click, and the other came from Click="OK_Click".

The key thing to realize is that if you wire up the eventhandler in XAML, don’t wire it up in code using Handles (and vice-versa). Thankfully in this scenario it’s obvious that there’s a problem because there’s a message box, but if the eventhandler was doing something more subtle (such as incrementing a counter or modifying some other state), this can lead to hard-to-diagnose bugs.

Spot the Bug! – Much ado about Nothing… Part 2! (Jonathan Aneja)

VBTeam — Fri, 06 Nov 2009 07:46:00 GMT

In yesterday’s post we saw that the use of the wrong comparison operator with Nothing in an If block can lead to surprising results. Let’s look at a slightly different case today:

Dim x As Integer = Nothing

If x = Nothing Then

MsgBox("A true statement - we land here")

Else

MsgBox("The statement is a lie - we land here")

End If

What gets printed? If the code is intended to print “A true statement…”, is there actually a bug in this code?

Answer: The code is correct according to its “specification” (I’m using the term loosely here J), so from a technical point of view there is no bug here. However, from a code readability and maintenance point of view, I’d argue that there is a bug.

The Nothing literal in VB means “default value for this type”, and for an Integer that would be 0. So the code above is exactly equivalent to this:

Dim x As Integer = 0

If x = 0 Then

MsgBox("A true statement - we land here")

Else

MsgBox("The statement is a lie - we land here")

End If

Now that’s way more readable than the version above, and dramatically reduces the potential for confusion. In general*, if you ever find yourself writing “= Nothing” in a conditional expression, you should either be changing the = to “Is” (as we saw yesterday), or you should change Nothing to the actual default value if possible.

The next post will have a real bug, I promise J

*Yes, there may be cases such as structure/generics/overloaded operators where you actually would want to say “= Nothing” – my point is that if you’re going to do this make sure you know what you’re doing, and insert a comment so that those reading your code also know what you’re doing J.

Spot the Bug! – Much Ado about Nothing… (Jonathan Aneja)

VBTeam — Wed, 04 Nov 2009 02:32:00 GMT

Microsoft has this neat mailing list called “Spot the Bug” where developers can send interesting snippets of code that look correct but actually have subtle bugs in them. The puzzles are a lot of fun and I’ve always thought it’d be a fun thing to try here on the team blog. Over the past year or so I’ve been keeping a list of interesting bug reports and emails where people have been tripped up by some of VB’s hidden subtleties (though admittedly many of these could apply to C# as well).

The format’s gonna be a bit of an experiment – let me know if you prefer to see the answer in the same post or posted a day later. Alright let’s get started…

Spot the Bug:

The following code is intended to print “Yes” – will it?

Dim x As Integer? = Nothing

If x = Nothing Then

MsgBox("Yes: x contains null")

Else

MsgBox("No: x does not contain null, and has a real value")

End If

Answer: No! We’re using the equality operator to compare a nullable integer with Nothing – this results in null propagation, i.e. the result of the expression is Nothing. An If-statement attempts to convert its condition to a Boolean, so basically we’re left with this:

If Nothing Then

Else

'Obviously we'll always land here

End If

This can be really surprising when working with nullables, so we’ve decided to add a warning for this case in VB10:

The warning explains the fix – use “Is” instead of = to avoid the null propagation and get the semantics you expect:

Dim x As Integer? = Nothing

If x Is Nothing Then

MsgBox("Yes: x contains null")

Else

MsgBox("No: x does not contain null, and has a real value")

End If

Check back for a similar case but with a bit of a twist tomorrow...

Getting Loopy (Matt Gertz)

VBTeam — Thu, 08 Oct 2009 00:50:00 GMT

In my last post, I talked about the hidden costs that can occur whenever you call out to methods, particularly in loops. In looking at my examples, reader KG2V commented that another thing that folks need to be aware of is avoiding the assumption that the world (or, in this case, a list) is a static thing. It’s a good point and it deserves some attention, particularly given that different languages will react in different ways to change.

To illustrate this point, let’s assume that we have a form with a ListBox on it, and that we also have a button on the form that, when clicked, runs the following VB code:

' Bad -- don't do this

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click

For i As Integer = 0 To ListBox1.Items.Count - 1

ListBox1.Items.RemoveAt(i)

End Sub

Ostensibly, we want to remove all of the items from the ListBox. (Yes, normally we’d use Clear() to do that, but stay with me for a moment; I’ll switch to more “real” cases in a few paragraphs.) But if we run this code, we’ll get an exception. Why? Because whenever we remove an object, all of the indices of the objects after it will decrease by 1. Let’s assume that there are three objects in the list - A, B, and C – so that Count=3:

· When i = 0, we’ll remove the object at index 0, which is A. B now moves to index 0, and C now moves to index 1.

· When i = 1, we’ll remove the object at index 1, which is C. There is nothing after C, so nothing else changes.

· When i =2, we’ll remove the object at index 2, which is… nothing. There’s only one object left, which is B, and it’s at index 0. So, we get an out-of-bounds exception.

In VB (as was pointed out to me in the comments section of my last point), the value of Count is only assessed once, right when the loop is encountered, so we will always loop through (in this case) three times.

But is the lack of reevaluation of Count the only issue? Maybe not. Let’s try the same method in C#, in which Count is evaluated on every iteration:

// Bad -- don't do this.

private void button1_Click(object sender, EventArgs e)

{

int i;

for (i = 0; i < listBox1.Items.Count; i++)

{

listBox1.Items.RemoveAt(i);

}

· When i = 0, we’ll remove the object at index 0, which is A. B now moves to index 0, and C now moves to index 1.

o Now, we’ll loop back to the top. The value of i becomes 1, and the value of Count becomes 2. The stop condition is not met, so we keep going.

· When i = 1, we’ll remove the object at index 1, which is C. There is nothing after C, so nothing else changes.

o Again, we loop back to the top. The value of i becomes 2, and the value of Count becomes 1. The stop condition is met, and we exit the loop.

So, although no exception is thrown, the method also fails in C# -- B is left behind. So, the problem isn’t whether or not Count is evaluated; it’s that the elements in the list are changing indices on each deletion.

Sometimes doing things backwards is good

This is why, in the case where multiple removals need to be made on an indexed list, a smart programmer (all of whom are yawning right now as they read this) will work backwards. That is, they start with the largest index and work down towards zero. For example, imagine that we want to remove the 4^th, 7^th, and 9^th element from a list. We don’t want to do it this way:

' Bad -- don't do this

ListBox1.Items.RemoveAt(4)

ListBox1.Items.RemoveAt(7)

ListBox1.Items.RemoveAt(9)

Once we’ve removed the 4^th item, then the element at 7 will have moved to 6 and the element at 9 will have moved to 8. After we’ve removed the new 7^th item, the element at 8 will move to 7, and so on. We’d either be removing the wrong elements or we’d crash. It’s far better to do them in reverse order:

ListBox1.Items.RemoveAt(9)

ListBox1.Items.RemoveAt(7)

ListBox1.Items.RemoveAt(4)

None of the indices up front will be affected by changes that are occurring behind them in the list – their indices won’t change, and this will work fine.

This issue comes up when you are (for example) deleting items from a listbox that supports multiselection. You basically have two ways to get the selected items in a listbox: you can use the SelectedIndices member function, which returns a collection of indices, or you can use SelectedItems, which returns a collection of selected items. Given either collection, there’s no way to say “remove all of these.” There is a “Remove” command on the resulting collections, but if you use it, you’ll just be removing the item from *that* collection and not from the ListBox, which has its own collection of items – essentially, you’ll just deselect the items.

So, what do you do? At first, it looks like you have two options; you could try removing them from the master list based on item, or based on object. Let’s look at removal based on the item:

' Bad -- don't do this

For Each index As Integer In ListBox1.SelectedIndices

ListBox1.Items.RemoveAt(index)

This won’t work. The selected indices are in numerical order (no matter in which order you selected them), so you’ll be sliding indices on each deletion and will subsequently delete the wrong things. You won’t crash if you overreach on an index, because the For…Each loop will check for Nothing when it does a MoveNext internally and will exit gracefully, but this is actually worse since it may take longer before you notice a problem!

This won’t work either, and will potentially crash:

' Bad -- don't do this

For index As Integer = 0 To ListBox1.SelectedIndices.Count - 1

ListBox1.Items.RemoveAt(ListBox1.SelectedIndices(index))

Again, the indices for the downstream objects will decrease, you’ll delete the wrong things, and you’ll likely crash.

You can, however, iterate down instead, as long as you are confident that the selected indices are in numerical order (as they will be in this case):

' This works:

For index As Integer = ListBox1.SelectedIndices.Count - 1 To 0 Step -1

ListBox1.Items.RemoveAt(ListBox1.SelectedIndices(index))

Having found something that works via iteration, let’s now consider the enumeration angle instead. In general, I prefer to enumerate lists whenever possible instead of iterating through them. This is not one of those times, though. Consider this code, which will fail:

' Bad -- don't do this

For Each item In ListBox1.SelectedItems

ListBox1.Items.Remove(item)

“Well, c’mon, why doesn’t this work?” I hear you cry. “I don’t care about indices in this case, I’m not even using them; I’m just removing specific items.” True, but if you run this code, you will indeed get an exception essentially stating that the collection has been modified and the list of selected items is no longer valid for enumeration. We can’t work around this by assigning the collection of selected items to another variable and enumerating on that, since that just creates a reference to the same collection. In order for it to work, you’ve have to get the references out of the collection itself so that the ListBox is no longer part of the equation on the removal loop’s assessment.

' Really, this is just silly -- don't ever do this

Dim selItems As New Collection

For Each item In ListBox1.SelectedItems

selItems.Add(item)

For Each item In selItems

ListBox1.Items.Remove(item)

Functionally, this will work; however, you shouldn’t do it for two reasons:

· First of all, it’s stupid – you have to loop through twice. Occasionally, I do need to clone lists, like when creating an editable list from a read-only list – I’ve done that in a previous blogpost on this site, in fact. But my motives are not so noble here; I’m using this for no other reason than allowing enumeration to work.

· Second, each call to RemoveItem has a hidden cost – namely, the list has got to go find that item. In this case, you can bet that there’s good hashing going on that doesn’t make that as painful as it might be, but do you really want to count on that, given the better numeric alternative above?

No, just there’s really no good way to do removal by enumeration that I’ve ever found. And since each object is totally clueless about whether it itself is selected or not, you can’t even enumerate through the collection yourself and delete it if it’s marked as selected.

Of course, I’ve just talked about deletions, since they are more interesting than additions due to the crash potential. However, additions can also mess you up in a loop due to similar index changes, and I’ve actually run into cases where a list may have both insertions and deletions done, so that I wasn’t even able to leverage the change in list size as a clue to figure out what had happened to the data. The bottom line is, whenever doing an operation within a loop, you need to understand whether or not that operation will collide with your loop conditions and assumptions. Generally, you control this in your code, but in multithreaded environments, where changes to an existing store of data might be made from a different thread “simultaneously” with your thread, you really need to understand how thread-safe your code is with respect to data changes. (But that is a story for another time.)

‘Til next time,

--Matt--*

Hidden Costs (Matt Gertz)

VBTeam — Tue, 06 Oct 2009 22:54:00 GMT

(Note: there was a grievous error in this post based on a bad assumption on my art regarding VB. Not feeling the need to hide my ignorance :-), I have instead made a number of edits in this post to bring it back to some semblance of reality.)

One thing that gets me annoyed with myself is realizing that the product or service I’ve just bought has some hidden costs that I didn’t anticipate. It might be as complicated as realizing that my plane ticket has all sorts of byzantine surcharges and luggage costs, or as simple as making budgeting for a new killer gaming PC and forgetting about the sales tax – it seems that there are always extra costs out there that will come back to bite you. Being (as I have said in past postings to this blog) an inherently lazy person, and being fully caught up in our “I must have the sparkly thing right now” culture, I’m apt to overlook the fine print in any purchase agreement unless I really force myself to slow down and pay attention to the details.

One of the times I really have to pay attention is when I’m reviewing code here at Microsoft. As a member of the release team that makes the final decisions as to what last-minute fixes are safe enough to be applied to an imminent release, it’s my job to take a look at the proposed fix and make sure that it doesn’t introduce more problems than it purports to solve – i.e., that it doesn’t add hidden costs.

On the rare occasion that I find a problem in someone’s code, it’s usually something that’s obviously dysfunctional – a case where a variable isn’t initialized properly, or where a different team has simultaneously made a change that will render this change dangerous. But some of the problems are more subtle, and might not be obvious if only minimal testing and review has been done. Consider the following code (very similar to a case I reviewed here at work the other day):

Public MyList As New List(Of String)

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click

Dim s As New System.Text.StringBuilder

For i As Integer = 0 To MyList.Count - 1

s.Append(MyList(i))

End Sub

Edit: This is an error in my blog post – I hadn’t realized that VB, unlike many other languages, only gets the value of the stop condition once (thanks to Phil Wells for pointing this out). To make my point, I would have to be using code like this:

Dim s As New System.Text.StringBuilder

Dim i As Integer = 0

Do While i < MyList.Count() - 1

s.Append(MyList(i))

i += 1

Loop

The method Count() might still have a hidden cost, but in the For Loop case, I’m at least only hitting it once. The fact that VB only analyzes the stop condition once leads to a different issue to be aware of that I’ll cover in my next blog.

Seems pretty simple, yes? When a button is clicked, the code iterates through the strings in a list and appends them to a StringBuilder, creating (for whatever reason) one long string containing all of the contents. And, to cursory appearances, it will function correctly.

However, the code has hidden costs. You see, written this way, the value MyList.Count is going to be reevaluated on every iteration of the “For” loop, even though the value itself isn’t changing. Furthermore, my indexing into MyList, which is always with reference to the beginning of the list, will also have a non-zero impact. This impacts the performance of the code and will make my customers unhappy over the sloth-like operation of my application.

In this case, the cost isn’t really high, as Count() is a property wrapping something that’s stored as a private integer member, and index referencing also has tricks to speed it up, but there’s still a cost and it can add up. It’s even worse if the Count() call has to be calculated! Consider this really awful code where I’ve created my own “List” type:

Public Class MyLameObject

' For some unknown reason, I'm creating my own linked list instead of using a List(Of) generic.

' Please don't do this for real!

Public data As String

Public NextMLO As MyLameObject

Public Sub Insert(ByVal mlo As MyLameObject)

If NextMLO IsNot Nothing Then

NextMLO = mlo

Else

mlo.NextMLO = NextMLO.NextMLO

NextMLO.NextMLO = mlo

End If

End Sub

Public Function Count() As Integer

Dim ct As Integer = 0

Dim current As MyLameObject = Me

Do While current IsNot Nothing

ct += 1

current = current.NextMLO

Loop

Return ct

End Function

Public Function Item(ByVal index As Integer) As MyLameObject

If index >= Count() OrElse index < 0 Then Return Nothing

Dim current As MyLameObject = Me

For i As Integer = 0 To index - 1

current = current.NextMLO

Return current

End Function

End Class

Public MyLameObjectHeader As New MyLameObject

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _

Handles Button1.Click

Dim s As New System.Text.StringBuilder

For i As Integer = 0 To MyLameObjectHeader.Count - 1

s.Append(MyLameObjectHeader.Item(i))

End Sub

Perhaps as a school assignment, I’ve created a singly-linked list which contains objects of type “MyLameObject” (instead of using optimized collections that we provide). I’ve also created a member function called “Count” which returns the number of objects in my list (starting from the current node) and another member function called “Item” which returns me a reference to a specific object in the list, as indexed from the current node. The code will compile and it will “work.” But, oh! It has so many hidden costs, and if the definition of MyLameObject exists in an assembly for which I don’t have the source code, I might not even realize it!

First, let’s look at button click handler. It’s calling Count() on every single iteration, and there will be a number of iterations equal to the value returned from Count(). Count(), in turn, walks the entire list every time it’s called. So, that means that if my list contains 1000 items, that means that I’ll be referencing a MyLameObject one million times! (This is what they refer to as an “O(n²) problem” in computer science classes.)

But wait, it gets worse: ~~the code for Item() calls Count() also on each iteration to verify that the index is not out of bounds – that brings us up to a count of 1001000 MyLameObject references~~.

Edit: As noted above, that isn’t true for VB, though it would be for many other languages

And, of course, Item() itself needs to walk the list to actual get to the desired item, on every iteration – that adds 500500 more object hits (using the n(n+1)/2 formula) , for a grand total of ~~1501500~~ 1500500 object hits. And all that just to concatenate 1000 strings! That, I fear, is going to slow down my code’s performance somewhat.

Now, of course I could add code to get track of values for Count(), and that would reduce my cost to a third of what it was. I could use some clever hashing algorithm to more easily get to the items while still being able to use method calls. I could enumerate the list myself instead of relying on “Count” or on “Item,” and that would really cut my costs down dramatically. Or, best of all, I could avoid reinventing the wheel and using the classes that VB.NET already supplies for me, since we do our best to optimize them.

But that’s not the point that I’m trying to make here. The point is, whenever you call a function, you are at its mercy performance-wise – you are stuck with whatever hidden costs it contains. You might not even be able to determine what these hidden costs are if you don’t own the code you’re calling, except by experimentation. And if you call that function iteratively, you’re just compounding the problem.

Now, you can’t avoid making calls into code you don’t own – at some level, we all use libraries or assemblies that are handed to us. But you can be smart about how you use them~~. Consider *this* code:~~

~~Dim s As New System.Text.StringBuilder~~

~~Dim count As Integer = MyList.Count~~

~~For i As Integer = 0 To count - 1~~

~~s.Append(MyList(i))~~

~~Next~~

~~Now, I’m only calling Count() once, so I minimize the impact of its cost! Or,~~

Edit: As above, this doesn’t actually make a difference in VB. Of course, you still have the cost of “Count(),” whatever it may be. In this case, it’s just a property read; if it’s some home-grown collection or data repository, Count() (or it’s analog) could be a lot more costly.

Consider this even better example that you can use on collections that support IEnumerable (as all System.Collections types do):

Dim s As New System.Text.StringBuilder

For Each data As String In MyList

s.Append(data)

Yeah! Now I’m firing on all cylinders! Now I don’t have to worry about indexing costs either – I’m just walking the list, collecting my strings in the fastest way possible. Really, the only cost I have to deal with is the cost of actually appending the data (which is in fact why I’m using the highly-optimized StringBuilder class instead of just concatenating strings using a much more costly s &= data line).

So, rule of thumb: whenever calling any method, expect hidden costs (magnified if you’re in a loop) and work to minimize them. Call the methods outside of the loop if they are providing data that will remain the same throughout the loop, such as a count, and avoid them altogether if there’s an alternative way to iterate through the data that doesn’t implicitly involve resetting your position. Your customers will appreciate the time savings!

‘Til next time,

--Matt--*

It’s a Small World, After All, part 2 – VB, C#, and GPS (Matt Gertz)

VBTeam — Wed, 05 Aug 2009 22:30:00 GMT

In my previous post, we fixed up a C# GPS library to provide more support, and wrote all of the UI for a VB GPS application, all based on (but modified from) a Mobile GPS sample in the Windows Mobile 6.0 SDK. In this post, we’ll finish up the app by enabling a bunch of cool functionality not exposed in the original sample.

The C# sample uses a helper function called UpdateData – I will too (as noted above), except that the code is going to deviate significantly. We’ll start out by checking is the GPS is actually running, just in case we called outside of an event:

Protected Sub UpdateData(ByVal sender As Object, ByVal args As System.EventArgs)

If vbgps.Opened Then

First, we’ll update the screen with whatever cached device data we have:

If device IsNot Nothing Then

Me.Text = "VBGPS: " & device.FriendlyName.ToString

Me.StatusLabel.Text = device.DeviceState.ToString

End If

This will change the title bar to include the name of the GPS device in use (in case you have multiple devices) and will set the StatusLabel to whatever the state of the GPS is (e.g., “On”).

All other interesting information comes from the cached position object:

If position IsNot Nothing Then

We’ll start with the altitude. There are two ways of calculating altitude – sea level (self-explanatory), and ellipsoid (which calculates altitude against a “perfect” ellipsoid representation of the otherwise pear-shaped earth). We’re going to go with ellipsoid. We’ll need to check if the information for it is reported as being valid, and if so, assigned the value to the appropriate label. The value is returned to us in meters, and we’ll also show it in feet by multiplying the result by 3.281 feet/meters. Again, we’ll format the results so that we only have two decimal places:

If position.EllipsoidAltitudeValid Then

Me.AltLabel.Text = CDbl(position.EllipsoidAltitude).ToString("####0.00") _

& " m (" & CDbl(position.EllipsoidAltitude * 3.281).ToString("####0.00") _

& "ft)"

End If

Next is velocity. The speed value will be in meters per second; We’ll show it in kph and mph. I’ll also show the heading (if valid), and separate the two by an “@” sign (e.g., “88.00 kph (54.69 mph) @ 45.23°”:

If position.SpeedValid Then

Me.VelLabel.Text = CDbl(position.Speed * 1.852).ToString("###0.00") _

& " kph (" & CDbl(position.Speed * 1.151).ToString("###0.00") & " mph)"

If position.HeadingValid Then

Me.VelLabel.Text = Me.VelLabel.Text & " @ " _

& position.Heading.ToString("##0.00") & "°"

End If

Latitude and longitude are next. We’ll be showing them in both DMS and DM format, using the methods we wrote in C#. The only interesting thing here is converting negative values to W or S indicators:

If position.LatitudeValid Then

Me.LatLabel.Text = position.LatitudeInDegreesMinutesSeconds.DMSString() _

& " (" & position.LatitudeInDegreesMinutesSeconds.DMString & ")"

If position.Latitude < 0 Then

Me.LatLabel.Text = Me.LatLabel.Text & " S"

Else

Me.LatLabel.Text = Me.LatLabel.Text & " N"

End If

If position.LongitudeValid Then

Me.LongLabel.Text = position.LongitudeInDegreesMinutesSeconds.DMSString() _

& " (" & position.LongitudeInDegreesMinutesSeconds.DMString & ")"

If position.Longitude < 0 Then

Me.LongLabel.Text = Me.LongLabel.Text & " W"

Else

Me.LongLabel.Text = Me.LongLabel.Text & " E"

End If

Satellites are a bit more complicated, and if you do a straight port of the C# sample, you’ll get runtime errors. This is because the C# code references values which may be NULL even if the values are valid – my VB code checks to see if the values are Nothing before referencing them. (A value of Nothing is equivalent to zero satellites in this case, since the C# library uses the existence and size of the satellite array to generate a value.)

There are three satellite components that we need to use – the number of satellites used to create a positioning solution, the number of them in view, and the total count of satellites – the resulting string should look something like (for example) “4/7 (8)”, depending on the actual number of satellites involved.

If position.SatellitesInSolutionValid AndAlso _

position.SatellitesInViewValid AndAlso _

position.SatelliteCountValid Then

Dim SatSol As Satellite() = position.GetSatellitesInSolution()

Dim SatView As Satellite() = position.GetSatellitesInView()

Dim SatStr As String

If SatSol IsNot Nothing Then

SatStr = SatSol.Length & "/"

Else

SatStr = "0/"

End If

If SatView IsNot Nothing Then

SatStr += SatView.Length & " ("

Else

SatStr += "0 ("

End If

Me.SatLabel.Text = SatStr & position.SatelliteCount & ")"

End If

You can actually get more information on each satellite (such as its location in orbit, etc.) simply by exploring the methods and fields on the satellite object, but for now this will do fine for our project.

Now that we’ve shown the information as to where we are, we need to tell the user how to get to where they are going. Creating maps and routes is just a bit beyond the scope of this blog, but we can certainly indicate direction and distance. Let’s assume the existence of a helper function called UpdateTargetInfo at this point – we’ll define it later:

UpdateTargetInfo()

End If

End Sub

Now, you’ll recall that we added fields to allow the user to specify the target point. We’ll want to translate the users entries into actual lat/long coordinates, and it would also be really cool if we could update the distance and direction in real-time. There are six fields and two combo boxes that are involved with the target, so let’s create a handler to deal with all of their change events (TextChanged for the text boxes, SelectedIndexChanged for the combo boxes):

Private Sub Target_TextChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles _

LatDegTB.TextChanged, LatMinTB.TextChanged, LatSecTB.TextChanged, _

LongDegTB.TextChanged, LongMinTB.TextChanged, LongSecTB.TextChanged, _

LatPosCB.SelectedIndexChanged, LongPosCB.SelectedIndexChanged

I’m going to use a helper function to collect the data, because collecting latitude data is identical to collecting longitude data, so we might as well treat them generically. The helper method will be called “CacheCoordinate” and we’ll define it later. As arguments, we’ll pass through the relevant controls and caches, and then update the distance and direction afterwards:

CacheCoordinate(LatDegTB, LatMinTB, LatSecTB, LatPosCB, TargetLatitude)

CacheCoordinate(LongDegTB, LongMinTB, LongSecTB, LongPosCB, TargetLongitude)

UpdateTargetInfo()

Now, the user could enter all sorts of errors accidentally into the text fields, any of which could cause an exception to be thrown. I could check and recheck for text and oddly-formed numbers being inserted into those fields, but for this exercise, I’m going to go with the moral equivalent of duct tape and simply use a Try block around the code we just wrote. If there’s an error, I’ll simply tell the user that their entered target information is invalid, and so the distance and direction cannot be determined:

Try

CacheCoordinate(LatDegTB, LatMinTB, LatSecTB, LatPosCB, TargetLatitude)

CacheCoordinate(LongDegTB, LongMinTB, LongSecTB, LongPosCB, TargetLongitude)

UpdateTargetInfo()

Catch ex As Exception

Me.DistLabel.Text = "Invalid target."

Me.DirLabel.Text = "Invalid target."

TargetLatitude = Nothing

TargetLongitude = Nothing

End Try

End Sub

Now, we’ll start to parse together the data, starting with latitude. The combo box for it has two values – “N” or “E” (at the 0 position) and “S” or “W”(at the 1 position) – so a simple check on the index will tell us if we’ll be using positive or negative coordinates:

Private Sub CacheCoordinate(ByVal DegField As TextBox, ByVal MinField As TextBox, _

ByVal SecField As TextBox, ByVal PosField As ComboBox, _

ByRef cache As DegreesMinutesSeconds)

Dim isPositive As Boolean ' South and west are negative values

isPositive = (PosField.SelectedIndex = 0)

Note that the cache needs to be passed in as ByRef, since we’ll be allocating new memory around it!

So, a user might want to enter data in three ways: degrees with a decimal portion; degrees and minutes, with minutes having a decimal portion; degrees, minutes, and seconds, with seconds having a decimal portion. To help the user, we’ll hide all subsequent fields if a decimal point is used in one of the earlier fields. That is, if the user enters “47.” in the degrees field, then we know that he/she won’t need the minutes or seconds fields, so we’ll just hide them:

If DegField.Text.Contains(".") Then

MinField.Hide()

SecField.Hide()

Next, we’ll get the degrees value and makes sure that it is between 0 and 180 degrees:

Dim ddeg As Double = CDbl(DegField.Text)

If ddeg > 180 OrElse ddeg < 0 Then

Throw New Exception()

End If

Now, if the coordinate is south or west, we’ll have to multiply by -1 to indicate that:

If Not isPositive Then

ddeg *= -1.0

End If

And then finally cache the coordinate:

cache = New DegreesMinutesSeconds(ddeg)

Now, if the degrees field didn’t have a decimal, we’ll need to remember to show the minutes field in case it had been hidden earlier:

Else

MinField.Show()

We also know that degrees will be a whole number, so let’s cache that away:

Dim deg As UInteger = CUInt(DegField.Text)

The next case is the degree-minutes case – if the minutes field has a decimal, we’ll know that seconds won’t be needed, so we’ll hide it:

If MinField.Text.Contains(".") Then

SecField.Hide()

We then validate both the degrees (0…180) and the minutes (0…60), and then cache the target using the appropriate DegreesMinutesSeconds constructor that we created earlier:

Dim dmin As Double = CDbl(MinField.Text)

If deg > 180 OrElse deg < 0 _

OrElse dmin > 60 OrElse dmin < 0 Then

Throw New Exception()

End If

cache = New DegreesMinutesSeconds(isPositive, deg, dmin)

If we’ve gotten this far without finding a decimal place, then we know that we’re using all of the fields (degrees, minutes, and seconds), so we should verify that seconds is showing, do the validation, and cache the target:

SecField.Show()

Dim min As UInteger = CUInt(MinField.Text)

Dim dsec As Double = CDbl(SecField.Text)

If deg > 180 OrElse deg < 0 _

OrElse min > 180 OrElse min < 0 _

OrElse dsec > 60 OrElse dsec < 0 Then

Throw New Exception()

End If

' Cache this data for later use

cache = New DegreesMinutesSeconds(isPositive, deg, min, dsec)

End If

End Sub

It’s time for us to write this UpdateTargetInfo() code. That code will be responsible for calculating both the distance and direction from our current position to our desired position. We’ll be using the Math library to do these calculations. The functions in the math library use radians, not degrees, but we can whip up a quick translation between the two:

Private Function DegToRad(ByVal deg As Double) As Double

Return (deg * Math.PI) / 180

End Function

Private Function RadToDeg(ByVal rad As Double) As Double

Return (rad * 180) / Math.PI

End Function

To calculate distance, we’ll be using the Haversine formula that we all learned in high-school trigonometry. I refreshed my memory on this formula (and the direction formula) at http://www.movable-type.co.uk/scripts/latlong.html. These formulae do calculations based on a great-circle, which (if you’ll recall) is actually the path to follow for the shortest distance between two points on a sphere. (Thus, if your destination is on the same line of latitude as you, the direction you want to go will not actually be due west or east unless you are at the equator.)

Assuming our current position is valid, we’ll go ahead & get out starting point, as well as define the radius of the earth:

Private Sub UpdateTargetInfo()

If position IsNot Nothing AndAlso position.LatitudeValid AndAlso _

position.LongitudeValid AndAlso _

TargetLatitude IsNot Nothing AndAlso TargetLongitude IsNot Nothing Then

Dim radius As Double = 6371 ' kilometers

Dim rlat1 As Double = DegToRad(position.Latitude)

Dim rlat2 As Double = DegToRad(TargetLatitude.ToDecimalDegrees)

Dim rlong1 As Double = DegToRad(position.Longitude)

Dim rlong2 As Double = DegToRad(TargetLongitude.ToDecimalDegrees)

We’ll also get the difference in latitude and longitude handy:

Dim rdeltaLat As Double = rlat2 - rlat1

Dim rdeltaLong As Double = rlong2 - rlong1

Now, we can calculate distance based on Haversine:

Dim a As Double = Math.Pow(Math.Sin(rdeltaLat / 2), 2) + _

Math.Cos(rlat1) * Math.Cos(rlat2) * Math.Pow(Math.Sin(rdeltaLong / 2), 2)

Dim c As Double = 2.0 * Math.Atan2(Math.Sqrt(a), Math.Sqrt(1 - a))

Dim distance As Double = radius * c

[Edit 8/7/09: Fixed typo in calculation of a -- used rlong2 instead of rlat2 accidentally. Will repost on Temple of VB site.]

The distance is described in kilometers at this point. If we’re under one kilometer, it’d be easier for the user if we switch to meters instead – and of course, we’d like to show miles and feet as well, all formatted nicely using ToString formatting:

If distance > 1.0 Then

Me.DistLabel.Text = distance.ToString("####0.00") & " km (" & CDbl(distance * 0.621).ToString("####0.00") & "mi)"

Else

Me.DistLabel.Text = (distance * 1000.0).ToString("####0.00") & " m (" & CDbl(distance * 3280.84).ToString("####0.00") & "ft)"

End If

Next is direction:

Dim theta As Double

theta = Math.Atan2(Math.Sin(rdeltaLong) * Math.Cos(rlat2), _

Math.Cos(rlat1) * Math.Sin(rlat2) - _

Math.Sin(rlat1) * Math.Cos(rlat2) * Math.Cos(rdeltaLong))

Dim degTheta As Double = (RadToDeg(theta) + 360.0) Mod 360

Me.DirLabel.Text = degTheta.ToString("##0.00") & "°"

And of course if the position information isn’t valid, then we need to tell the user:

Else

Me.DistLabel.Text = "No GPS data available."

Me.DirLabel.Text = "No GPS data available."

End If

End Sub

And that’s it! Debugging it is a bit tricky, since you have to take it outside to try it out (I was basically running in and out of my house to try out new ideas I’d just coded), but it’s fully functional and would be useful for (for instance) geocaching or surveying. Going forward, I’ll probably add more functional to mark areas that I was interested in persisting – once I get some more free time. J The current version’s code is available at my Temple of VB site – it also includes a setup project for CABbing up the file, as well as a console application to test out the direction/distance functionality. Enjoy!

‘Til next time,

--Matt--*

It’s a Small World, After All, part 1 – VB, C#, and GPS (Matt Gertz)

VBTeam — Wed, 05 Aug 2009 00:34:00 GMT

The title of this blog post has sort of a triple meaning for me. First of all, I just got back from a long (and wonderful!) cruise in the Caribbean, followed by a stop at Disney World. And of course, if you go to Disney World with kids, it’s the law that you have to go through the “It’s a Small World” ride, thereby having the accompanying song burned into your brain for the next six months.

Secondly, “It’s a Small World” also reminds me of how new technologies are bringing us closer together. It’s amazing to me that I can do a full presentation in (for example) Asia without having to leaving my office. For such scenarios to work, a number of different technologies have got to work together, and that’s tricky to get right. In this blog post, I’m going to be working with both VB and C# and, while they are not really different technologies in the same sense as a phone and a video camera, it’s nevertheless very cool that you can work with both to achieve a cohesive “whole.”

Finally, in the third sense, “It’s a Small World” came to mind while I was working on my latest hobby project (which I’ll detail in this blog) – a GPS program for my Smartphone. Verizon Wireless recently unlocked the GPS functionality for the Samsung Saga (one of which I own), and since I’ve always been really interested in GPS ever since it was made available to civilians, this was a great opportunity for me to jump in and try my hand at the GPS. So, in this two-part series, I’ll be walking you through a GPS app which uses both C# and VB to support its functionality.

“Um, isn’t there already a GPS sample for Smartphones?”

Well, yes, and you can get it from the Windows Mobile 6 SDK, which you can download from here. In fact, that’s where I’m going to start this project. (This will work on both VS2005 and VS2008, by the way.)

If you download the SDK and run the C# “GPS” sample (not the “Mobile GPS” sample; that’s for C++), you’ll see that it’s pretty simple. There are two pieces; a class library which wraps the native GPS calls into managed calls, and a mobile application which displays the GPS info. The UI for the mobile application is very simple – there is a menu item to exit the program, another menu item pair to start and stop the GPS, and a label. The GPS device generates the events, the UI handles them and appends the text to the label – that’s it. It’s a good place to start, but it really doesn’t fit a daily usage bill. I want my GPS program to always display at-a-glance:

· The state of the GPS

· The number of satellites in the solution and how many of those are available

· Latitude and longitude – both in DMS and DM format (since many geocaching sites are given in DM format)

· My altitude

· My velocity (speed and direction)

· A way to specify a target location, and the distance/direction to it.

That’s a lot to cram onto a phone screen – but I managed to fit it in. (I plan on adding more later, particularly a way to mark locations and cache them to use as targets later, but this is a good start.) Here’s how I went about it:

Creating a new GPS UI

First, open the GPS sample solution (if you haven’t already) and remove the “GpsSample” project. (You might want to create a copy of the solution first, so that you have the old one for reference.) We’re going to write a new, better UI that uses VB instead, so add a VB Smart Device Project to the solution, calling it “VBGPS” or something like that. (Right-click the solution, choose “Add Project,” “Visual Basic,” “Smart Device,” type in “VBGPS” for the name, and press OK.) In the next dialog, select the “Device Application” project type and press “OK.”

In the new project, you’re going to need to add a reference to the Microsoft.WindowsMobile.Samples.Location class library, so right-click the VBGPS project and choose “Add Reference…” Navigate to the “Projects” tab and select the aforementioned class library, then press “OK.” Now, you are hooked up to the C# code which wraps the native GPS functionality.

Double-click “Form1” in the VBGPS” project to bring up the form (if it’s not visible already). In the property grid, change the FormFactor property to match the form factor of your phone. (I have a square screen on my phone, so I’ve chosen “Windows Mobile 6 Professional Square.”) You can also change the Text of the form to something like “VBGPS” so that the title of the window doesn’t say “Form1.”

Now, we’ll start adding controls. First, we’ll add the menu controls. These will be the same as the C# version of the sample. The menu control already exists by default, so click on the left-hand bottom menu and change its text to “Exit” in the property grid – you can also give the control a better name (e.g. “ExitMenuItem”) if you like. Click on the right-hand bottom menu and change its text to “GPS,” again changing the control name if you like (e.g. “GPSMenuItem”). With “GPS” still selected, click the “Type Here” above it and add two menu items – “Start GPS” and “Stop GPS.” While each is selected, change their control names to something more intuitive in the property grid (e.g. “StartGPSMenuItem” and “StopGPSMenuItem” respectively).

Now, we’ll add the labels and such. For the following functionality, I’ll drag out two labels – one for the name of the GPS property, and one next to it to contain its value:

· Status

· Satellites

· Lat (i.e., latitude)

· Long (i.e., longitude)

· Alt (i.e., altitude)

· Vel (i.e., velocity)

Status and Satellites should share a line (for a total of four labels on one line); the others have a line each to themselves. All of them should be set to 8pt font in order to fit on the screen, and the value labels should have meaningful names set for them in the property grid. (I used “StatusLabel,” “SattLabel,” “LatLabel,” “LongLabel,” “AltLabel,” and “VelLabel.)

We also want to be able to specify a target location. So, farther down on the form, we’ll drag out a label and change its text to “TargetLat:”. To the right of it, we add three small text boxes – these will hold degrees, minutes, and seconds. Finally, to the right of those, we’ll drag out a small combo box. In the property grid, make sure its Type is “DropDownList,” and in the Items collection, add “N” and “S” as possibilities. All of these controls should be set to 8pt fonts using the property grid, and all of the text and combo boxes should have meaningful names. (I chose “LatDegTB,” “LatMinTB,” “LatSecTB,” and LatPosCB.)

Now, we’ll select the entire line of controls and, while holding down the “Control” key, drag a new copy of them below the existing ones. These will be the longitude target controls, so make the appropriate name and text changes in the copies, and also change the copied combo box items to “E” and “W.”

Finally, we’ll add two more label pairs below that like we did at the beginning. One will be for “Distance” and the other for “Direction” – make sure that the value labels have good names like “DistLabel” and “DirLabel.”

That’s the UI. It just barely fits on the screen, and it we want to add any more functionality, we’d have to bring up another window. But this will get us going, so let’s write some code.

The C# code

First, let’s make a few changes in the class library. As I mentioned above, we’re going to keep the class library as a C# endeavor. There’s no reason why it couldn’t be changed to VB code, but since it’s just a bunch of wrappers and they all work pretty well, there’s no need to invest the time to change the code. However, there are a couple of helper methods that I want to either change or add, and they (will) exist in the DegreesMinutesSeconds helper class defined in DegreesMinutesSeconds.cs. (We’ll get back to VB code shortly.)

DegreesMinutesSeconds is a class that allows for easy manipulation of latitude and longitude data. Not only does it store a particular coordinate, but it gives you two ways to interact with the data – as pure degrees (e.g., -82.673529) or as degrees/minutes/seconds (e.g., -82° 40’ 24.7044”). In this model, North and East are positive values; West and South are negative values.

This is all well and good, but I like to go geocaching, and in geocaching the coordinates are often described in terms of degrees and minutes (e.g., -82° 40.41174’). I would like to therefore support that format as well. Currently, the members of this class are:

uint degrees; /// In VB, this would be Private degrees As UInteger

uint minutes; /// In VB, this would be Private minutes As UInteger

double seconds; /// In VB, this would be Private seconds As Double

and each of these have properties associated with them; for example:

public uint Degrees /// VB: ReadOnly Property Degs() As UInteger

{

get { return degrees; } /// VB: Get: Return degrees: End Get

}

However, we want to be able to express coordinates that have a fractional minute, and so we add the following:

double dminutes;

public double DMinutes

{

get { return dminutes; }

}

Now we have to use it. There are already a couple of constructors, and we’ll need to fix them up to set dminutes -- additions are underlined. The code is close enough to VB that I won’t bother providing a helpful translation in the blog – just remember that “(uint) x” is equivalent to “CUInt(x)”, etc:

public DegreesMinutesSeconds(double decimalDegrees)

{

isPositive = (decimalDegrees > 0);

degrees = (uint)Math.Abs(decimalDegrees);

dminutes = (Math.Abs(decimalDegrees) - Math.Abs((double)degrees)) * 60.0;

minutes = (uint)dminutes;

seconds = (dminutes - (double)minutes) * 60.0;

}

public DegreesMinutesSeconds(bool isPositive, uint degrees, uint minutes, double seconds)

{

this.isPositive = isPositive;

this.degrees = degrees;

this.minutes = minutes;

this.seconds = seconds;

this.dminutes = minutes + seconds / 60.0;

}

I also need to add an entirely new constructor to take decimal minutes as an argument:

public DegreesMinutesSeconds(bool isPositive, uint degrees, double dminutes)

{

this.isPositive = isPositive;

this.degrees = degrees;

this.dminutes = dminutes;

minutes = (uint)dminutes;

seconds = (dminutes - (double)minutes) * 60.0;

}

So, that’s the “read” changes that we need to make; now, we need to update the “write” routine. There is a “ToString” routine already, but I don’t like it because it doesn’t use the degree character (°) and it only prints out in DMS format – I want DM as well. So, I’ll create two new methods:

public string DMSString()

{

return degrees + "° " + minutes + "' " +

seconds.ToString("##0.00") + "\"";

}

public string DMString()

{

return degrees + "° " + dminutes.ToString("##0.00") + "' ";

}

These are nearly identical to their VB counterparts – replace “+” with “&”, get rid of the semicolons and braces, rearrange the signature, and you’re pretty much there. Note that we’re making good use of the formatting ability of “ToString” – the format “##0.00” (identical to what we’d use if writing this in VB) means that we only want 2 decimal places, and the we don’t want to see leading zeroes in the tens’ or hundreds’ place. (We can’t have more than four digits left of the decimal place, since coordinates only go up to 180°.)

Finally, change ToString() to return the DMSString() function instead of the code already there, and we’re done with the C# code changes. C# code does not compile automatically, so we’ll right-click the class library project and choose “Build” – the class library is now ready for use to use.

Back to VB

It’s time to write the support code for our UI, so right-click on some unused part of the VBGPS form and choose “View Code.”

We need to add some members. First, we need to create an object that represents the GPS device. The class library exposes one, and creating it is pretty easy:

Dim vbgps As Gps = New Gps() ' The GPS device

The GPS device will be sending us events, and we need a way to handle those. We can use an EventHandler to do this:

Private updateDataHandler As EventHandler ' Handle GPS events

There are two kinds of events – “state” events (is the GPS on, etc.) and “position” events (where are we, how fast as we going, etc.). We will cache this information whenever it is sent to us for later reference:

Dim device As GpsDeviceState ' Passed to us by GPS device events

Dim position As GpsPosition ' Passed to us by GPS device events

(This is all identical to the original sample, except translated to VB.) I also want to be able to cache the target location where I’m heading to, and I can leverage the DegreesMinutesSeconds class for this:

Dim TargetLatitude As DegreesMinutesSeconds ' Where do we want to go?

Dim TargetLongitude As DegreesMinutesSeconds ' Where do we want to go?

Now let’s start with the menu events, because that’s where everything begins or ends. These are all simple – we start or stop the GPS device and update a few menu items:

Private Sub startGpsMenuItem_Click(ByVal sender As Object, ByVal e As EventArgs) Handles StartGPSMenuItem.Click

If Not vbgps.Opened Then

vbgps.Open()

End If

StartGPSMenuItem.Enabled = False

StopGPSMenuItem.Enabled = True

End Sub

Private Sub stopGpsMenuItem_Click(ByVal sender As Object, ByVal e As EventArgs) Handles StopGPSMenuItem.Click

If vbgps.Opened Then

vbgps.Close()

End If

StartGPSMenuItem.Enabled = True

StopGPSMenuItem.Enabled = False

ResetValues()

End Sub

Private Sub exitMenuItem_Click(ByVal sender As Object, ByVal e As EventArgs) Handles ExitMenuItem.Click, MyBase.Closed

If vbgps.Opened Then

vbgps.Close()

End If

Close()

End Sub

Note how the Closed and Exit events are both handled by the same method, which simply shuts down the GPS and exits the program. The other two methods also have to update the menu items to indicate whether stopping or starting is possible. (Again, these are identical in the C# versions in the sample.)

Next thing to do is to create the handlers for the GPS events. These are very trivial, and a straight port from the C# example:

Protected Sub gps_LocationChanged(ByVal sender As Object, ByVal args As LocationChangedEventArgs)

position = args.Position

Invoke(updateDataHandler)

End Sub

Protected Sub gps_DeviceStateChanged(ByVal sender As Object, ByVal args As DeviceStateChangedEventArgs)

device = args.DeviceState

Invoke(updateDataHandler)

End Sub

Basically, we’re just caching the information that the GPS device is sending us, and then invoking our overall handler (which we defined above) to deal with the information. We could call a helper method directly instead of using Invoke, but this gives us more wiggle room – we might want to re-route the events elsewhere to a different handler in certain situations, and this setup allows us the leeway to do that programmatically rather than hard-coded.

Of course, I haven’t turned on the handlers yet. I do that in the Form1_Load handler (which you can add by double-clicking on an empty area on the form). The relevant lines are:

AddHandler vbgps.DeviceStateChanged, New DeviceStateChangedEventHandler(AddressOf gps_DeviceStateChanged)

AddHandler vbgps.LocationChanged, New LocationChangedEventHandler(AddressOf gps_LocationChanged)

Now the GPS events will be received. I also need to define the updateDataHandler – I’ll point it to a function called UpdateData (which I haven’t written yet)

updateDataHandler = New EventHandler(AddressOf UpdateData)

While I’m in Form1_Load, I might as well initialize the various fields and target data:

ResetValues()

StopGPSMenuItem.Enabled = False ' The C# sample forgets to do this

' Zero out the text boxes and set the target to 0 degrees N and E.

Me.LatDegTB.Text = "0"

Me.LatMinTB.Text = "0"

Me.LatSecTB.Text = "0"

Me.LongDegTB.Text = "0"

Me.LongMinTB.Text = "0"

Me.LongSecTB.Text = "0"

Me.LatPosCB.SelectedIndex = 0

Me.LongPosCB.SelectedIndex = 0

TargetLatitude = New DegreesMinutesSeconds(False, 0, 0, 0.0)

TargetLongitude = New DegreesMinutesSeconds(False, 0, 0, 0.0)

ResetValues() is a function which does initialization that I might have to do more than once – for example, when stopping the GPS, I need to reset the feedback to the user to indicate that no data is available. It looks like this:

Private Sub ResetValues()

Me.Text = "VBGPS"

Me.StatusLabel.Text = "Off"

Me.AltLabel.Text = "---"

Me.VelLabel.Text = "---"

Me.LatLabel.Text = "---"

Me.LongLabel.Text = "---"

Me.SatLabel.Text = "Unavailable"

Me.DistLabel.Text = "---"

Me.DirLabel.Text = "---"

End Sub

That’s it for this post. In tomorrow’s concluding post, I’ll be adding all of the “meat” of the functionality (updating fields, calculating paths and distances) – all using VB, of course!

‘Til next time,

--Matt--*

Phoning Home, revisited (Matt Gertz)

VBTeam — Thu, 21 May 2009 20:43:00 GMT

In my post “M. G. Phone Home,” I discussed how to write a simple phone application for Windows Mobile, using Visual Basic, which accesses the Bluetooth service. What I didn’t discuss was how to deploy it to the phone via CAB. Since I purchased a new phone yesterday (a Samsung Saga, running Windows Mobile 6.1), and I’ve discovered that I need the same app on it, I thought this would be an opportune time to discuss how to do this, since it’s not obvious and slightly different from the distribution of “normal” applications. If you want to follow along, you can find the code at my Temple of VB site (direct release link is here).

(By the way, I’ve modified the app’s code slightly from what I wrote in that previous blog -- I have assigned an icon to the application in the project’s properties, because I got tired of seeing the default, non-intuitive icon. If you do this also, make sure that, after doing so, you select the icon in the project’s files and, in the property grid, set its “Build Action” to “Embedded Resource.” If you don’t do that last step, you won’t see the icon on the phone.)

Once you’ve got your phone app completed and debugged (as discussed in the aforementioned blog), choose “File-> Add->New Project.” Select “Smart Device CAB Project” under the “Other Project Types->Setup and Deployment” tree node, and give the project some meaningful name (ResetBluetooth, for example). Select OK so that the project is created.

In the property grid for the new project, make sure that “Manufacturer” and “ProductName” are set however you want them to be, since they will be visible in the program list on the phone.

Now, in the Solution Explorer, right-click the new project and choose “Add->Project Output.” In the resulting dialog, make sure that the first project is selected (the one with the actual code), choose “Primary Output” and click OK. The CAB project will now always contact that project to get its outputs when creating the CAB.

You’re not quite finished, though. You need to add a couple of shortcuts so that you can actually interact with the program on your phone once it’s installed. To do this, bring up the CAB project’s File System Editor if it’s not already visible (right-click the project, choose “View->File System”). In the left-hand pane, you should see “Application Folder” and “Program Files Folder.” “Application Folder” is where the code will end up; don’t change anything about it.

However, “Program Files Folder” is empty, and you need to add a shortcut to the program in it. Select that folder, and in the right-hand pane, right-click anywhere and choose “Create New Shortcut.” In the resulting dialog, navigate into the Application Folder and select “Primary Output from ResetBluetooth (Active)” (or whatever you called your original program). Click “OK.” The Shortcut will be selected for editing, and it will have an atrociously long, descriptive name – give it a more sensible name like “Reset Bluetooth” or something.

You’re still not done, though -- you need to add one more folder. Right-click the “File System of Target Machine” node in the left-hand pane and choose “Add Special Folder->Start Menu Folder.” Inside that new folder, add the same shortcut to the primary output that you added in the “Program Files” folder, and give it the same sensible name.

Now you’re done. Build the CAB project, and you’ll find the CAB file in its Release subdirectory. You can copy that over to your phone via the usual ActiveSync mechanism, and then run it on the phone to install it. (I usually map a phone key to that program so that it’s trivial to launch the application – check your phone’s manual for instructions on how to do that.) And that’s it!

‘Til next time,

--Matt--*

CodeRush Xpress 9.1 Beta: 59 Refactorings, 17 Consume-first providers, and Much more! (Lisa Feigenbaum)

VBTeam — Tue, 05 May 2009 06:07:21 GMT

Very exciting news! Developer Express is coming out with a new version of the FREE add-in we all know today as Refactor!. The new product, CodeRush XPress, builds on Refactor! by increasing the refactoring count to 59! It also includes a host of other editing functionality, making it a much richer tool for all-around IDE productivity. Consume-first providers enable a different way of programming, whereby you can refer to variables, properties, classes, and other members before they are defined. Then the IDE tools insert the definition for you, so you don't need to write all that plumbing code, or break your thought flow. There are a number of navigation features in CodeRush Xpress such as Tab to Next Reference, CamelCase Navigation, Quick Symbol Navigation and File Navigation. There are also editing features, including Smart Cut, Smart Copy, Structural Highlighting, and Duplicate Line.

The best way to learn these features is to see them in action. Take a look at the VB.NET video here:

CodeRush Xpress 9.1: VB.NET Video

It's a great demonstration of the features and also very entertaining, with fun personalities Mark Miller & Dustin Campbell. For more information, please see the blog post by Mark Miller, Chief Scientist of Developer Express. And finally, here's a link to the download!

FREE DOWNLOAD: CodeRush XPress 9.1 Beta for VS 2005 and VS 2008

Keep the Customer Satisfied (Matt Gertz)

VBTeam — Tue, 14 Apr 2009 06:21:00 GMT

As I’ve written elsewhere, the toughest critics for any work you do can always be found in your own family. Pleased at the immense work that I’d done in scanning in and tagging all of my photos and media (as noted in this post), and with my ego sufficiently boosted by writing a screensaver in VB that would display not only the pictures but the tags associated with them, it was a deflating experience to have my middle child, Aidan, pepper me with comments like “That’s not me; that’s Brandon” or “You didn’t include Grandpa in the tags, but I can see his ear in this photo.”

In order to preserve the peace (and find the inevitable set of photos with bad tagging or poor rotation), I needed to open up the code to give the kids a way to let me know which photos needed to be re-examined. But how to do this? I’ve currently got the photos set to display for 30 seconds, which is a limited amount of time for the kids to get over to my desk, pull out the keyboard tray, and somehow record a flaw without turning off the screensaver.

“X” marks the spot

So, I considered my customers. My kids would likely be coming over from the couch, which is to the left of my desk. Pulling out the keyboard tray could jiggle the mouse and end the screensaver, so I wanted a key that they could reach without moving anything. Furthermore, it needed to be a memorable key, and so I settled on “X” (as in “X” marks the spot), which is of course located on the left side of the keyboard.

Now, this sounds a lot like overthinking, doesn’t it? But really, all design decisions need to take in account customer abilities and cognitive associations. I could just as easily have chosen “F5” as the keystroke, but besides creating an added potential for moving the mouse disruptively (an accessibility issue), the fact is that the key “F5” would have no association for my kids whatsoever. “X,” however, is an “interesting” letter and likely to stick in their minds.

So, anyhow, here’s how I went about it code-wise: I opened up the project that’s presented in the aforementioned post and navigated to the code for the frmScreenSaver object. Inside that code, I added an event handler for “X” thusly:

Private Sub frmScreenSaver_KeyPress(ByVal sender As Object, _

ByVal e As System.Windows.Forms.KeyPressEventArgs) Handles Me.KeyPress

First thing to do is check to see if “X” was pressed:

If e.KeyChar = "x" OrElse e.KeyChar = "X" Then

OK, “X” was pressed. Now, do I actually have a file that I’m currently showing? If my screensaver couldn’t find any files, then I wouldn’t have one. I can leverage the m_currentFile variable to check:

If Not String.IsNullOrEmpty(m_currentFile) Then

OK, I’ve got a file. So, I’m going to log this filename to a text file, appending it to whatever is already in that file (or creating it if none have been logged yet). (Every Saturday, I check this file for the accumulated complaints, examine the photos, make the required fixes, and delete the log file.)

My.Computer.FileSystem.WriteAllText( _

My.Computer.FileSystem.SpecialDirectories.MyDocuments _

& "\FilesToFix.txt", m_currentFile & vbCrLf, True)

Pretty simple! But I need to provide feedback to my kids that their keystroke was accepted, and so I add a simple “beep:”

My.Computer.Audio.PlaySystemSound(Media.SystemSounds.Exclamation)

End If

End Sub

And that’s it. I build the project in retail, rename it to be a *.scr file, and copy it up the the system directory.

“Is that really necessary to look at, dear?”

The second complaint I received about the screensaver came not from my kids but from my wife, the crux of the problem being that the screensaver didn’t discriminate between good pictures and bad pictures. This could be somewhat embarrassing when friends were visiting. For example, I’ve got a set of photos from when I was in Dubai on a recruiting trip a few years back. The photos weren’t just taken by me, but by my co-workers as well. Evidently, one of them was highly impressed with the bidet in their hotel bathroom and decided to commemorate it with a photo -- not something that my wife was crazy about seeing on the screen. And, while I am often impressed by the artistic abilities of my kids, the fact of the matter is that their photos are often punctuated by close-ups of the dog’s butt, their best friend’s eyeball, or some incredibly blurry thing that can’t be made out at all.

So, to address this problem, I decided to add a “nuke” feature to the screensaver. When the “N” key (another easy-to-reach key with a good mnemonic -- "N" stands for "nuke") is pressed for a given photo in the collection, I want to eliminate it and move to the next picture. Sounds simple, no? It’s just a modification of the “X” code from above.

But here’s the problem: my kids are wonderfully smart, but I don’t trust them to be good judges of whether or not a photo should be permanently deleted (and, depending on the timing, they might use the key just as the photo changed, thus deleting the wrong photo). I therefore needed to construct a way to send the photo to a “penalty box” until I had the time to review the photo. Furthermore, this “penalty box” needed to be able to persist between sessions.

Here’s how I set about it: first, in the same event I created above, I check for the “N” key and for the existence of the file:

ElseIf e.KeyChar = "n" OrElse e.KeyChar = "N" Then

If Not String.IsNullOrEmpty(m_currentFile) Then

I log the picture just as I did before, although to a different file this time:

My.Computer.FileSystem.WriteAllText( _

My.Computer.FileSystem.SpecialDirectories.MyDocuments _

& "\FilesToNuke.txt", m_currentFile & vbCrLf, True)

My.Computer.Audio.PlaySystemSound(Media.SystemSounds.Exclamation)

I then remove the photo from the list of files by finding its index and calling “RemoveAt()”:

Dim index As Integer = m_files.IndexOf(m_currentFile)

If index >= 0 Then

m_files.RemoveAt(index)

m_fileCount -= 1

End If

And then I call “DrawPicture(),” which forces a move to the next picture without waiting for the timer:

DrawPicture()

End If

Unfortunately, if the screensaver is interrupted before I get a chance to review the “photos to nuke” on Saturday, it will re-create the file list with the bad photo(s) still in it the next time that it restarts. Therefore, I need to adjust how I create the file list in the frmScreenSaver_Load() event handler – it needs to read from the “FilesToNuke.txt” file (if it exists) and remove such photos from the photo collection that it generates.

Here’s how I do that – first, I change m_file’s type to be a normal collection rather than a read-only collection, so that I can alter it:

Private m_files As New Collection(Of String) ' List of files

Then, in the Load event handler, I make a few minor modifications (in bold):

Dim files As ReadOnlyCollection(Of String) ' List of files

If m_Options.UseSubdirectories = True Then

files = My.Computer.FileSystem.GetFiles(m_Options.Directory, _

FileIO.SearchOption.SearchAllSubDirectories, "*.jpg")

Else

files = My.Computer.FileSystem.GetFiles(m_Options.Directory, _

FileIO.SearchOption.SearchTopLevelOnly, "*.jpg")

End If

That code is the same as before, except that I read in the collection for the new variable “files” rather than m_files.

Now, we encounter a pet peeve of mine – the method GetFiles returns a read-only collection rather than just a normal collection. This means that we can’t remove anything from the collection we get back from GetFiles(), and as noted above, I need to remove the questionable files from the collection until such time as I get around to reviewing and deleting the files permanently. (One day, I’m going to write a blog which discussed the correct reasons for using read-only objects – I'm all for security, but it's too easy go overboard with it sometimes, in my opinion.)

I have two choices – either write my own (thorough!) routine for enumerating files, or else bite the bullet and copy the read-only collection to a modifiable collection. (Of course, I could alter the Timer handler so that I check the random result against “bad” filenames every time the timer fires, but that would be taking on a perf hit on every event, not just the initialization.) Being inherently lazy, I’ll just copy the collection (ooh, I feel so dirty!) into m_files, which is the version that I ultimately cache & use internally:

' Copy to a writeable collection (why is the other collection read-only?)

For Each f As String In files

m_files.Add(f)

The worst (ethically) is over; I will now load in the set of questionable files from the "FilesToNuke.txt" file and remove them from the collection. Fortunately, the files being separated in the file by a carriage return, it’s easy for me to read them in and separate them into a “nuke” list, which I can then iterate to remove the corresponding items from the main collection. (I could also have read this list a priori and prevented the items from being copied into the modifiable collection above, but that’s actually less performant, as I would have far more misses than hits, even if I removed items from the “nuke” list after the corresponding entry was found.)

' Load files to ignore

Try

Dim separator() As String = {vbCrLf}

Dim sFilesToIgnore As String = _

My.Computer.FileSystem.ReadAllText( _

My.Computer.FileSystem.SpecialDirectories.MyDocuments _

& "\FilesToNuke.txt")

Dim sarrFilesToIgnore() As String = _

sFilesToIgnore.Split(separator, StringSplitOptions.RemoveEmptyEntries)

For Each s As String In sarrFilesToIgnore

Dim index As Integer = m_files.IndexOf(s)

If index >= 0 Then

m_files.RemoveAt(index) ' Don't want to see this file anymore

End If

Catch ex As Exception ' File not found

End Try

Done -- build, rename, copy to the system directory. Now, my wife and kids and can easily log files that *might* need to be deleted and, furthermore, be spared the sight of them, no matter how many times the screensaver stops and starts, until I get a chance to make the permanent deletion.

That’s it; all done (until my family requires me to add more functionalityJ). I’ve uploaded the new code to my “Temple of VB” site (see the link below -- I'm going to stop uploading files to this blog since it's problematic to maintain the code in two sites).

‘Til next time,

--Matt--*

Veni, MIDI, Vici: Generating a simple MIDI file using VB, part 2 (Matt Gertz)

VBTeam — Sun, 01 Mar 2009 21:00:00 GMT

In part 1 of this series, I constructed a pair of classes to supporting persisting MIDI data to files. In this entry, I’ll now leverage that code to support an (admittedly limited) music editor experience.

Caveat: As I mentioned in the first post, I’m sure many readers will be far more knowledgeable about MIDI than I am, and will justifiably roll their eyes at this code due to its limited scope. I will only be generating simple type-1 MIDI files that only use the Note On and Note Off events, and which don’t use metadata, targeting a “Save” scenario only. The idea of this exercise was to understand MIDI and how to code against it in VB, not to generate a fully-functional music generation program. Coding up “Load” and supporting more of the MIDI functionality would be a more time-consuming process which maybe I’ll get to one day.

I would love to be able to write a full-fledged editor with all of the music printed out, all WYSIWYG, but unfortunately I have a day job which would be impacted and so I’m opting for the Commodore-128 experience I mentioned in the previous post. Basically, I will (arbitrarily) support four tracks of music, each track containing notes, and each note derived from the following format:

dTv

Where:

· d is the duration of the note (a floating-point value; i.e., since 4/4 time is assumed, 1.0 would be a quarter note, 1.5 would be a dotted quarter note, 0.5 an eighth note, etc.)

· T is the tone of the note (i.e., anything from '''''C through G'''''' or R (for rest))

· v is the volume from 0 to 127 (i.e., &H0 through &HFF), which is never used for a rest.

So, in my design, a track which played a whole-note (4 beats) middle C, rested for a half-note (2 beats), and then dropped down to 'G for dotted quarter-note (1.5 beats), all at a volume of 60, would look like this:

4.0C60, 2.0R, 1.5'G60

That’s not nearly as nice to look at as the actual musical score, but it will allow me to give an example of parsing text data, so on we go…

The form

On my Windows application, I have four combo boxes in a vertical pattern, with a long text box adjacent to each. The combos’ DropDownStyle properties are all set to DropDownList, and the Items property for each is preset to be the numbers 1 through 15 (these numbers indicate MIDI channels), plus “blank” (a simple carriage return) – blank is the default value (i.e., unused track). The text boxes (which will contain the “dTv” notes) all start out as ReadOnly = True, and switch to editable only if the corresponding combo channel is non-blank. I also have a “Save” button to generate the MIDI output, and I added a SaveDialog object as well. That’s pretty much the extent of the form.

Back in the code, I’ll add an instance of the MIDI object I defined in the previous post:

Public Class Form1

Private Song As New MIDI

Now, I need to deal with the notes!

Specifying the notes that can be used

In order to support the parsing of the track information, I’ll need to translate the tone values from characters to the numbers that MIDI expects (of which there are 128). The best way to do this is to create a collection mapping the text value to the numeric value, so we can create the mapping once and be done with it:

Private Notes As New Collection

Const NumberOfNotes As Integer = 128

Now, I could do something lame like:

Notes.Add(60, "C")

Notes.Add(61, "C#")

And so on, but there are 128 potential values, and some of them have multiple names (for every sharp, there’s a corresponding flat), so that would be a lot of work. So, I wrote some helper routines to try to do this in a smarter way.

First, I need to find out how many single quote marks I need to add to the note. Each quote preceding the note indicates an octave one lower than the one occupied by middle C; conversely, a quote following a note is indicative of a higher octave. (That is, ‘C indicates a note that is one octave lower than middle C, whereas C’ indicates a note that is one octave higher.) There are twelve distinct notes in an octave, including accidentals (flats and sharps), so for a given value, I divide by twelve to determine its octave, and use the remainder (modulus) to determine its position within that octave:

Private Sub InitializeNotes()

For i As Integer = 0 To NumberOfNotes - 1

Dim octave As Integer = i \ 12

Dim tone As Integer = i Mod 12

Then, for each number, I call a helper function to do the actual work of creating the textual representation of the corresponding note. “C” is the first note in MIDI, and so would have a remainder of zero:

Select Case tone

Case 0

AddNote(i, octave, "C")

AddNote(i, octave - 1, "B#") ' A sharped B is technically in the next lower octave

Case 1

AddNote(i, octave, "C#")

AddNote(i, octave, "Db")

Case 2

AddNote(i, octave, "D")

(And so on.) Note that I am adding two notes for each accidental (one for its sharp representation, and one for its flat representation), since I don’t want to force the user to use a specific one. I also accommodate B# (= C), E# (= F), Fb ( = E), and Cb (= B), though these are rarely used in most music. (I don’t currently support double-flats or double-sharps, though it would be easy enough to do – just add more entries.)

At the end of these 128 additions, I also add an entry for rests directly:

Case 11

AddNote(i, octave, "B")

AddNote(i, octave + 1, "Cb") ' A flatted C is technically in the next higher octave

End Select

Notes.Add(NumberOfNotes, "R")

End Sub

AddNote() is a simple method that determine the quotes (if any) for the note and appends them or prepends them in the right order. (The 5^th octave is the middle octave and therefore has no quotes.)

Private Sub AddNote(ByVal value As Integer, ByVal octave As Integer, ByVal noteName As String)

Dim octaveQuotes As String = GetOctaveQuotes(octave)

If octave < 5 Then

Notes.Add(value, octaveQuotes & noteName)

ElseIf octave > 5 Then

Notes.Add(value, noteName & octaveQuotes)

Else

Notes.Add(value, noteName)

End If

End Sub

You’ll note that I use yet another helper function (GetOctaveQuotes) to get the actual number of quotes which are appended or prepended. The number of quotes increases as you move away from the middle octave:

Private Function GetOctaveQuotes(ByVal octave As Integer) As String

Dim octaveQuotes As New StringBuilder

If octave < 5 Then

octaveQuotes.Append("'", 5 - octave)

Else

octaveQuotes.Append("'", octave - 5)

End If

Return octaveQuotes.ToString

End Function

And now we have everything we need to initialize the notes. My form’s Load() event calls that initialization, and also creates the four tracks that we’ll support:

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

Song.AddTrack()

InitializeNotes()

End Sub

Form events

There are only two interesting events in my code – changing the channel on a track, and saving the music to a MIDI file.

Track changes

When the track changes, I want to disable or enable the corresponding text box based on whether or not the channel is blank. If it is blank, then I disable the text box and clear its contents; otherwise, I enable it. Rather than create a separate event handler for each combo box, I address them all in one handler:

Private Sub Track1Channel_SelectedIndexChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) _

Handles Track1Channel.SelectedIndexChanged, Track2Channel.SelectedIndexChanged, Track3Channel.SelectedIndexChanged, Track4Channel.SelectedIndexChanged

By casting the sender object to a ComboBox, I’ll be able to determine which combo box sent the event, and which text box corresponds with it. (The index value will be used later to identify the song’s specific track which corresponds to a given combo/text set.)

Dim combo As ComboBox = CType(sender, ComboBox)

Dim text As TextBox

Dim index As Integer = 0

If combo Is Track1Channel Then

text = Track1

index = 0

ElseIf combo Is Track2Channel Then

text = Track2

index = 1

ElseIf combo Is Track3Channel Then

text = Track3

index = 2

Else

text = Track4

index = 3

End If

Now, it’s pretty straightforward to the activations or deactivations. The “blank” choice is in index 0 in my combobox, so if the selected index is 0, I turn everything off (after a prompt, of course), otherwise, I turn everything on. In either case, I update the appropriate track with its new channel:

If combo.SelectedIndex = 0 Then

If MsgBox("Delete all of the track information?") = MsgBoxResult.Ok Then

text.ReadOnly = True

text.Text = ""

Song.Tracks(index).TrackData.Clear()

Song.Tracks(index).Channel = -1

Else

' Change the index back -- Channel must be non-zero

combo.SelectedIndex = Song.Tracks(index).Channel - 1

End If

Else

text.ReadOnly = False

Song.Tracks(index).Channel = combo.SelectedIndex - 1

End If

Note that I’m cheating a little in that code – I happen to know that channel 0 is in index 1, channel 1 is in index 2, etc. This allows me to take a shortcut and a priori know that the channel is simply the selected index minus 1, rather than getting the text from the combobox and converting it to an integer.

Saving the music to a MIDI file

In order to save the music the user has specified, I need to translate the text he or she entered into MIDI format bytes and insert them into the tracks. I do the bulk of this work via a function called GenerateTrack, which takes a textbox and it’s corresponding track index as arguments, and which returns False if the track generation failed (because of a bad format or because it was not a valid track). Throughout this method, I will throw an exception any time I see a badly formatted music string so I can handle those errors all in one place.

Private Function GenerateTrack(ByVal trackTextBox As TextBox, ByVal index As Integer) As Boolean

The first thing to do verify that that track is valid (i.e., has a valid channel assigned to it), and clear out any existing track information:

If Not Song.Tracks(index).ValidTrack Then

Return False

End If

Song.Tracks(index).TrackData.Clear()

Next, I retrieve the music text and remove any spaces in the text:

Dim musicText As String = trackTextBox.Text

musicText = musicText.Replace(" ", "") ' Remove whitespace characters

I’ve then defined a couple of index counters to allow me to walk through the musicText, as well as a Double which will allow me to remember rests (which, in my application, are just delays between two notes and not really a thing in and of themselves):

Dim currentIndex As Integer = 0

Dim count As Integer = 0

Dim restBeats As Double = 0.0

Now, I loop over the characters in the string to begin parsing them:

While currentIndex < musicText.Length()

Step 1 is to get the beats associated with a note. I start with the current character and keep stepping until I find something that isn’t a number or a decimal point. (And If I find a decimal point, I make sure that I haven’t already found one on this note.) If I find no numbers, or too many decimals, or a decimal without a fractional part, I throw an error. Otherwise, I convert the number to a true Double. During all of this, currentIndex points to the presumed beginning of the beats, and count contains the number of characters to consume in the beats:

Dim beats As Double = 0.0

Dim dot As Boolean = False

While (musicText(currentIndex + count) >= "0" _

AndAlso musicText(currentIndex + count) <= "9") _

OrElse musicText(currentIndex + count) = "."

If musicText(currentIndex + count) = "." Then

If dot = True Then

Throw New ApplicationException("Bad beat format in track " & _

index.ToString())

Else

dot = True

End If

count += 1

End While

' Now get the beats!

If count = 0 OrElse (count = 1 AndAlso dot = True) Then

Throw New ApplicationException("No beats found for a note in track " & _

index.ToString())

End If

beats = Double.Parse(musicText.Substring(currentIndex, count))

Having gotten this far, I update currentIndex point past the beats and reset count to zero – time to get the note!

currentIndex = currentIndex + count

count = 0

Dim note As Integer = 0

Getting the note is very similar to getting the beats, except in this case I’m paying attention to quotes and accidentals instead of decimal points. Quotes can appear on either the left side or the right, but not both, so I need to have a Boolean to indicate if I’ve already found quotes on the left side:

Dim foundQuotes As Boolean = False

While musicText(currentIndex + count) = "'"

count += 1

foundQuotes = True

End While

Next I’ll look for the note. Since the note (excluding the # or b) only takes one character, this is an easy check to see if the next character is A through G (notes) or R (a rest):

If (musicText(currentIndex + count) < "A" _

OrElse musicText(currentIndex + count) > "G") _

AndAlso musicText(currentIndex + count) <> "R" Then

Throw New ApplicationException("Unrecognized note in track " & _

index.ToString())

End If

count += 1

And then I check for a flat or sharp and update the counter if I find one.

If musicText(currentIndex + count) = "#" _

OrElse musicText(currentIndex + count) = "b" Then

count += 1

End If

Now I check again for quote marks, remembering that if I found them on the left side, I’d better not find them on the right side (a note can’t be both higher and lower than the middle octave):

While musicText(currentIndex + count) = "'"

If foundQuotes = True Then

Throw New ApplicationException("Quotes on both side of a note in track " & _

index.ToString())

End If

count += 1

End While

Now I can get the note and look it up in my collection, and then update the counters again to grab the volume:

Dim key As String = musicText.Substring(currentIndex, count)

note = Notes(key)

currentIndex = currentIndex + count

count = 0

Okay, that’s two down. The final thing I need to retrieve from a given “dTv” triplet is the volume, which is an integer. However, rests don’t have volumes, and since I’ve defined a rest as NumberOfNotes, I can just check that value to see if I need to read a volume:

Dim volume As Integer = 0

If note <> NumberOfNotes Then ' Rests don't have volumes

(If the user provided a volume for a rest, I’ll catch that later and correctly throw an error when I try to parse the next note.)

Since this is just an integer, the rest of the code is easy – I keep crawling while the current character is 0 through 9, and if I get to the end and have found nothing, I’ll throw an error. Otherwise, I’ll just translate the volume to a true Integer and update the counters for the next thing to find:

While currentIndex + count < musicText.Length() _

AndAlso musicText(currentIndex + count) >= "0" _

AndAlso musicText(currentIndex + count) <= "9"

count += 1

End While

If currentIndex = 0 Then

Throw New ApplicationException("No volume found for a note in track " & index.ToString())

End If

volume = Integer.Parse(musicText.Substring(currentIndex, count))

currentIndex = currentIndex + count

count = 0

End If

That’s it for the parsing of that note; now I can update the track with the results. There are two cases here: either I have a note, or I have a rest. In the case of a rest, all I do is cache the duration of the rest. If it’s a note, I turn the note on after any cached rest, turn it off after a certain number of beats, and then clear the rest cache:

If note = NumberOfNotes Then

restBeats = beats ' A rest; just have the next note start later

Else

Song.Tracks(index).AddNoteOnOffEvent(restBeats,_

MIDI.Track.NoteEvent.NoteOn, CByte(note), CByte(volume))

Song.Tracks(index).AddNoteOnOffEvent(beats, _

MIDI.Track.NoteEvent.NoteOff, CByte(note), 0)

restBeats = 0

End If

I’ve finished working with the note, so I’ll see if there’s another note by checking the value of currentIndex compared to the length of the string. If I’m at the end, I can exit the while loop:

If currentIndex >= musicText.Length Then

Exit While ' No more notes!

End If

Otherwise, I’ll verify that the next character is a comma. If it is, then I’ll increment appropriately and loop back. Otherwise, it’s an error:

If musicText(currentIndex) = "," Then

currentIndex += 1

Else

Throw New ApplicationException ("Missing comma in track " & index.ToString())

End If

End While

Being out of the While loop, I need to verify that data got saved. If currentIndex is non-zero, then I know that I saved data (because it I ran into trouble later, I would have thrown an error). If I didn’t save data, then I need to return False:

If currentIndex = 0 Then

Return False ' Nothing got written out

End If

If we’ve gotten this far, then the generation was successful, and we’re done:

Return True

End Function

Now, finally, I can support the “Save” button. I’ll double click on it to generate the handler, and then start adding code. First, I need try to generate each track. If all of them returned False, then there was nothing to save, and I’ll abort the operation. But, since GenerateTrack() can also throw exceptions, I’ll add a Try-Catch structure to catch those. The catch handler will display the error to the user, and then abort the save:

Private Sub Save_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Save.Click

Try

If GenerateTrack(Track1, 0) = False And _

GenerateTrack(Track2, 1) = False And _

GenerateTrack(Track3, 2) = False And _

GenerateTrack(Track4, 3) = False Then

MsgBox("No tracks had valid data to write out")

Return

End If

Catch ex As Exception

MsgBox("Error while saving: " & ex.Message.ToString)

Return

End Try

It’s important to use “And” for that instead of “AndAlso,” because otherwise you’ll short-circuit tracks and not write them in.

Next, I need to pop up the save dialog box to determine where to save the file to. I’ll pre-populate this to call the file “Untitled.mid” and have it point to “My Documents:”

Me.SaveMIDIDialog.DefaultExt = "MID"

Me.SaveMIDIDialog.FileName = _

My.Computer.FileSystem.CombinePath(My.Computer.FileSystem.SpecialDirectories.MyDocuments, _

"Untitled.mid")

Me.SaveMIDIDialog.InitialDirectory = _

My.Computer.FileSystem.SpecialDirectories.MyDocuments

Me.SaveMIDIDialog.Filter = "VB MIDI files (*.MID)|*.MID"

Then, assuming that the user didn’t cancel, I just call Save on the MIDI song:

Dim result As DialogResult = Me.SaveMIDIDialog.ShowDialog

If result = DialogResult.OK Then

Song.Save(SaveMIDIDialog.FileName)

End If

End Sub

And that’s it! Launch the app, and you can start inserting music, save it, and then double-click on the resulting file to play it in Windows Media Player (or whatever you’ve got MIDI file set to). Here’s a couple samples from Howard Shore’s “The Fellowship of the Ring” score:

Sample 1:

First track, channel 0: 1B'60,1.75C''65, 0.25B'70, 0.25C''75, 0.25B'80, 0.25A'85, 0.25C''90, 1.0B'95, 3.0E'80

Second track, channel 1: 4.0G60, 4.0A60

Third track, channel 2: 4.0'D#60, 4.0'F#60

Fourth track, channel 3: 4.0''C60, 2.0'''B80, 1.0''C#60, 1.0''D60

Sample 2:

First track, channel 0: 2.0D60, 1.5C70, 0.25C70,0.25C70, 3.5D70, 0.25G60, 0.25A60, 1.5Bb60, 0.25A70, 0.25G70, 1.5F70, 0.25G70, 0.25A70, 2.0G70, 1.0F65, 1.0E60

Second track, channel 12.0'A60, 1.5'A60, 0.25'A70,0.25'A70, 3.5'A70,0.25'G60, 0.25'A60, 2.0'F60, 2.0'A70, 2.0'G70, 1.0'F65, 1.0'G60

Third track, channel 2: 2.0'F#60, 1.5'F60, 0.25'F70,0.25'F70, 4.0'F#70, 2.0'D60, 2.0'F70, 2.0'D70, 1.0'D65, 1.0'E60

Fourth track, channel 3: 2.0''D60, 1.5''F60, 0.25''F70,0.25''F70,4.0''D70, 2.0''Bb60, 2.0''A70, 2.0''D70, 1.0''Bb65, 1.0'C60

This is obviously just the tip of the iceberg – by adding to this application, I could assign different instruments to different tracks (via the “ProgramChange” event), persist metadata containing lyrics, and so on. (I don’t plan on doing that myself, since for me I simply wanted to learn more about MIDI, but who knows? Maybe later....) The completed code (along with another method which describes setting metadata) is attached to this blog post, and will also be posted on my Temple of VB site.

‘Til next time,

--Matt--*

Veni, MIDI, Vici: Generating a simple MIDI file using VB, part 1 (Matt Gertz)

VBTeam — Fri, 27 Feb 2009 21:01:00 GMT

As I’ve alluded to in previous blogs, music has always been a big part of my life, particularly performance music. I’ve been a clarinet and saxophone player for many years, am an avid singer, and (with the help of friends) I’ve done my best to teach myself piano and drums.

Composition of music, however, has always been a problem for me. I’ve written a few small pieces, but any attempt to write something larger has always ended up with me giving up after fifty or so measures. Programs to help a person create their own compositions have certainly come a long way, but they all have their idiosyncrasies. For example, one aspect of this that I’ve never been able to wrap my head around are MIDI channels and instruments – invariably, I always get these set wrong as my brain seems incapable of grokking the nuances of those areas. I’m still waiting for a low-cost composition program in which I can say “Piano plays this, clarinet plays this, and bass plays that,” and ignore the details of channels and whatnot.

It was simpler (though far less powerful!) when I had a Commodore 128. This was a gift I’d received for graduation, a fun machine that had three different operating systems (C64, C128, and CP/M) built into it. In the C128-mode, the version of BASIC included in the OS had a “Play” command which took a string of characters representing note pitches and durations. There were three voices which you could set to different instruments (well, envelopes, really), and the Play() call was asynchronous, so you could make chords by coding three Play() commands in a row. In practice, there was still a certain lag between the voices – it was not a speedy machine – but it was still a lot of fun to set up music in it.

I’ve decided that I’d enjoy the composition process more, given the tools that I have, if I understood how MIDI actually worked. After searching around on the Internet, I found a good article at Skytopia (http://www.skytopia.com/project/articles/midi.html) which listed out the basics of the MIDI format and also provided “for further information” links. Given that, I set out to create a MIDI-generation program which would mimic my C-128 experience, as well as give me some grounding in the MIDI format.

Caveat: I’m sure many readers will be far more knowledgeable about MIDI than I am, and will justifiably roll their eyes at this code due to its limited scope. I will only be generating simple type-1 MIDI files that only use the Note On and Note Off events, and which don’t use metadata, targeting a “Save” scenario only. The idea of this exercise was to understand MIDI and how to code against it in VB, not to generate a fully-functional music generation program. Coding up “Load” and supporting more of the MIDI functionality would be a more time-consuming process which maybe I’ll get to one day.

I started out by creating a Windows Application called VBMidi. But before I coded up the form, I took some time to craft out some support code to help me, as covered in the next section.

The gist of MIDI

MIDI files are composed of a well-defined header containing general information about the music, followed by a series of tracks containing actual notes, durations, and volumes for each track. To capture this, I added a new class to my application called MIDI. (Right-click the project, choose “Add,” and then choose “Class…”)

In this class, I set up some of the boilerplate information:

Public Class MIDI

' These are fixed data:

Dim MIDIHeader() As Byte = {&H4D, &H54, &H68, &H64, &H0, &H0, &H0, &H6}

Dim SubFormatType() As Byte = {&H0, &H1} ' Type-1 MIDI file (as opposed to Type-0)

MIDIHeader is always the first thing in the MIDI file, and just identifies this as a MIDI file. SubFormatType, on the other hand, is a two-byte field which, in my case, contains the bytes to identify this as a type-1 MIDI file (i.e., supporting multiple tracks, unlike type-0). Note that I’m using hexadecimal to define the bytes. When working with byte information, it’s traditional to use hex instead of decimal, as it’s a lot easier to see what will happen when bytes are concatenated or split apart into “nibbles” (groups of 4 bits).

The speed of the music is something I’ll also want to track at a high level, and I define that here:

Const ticksPerBeat = &H80

' These could be changed (in theory) by the program

Dim Speed() As Byte = {&H0, ticksPerBeat } ' Default to 128 ticks per beat

Speed can support two bytes, but as I’m defaulting to 128 (= &H80) ticks per beat, the first byte is 0.

All of the other data is owned by the tracks. I opted to create a nested class called “Track” to hold it. One of the first things I did in Track was to define the events that could exist:

Public Class Track

Public Enum NoteEvent

NoteOff = &H8

NoteOn = &H9

' Advanced

AfterTouch = &HA

ControlChange = &HB

ProgramChange = &HC

ChannelPressure = &HD

PitchWheel = &HE

End Enum

In this example, I’ll only be using the first two events – turning a note on, and turning it off. Each Track also has header and exit information:

' These are fixed data

Dim TrackHeader() As Byte = {&H4D, &H54, &H72, &H6B}

Dim TrackOut() As Byte = {&H0, &HFF, &H2F, &H0}

And then there’s all of the stuff in-between, such as the actual note data (stored in bytes) and metadata (also stored in bytes). I’ll be defining a container for metadata for the sake of completeness, even though I won’t be using it in this example:

' These can be changed by the program

Public TrackData As New List(Of Byte)

Dim TrackMetadata As New List(Of Byte)

Music can be played on one of 16 channels (&H0 through &HF). I’ve opted to create a “one channel per track” rule in my code, although this isn’t a requirement in the MIDI format. I’ve used channel = -1 to indicate that the track isn’t being used (even using a signed byte, I still have space for this, since the channel information only takes half of a byte), and I created a function to tell me if that’s the case:

Public Channel As SByte = -1

Public Function ValidTrack() As Boolean

Return Channel >= 0

End Function

Now, I need a way to actually add a note to the track. That function looks like this:

Public Sub AddNoteOnOffEvent(ByVal beatOffset As Double, ByVal ev As NoteEvent, _

ByVal note As Byte, ByVal volume As Byte)

This method requires a bit of explanation. First, let’s cover the arguments passed in:

· The caller will pass in the note’s beat offset (the difference between this event and the previous one) via a Double -- so, for example, assuming we’re in 4/4 time with a quarter note taking one beat, an eighth-note offset would be passed in as 0.5.

· The NoteEvent determines whether I’m turning on or off a note (there are other event possibilities, but as I’ve mentioned before, I’m going to ignore them for this application).

· The Note is just an index into the list of possible tones (for example, middle C is a 60 = &H3C).

· Finally, volume is just a value between 0 and 127.

Now, into the code for the function. If the track currently has no channel set for it, then I don’t bother adding the note and instead just return, since the note information has to be combined with the channel information.

If Not ValidTrack() Then Return

The next thing I do in that code is translate the note’s beatOffset to something MIDI can understand. The duration is with respect to the ticks per beat (defined earlier in the constant called rate as being 128 ticks per beat), so I multiply the two numbers together to get the number of ticks, casting it as an unsigned integer into something called tickOffset.

Dim tickOffset As UInt32 = CType(beatOffset * rate, UInt32)

Now I can actually start adding bytes to the TrackData. Assuming that the NoteEvent is either an On or Off, I’ll first add the tickOffset into the data. However, I can’t just blast in the value of tickOffset. MIDI requires a special format for durations which is a little screwy. Instead of saying “the duration data lasts this many bytes, and here they are,” they instead require a format where the final byte in the duration sequence is less than 128 (i.e., less than &H80). So, 127 ticks would be formatted as &H7F, but 128 ticks would be formatted as &H80 &H00, and this increases up to maximum possible value of &HFF &HFF &HFF &H7F, representing 268435455 ticks. I have a helper function to create this formatting for me, which I found at http://jedi.ks.uiuc.edu/~johns/links/music/midifile.htm and which I translated to VB:

Private Function TranslateTickTime(ByVal ticks As UInt32) As Byte()

Dim value As UInt32 = ticks

Dim buffer As UInt32

buffer = ticks And &H7F

value = value >> 7

While value > 0

buffer = buffer << 8

buffer = buffer Or ((value And &H7F) Or &H80)

value = value >> 7

End While

' The encoded values are now in the buffer backwards, so retrieve them...

Dim blist As New List(Of Byte)

While True

blist.Add(CByte(&HFF And buffer))

If (buffer And &H80) > 0 Then

buffer = buffer >> 8

Else

Exit While

End If

End While

Return blist.ToArray

End Function

I’m not going to get too deep into that function; suffice to say that I step through each byte in the ticks variable, retrieve up to &H7F bytes worth, increment the adjacent byte to a base of &H80 if it goes over, and continue through the ticks in that way. When I’m done, the bytes will be in reverse order in a buffer, so I pop bytes off that buffer and into a list of bytes, from which I generate a byte array to pass back. Back in the AddNoteOnOffEvent method, I then call it thusly:

If ev = NoteEvent.NoteOn OrElse ev = NoteEvent.NoteOff Then

TrackData.AddRange(TranslateTickTime(tickOffset))

which will add all of the bytes in the array that I returned into the TrackData. The next byte that needs to go in contains both the event and the channel – each of those takes up one nibble in the byte, so I’ll shift the event four places to the left and “or” the result with the channel. Since Channel is currently a signed byte and I need it to be a nibble, I need to explicitly cast it to Byte. (I also “and” it with &HF to eliminate the upper nibble in the resulting channel byte, though that really isn’t required since the upper nibble should already be zero.)

TrackData.Add((ev << 4) Or (CByte(Channel) And &HF))

Note and Volume are, thankfully, already in the correct format (byte), so I just add them directly.

TrackData.Add(note)

TrackData.Add(volume)

End If

End Sub

TrackData now contains the music, and I now create a Save() function for the track object to write it out to the MIDI file. This is pretty straightforward except for TrackSize. Since that value is an integer and I don’t necessarily know what order its bytes will be persisted in (it varies based on chip architecture), I’m explicitly saving it out byte-by-byte, using shifting and casting to make it work correctly:

Public Sub Save(ByVal filepath As String)

If ValidTrack() Then

My.Computer.FileSystem.WriteAllBytes(filepath, TrackHeader, True)

Dim TrackSize As UInt32 = TrackData.Count() + TrackMetadata.Count() + TrackOut.Count()

Dim byteTrackSize(0 To 3) As Byte

byteTrackSize(0) = CByte((TrackSize >> 24) And &HFF)

byteTrackSize(1) = CByte((TrackSize >> 16) And &HFF)

byteTrackSize(2) = CByte((TrackSize >> 8) And &HFF)

byteTrackSize(3) = CByte((TrackSize And &HFF))

My.Computer.FileSystem.WriteAllBytes(filepath, byteTrackSize, True)

My.Computer.FileSystem.WriteAllBytes(filepath, TrackData.ToArray, True)

My.Computer.FileSystem.WriteAllBytes(filepath, TrackMetadata.ToArray, True)

My.Computer.FileSystem.WriteAllBytes(filepath, TrackOut, True)

End If

End Sub

That’s it for the Track subclass. Back in the MIDI class, I can add code to set up the tracks:

Public Tracks As New List(Of Track)

Public Function AddTrack() As Track

Dim t As New Track

Tracks.Add(t)

Return t

End Function

And then a Save() method to save the MIDI header information and all of the tracks. Again, this is pretty straightforward. I save out the header and format information to the file, determine how many tracks are valid and persist that information out to the file in the appropriate byte-order, save out the speed data for the MIDI file as well, and then iterate through each track and let each one save its data (the track will handle the case where’s it’s invalid). I’ve wrapped the whole thing up in a try-catch structure in case there’s a problem accessing the file at any time.

Public Sub Save(ByVal filepath As String)

Try

My.Computer.FileSystem.WriteAllBytes(filepath, MIDIHeader, False)

My.Computer.FileSystem.WriteAllBytes(filepath, SubFormatType, True)

Dim numTracks As UShort = 0

For Each t In Tracks

If t.ValidTrack Then

numTracks += 1

End If

Dim byteTracks(0 To 1) As Byte

byteTracks(0) = CByte((numTracks >> 8) And &HFF)

byteTracks(1) = CByte((numTracks And &HFF))

My.Computer.FileSystem.WriteAllBytes(filepath, byteTracks, True)

My.Computer.FileSystem.WriteAllBytes(filepath, Speed, True)

For Each t In Tracks

t.Save(filepath)

Catch ex As Exception

MsgBox("Unable to save the file due to the following error:" & vbCrLf & ex.Message)

Return

End Try

End Sub

One thing I should note: you’ll see that the first call to WriteAllBytes uses “False” for its third parameter, whereas the other all use “True.” A value of True means that the data will be appended to the file instead of overwriting the file, so it’s the first call I make that overwrites any existing file, and the subsequent calls append data to the new incarnation of that file.

So, that’s it for the support code. In part two of this series, I’ll use this code to drive the music editing functionality.

‘Til next time,

--Matt--*

An Updated Screensaver Example (Matt Gertz)

VBTeam — Sat, 24 Jan 2009 05:30:00 GMT

I’ve just completed a task that I set out to do about five years ago, and I am pretty proud (and tired)! I have just finished scanning in every single photo that I’ve acquired over my 40+ years of life, fixing up their dates to reflect the date when the picture was taken, not when it was scanned. Furthermore, I have tagged every photo on the disk drive (scanned or originally digital) with metadata saying who was in the photo and where it was taken. All of my family videos have been scanned in as well, and all of that work (plus all of my music tracks and personal documents) is now backed up weekly onto a 1.5TB disk that I store in a fireproof safe. I’ve now got over 16,000 photos and 20+ hours of video on the system, going all the way back to the year 1875 (a picture of my great-great-grandparents on their wedding day), all of which are (hopefully) now preserved against tragic circumstances.

Of course, having done all that work, I wanted to relax and view the photos! I didn’t want to buy one of those picture frames that can do slide shows, since they are expensive and I’d have to find one that would support a big enough (and also expensive) memory card – it’s 22GB worth of pictures.

My first choice was to use the screensaver that comes with Windows. I run both Windows Vista and Windows XP at home (and Windows7 at work!), and the photo screensaver that comes with them is pretty decent in both cases. But, after a while, I got tired of my kids asking “Who is that? When was that? Where was that?” over and over again. If only I had a setting on the screensaver that would show the “DateTaken” property, and the Tags associated with the photo…

Well, of course, this was a good opportunity for me to learn about screensavers, which I hadn’t really ever thought much about before. And thus began the journey…

What is a screensaver?

A screensaver is just an application renamed to have a .SCR extension, and placed in the Windows system directory. That’s it.

Now, of course, the application should be a little special. It needs to take up the whole screen, it shouldn’t have borders, menus, captions, or any other decorations, and it needs to turn itself off when the mouse moves. Furthermore, it needs to expose its options in a certain way, so that the user can set them in the screensaver control panel.

I found out that MSDN has an example of a screensaver built using VS2003-level functionality, but targeting .NET 2.0. You can find it here, and I’ll be referring back to it throughout this blog, much of which won’t make sense unless you’ve read through that code (consider it as homework J). That screensaver draws random shapes on the screen and gives you a few options to change the speed and quality of the shapes. However, it doesn’t leverage any of the new coolness we’ve introduced in recent versions of Visual Basic, so I figured that it was time for a screensaver makeover. I copied it down to my machine and opened it up. It has three classes in it – an Options class, an Options form, and a Screensaver form. We’ll discuss these in order.

The options class

The options class defines settings that the user wants to persist between runs, and also provides a mechanism for strong them. The original settings were:

Private m_Speed As String = "Fast"

Private m_Shape As String = "Ellipse"

Private m_IsTransparent As Boolean = True

I changed these to:

#Region "Member variables"

Private m_Speed As Integer = 6

Private m_ShowTags As Boolean = True

Private m_ShowDates As Boolean = True

Private m_Directory As String = ""

Private m_UseSubdirectories As Boolean = True

#End Region

Basically, I’m going to let the used specify the time (in seconds) that the picture should stay up, whether or not to show the tags and the date superimposed on the photo, where to look for photos, and whether or not to search subdirectories of that directory. I also went ahead & generated get/set properties for each of those, ripping out the old ones.

Now, the rest of this file spends a lot of its code in opening up an options file, reading the data, writing to it, etc. Fortunately, we don’t need any of that code anymore. To set up automatic setting storage, I simply right-clicked the project, chose “Properties,” navigated to the Settings tab, and entered in my five settings as given above. My entire persistence code then became:

Public Sub LoadOptions()

Me.Speed = My.Settings.Speed

Me.ShowDate = My.Settings.ShowDate

Me.ShowTags = My.Settings.ShowTags

Me.Directory = My.Settings.Directory

Me.UseSubdirectories = My.Settings.UseSubdirectories

If String.IsNullOrEmpty(Directory) Then ' Default to "My Pictures" if not initialized

Me.Directory = My.Computer.FileSystem.SpecialDirectories.MyPictures

End If

End Sub

Public Sub SaveOptions()

My.Settings.Speed = Me.Speed

My.Settings.ShowDate = Me.ShowDate

My.Settings.ShowTags = Me.ShowTags

If Not String.IsNullOrEmpty(Directory) Then ' Don't bother saving

My.Settings.Directory = Me.Directory

End If

My.Settings.UseSubdirectories = Me.UseSubdirectories

My.Settings.Save() ' Necessary since we'll be forcing application exits later

End Sub

eliminating about 40 lines of code devoted to serializing out the class.

The options form

Of course, by that point, I was getting build errors all over the place, since I was now out of synch with the options form and the screensaver form. Let’s take a look at the options form. For clarity’s sake, I wanted to hide the form-initialization code that VS2003 used to shove into the class file. I created a new file in the project, named it “frmOptions.Designer.vb”, and typed the following into it:

<Global.Microsoft.VisualBasic.CompilerServices.DesignerGenerated()> _

Partial Class frmOptions

Inherits System.Windows.Forms.Form

End Class

I then copied all of the generated crud into that partial class and got it out of the way.

All I really needed to do now is to replace the existing controls with three checkboxes (tags,date, and subdirectories) and two edit boxes (speed and directory). That’s easy enough to do. However, not content with doing it the easy way, I decided to limit the “speed” text box so that it can only accept numbers. There’s a VB snippet that does exactly that for combo boxes (“Windows Forms Applications”-> Forms->Restrict a Control’s Acceptable Keystrokes”), and I’ve modified it for my edit box:

Class restrictedTextBoxClass

Inherits TextBox

Const WM_KEYDOWN As Integer = &H100

Protected Overrides Function ProcessCmdKey _

(ByRef msg As Message, _

ByVal keyData As Keys) As Boolean

If msg.Msg = WM_KEYDOWN Then

Return Not ((keyData >= Keys.D0 And keyData <= Keys.D9) _

Or keyData = Keys.Back Or keyData = Keys.Left _

Or keyData = Keys.Right Or keyData = Keys.Up _

Or keyData = Keys.Down Or keyData = Keys.Delete)

End If

Return MyBase.ProcessCmdKey(msg, keyData)

End Function

End Class

Then, given that, I reopened the frmOptions.Designer.vb file that I just created (can’t find it? Make sure that “Show All Files” is turned on in the Solution Explorer’s tool bar) and changed TextBox to restrictedTextBoxClass in two locations:

Friend WithEvents txtSpeed As frmOptions.restrictedTextBoxClass

…

Me.txtSpeed = New ScreenSaver.frmOptions.restrictedTextBoxClass

I had to explicitly *rebuild* at this point – otherwise, the designer wouldn’t have known how to render the control if I were I to switch to the designer.

The screensaver form

Here’s where the real work happened. Using the error messages in the Error List, I ripped out the lines of code that referred to things that didn’t exist anymore (like graphics, eliipses, etc). I also moved the initialization crud into a partial class file, like I did for the options dialog.

The form used doesn’t actually start out with any controls on it. I set its BackColor to black, and then I added two controls (and the order was important):

(1) A PictureBox control which I sized to be the same size as the form. I set its BackColor to be black, and set its SizeMode property to Zoom. (I will not be doing any cutesy transition effects – I dislike those intensely, so I’ll leave that as an exercise for the reader.)

(2) A label control with the BackColor set to black and the ForeColor set to White. My default text for this control was “Loading Pictures…”

There’s nothing else I have to do to the form itself – it’s already set up to fill the monitor (WindowState=Maximized), decorations are turned off (ControlBox = False, MinimizeBox and MaximizeBox are False, ShowInTaskbar = False, SizeGripStyle=Hide), and TopMost is equal to True. Note that you will want to temporarily change TopMost to be False when developing & debugging; otherwise, you won’t be able to see the debugger, unless you are running dual-monitor!

I knew that I was going to need to use some .NET 3.0 functionality in order to dig out the picture metadata, so I right-clicked the project and chose “Properties.” On the “Compile” tab, I clicked the “Advanced Compiler Options” button and, on the bottom of the resulting window, I changed the Target Framework to be the 3.5 version (3.0 would have worked also, but I like being current). I then used the “Add Reference” menu item off of the project to add some needed references to the project – PresentationCore (found by navigating to C:\Program Files\Reference Assemblies\Microsoft\Framework\v3.0\PresentationCore.dll on the Browse tab) and WindowsBase (found on the .NET tab).

Now, it was all coding. My member variable had been whittled down to this:

Private m_Options As New Options()

Private m_Random As New Random()

Private m_IsActive As Boolean = False

Private m_MouseLocation As Point

Private m_files As ReadOnlyCollection(Of String)

Private m_fileCount As Integer = 0

Those would allow me to track the user options, generate random numbers, determine if the mouse was active and where it was at, hold onto the list of picture files that I wanted to display, and keeping a count of the latter as well.

I created a helper function to position my label. Basically, I always want it exactly at the bottom of the screen, centered horizontally:

Private Sub SetLabelLocation()

Me.lblDescription.Top = Me.Size.Height - Me.lblDescription.Height

Me.lblDescription.Left = (Me.Size.Width - Me.lblDescription.Width) \ 2

Me.lblDescription.Show()

End Sub

Now I could rewrite the form’s Load event handler (comments in all of this code omitted for brevity, though you’ll see them in the final product):

Private Sub frmSceenSaver_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

m_Options.LoadOptions()

SetLabelLocation()

Me.tmrUpdateScreen.Interval = m_Options.Speed * 1000

Me.tmrUpdateScreen.Enabled = True

If m_Options.UseSubdirectories = True Then

m_files = My.Computer.FileSystem.GetFiles(m_Options.Directory, FileIO.SearchOption.SearchAllSubDirectories, "*.jpg")

Else

m_files = My.Computer.FileSystem.GetFiles(m_Options.Directory, FileIO.SearchOption.SearchTopLevelOnly, "*.jpg")

End If

If m_files IsNot Nothing Then

m_fileCount = m_files.Count

Else

Me.lblDescription.Text = "No pictures found!"

SetLabelLocation()

End If

End Sub

This is pretty straightforward code: I load the options from the user settings, move the label to the correct position, translate to desired seconds of duration to milliseconds, and enable the Timer (which was already attached to the form in the original code). Then, I do a search for all JPG files in the desired directory (and in subdirectories, if the user chose that option) and collect them in the m_files object. If I got any files back, then I keep track of the count to use later on when generating a random number. Otherwise, I tell the user that I couldn’t find any pictures. (The string should really go into the resources, but that makes the blog posts less readable.)

As with the original version that I downloaded, I wanted the application to end when the user moves or clicks the mouse. The problem, however, is that the label and picture are hiding the form, so that the form never gets mouse events. This was easily remedied by adding the appropriate events to the event handlers (I’ve underlined those below), and otherwise this code is unchanged:

Private Sub frmScreenSaver_MouseMove(ByVal sender As Object, _

ByVal e As System.Windows.Forms.MouseEventArgs) Handles MyBase.MouseMove, _

PictureBox1.MouseMove, lblDescription.MouseMove

and

Private Sub frmScreenSaver_MouseDown(ByVal sender As Object, _

ByVal e As System.Windows.Forms.MouseEventArgs) Handles MyBase.MouseDown, _

PictureBox1.MouseDown, lblDescription.MouseDown

Periodically, the timer will fire, and that calls the Tick handler, wherein all I did was change the name of the helper function from DrawShape to DrawPicture (if any files exist to be drawn):

Private Sub tmrUpdateScreen_Tick(ByVal sender As System.Object, ByVal e As _

System.EventArgs) Handles tmrUpdateScreen.Tick

If m_fileCount <> 0 Then

DrawPicture()

End If

End Sub

As I mentioned above, DrawShape became DrawPicture, and I ripped out all of the code from it and entered the strange and inscrutable world of image metadata. Metadata such as “DakeTaken” and “Keywords” aren’t available from the normal FileInfo; you have to dig for them, and it’s not an intuitive process. I started out by getting a random number from 0 to m_fileCount - 1, and then determining if I need to grab metadata from the resulting file:

Private Sub DrawPicture()

Dim index As Integer = Me.m_Random.Next(0, m_fileCount - 1)

If m_Options.ShowDate = True OrElse m_Options.ShowTags = True Then

“Index” is the index of the picture I’ll be showing. Now, I needed to crack that file open:

Dim jpegStream As New System.IO.FileStream(m_files(index), _

FileMode.Open, FileAccess.ReadWrite, FileShare.ReadWrite)

Dim jpegDecoder As New JpegBitmapDecoder(jpegStream, _

BitmapCreateOptions.PreservePixelFormat, BitmapCacheOption.Default)

Dim jpegFrame As BitmapFrame = jpegDecoder.Frames(0)

Dim jpegInplace As InPlaceBitmapMetadataWriter = _

jpegFrame.CreateInPlaceBitmapMetadataWriter()

The first line should look pretty familiar – I’m just opening up a file like normal. In the second line, I’m attaching the resulting stream to a JpegBitmapDecoder, which allows me to treat the file as if it is a JPEG (which it is), so that I don’t need to know or care about the JPEG format when parsing through it. The third line gets me the first frame of that JPEG (and yes, 99.9999% of the time, there’s only one frame), and in the fourth line, I get a pointer to the metadata of that frame.

(BTW: Yes, the object is called a “metadata writer.” There is no such thing as a “metadata reader” – you use this object for both. Yes, that’s silly. My screensaver just does reading, of course; if you’re interested in how to actually *write* metadata into the file once you’ve gotten this far, I’ve coded up an example in the completed code, attached at the bottom of this post.)

The next bits retrieve metadata from the writer and combine them into a display string:

Dim sDescription As String = ""

If m_Options.ShowDate = True Then

If Not String.IsNullOrEmpty(dt) Then

Dim ddt As Date = CDate("#" & dt & "#")

sDescription = ddt.Date & ": "

End If

“DateTaken” actually returns the time as well, and I just wanted the date, so I converted the DateTaken string to a true date and then retrieved the Date portion from it.

If m_Options.ShowTags = True Then

If jpegInplace.Keywords IsNot Nothing AndAlso jpegInplace.Keywords.Count > 0 Then

For Each keyword As String In jpegInplace.Keywords

If Not keyword.StartsWith(" ") Then

sDescription += keyword & ", "

End If

Tags are referred to as “Keywords” in metadata, and they are stored in a read-only collection which I have to iterate through. I ignore tags that start with a space character – this is because I personally mask out incorrect tags with spaces rather than removing them. This is because it’s important to keep the overall size of the metadata constant when modifying the file in-place, and I (for whatever reason) frequently write in the wrong tag. (The proper way to remove bad tags is to create a copy of the file which lacks them, but that’s heavy-weight.)

After that, I do a bit of cosmetic work on the string:

If sDescription.EndsWith(", ") OrElse sDescription.EndsWith(": ") Then

sDescription = Microsoft.VisualBasic.Left(sDescription, sDescription.Length - 2)

End If

As you can see, I’ve been concatentating the strings with “: “ or “; “, and since I’m too lazy to use fancy logic in the loop to look ahead to make sure I don’t add an extra one, I just trim any that I don’t need when all done.

Then I set the text of the label to be the description I’ve just created, center the label, and close the file:

Me.lblDescription.Text = sDescription

SetLabelLocation()

jpegStream.Close()

It was important for me to remember to close the file, since I’m about to tell the picture control to use that same file, and they can’t use it at the same time. But first, before loading up the picture, my code hides the label if the user didn’t want to show any text at all:

Else

Me.lblDescription.Hide()

End If

Now all that remains is to show the picture:

Me.PictureBox1.Load(m_files(index))

End Sub

And that’s it; the old shape screensaver has been successfully transformed into a new picture screensaver that also shows the viewer the date the picture was taken, who is in the picture, and where they were. The last thing to do, after building and debugging the app, is to copy it up to the c:\windows\system32 direcotry and change its extension to be SCR instead of EXE.

Calling the screensaver from Windows

Note that I didn’t need to change the “Main” function, but I’ll briefly describe it here anyway. First, we note that this is a single-threaded application which can handle arguments passed to it:

<STAThread()> Shared Sub Main(ByVal args As String())

If args.Length > 0 Then

Windows will pass one of three flags as arguments. The first possibility is “p”, which means “show a preview of the screensaver.” As with the original version of this code, I didn’t do any special here, but just exited, since previews are beyond the scope of this blog and frankly, if you need a preview of a slideshow, then you’re not understanding the screensaver altogether:

If args(0).ToLower = "/p" Then

Application.Exit()

End If

The second option is “c”, which means that Windows wants to display the option settings. Once the user dismisses the options, I close down the application:

If args(0).ToLower.Trim().Substring(0, 2) = "/c" Then

Dim userOptionsForm As New frmOptions()

userOptionsForm.ShowDialog()

Application.Exit()

End If

The third option (and also the default option, if no arguments are supplied) is “s”, which means that I should show the screensaver itself, and then close it down once it’s exited:

If args(0).ToLower = "/s" Then

Dim screenSaverForm As New ScreenSaver.frmScreenSaver()

screenSaverForm.ShowDialog()

Application.Exit()

End If

Else

Dim screenSaverForm As New ScreenSaver.frmScreenSaver()

screenSaverForm.ShowDialog()

Application.Exit()

End If

End Sub

And there you have it. The completed code (along with another method which describes setting metadata) is attached to this blog post, and will also be posted on my Temple of VB site.

‘Til next time,

--Matt--*

[Edit: I re-posted the ZIP file and modified the blog so that the SizeMode for the Picture was correctly set to Zoom instead of Center Image, and I now force a save of the options when changes are applied so that Application.Exit doesn't skip that step.]

Did you know? You can unwind the call stack from exceptions (Bill Horst)

VBTeam — Tue, 09 Dec 2008 19:00:00 GMT

The ability to unwind the call stack from exceptions is one of the debugger features that was newly introduced in Visual Basic.NET 2005. When the debugger hits a first-chance exception, you can unwind the call stack in order to make code edits to fix the exception and continue debugging with the changes. The exception assistant UI will have an “Enable Editing” option which will unwind the debugger to the topmost call stack frame with code in the current solution.

When an exception is unhandled, the unwind will occur automatically, but this can be turned on and off from the Options dialog (under Tools).

If you attempt to edit code after an exception has been hit, but before an unwind, you're allowed the option of unwinding and editing the code, stopping the debugging session, or canceling the edit.

The user can also unwind from the call stack window, by right-clicking the desired frame and selecting “Unwind To This Frame”. This is only available when an exception has been hit and not yet unwound, and only on frames sufficiently high on the call stack.

We hope that this functionality will allow you to be more effective in their debugging, and will help you better leverage the “Edit and Continue” capabilities in Visual Basic.