Setting the border title

borderlayoutmanager.C creates two bordered elements. The one on the right has a title. A bordered widget 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 widget.

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

Without a title the border layout manager automatically installs a theme-specified background color for the widget 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 widget 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 widget's background color either.

Note

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

The established approach to modifying the contents of a bordered widget 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.