Desktop Container

Benefits

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

Reusable Controls

Since a Container 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 itself also makes it easy to encapsulate any specific methods or properties that are needed to tie all the controls together.

Using Desktop Containers

Custom Controls

Even more generically, you can create your own custom controls using a Container. 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 can be easily reused in all your projects.

Simplify Layouts

Use a Container 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 Containers, 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 Containers, one for each area of the user interface.

You may then find that your window layout will instead have just a few Containers 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 Containers 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 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 to the new tab page.

Layout

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

Dynamic Controls

When you click on a Container 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.

You have two ways to add a Container 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 Container itself is not visible in your running app. Your app only see the controls on the Container and not the Container itself.

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

In addition to adding Containers to Windows, Containers can be added to other Containers.

Window with Container in a Page Panel

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

Methods

EmbedWithin

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

EmbedWithinPanel

Allows you to add a Container 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 to add all the user interface controls to the page.

Usage in Code

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

Adding Containers at Run-time

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

The following code in the Opening event handler of a Window adds a Container 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 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 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 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 that has been added to a layout cannot have its containing controls modified on the layout. You have to go back to the Container and change the controls using its Layout Editor.

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

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

Example Projects

These Container sample projects are included with Xojo:

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

UserGuide