UserGuide:Desktop Container Control

Benefits

There are many great reasons to use Container Controls in your projects instead of creating windows with lots and lots of controls.

Reusable Controls

Since a Container Control can be easily added to Windows, you can reuse these controls in multiple places without recreating the entire layout and any required code. The Container Control itself also makes it easy to encapsulate any specific methods or properties that are needed to tie all the controls together.

Using Desktop Container Controls

Custom Controls

Even more generically, you can create your own custom controls using Container Controls. Xojo includes an example project that demonstrates how to create an OKCancelContainer whose buttons are properly position themselves on Windows/Linux and macOS (where OK/Cancel typically appears as Cancel/OK). Such a Container Control can be easily reused in all your projects.

Simplify Layouts

Use a Container Control to simplify your Window layouts. Instead of adding dozens (or hundreds) of controls onto a Window, which makes it more complex and potentially adds lots of fragile dependencies, instead group your layout into multiple Container Controls, each having only the controls they need.

Most Window layouts have multiple areas that are mostly independent from each other. Consider a Mail app which typically has a section on the left with mailboxes, a section at the top with messages and a section at the bottom that shows the email message itself. This could easily be three Container Controls, one for each area of the user interface.

You may then find that your window layout will instead have just a few Container Controls on it and is now much easier to work with while at the same time benefitting from better code organization and data separation.

Managing Screen Layouts

Dynamic Window Layouts

Because Container Controls can also be added at run-time, you can use them to create flexible user interfaces. A common example of this is an interface that has a variable number of tabs, such as a web browser.

You can have a Container Control that consists of an HTML Viewer and a Text Field for the URL address. When the user chooses to add a new tab, you append the tab to the Tab Panel and then dynamically add the Container Control to the new tab page.

Layout

To use a Container Control on a window, you first have to add one to your project using the Insert ↠ Container Control menu from the Insert button or menu.

Dynamic Controls

When you click on a Container Control in the Navigator, a Layout Editor very similar to the Window Layout Editor appears. In this Layout Editor, you can add controls to the Container Control.

You have two ways to add a Container Control to your windows. First, you can drag it from the Navigator onto the Window Layout Editor. Or you can find it in the Library in the Project Controls section and drag it from there to the Window Layout Editor.

A ContainerControl itself is not visible in your running app. Your app only see the controls on the Container Control and not the Container Control itself.

Container Controls are commonly used to simplify window layouts. You can add Container Controls to a window as described above or dynamically at run-time.

In addition to adding Container Controls to Windows, Container Controls can be added to other Container Controls.

Window with Container Control in a Page Panel

Container Controls cannot be configured as UserGuide:Desktop Control Sets. You can use Control Sets within a Container Control.

Methods

EmbedWithin

Allows you to dynamically add a Container Control to a window, another Container Control or another control programmatically.

EmbedWithinPanel

Allows you to add a Container Control to a specific page in a Tab Panel or Page Panel. This is useful for app that contain a variable number of pages. You can add a page at run-time and then use a Container Control to add all the user interface controls to the page.

Usage in Code

You can add and remove Container Controls from your layouts are run-time.

Adding Containers at Run-time

The EmbedWithin method of a Container Control allow you to dynamically add a Container Control to a window, another Container Control or another control programmatically.

The following code in the Open event handler of a Window adds a Container Control to the window in the top left corner:

Var cc As New MyContainer
cc.EmbedWithin(Self, 0, 0)

EmbedWithinPanel Allows you to add a Container Control to a specific page in a Tab Panel or Page Panel. This is useful for app that contain a variable number of pages. You can add a page at run-time and then use a Container Control to add all the user interface controls to the page.

The following code adds a new tab to a Tab Panel and then adds a Container Control to it:

MainTab.AddPanel("New Tab")
Var tabNum As Integer
tabNum = MainTab.PanelCount - 1

Var cc As New MyContainer
cc.EmbedWithinPanel(MainTab, tabNum)

Removing Containers at Run-time

To remove a container at run-time, you need to call its Close method. However, you'll typically want to remove the container in a different part of code than where you created it. This means you'll need to keep a reference to it. In the examples above, the container is created using a local variable which goes away when the method (or event ends). To keep a reference, use a property instead of a local variable. For example, add the container like this:

// MainContainer is a property defined as:
// MainContainer As MyContainer
MainContainer = New MyContainer
MainContainer.EmbedWithin(Self, 0, 0)

Since saved the reference to the container in a property, you can now refer to it in another part of your code that can access the property (such as a different method or event on the window):

If MainContainer <> Nil Then
MainContainer.Close
End If

Subclassing

A Container Control that has been added to a layout cannot have its containing controls modified on the layout. You have to go back to the Container Control and change the controls using its Layout Editor.

If you want to add additional controls to a Container Control without modifying the original Container Control, create a new Container Control and add the first Container Control to it. There is no limit to the number of Container Controls you can embed in this manner.

You cannot subclass Container Controls created with the Layout Editor. However, you can create a class with methods and properties that Container Controls can inherit. To do so, create a new class (perhaps BaseContainer) with the properties and methods you want and set its Super to “ContainerControl”. Then, in the Container Controls you create change their Super from “ContainerControl” to the name of the class you created (BaseContainer). These Container Controls will now have access to the properties and methods from BaseContainer.

Example Projects

These Container Control sample projects are included with Xojo:

Examples/Desktop/ContainerControlExample
Examples/Desktop/DownloadContainer
Examples/Desktop/TabbedWebBrowser
Examples/Desktop/Custom Controls/OKCancelContainer

UserGuide

Desktop Container Control

From Xojo Documentation

Contents