Bug? Feature? You be the judge...

While working on the xbox friends thing, I decided to create a clone of the user interface that Windows Messenger uses.  It's sort of like a treeview (or group box) and has a vertical scrollbar visible when the list is larger than the displayable area.

So, I add a vertical scrollbar to the control and make it visible when the need arises.  Easy enough.

Now for the problem.  When I set the Maximum to the number of items in the display and scroll all the way to the bottom of the scrollbar I don't get the Maximum value.  I get some other value.  For example, if there are 41 people in the list separated into three groups, I should have 44 lines to display.  If my view can only handle 15 then I need the scrollbar.  I set the Maximum to 44.  When I scroll to the bottom, it gives me 35??????

After playing with this for a while, I determined what was happening.  The Maximum value is not what will be returned by Value when the scrollbar is at maximum.  The maximum Value is (Maximum - LargeChange) + 1.  Hmmm... that didn't seem right... so I launched VB6 and setup a little test.  Yup, in VB6 it gives maximum value is Max; LargeChange doesn't come into play at all.  So my memory was serving me correctly.

OK, so maybe it changed in .NET.  Time to look at the documentation.  For LargeChange it states the following:

Gets or sets a value to be added to or subtracted from the Value property when the scroll box is moved a large distance.

and in the remarks section:

When the user presses the PAGE UP or PAGE DOWN key or clicks in the scroll bar track on either side of the scroll box, the Value property changes according to the value set in the LargeChange property.

Hmmm... pretty much was I expected and sounds like the same thing VB6 would say.  It doesn't say anything about LargeChange coming into play when returning what the maximum value will be.  It just says that LargeChange determines how much the change will be if you page up, page down or click in the scrollbar area around the position indicator.

Now, I'm not saying this is a bad thing.  If you set the LargeChange to a value that represents how many items can be displaying; you won't have to make any further calculations in order to get the display to show the Maximum - displayItems (meaning, you won't have only one item showing in the list; always having a full display).

However, if this is a bug, then I'm concerned if I write my code this way and moving forward to Whidbey; if they 'fix' it, then my code will stop working.  If it's not a bug, then the documentation needs to be updated accordingly.

I also posted this to the Windows Forms.com Forum about a week ago and haven't gotten a response (8 views, but no response). :-(

So, now I leave it up to you to decide.  Is this a Bug?  or a Feature?

[update] I guess I should have dug a little deeper into the documentation.  If you look at the Note in the Remarks sections for Maximum, it states the following:

Note   The value of a scroll bar cannot reach its maximum value through user interaction at run time. The maximum value that can be reached is equal to the Maximum property value minus the LargeChange property value plus one. The maximum value can only be reached programmatically.

So it is by design.  I guess I would have expected the same note to be in the LargeChange documentation as well.  So, if there is a 'bug', then it's in the documentation.  Also, the upgrade wizard doesn't point out this fact either.  I tested using some code in the Change event to display the values of Maximum, LargeChange and Value.  Here's what it looks like after the upgrade wizard.

'UPGRADE_NOTE: VScroll1.Change was changed from an event to a procedure. Click for more: 'ms-help://MS.VSCC.2003/commoner/redir/redirect.htm?keyword="vbup2010"'
'UPGRADE_WARNING: VScrollBar event VScroll1.Change has a new behavior. Click for more: 'ms-help://MS.VSCC.2003/commoner/redir/redirect.htm?keyword="vbup2065"'
Private Sub VScroll1_Change(ByVal newScrollValue As Integer)
  Me.Text = (VScroll1.Maximum - VScroll1.LargeChange + 1) & "," & VScroll1.LargeChange & "," & newScrollValue
End Sub

It just lets you know about the Change event, nothing about Maximum/LargeChange changing behavior.  So, my suggestion to the VB.NET team, add the same note to the LargeChange property and update the upgrade wizard to point out about the this change in behavior between VB6 and VB.NET.

Thanks to Prashanth for pointing me to the Longhorn SDK documentation.  After looking at the LargeChange property (which still does not have this note), I decided to just take a look at Maximum to see if it had changed.  Sure enough, the note block will smack you in the face.  So I jumped into Visual Studio to see if Maximum had the same note.  It does, but doesn't quite jump out at you like the Longhorn docs do; but hey, at least now I know that it's not a bug ;-)