Chapter 3. Text labels

Index

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:

x::w::halign::left

Align all lines in the label on the left margin.

x::w::halign::center

Center all the lines.

x::w::halign::right

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:

x::w::bidi::left_to_right

Draw this label as left-to-right text.

x::w::bidi::right_to_left

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.

Note

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.