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.

<halign>left</halign>

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

<valign>middle</valign>

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

<horizontal_visibility>automatic</horizontal_visibility>

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

<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.

<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).

   <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/>

Specifies a menuoption menu attribute, in a type=menubar factorys that creates menu items.

menuoption

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_element() 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.