# Control Templates

[Control Templates](../../.././gacui/kb/ctemplates.md) offer customization of control appearances.

## Theme Name

A theme name is:
- An enum item in **(vl::)presentation::theme::ThemeName**, which could also be an argument in some control constructors.
- A property in in **(vl::)presentation::theme::ThemeTemplates**, which defines [default control templates](../../.././gacui/kb/dtemplates.md) for controls whose **ControlTemplate** property is **empty**. In documents for [each controls](../../.././gacui/components/controls/home.md), the **Template Name** record indicates the correct theme name for this control, and the **Template Tag** record indicates the correct control template tag for this control.

For any control template **\<X/\>**, its full class name is **(vl::)presentation::presentation::templates::GuiX**.

Multiple control themes could share the same control template class. Multiple controls could share the same control theme.
- These control themes are actually the same control class, like **\<CheckBox/\>** and **\<RadioButton/\>**.
- The derived control class has no extra visual or layout feature, like **\<Window/\>** and **\<Popup/\>**.
- The derived control class expresses the same UI concept, only with more programming features, like **\<TextList/\>** and **\<BindableTextList/\>**. It is very common to implement a control template using its derived control template class. For example, **\<RibbonTabTemplate/\>** is also a legal control template class for **\<Tab/\>**, because it inherits from **\<TabTemplate/\>**. In the default GacUI control template **DarkSkin**, **\<Tab/\>** and **\<RibbonTab/\>** looks exactly the same, there is no reason to write two control template implementations.

### The Window Theme name

**Window** theme name is special, it points to the following theme names in different condition:
- **CustomFrameWindow**, when **ThemeProperties::PreferCustomFrameWindow** is **true** or **null**.
- **SystemFrameWindow**, when **ThemeProperties::PreferCustomFrameWindow** is **false**.

In hosted mode, non-main windows must use a window template that offers custom frame (**CustomFrameEnabled** is **true**).

## Control Templates

Some control themes are for a specific part of a control. For example, **CheckTextListItem** and **RadioTextListItem** are two item background themes, controls will be created with these themes when a **\<TextList/\>** is assigned **Check** or **Radio** view, to create a check box or radio button put before a list item.

Here are a full list of these control themes:
- **ShortcutKey**: Labels indicates the **ALT** key sequence to focus or execute a control, when a window has the **ALT** key pressed, and is waiting for a complete key sequence.
- **Tooltip**: A theme for the system created **\<Popup/\>** to display the **TooltipControl** property for a control.
- **ListItemBackground**: Item background for all list items, to render the **Selected** state, when a **DisplayItemBackground** is **true** (by default) for the list control.
- **TreeItemExpander**: Triangle buttons before a tree view item, to render the **Expanded** state, when there is not customized item template assigned to the list control.
- **CheckTextListItem**: Check boxes before a list item in **\<TextList/\>** or **\<BindableTextList/\>** when switched to the **Check** view.
- **RadioTextListItem**: Radio buttons before a list item in **\<TextList/\>** or **\<BindableTextList/\>** when switched to the **Radio** view.
- **RibbonGalleryItemList**: A theme for the list control in the drop down menu from **\<RibbonGallery/\>**.

Here are all predefined control templates and their control themes:
- **<ControlTemplate/>`missing document: /gacui/components/ctemplates/ControlTemplate.html`**: CustomControl, GroupBox, MenuBar, MenuSplitter, ToolstripToolBar, ToolstripToolBarInMenu, ToolstripSplitter, ToolstripSplitterInMenu, RibbonSplitter, RibbonToolstripHeader
  - **<LabelTemplate/>`missing document: /gacui/components/ctemplates/LabelTemplate.html`**: Label, ShortcutKey
  - **<DocumentLabelTemplate/>`missing document: /gacui/components/ctemplates/DocumentLabelTemplate.html`**: SinglelineTextBox, DocumentLabel, DocumentTextBox
  - **<WindowTemplate/>`missing document: /gacui/components/ctemplates/WindowTemplate.html`**: Window, Tooltip
    - **<MenuTemplate/>`missing document: /gacui/components/ctemplates/MenuTemplate.html`**: Menu
      - **<RibbonToolstripMenuTemplate/>`missing document: /gacui/components/ctemplates/RibbonToolstripMenuTemplate.html`**: RibbonToolstripMenu
  - **<ButtonTemplate/>`missing document: /gacui/components/ctemplates/ButtonTemplate.html`**: Button
    - **<SelectableButtonTemplate/>`missing document: /gacui/components/ctemplates/SelectableButtonTemplate.html`**: ListItemBackground, TreeItemExpander, CheckTextListItem, RadioTextListItem, CheckBox, RadioButton
      - **<ToolstripButtonTemplate/>`missing document: /gacui/components/ctemplates/ToolstripButtonTemplate.html`**: MenuBarButton, MenuItemButton, ToolstripButton, ToolstripDropdownButton, ToolstripSplitButton, RibbonSmallButton, RibbonSmallDropdownButton, RibbonSmallSplitButton, RibbonLargeButton, RibbonLargeDropdownButton, RibbonLargeSplitButton
        - **<ListViewColumnHeaderTemplate/>`missing document: /gacui/components/ctemplates/ListViewColumnHeaderTemplate.html`**
        - **<ComboBoxTemplate/>`missing document: /gacui/components/ctemplates/ComboBoxTemplate.html`**: ComboBox
          - **<DateComboBoxTemplate/>`missing document: /gacui/components/ctemplates/DateComboBoxTemplate.html`**: DateComboBox
  - **<ScrollTemplate/>`missing document: /gacui/components/ctemplates/ScrollTemplate.html`**: HScroll, VScroll, HTracker, VTracker, ProgressBar
  - **<ScrollViewTemplate/>`missing document: /gacui/components/ctemplates/ScrollViewTemplate.html`**: ScrollView
    - **<DocumentViewerTemplate/>`missing document: /gacui/components/ctemplates/DocumentViewerTemplate.html`**: MultilineTextBox, DocumentViewer
    - **<ListControlTemplate/>`missing document: /gacui/components/ctemplates/ListControlTemplate.html`**
      - **<TextListTemplate/>`missing document: /gacui/components/ctemplates/TextListTemplate.html`**: TextList, RibbonGalleryItemList
      - **<ListViewTemplate/>`missing document: /gacui/components/ctemplates/ListViewTemplate.html`**: ListView
      - **<TreeViewTemplate/>`missing document: /gacui/components/ctemplates/TreeViewTemplate.html`**: TreeView
  - **<TabTemplate/>`missing document: /gacui/components/ctemplates/TabTemplate.html`**: Tab
    - **<RibbonTabTemplate/>`missing document: /gacui/components/ctemplates/RibbonTabTemplate.html`**: RibbonTab
  - **<DatePickerTemplate/>`missing document: /gacui/components/ctemplates/DatePickerTemplate.html`**: DatePicker
  - **<RibbonGroupTemplate/>`missing document: /gacui/components/ctemplates/RibbonGroupTemplate.html`**: RibbonGroup
  - **<RibbonIconLabelTemplate/>`missing document: /gacui/components/ctemplates/RibbonIconLabelTemplate.html`**: RibbonIconLabel, RibbonSmallIconLabel
  - **<RibbonButtonsTemplate/>`missing document: /gacui/components/ctemplates/RibbonButtonsTemplate.html`**: RibbonButtons
  - **<RibbonToolstripsTemplate/>`missing document: /gacui/components/ctemplates/RibbonToolstripsTemplate.html`**: RibbonToolstrips
  - **<RibbonGalleryTemplate/>`missing document: /gacui/components/ctemplates/RibbonGalleryTemplate.html`**: RibbonGallery
    - **<RibbonGalleryListTemplate/>`missing document: /gacui/components/ctemplates/RibbonGalleryListTemplate.html`**: RibbonGalleryList

## Properties

All control templates has three kinds of properties:
- **Input Property**: Such property is assigned by the control, to communicate with the item template.
- **Output Property**: Such property is assigned by the item template, to communicate with the control.
- **Exchange Property**: Such property is assigned by both the item template and the control, to communicate with each other.

Properties of **GuiTemplate** are all **input property**:
- **Font**: Always sync to the **Font** property of the control.
- **Context**: Always sync to the **Context** property of the control.
- **VisuallyEnabled**: Always sync to the **VisuallyEnabled** property of the control.
- **Text**: Always sync to the **Text** property of the control.

