MSDN-Example with Collection(of T)

microsoft.public.dotnet.languages.vb

11 Apr 2006 3:09 PM

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

--
E-Mail: r._sch_nei_d_er#_we_ingar_t_ner.c_om
(remove each '_' from the address and replace '#' with '@')

11 Apr 2006 4:12 PM

Larry Lard

Robert Schneider wrote:

> 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.

--
Larry Lard
Replies to group please

12 Apr 2006 5:44 AM

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.

Show quoteHide quote

>> 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
>

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?

Show quoteHide quote

> "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."
>

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

12 Apr 2006 2:45 PM

Larry Lard

Robert Schneider wrote:
Show quoteHide quote

> >> 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
> >
>
> 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.

--
Larry Lard
Replies to group please

13 Apr 2006 6:00 AM

Robert Schneider

Thank you for the explanations.
Robert

--
E-Mail: r._sch_nei_d_er#_we_ingar_t_ner.c_om
(remove each '_' from the address and replace '#' with '@')

Show quoteHide quote

"Larry Lard" <larryl***@hotmail.com> schrieb im Newsbeitrag
news:1144853151.302328.159240@u72g2000cwu.googlegroups.com...
>
> Robert Schneider wrote:
>> >> 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
>> >
>>
>> 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.
>
> --
> Larry Lard
> Replies to group please
>