appearances
Prev Appendix B. LibCXXW theme files Next

appearances

Creating custom appearance objects

Each appearance creates a custom appearance object. uigenerator3.C creates a checkbox with a custom visual appearance. The default checkbox image gets replaced with a chevron that alternates between pointing left and right, with a large, blocky input focus frame around it.

uigenerator3.xml

<?xml version="1.0" encoding="utf-8"?>
<theme version="1"
       xmlns:xi="http://www.w3.org/2003/XInclude">

  <dim id="cell-padding">20</dim>

  <color id="focusoff">
    <r>.8</r>
    <g>.8</g>
    <b>.2</b>
  </color>

  <color id="focuson1">
    <r>.2</r>
    <g>.2</g>
    <b>.8</b>
  </color>

  <color id="focuson2">
    <r>.2</r>
    <g>.8</g>
    <b>.2</b>
  </color>

  <border id="custom-focusoff">
    <color>focusoff</color>
    <width>1</width>
    <height>1</height>
  </border>

  <border id="custom-focuson" from="custom-focusoff">
    <color>focuson1</color>
    <color2>focuson2</color2>
    <dash>1</dash>
  </border>

  <appearance id="custom-checkbox-focus-border" type="focus_border">
    <focusoff_border>custom-focusoff</focusoff_border>
    <focuson_border>custom-focuson</focuson_border>
  </appearance>

  <appearance id="custom-checkbox" type="image_button">
    <images>
      <reset />
    </images>

    <focus_border>custom-checkbox-focus-border</focus_border>

    <images>scroll-left1</images>
    <images>scroll-right1</images>

  </appearance>

  <layout id="main-window-grid" type="grid">

    <padding>
      <row>0</row>
      <side>top</side>
      <padding>cell-padding</padding>
    </padding>
    <padding>
      <row>0</row>
      <side>bottom</side>
      <padding>cell-padding</padding>
    </padding>

    <padding>
      <col>0</col>
      <side>left</side>
      <padding>cell-padding</padding>
    </padding>
    <padding>
      <col>1</col>
      <side>right</side>
      <padding>cell-padding</padding>
    </padding>
    <valign>
      <row>0</row>
      <valign>middle</valign>
    </valign>
    <append_row>
      <name>main-window-contents</name>
    </append_row>
  </layout>

  <factory id="main-window-contents" type="grid">
    <element>
      <name>checkbox</name>
    </element>
    <element>
      <name>label</name>
    </element>
  </factory>

</theme>

Each appearance must have a unique id and a valid type. The first occurence of an appearance with a designated id takes effect, and subsequent appearances with the same id get ignored.

Creating and using appearance objects

auto generator=x::w::const_uigenerators::create("uigenerator3.xml");

// ...

factory->create_checkbox(generator->lookup_appearance("custom-checkbox"));

A generator's lookup_appearance returns an appearance object specified by its “id”. This theme file creates an appearance object named “custom-checkbox”, and lookup_appearance() returns it. This gets passed to a factory's create_checkbox() that takes an optional appearance object as a parameter, and this sets the new checkbox's appearance using the specified appearance object.

lookup_appearance() returns a generatic x;::w::const_appearance object from which all appearance objects get derived from. The following table lists all appearance object classes and the types which create them.

appearance 's optional from attribute specifies another, “parent” appearance that this appearance gets based from. The following table lists all available appearance types, and the resulting appearance object class. from specifies either:

  • The id of another, parent appearance object.

  • One of the built-in themes from the following table. The default built-in theme gets used when a from parent does not get specified.

type="type"

Appearance object

Built-in themes

book

x::w::const_book_appearance

  • theme (default)

bookpage

x::w::const_bookpage_appearance

  • theme (default)

button

x::w::const_button_appearance

  • normal_theme (default)
  • default_theme

color_picker

x::w::const_color_picker_appearance

  • theme (default)

combobox

x::w::const_combobox_appearance

  • theme (default)

date_input_field

x::w::const_date_input_field_appearance

  • theme (default)

element_popup

x::w::const_element_popup_appearance

  • theme (default)

file_dialog

x::w::const_file_dialog_appearance

  • theme (default)

focus_border

x::w::const_focus_border_appearance

  • theme (default)
  • none_theme
  • menu_theme
  • thin_theme
  • visible_thin_theme
  • slider_theme
  • combobox_button_theme
  • input_field_theme
  • list_theme
  • visible_list_theme
  • attached_button_theme
  • dateeditbutton_theme

font_picker

x::w::const_font_picker_appearance

  • theme (default)

frame

x::w::const_frame_appearance

  • theme (default)

generic_window

x::w::const_generic_window_appearance

  • main_window_theme (default)
  • date_input_field_theme
  • list_contents_theme
  • combobox_theme
  • tooltip_theme

image_button

x::w::const_image_button_appearance

  • checkbox_theme (default)
  • radio_theme
  • item_theme
  • book_left_theme
  • book_right_theme
  • date_popup_left_theme
  • date_popup_right_theme

input_field

x::w::const_input_field_appearance

  • theme (default)
  • editable_combobox_theme

item_button

x::w::const_item_button_appearance

  • theme (default)

item_layout

x::w::const_item_layout_appearance

  • theme (default)

list

x::w::const_list_appearance

  • theme (default)
  • list_pane_theme
  • table_theme
  • table_pane_theme

main_window

x::w::const_main_window_appearance

  • theme (default)

pane

x::w::const_pane_appearance

  • theme (default)
  • focusable_list
  • file_dialog_dir
  • file_dialog_file

pane_layout

x::w::const_pane_layout_appearance

  • theme (default)

peephole

x::w::const_peephole_appearance

  • theme (default)

popup_list

x::w::const_popup_list_appearance

  • menu_theme (default)
  • submenu_theme
  • contextmenu_theme

print_dialog

x::w::const_print_dialog_appearance

  • theme (default)

progressbar

x::w::const_progressbar_appearance

  • theme (default)

scrollbar

x::w::const_scrollbar_appearance

  • theme (default)

scrollbar_images

x::w::const_scrollbar_images_appearance

  • horizontal1 (default)
  • horizontal2
  • vertical1
  • vertical2

table

x::w::const_table_appearance

  • theme (default)

tooltip

x::w::const_tooltip_appearance

  • tooltip_theme (default)
  • static_tooltip_theme
  • direction_tooltip_theme

tooltip_border

x::w::const_tooltip_border_appearance

  • theme (default)
  • nonalpha_theme

Contents of appearances in theme files

<appearance id="custom-checkbox-focus-border" type="focus_border">
  <focusoff_border>custom-focusoff</focusoff_border>
  <focuson_border>custom-focuson</focuson_border>
</appearance>

Each appearance contains elements whose names match the names of the fields in the corresponding appearance classes. A focus border appearance object contains two fields, focusoff_border, and focuson_border, and an appearance with a focus_border type specifies their values accordingly.

If not explicitly specified, the value of each field comes from the parent appearance, explicitly specified by the from attribute, or the default parent.

The fields get specified as follows:

std::string fields 
<images>scroll-left1</images>

std::string values get specified directly.

x::w::border_arg fields 
<focuson_border>custom-focuson</focuson_border>

x::w::border_arg values are are ids of borders in the theme file. They may also reference border ids from the current display theme, but this is not documented. A more future-proof way of borrowing a standard theme border is to use one of the built-in theme appearance objects as the parent object and not changing the existing x::w::border_arg value.

x::w::color_arg and x::w::text_color_arg fields 
<color2>focuson2</color2>

Color values are are ids of colors in the theme file. They may also reference border ids from the current display theme, but this is not documented. A more future-proof way of borrowing a standard theme border is to use one of the built-in theme appearance objects as the parent object and not changing the existing color value.

Color values may also reference standard HTML 3.2 colors.

x::w::dim_arg fields 
  <dim id="cell-padding">20</dim>


  <scroll_button_height>cell-padding</scroll_button_height>

x::w::dim_arg values are are ids of dims in the theme file. They may also reference border ids from the current display theme, but this is not documented. A more future-proof way of borrowing a standard theme border is to use one of the built-in theme appearance objects as the parent object and not changing the existing x::w::dim_arg value.

x::w::font_arg fields 
<shortcut_font>small</shortcut_font>

x::w::font_arg values are are ids of fonts in the theme file. They may also reference border ids from the current display theme, but this is not documented. A more future-proof way of borrowing a standard theme border is to use one of the built-in theme appearance objects as the parent object and not changing the existing x::w::font_arg value.

See the section called “Specifying fonts” for more information on how to define custom fonts.

x::w::halign fields 
<horizontal_alignment>center</horizontal_alignment>

These fields contain x::w::halign values.

x::w::scrollbar_visibility fields 
<pane_scrollbar_visibility>automatic</pane_scrollbar_visibility>

These elements contain x::w::scrollbar_visibility values.

x::w::text_param fields 
<font id="ok_font">
  <family>liberation mono</family>
  <point_size>18</point_size>
</font>


<ok_label>${font:ok_font}Ok</ok_label>

These fields contain x::w::text_param values.

x::w::valign fields 
<vertical_alignment>middle</vertical_alignment>

These fields contain x::w::valign values.

x::w::const_type_apperance fields 
<focus_border>custom-checkbox-focus-border</focus_border>

std::optional and std::vector fields

<images>
  <reset />
</images>

<images>scroll-left1</images>
<images>scroll-right1</images>

A new appearance element starts with the values of all fields copied from its parent appearance object, then each value in the appearance element replaces the value of the corresponding field in the new appearance object. Some fields in appearance objects are std::optional or std::vectors. Each value of a std::vector field gets appended to a vector. Specifying a reset for a std::vector value erase()s its existing contents. Specifying a reset for a std::optional reset()s its value.

New values of a std::vector usually gets specified after reseting the values it inherited from its parent appearance object.

Prev Up Next
Scroll-bar element widgets Table Of Contents cxxwcreator tool