Don’t mix “controls” and “parent” with “class” and “superclass”, people can get confused.
That said, a class event of an instance can be bubbled up to its superclass and beyond until the base class (if needed) for sure.
I can’t point you to specific pages, but I initially learned all this stuff from the documentation, so I know it’s in there somewhere. One example would be KeyDown, where the docs do say if you return True, the superclass will not handle the event. I seem to remember a discussion of event propagation in the User Guide. But I hardly ever go there anymore.
Well maybe if it’s in there somewhere, the Xojo team can make it more prominent or easier to find in the documentation.
Personally I’ve seen bits and pieces of this, but nothing to the extent that Thom has documented.
Perhaps it’s me that’s confused 
I just tried this: I made a class myListbox with a super of DesktopListbox, and added a couple of instances of that to a Window. I then added PaintCellText to one instance, and found I could still add that event to the superclass. But once I’d done that, I couldn’t add PaintCellText to the other instance. I’d always thought that you could either handle an event in the instance, or its superclass, but not both. But that seems not to be the case although to make it not be the case requires adding the event handlers in a particular order.
Edit: Ah, I see I can create an event handler in the super and an instance - the IDE permits it - but the compiler then complains. This would appear to prevent the notion of an event bubbling up from an instance to its super.
And are you saying an event cannot be handed of to the parent of a control?
You can most certainly add an event in both superclass and subclass. The superclass has to re-raise the event for it to be valid in the subclass.
Superclass xyz event:
// do stuff before the subclass event runs
RaiseEvent xyz
// do stuff after the subclass event code runs
If the superclass doesn’t raise the event for the subclass, you get your compile error.
1 Like
At the risk of being pedantic, let me differentiate the way methods and events are called. Xojo has a fairly unique approach to events that may be causing confusion for people coming from other languages. And yes, this is in the documentation.
Given a class structure like
Superclass
Subclass1 inherits from Superclass
Subclass2 inherits from Subclass1
And given that we are dealing with an object of Subclass2, then
Methods are resoved bottom up, ie., if Subclass2 implements Method1, then that will be called. Otherwise, if Subclass1 implements Method1, that will be called. Etc. There is a mechanism to allow method calls to percolate up, which is using Super.MethodName. Otherwise, execution stops at that level in the hierarchy.
For example, if both Subclass1 and Subclass2 implement Method1, then the method in Subclass2 will execute. Subclass1.Method1 will not execute unless Subclass2.Method1 calls Super.Method1.
Events are resolved top down. Superclass is checked first for the event. If it does not implement the event, then Subclass1 is checked. If it does not implement the event, then Subclass2 is checked. The first one that implements the event is the one that is executed.
For example, if Subclass1 and Subclass2 both implement Event1, then the code in Subclass1 will be executed. The code in Subclass2 will not be executed (and will cause a compiler error) unless the Event1 code in Subclass1 re-raises the event. In that case, the code in Subclass2 will also be executed.
My apologies for veering so off topic.
5 Likes
In order to be complete, and also pedantic, there is a whole 'nother layer of complexity when you introduce control parent/child relationships. This is typical of Key and Mouse events. Consider
Window1
Canvas1 on Window1
Both can react to KeyDown events. If the cursor is over Canvas1, then it’s event will be executed. If Canvas1.KeyDown does not return True, then Window1.KeyDown will also be executed after Canvas1.KeyDown finishes. However, if Canvas1.KeyDown returns True, then Window1.KeyDown will not be executed at all.
Note that the hierarchy of super/subclass events comes into play beforehand, so if Canvas1 is a subclass of SuperCanvas and Canvas1 doesn’t implement the event, but SuperCanvas does, then the True/False return from SuperCanvas.KeyDown determines whether Window1.KeyDown is called.
I was saying that using such choice of words trying to point to Class Hierarchy, confuses people, because a “Control” is a very specific kind of instance of a class that can be assigned to surfaces (as another control), views and windows. And such surface to where the control belongs is called the “parent” of the control, and in Xojo it determines its presentation z-order, and has nothing with class hierarchy, so it can confuse people.
You must distinguish between event handlers and event definitions.
You can only create event definitions in classes and subclasses andcan create an event DEFINITION anywhere in the inheritance chain. Then that event is available to the instances of that class or it’s subclasses. But once you implement the event that it’s…
Unless you have the event handler call an different event definition (though it can be named the same with the same signature) defined in a superclass… So you can cub and event up, but you define how the happens.
That is not built it… You can code it to that, but event mechanism only works by default within a single CLASS hierarchy.
-karen
I don’t understand that.
It’s only “idiot proof” because the exact condition(s) for when the Window.Opening event will fire have been explicitly defined to include “A window receives its Opening event after all of the controls have received their Opening events.” Without knowledge of that definition, the foregoing cannot be depended on.
All of Xojo’s specific event conditions give a natural rise to an expected order of events in a typical application, and I believe what the OP might be suggesting is that the documentation contain some consolidated discussion of the expected order of program flow that naturally arises from Xojo’s event conditions. Especially if that natural order might differ from one platform to another.
2 Likes
Again, correct event programming should be done with self-contained code in each event handler, which makes knowing the order in which events fire irrelevant.
1 Like
I agree, with the exception of the Open / Close events, which are well defined.
To help me understand, perhaps you could share a real world example of a typical Window.Opening event code that is completely immune to event firing order.
I really appreciate your additional thoughts here Tim and as I was copying some of your comments into my own personal notes, I discovered that I completely skipped over one of my other notes regarding this topic. Doh!
Not to discount Thom’s great work in documenting this, but Christian @ MBS went even deeper with a very thorough blog post a little over a year ago. I’ve updated the feedback ticket to include this link.
So this brings me back to why I originally created the feedback item. Maybe some of this information is well defined but clearly isn’t officially documented in a single spot within the Xojo documentation. That’s the crux of my request. Let’s get all of this info out of the forum, blog posts, people’s brains, etc. and instead get it where one might first look for it, the official Xojo documentation (e.g. single spot where you can do an in-depth document versus piecemeal across the documentation).
1 Like
Anything that is actually in Window.Opening should be safe, because all of the controls have been instantiated.
By “self-contained code”, in individual controls’ Opening events, I think Michel means that the code should not count on anything having been defined in another control’s Opening event, because the other control might not exist yet.
Before I understood this, many years ago, I remember the inconsistent results I got–inconsistent because sometimes I got lucky. 
Event order is documented in these 3 places.
https://documentation.xojo.com/api/user_interface/desktop/desktopwindow.html#desktopwindow-opening
These comments are also repeated in the corresponding event documentation. I fear that pulling all of that together in a single page would just create a page that is as difficult to find as most other things in the documentation. We’ll cheer when it is created and then nobody will ever read it again. I think the docs at the specific event definition are much more effective, but that’s just my personal take on it. And yes, I know you aren’t advocating moving that information.
I wonder if the current rash of Event Order posts was generated by a single post where the user had gotten Window Open and Control Open reversed in his head and complained about it. A quick peek at the Window Open documentation would have resolved it.
2 Likes
I’m fine with details of events being in their own docs sections, as you’ve point out is the case for application and window. I just wish they’d be a little more careful with wording, as the docs for Window.Opening say
“Controls also receive Opening events. A window receives its Opening event after all of the controls have received their Opening events.”
In my mind, an event is not received, it’s generated.
An overview article about event sequencing in general as requested by the OP would imo be appropriate for the User Guide, but I’m not sure that that is even supported anymore.
Yes, maybe I’m an overly visual person, but I’d be happy with some kind of simple diagram with some textual description to augment, similar to what Apple has done through the decades when documenting the responder chain and here’s another earlier example from them. But I’m not picky as I’d be thrilled if all of this was simply consolidated fully in text.
To be completely picky it is not “after all of the controls have received their Opening events” either, it is after each controls Opening event has completed. Window opening does not start until all control Openings have finished.
2 Likes
Agreed.