Technical Q&A QA1215

Do I have to call CreateRootControl after creating my window?

Q: Do I have to call CreateRootControl after creating my window?

A: It depends on which system you're running and what you want to do in the window.

With the advent of the new High Level Toolbox in Mac OS 8.x, and later on in Mac OS 9.x, you had to create a root control, using CreateRootControl, if you wished to use embedding controls (tabs, groups, etc.) or specific controls such as the listbox or the databrowser.

With the advent of Mac OS X 10.0 and 10.1, you no longer had to create the root control yourself since the High Level Toolbox was doing it for you automatically as soon as the first control was created in the window. You could leave, in your source code, the CreateRootControl call after creating the window since, although now useless, it was benign.

With the advent of Mac OS X 10.2, this API now matters again.

If you create a compositing window (kWindowCompositingAttribute), you are most likely going to embed your controls (or rather HIViews) in the content view of your window, and in that case, you do not need to have a root control so you don't need to call CreateRootControl.

If you create a non-compositing window and wish to use embedding controls (tabs, groups, etc.) or specific controls such as the listbox or the databrowser, then you still need a root control. If you create controls in your window with the CreateFooControl APIs and pass a valid window parameter, then a root control will be automatically created for you, as in the past, so you don't need to call CreateRootControl yourself. But, if you take advantage of the new way of creating controls, ie. passing NULL as window parameter for later embedding, be very careful that, at some point, you call CreateRootControl and embed your control hierarchy in that root control. Do not attempt to embed your control hierarchy in the content view returned by HIViewFindByID + kHIViewWindowContentID as this is not supported and may or may not work in the present or the future.

When compositing is off, the root control of a window is not the same entity as the content view of that window.
When compositing is on, they are the same entity (as a convenience for developers).

[Nov 12 2002]