MSDN-Example with Collection(of T)

[Robert Schneider]

Hi,

the msdn documentation provides an Dinosaurs example that uses the
objectmodel.collection class. Just have a look on the help page for this
class.

I don't understand what happens here. Or I cannot find more detailed
documentation for this behavior. What I mean is the invocation of the
Dinosaurs.Add method which is derived from Collection(of String). The method
seems to invoke the overridden InsertItem method. Can this method be viewed
as a OnInsertItem method? Which is also public? Where is this behaviour
descriped? Or is it obvious and I'm an idiot?

Any hints?

Cheers,
Robert

 

[Larry Lard]

Hi,

the msdn documentation provides an Dinosaurs example that uses the
objectmodel.collection class. Just have a look on the help page for this
class.

<http://msdn2.microsoft.com/en-us/library/ms132397(VS.80).aspx>, for
reference. You can obtain an external URL for stuff you find in the
VS2005 help by googling for appropriate words and adding the search
term site:msdn2.microsoft.com.

I don't understand what happens here. Or I cannot find more detailed
documentation for this behavior. What I mean is the invocation of the
Dinosaurs.Add method which is derived from Collection(of String). The method
seems to invoke the overridden InsertItem method. Can this method be viewed
as a OnInsertItem method?

Yes, if you like. Like the Overrideable Protected "OnSomething" methods
in the WinForms world, these Overrideable Protected "SomethingItem"
methods are an invitation to inheritors to extend the class's behavior
in particular circumstances. The modifiers themselves suggest this:
Protected means 'only an inheritor has access to this' and Overrideable
means 'reimplement me if you want to change behavior' - put them
together and there you have it.

Which is also public?

No, it's not public. The nearest equivalent public method is Insert -
this is what *clients* of the collection will call when they want
something inserted. You will note that the help page for Insert says:

"Notes to Inheritors: Derived classes can override InsertItem to change
the behavior of this method. "

Where is this behaviour
descriped?

Well, the rubric for Example 2 on the very page we are talking about
says:

"The following code example shows how to derive a collection class from
a constructed type of the Collection generic class, and how to override
the protected InsertItem, RemoveItem, ClearItems, and SetItem methods
to provide custom behavior for the Add, Insert, Remove, and Clear
methods, and for setting the Item property."

Or is it obvious and I'm an idiot?

Generics are to a certain extent 'obvious once you get it', BUT the
*reference* documentation is probably not the best way to try and learn
this stuff. Although the .NET 2.0 docs are hugely improved over the
1.0/1.1 docs (which were insultingly boiler-plate in style), there are
still better resources. Context sensitve help will usually take you to
pages like the above, which are designed to be *references* - there are
more *learning*-oriented pages elsewhere in the 'help hierarchy', eg
try

<http://msdn2.microsoft.com/en-us/library/w256ka79(VS.80).aspx>

and the whole section of the help tree that that page is found in.

Or, a good book - I am currently working through Balena's VB2005 book
(published earlier this year), and while I haven't got to Generics yet,
so far it is all up to his usual high standard.

 

[Robert Schneider]

Thank you Larry for the considerate answer.

<http://msdn2.microsoft.com/en-us/library/ms132397(VS.80).aspx>, for
reference. You can obtain an external URL for stuff you find in the
VS2005 help by googling for appropriate words and adding the search
term site:msdn2.microsoft.com.

I'll do this next time.

Yes, if you like. Like the Overrideable Protected "OnSomething" methods
in the WinForms world, these Overrideable Protected "SomethingItem"
methods are an invitation to inheritors to extend the class's behavior
in particular circumstances. The modifiers themselves suggest this:
Protected means 'only an inheritor has access to this' and Overrideable
means 'reimplement me if you want to change behavior' - put them
together and there you have it.

No, it's not public

Sorry for that. But one other question comes to my mind: Could it make sense
to call those methods directly in an derived class? Technically, this is
possible. But is it also sensible? I ask that also for windows forms classes
with their On... methods. Or is it more advisable to call the correlating
official public methods?

"Notes to Inheritors: Derived classes can override InsertItem to change
the behavior of this method. "


Well, the rubric for Example 2 on the very page we are talking about
says:

"The following code example shows how to derive a collection class from
a constructed type of the Collection generic class, and how to override
the protected InsertItem, RemoveItem, ClearItems, and SetItem methods
to provide custom behavior for the Add, Insert, Remove, and Clear
methods, and for setting the Item property."

I guess I'm too used to the OnSomethingHappend naming scheme. For me it
would be much clearer if those method names would start withn an On. This is
also done in the non-generic CollectionBase class. Is there a reason why MS
developers decided to not follow this naming convention in the Collection
class as well? Propably because they want to confuse their customers.

Cheers,
Robert

 

[Larry Lard]

Sorry for that. But one other question comes to my mind: Could it make sense
to call those methods directly in an derived class? Technically, this is
possible. But is it also sensible? I ask that also for windows forms classes
with their On... methods. Or is it more advisable to call the correlating
official public methods?

Generally when you have the more private methods available, you would
use them. There aren't really any hard and fast rules, but it 'makes
more sense' for a derived class to use InsertItem rather than Insert to
do its inserting. For example, suppose I had a DinosaurGarden, which is
a subclass of Collection(Of Dinosaur), and I want to ensure that
whenever someone adds a dino to this collection, a predator or prey
dino for the new dino is also added. I would do something like this:

Protected Overrides Sub InsertItem( _
ByVal index As Integer, ByVal newItem As Dinosaur)

'insert this dino
MyBase.InsertItem(index, newItem)
'make a dino it can play with
Dim counterpartDino As Dinosaur = Dinosaur.Playmate(newItem)
'also insert the playmate
MyBase.InsertItem(index, counterpartDino) '**************

End Sub

Note that if instead of the highlighted line I instead had

Me.Insert(index, counterpartDino)

then I would create an infinite loop, because Insert would call
InsertItem and so on. Here using InsertItem makes sense, because I am
doing something internal to the class. However, elsewhere in the class
it might make sense to use the public methods. For example, I might
have an initial seeding routine for the garden:

Public Sub Seed()
Me.Insert(0, New Dinosaur("Velociraptor"))
Me.Insert(0, New Dinosaur("Brontosaurus"))
End Sub

Here, it makes sense for me to use the public Insert method, because
even though this is a method within the Garden class, in a sense it is
a client of the Insert method. I am just inserting dinos into myself
the same as anyone else would.

This kind of thing just takes time, and immersion / exposure to lots of
code, to get a feel for.

Certainly in the WinForms world it's easier to see the appropriate
thing to do: for example, OnPaint is where one writes one's own
painting, but to force a repaint, it's Invalidate().

I guess I'm too used to the OnSomethingHappend naming scheme. For me it
would be much clearer if those method names would start withn an On. This is
also done in the non-generic CollectionBase class. Is there a reason why MS
developers decided to not follow this naming convention in the Collection
class as well? Propably because they want to confuse their customers.

I don't know any reason for sure. It might be that Generics was
produced by a different team than originally produced
System.Collections, so they didn't notice the existing convention.
"OnX" is a fairly standard idea though, going back certainly as far as
the Object Model Naming Guidelines of the late 1990s, so it is a bit
strange.

 

[Robert Schneider]

Thank you for the explanations.
Robert