Before we get into actual usage, it's best to understand the problem TrueWindow is designed to solve, and that problem is interacting with the parent window of a control. Every RectControl and ContainerControl has a Window property which provides you with the parent Window of that item. But when you're nesting ContainerControls, the issue becomes more complex since ContainerControl is a subclass of Window. Because the problem only appears when nesting ContainerControls, and ContainerControl is a Professional Edition feature, you will need a copy of REALbasic Professional Edition or a trial version to follow along.
We're going to do something very simple to demonstrate how this works. We'll create a PushButton subclass that displays a message containing the window's title. But first, we'll do it "wrong" to demonstrate the benefit of TrueWindow.
Start a new project. Create a subclass of PushButton called MyPushButton. Double-click it and in the action event, enter
Your subclass is done for now. Now, create a ContainerControl called ButtonView. Double-click it, and place a MyPushButton on it. You may give it a caption and place it however you like, that's not important to this tutorial.
Now, open Window1, and place a ButtonView on the window. You should see your button you just setup in the last step. Again, position it however you like. Title Window1 "Hello World". Now run the project and click your button. If all went according to plan, you should see an empty dialog appear.
Since ContainerControl is a Window, when MyPushButton calls Me.Window it gets the instance of the ContainerControl, then grabs that container's title - which we never set and the user never sees.
This is where TrueWindow comes in handy. It will return the topmost window regardless of the level of nested ContainerControls. So change MyPushButton's Action event to:
Now run the project again. This time when you click the button, you'll see the window's title. Excellent! The MyPushButton subclass will function equally well placed directly on Window1, since TrueWindow always returns the topmost Window, even if no nesting has occurred.
There are other uses for TrueWindow as well. If you're designing a custom control based on Canvas and need to fill the background to match the window it's on, TrueWindow is perfect for this:
If Me.TrueWindow.HasBackColor Then
G.ForeColor = Me.TrueWindow.BackColor
G.ForeColor = FillColor
You could also use it to display a sheet on the parent window of a ContainerControl without knowing which window it'll be embedded on:
Dim MySheet As New MySampleSheetWindow
So there you have it. TrueWindow makes it easier for control subclasses to interact with their “real” (from a user’s perspective) parent window without worrying about how the class will be used.