Setting the border title

borderlayoutmanager.C creates two bordered elements. The one on the right has a title. A bordered element with a title requires some additional space, to make room for the title text, so borderlayoutmanager.C aligns both elements on their bottom margins, for an even look.

x::w::new_borderlayoutmanager nblm{
    (const x::w::factory &f)
         // ...

nblm.title("Hello world");

x::w::new_borderlayoutmanager's title is an initially empty x::w::text_param. A non-empty title creates a title for the bordered display element.

borderlayoutmanager.C's left bordered element does not have a title, unlike the the right bordered element. Besides the title, the two bordered elements have a slightly different visual apperance. The title-less bordered element has a slightly shaded, visually-highlighted background color.

Without a title the border layout manager automatically installs a theme-specified background color for the element in the border. Turn off this default behavior by setting the no_background flag in the x::w::new_borderlayoutmanager. This behavior gets automatically turned off when creating a border with a title, which is why the right bordered element has a plain background color. There's no explicit border drawn under the title, to serve as an explicit edge to the highlighted border. It would not look good, so the highlighted background does not get installed when the new border has a title.

blm->update_title("Lorem Ipsum");

The border layout manager's update_title() replaces the container's current title. The title should not be an empty string, and bordered containers that got created without a title should not use update_title to specify a title after their creation. Adding or removing a title requires resizing the container. This is because the title uses up. additional vertical real estate; and the border layout manager does not update the existing element's background color either.


An untitled border element's default background color gets set when the bordered element gets created. The border layout manager inherits from the utility singleton layout manager object, which implements methods for replacing the element in the container. The default bordered element's background color gets installed only in the border layout manager's container's initial element. The singleton layout manager's replace() should be considered as undocumented.

The established approach to modifying the contents of a bordered element is to use x::w::new_borderlayoutmanager's constructor's callback to create a discrete container, with a stock grid layout manager, and use the grid layout manager to control the contents inside the border. The page, book, or event pane layout managers are other available options.