Using EmbeddedContainer

EmbeddedContainer is a class I added to LWUIT 1.5 without much fanfare out of a simple necessity, the problem is that this necessity existed only within the GUI builder and the class makes no sense outside of the context of the GUI builder. How do you document something like that???
The necessity came about due to Triplay's application designs (our original GUI builder beta site), their design was iPhone inspired and so it relied on tabs (iPhone style tabs at the bottom of the screen) where different features of the application are within a different tab.

This didn't mesh well with the LWUIT GUI builder navigation logic and so we needed to rethink some of it. I wanted to reuse GUI as much as possible while still enjoying the advantage of navigation being completely managed for me.
Android does this with Activities and the iPhone itself has a view controller, I don't like both approaches and think they both suck. The problem is that you have what is effectively two incompatible hierarchies to mix and match which is why Android needed to "invent" fragments and Apple can't mix view controllers within a single application.

The Component/Container hierarchy is powerful enough to represent such a UI but we needed a "marker" to indicate to the UIBuilder where a "root" component exists so navigation occurs only within the given "root". Here EmbeddedContainer comes into play, its a simple container that can only contain another GUI from the GUI builder. Nothing else. So we can place it in any form of UI and effectively have the UI change appropriately and navigation would default to "sensible values".

Navigation replaces the content of the embedded container, it finds the embedded container based on the component that broadcast the event. If you want to navigate manually just use the showContainer() method which accepts a component, you can give any component that is under the EmbeddedContainer you want to replace and LWUIT will be smart enough to replace only that component.

You can see an example of building a simple Tab based UI with the GUI builder and embedded container in the video above. The nice part about this is that this UI can be very easily refactored to provide a more traditional form based UI without duplicating effort and can be easily adapted to a more tablet oriented UI (with a side bar) again without much effort.