Tuesday, March 3, 2009

REALbasic's New TrueWindow Feature

REALbasic 2009r1 adds a new TrueWindow property to any subclass of Window and RectControl. If you use any control subclasses, design your own Canvas-based custom controls, or use ContainerControls, TrueWindow just might make your life easier.

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.


Mike Bailey said...

Thanks. This feature is going to come in handy!

Anonymous said...

We could always find the base window by looping and testing if the parent window is a container control or not however this is more convenient for sure!

But (and there is always a but! ;) ) most of the time I found myself finding the true window it was when I wanted to calculate the top and left value of a RectControl, either in "true window" coordinates, or in Screen coordinates to pop up a menu for a custom control.

In that case I still have to walk up the potential container hierarchy, so It would be nice if we could get the true window coordinates as well as the true window.

- Karen

Thom McGrath said...

You're right, this can be done using existing REALbasic code. But I don't think anybody will argue with features that allow you to write less code.

File a feature request, I could see adding Screen* and Window* properties.

MBedesem said...


Is this feature described in the documentation, or will it be?

In general, what is the best way to learn about changes and new facilities in more detail than is in the release notes?


Thom McGrath said...

The Language Reference does include a quick description of the TrueWindow property.