Other values in theme files
Prev Appendix B. LibCXXW theme files Next

Other values in theme files

Values for various properties of supported theme widgets and appearance objects directly translate to the values of various LibCXXW data types.

x::w::halign values

<halign>left</halign>

An x::w::halign value is one of: “left”, “center”, “right”, or “fill”.

x::w::valign values

<valign>middle</valign>

An x::w::valign value is one of: “top”, “middle”, “bottom”, or “fill”.

x::w::scrollbar_visibility values

<horizontal_visibility>automatic</horizontal_visibility>

An x::w::scrollbar_visibility value is one of: “never”, “always”, “automatic”, or “automatic_reserved”.

x::w::text_param values

<label type='theme_text'>${context:file-dialog}Directory:</label>

The content of elements that specify values of x::w::text_param fields is x::w::theme_text-formatted text with references to colors and fonts defined in the theme file or the default display theme.

Using gettext with x::w::text_param values

If the generator object has an optionally attached message catalog, each text label in the theme file gets looked up in the message catalog. The type attribute gets ignored when creating widget from the theme file, and it serves to mark translatable text in the theme file, such as the one in the label element. gettext tools know look only for translatable strings in C/C++ source, so LibCXXW provides an XML stylesheet that creates a pseudo-C/C++ file that does not get compiled, but it contains translatable strings that gettext's msgfmt picks up and adds to the message catalog template.

The extract-theme-text.xsl file in LibCXXW's theme directory is a stylesheet that generates pseudo C/C++ source containing text from any element with a type="theme_text" in a theme file: 

xsltproc .../extract-theme-text.xsl theme.xml >strings.C

If theme.xml's contents include the above example, the resulting strings.C has the following contents: 

_("${context:file-dialog}Directory:")

This gets picked up by msgfmt and included with the rest of the application's translatable strings. LibCXXW provides automake macros to automate this process. In the Makefile.am: 

$(call EXTRACT_THEME_TEXT_GEN,strings.C,theme.xml)

This creates Makefile rules that automatically build strings.C from theme.xml. The EXTRACT_THEME_TEXT_GEN macro comes from LibCXXW's @LIBCXXW_AM@ framework. 

#include <x/locale.H>
#include <x/messages.H>

// ...
auto utf8_locale=x::locale::base::utf8();

auto catalog=x::messages::create("app", utf8_locale);

auto generators=x::w::const_uigenerators::create("uigenerator4.xml", catalog);

Specifying the optional x::messages parameter, when creating a generator object, attaches a message catalog to the generator generator. The message catalog should explicitly use a UTF-8 x::locale so that the translated messages get directly converted to Unicode.

x::w::shortcut values

<shortcut type='theme_text'>${context:settings-dialog}Alt-G</shortcut>

An x::w::shortcut contains text that uses the same x::w::theme_text formatting as x::w::text_param values, except fonts, colors, and other visual markup references are not allowed, of course. Keyboard shortcuts frequently associate with buttons and labels that have translatable text; with distinct ${context}s that discriminate different text. This allows the associated keyboard shortcuts also have translated text; and if the main button or label's text gets translated, the associated keyboard shortcut gets revised accordingly.

Note

This means that a shortcut must use “$$” to refer to the $ key.

The specified shortcut text selects the most appropriate x::w::shortcut constructor: a single character, or one or more modifiers, like “Ctrl” or “Alt”, followed by a single character, or “Fn” (function key), or a recognized special key (like “Left” or “Del”).

x::w::list_item_param values

   <items>

      <name>option_1</name>
      <shortcut>Alt-1</shortcut>
      <label type="theme_text">Option1</label>

      <separator />

      <name>option_2</name>
      <shortcut>Alt-2</shortcut>
      <label type="theme_text">Option1</label>

   </items>

List layout manager's methods that add new items to the selection list take a vector of x::w::list_item_param values. These various variant values get specified as follows:

label

A selection list text value, specified as a x::w::text_param value.

image

Specifies a selection list image icon value.

<separator/>

Inserts a list separator, a x::w::separator value in the x::w::list_item_paramvector.

shortcut

Specifies a keyboard x::w::shortcut value.

inactive_shortcut

An inactive keyboard shortcut value.

hierindent

Specifies an identation level of this list item in a hierarchical list: 

<hierindent>1</hierindent>
name

Specifies an identifier for the following list item.

<menuoption/>

<menuoption/> inserts a x::w::menuoption menu attribute, in a x::w::list_item_param. In a type=“menubar” factorys that creates menu items.

menugroupname</menugroup>

Inserts a x::w::menuoption with an initialized radio_groupname.

<selected/>

Inserts a a x::w::selected value in the x::w::list_item_paramvector.

submenu

Specifies a “submenu” menu attribute, in a type=“menubar” factorys that creates menu items. The following example in uigenerator6.C creates a “Recent” submenu: 

<name>file_recent</name>
<submenu>
  <append_items>
    <items>
       <name>file_recent_file_1</name>
       <label type="theme_text">File 1</label>
       <name>file_recent_file_2</name>
       <label type="theme_text">File 2</label>
     </items>
  </append_items>
</submenu>
<label type="theme_text">Recent</label>

submenu, like any other item attribute, must precede it's list item, in this case a “Recent” label. submenu contains an inner list of type=“list” layout elements; typically an append_items that defines the submenus's contents.

All x::w::list_item_param values must follow the same relative ordering rules as actual x::w::list_item_param values, specifically: all attributes of a list item (such as its keyboard shortcut or its hierarchy indentation value) must precede their label or the image list item value. This includes the name identifier. All attributes must precede the first label or the image list item value in a multi-column list.

List item names

   <items>

      <name>option_1</name>
      <shortcut>Alt-1</shortcut>
      <label type="theme_text">Option1</label>

      <separator />

      <name>option_2</name>
      <shortcut>Alt-2</shortcut>
      <label type="theme_text">Option1</label>

   </items>


x::w::uielements elements;

layout->generate("main-window-grid",
                 generator, elements);

x::w::listitemhandle h=elements.get_listitemhandle("option_1");

A name element in a x::w::list_item_param values list is not an actual x::w::list_item_param value. This element assigns an identifer to the following list item. After generating the contents of a selection list, After the widgets get generated, get_listitemhandle() retrieves a x::w::listitemhandle for the new list item specified by its name.

name element values are optional, but if specified every item in a x::w::list_item_param values list must have a name.

List item status_change callbacks

   <items>

      <status_change>file_new_callback</status_change>
      <label>New</label>
      <status_change>file_open_callback</status_change>
      <label>Open</label>

   </items>


x::w::uielements elements;

elements.list_item_status_change_callbacks.emplace(
        "file_new_callback",
        (ONLY IN_THREAD, const w::list_item_status_info_t &info)
        {
            file_new(IN_THREAD);
        });

    factories.list_item_status_change_callbacks.emplace(
        "file_open_callback",
        (ONLY IN_THREAD, const w::list_item_status_info_t &info)
        {
            if (std::holds_alternative<x::w::initial>(info.trigger))
                return;
            file_open(IN_THREAD);
        });


layout->generate("main-menu",
                 generator, elements);

A status_change element in a x::w::list_item_param values list installs a list status change callback (status change callbacks also report menu item selections). x::w::uielements's list_item_status_change_callbacks member is an associate container that maps callback names to the actual callbacks.

status_change retrieves the callback, by name, and puts it into the x::w::list_item_param.

x::w::bidi values

<element id="title">
    <label type="theme_text">Lorem Ipsum</label>
    <options>
        <direction>right_to_left</direction>
    </options>
</element>

An x::w::bidi value is one of “automatic”, “left_to_right” or “right_to_left”.

x::w::bidi_format values

<element id='name'>
  <config>
    <directional_format>always</directional_format>
  </config>
</element>

An x::w::bidi_format value is one of “none”, “automatic” or “embedded”.

Prev Up Next
fonts Table Of Contents containers