Chapter 3. Text labels


Bi-directional labels
#include <x/w/label.H>

x::w::label s=factory->create_label("Hello world");

create_label() creates a simple widget, a x::w::label, that displays text. The first parameter to create_label() is actually a x::w::text_param object. An explicitly-constructed x::w::text_param gives the ability of using custom fonts and colors for the new label. Labels use a default font and color, if not specified in the x::w::text_param.

\n characters in the text string create labels with multiple lines. create_label() takes an optional second parameter which is a x::w::label_config that configures the label widget's appearance. x::w::label_config's alignment value specifies formatting of labels with have multiple lines of text:


Align all lines in the label on the left margin.


Center all the lines.


Align all lines against their right margin.

Sometimes it's desirable to explicitly set the alignment even for labels with just a single line of text. Normally widgets get automatically sized for their content, but it's possible that a container adjusts the label to a wider size that it needs, due to other elements in the container. The alignment setting ends up governing where the text gets padded.

The alignment value is std::optional. An unspecified value defaults to the label's text direction (x::w::halign::left if the label contains left-to-right text and x::w::halign::right if the label contains right-to-left text).

Bi-directional labels

The label's text rendering direction comes from x::w::label_config's direction setting:


Draw this label as left-to-right text.


Draw this label as right-to-left text.

x::w::bidi::automatic (default)

Draw this label according to the default direction of its text according to the Unicode bi-directional algorithm.

x::w::label_config's default settings have the following results:

  • The label direction gets set based on its text. This uses the Unicode bi-directional algorithm to pick the first character in the label that has a strong left-to-right or right-to-left rendering indication.

  • The label's alignment gets set based on its direction.

Labels without any strong left-to-right or right-to-left characters default their direction that's heuristically derived from the locale.


Executables that link with LibCXXW automatically load the default environment locale, i.e.:

setlocale(LC_ALL, "");

It is not necessary to do this explicitly, this is done by automatically, by default.