Tech Tip: The Document Outline Window

Have you gone crazy trying to find a UI control on the Visual Studio design canvas?

Have you been swearing like a stevedore trying to get your docking straight only to find that the control you set to “Dock Fill” is obscuring the control set to “Dock Top”?

Clear the blue air with a little-known feature of Visual Studio 2005 called “Document Outline”.

Don’t do that!

I see a lot of customer code. Usually the code is in big trouble by the time it crosses my desk. More often than not, there’s an “Everything-but-the-kitchen-sink” form with a gazillion panels, tab controls, tabs, grids, and everything else loaded into a single class.

Visual Studio can take a minute just to present the Form and, once shown, it takes agonizing seconds to shift focus from one control to the next.

One more change and the control falls completely apart. You get the “White Screen of Death” and you are pretty sure you just saw your career implode along with the application.

There is only one answer. Don’t do this!  You have to learn to break this Form up into component parts and re-assemble them programmatically with controller logic.

That is a lesson for another day. But it bears mentioning here that the “Document Outline”, which we’ll describe in a moment, may just save you one more time.

Enough said. Let’s take the better behaved cases.

The Docking Problem 

Imagine a simple UserControl with a BindingNavigator and a SplitContainer. The BindingNavigator should dock to the top and the SplitContainer should dock fill below.

We don’t remember in which order we dragged them on to the canvas but we know that it looks like this:

It seems ok but, when you run, the application displays:

That’s wrong. We want to see:

The SplitContainer is docking under the BindingNavigator, hiding the “Id” and other controls at the top of the view – the view the program dropped into the upper panel.

Our traditional recourse is to return to the Visual Studio design view and fumble around with the “Properties” window which looks like so:

The list is in alphabetical order, making it easy to find a control by name (which you generally don’t know) but impossible to tell how the controls relate to each other.

It is amazingly difficult to discover the type of a control. The display of the type name in the ComboBox gets about half way through the namespace before the window edge cuts it off and there is no way to scroll over to reveal the meat of the type name. There’s no tool tip. And the body of the Properties grid doesn’t tell you the type either.

Docking Rules

We read somewhere that docking should be done “inside out” meaning that the “first” control should “Dock Fill” and the later controls should spiral out from there. The last control mentioned docks to the outer edge of the Form.

That’s a great rule but (a) we never remember if the rule is “inside out” or “outside in”, (b) we can’t see the order of the controls as they are now, and (c) we have no easy or obvious way to change the control order even if I knew what it was.

Eventually we dive into the designer file, into the InitializeComponent() method with the ominous warning “do not modify the contents of this method with the code editor.”

There we fiddle around in the section that adds the SplitContainer and BindingNavigator to the UserControl.

We see

this.Controls.Add(this.mNavigator);

this.Controls.Add(this.mPageSplitContainer);

We reverse them to get

this.Controls.Add(this.mPageSplitContainer);

this.Controls.Add(this.mNavigator);

Run again and it works!

We heave a sigh of relief and move on to your next challenge, grateful that we were only working with two docked controls and not an “Everything-but-the-kitchen-sink” Form.

It still took us twenty minutes and a pint of Pepto Bismal. There has to be a better way.

There Is a Better Way

Visual Studio 2005 introduced the “Document Outline” window to cope with these problems. You probably never noticed it because (a) it’s hidden in the menu structure and (b) the name of the window is fiendishly obscure.

You’ll find it in “View | Other Windows |  Document Outline”. The key chord “Ctrl + Alt + T” pops it up as well.

While this window is great for navigating deeply nested HTML and ASPX pages, today we'll see how it can be lifesaver for visual control developers. Here it is describing our example control:

We immediately see that the BindingNavigator appears “before” the SplitContainer. That must be the problem. We simply drag-and-drop the SplitContainer above the BindingNavigator and, voila.

Note that the parts – Panel1 and Panel2 and anything they contain – travel along with it.

We compile and run to confirm that this fixes the problem.

We don’t have to remember whether we design docking controls inside-out or outside-in. It’s all very clear right on the canvas.

Additional Benefits

Permit me a few more observations.

·       We see the complete hierarchy of the controls on the form.

·       We can expand and collapse the tree view to see how controls nest.

·       We can learn the type of any control.

·       We can hide (or show) the usually-uninformative namespace.

·       The icons help us quickly identify a control of interest.

·       We can find a control that is hiding under another control.

·       We can drag one more controls into any container control (e.g. a panel).

That last feature alone is balm for that most irritating of operations – moving Labels and TextBoxes into their proper containers.

Take Away

Do yourself a huge favor and make the “Document Outline” a permanent fixture among the windows pinned to your Visual Studio shell. You will be ever so glad you did.