#
Themes

###### Identifier:

org.eclipse.ui.themes

###### Description:

This extension point is used to customize the appearance of the UI. It allows definition of color and font entities as well as theme entitities. Themes allow applications to selectivly override default color and font specifications for particular uses.

###### Configuration Markup:

<!ELEMENT extension (theme* , colorDefinition* , fontDefinition* , themeElementCategory* , data* , categoryPresentationBinding*)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

- point - a fully qualified identifier of the target extension point
- id - an optional identifier of the extension instance
- name - an optional name of the extension instance

<!ELEMENT theme (colorOverride* , fontOverride* , description? , data*)>

<!ATTLIST theme

id CDATA #REQUIRED

name CDATA #IMPLIED>

A collection of font, color and data overrides. Such a collection may be used to alter the appearance of the workbench. Many theme elements may exist with the same id. This allows compontent authors to contribute to existing themes.

- id - a unique name that will be used to identify this theme
- name - a translatable name of the theme to be presented to the user. At least one theme definition with any given id should contain this attribute.

<!ELEMENT themeElementCategory (description)>

<!ATTLIST themeElementCategory

id CDATA #REQUIRED

parentId CDATA #IMPLIED

class CDATA #IMPLIED

label CDATA #IMPLIED>

A logical grouping of theme element definitions. This category may include colors and fonts.

- id - the id for this category
- parentId - the id of the parent category, if any.
- class - a class that implements `org.eclipse.ui.themes.IThemePreview`
- label - a translatable name of the theme element category to be presented to the user

<!ELEMENT colorDefinition (colorFactory? , colorValue* , description?)>

<!ATTLIST colorDefinition

id CDATA #IMPLIED

label CDATA #REQUIRED

defaultsTo CDATA #IMPLIED

value CDATA #IMPLIED

categoryId CDATA #IMPLIED

colorFactory CDATA #IMPLIED

isEditable (true | false) >

A symbolic color definition.

- id - a unique id that can be used to identify this color definition.
- label - a translatable name of the color to be presented to the user.
- defaultsTo - the id of another color definition that is the default setting for the receiver. When there is no preference for this color the color registry will have the value of defaultsTo set for it in the registry. Only one of `defaultsTo`, `value` or `colorFactory` may be defined.
- value - The default value of this color. The value may be specified in the following ways:
  - a String containing comma seperated integers in the form red,green,blue
  - a String that maps to an SWT color constant (ie: COLOR_RED).
  Only one of `defaultsTo`, `value` or `colorFactory` may be defined. If `value` is specified, additional value definitions may be specified on a per platform/windowing system basis via the `colorValue` element.
- categoryId - the optional id of the `themeElementCategory` this color belongs to.
- colorFactory - a class that implements `org.eclipse.ui.themes.IColorFactory`. This may be used instead of `value` to specify the default value of the color. Please be advised that this should be used with caution - usage of this attribute will cause plugin activation.
- isEditable - whether the user should be allowed to edit this color in the preference page. If this is `false` then the contribution is not shown to the user.

<!ELEMENT fontDefinition (fontValue* , description?)>

<!ATTLIST fontDefinition

id CDATA #REQUIRED

label CDATA #REQUIRED

value CDATA #IMPLIED

categoryId CDATA #IMPLIED

defaultsTo CDATA #IMPLIED

isEditable (true | false) >

A symbolic font definition.

- id - a unique name that can be used to identify this font definition.
- label - a translatable name of the font to be presented to the user.
- value -

  the font value. This is in the form: `fontname-style-height` where `fontname` is the name of a font, `style` is a font style (one of `"regular"`, `"bold"`, `"italic"`, or `"bold italic"`) and `height` is an integer representing the font height.

  Example: `Times New Roman-bold-36`.

  Only one (or neither) of `value` or `defaultsTo` may be used.

  If `value` is specified, additional value definitions may be specified on a per platform/windowing system basis via the `fontValue` element.
- categoryId - the optional id of the `themeElementCategory` this font belongs to.
- defaultsTo - the id of another font definition that is the default setting for the receiver. When there is no preference for this font the font registry will have the value of defaultsTo set for it in the registry.

  Only one (or neither) of `value` or `defaultsTo` may be used.

- isEditable - whether the user should be allowed to edit this color in the preference page. If this is `false` then the contribution is not shown to the user.

<!ELEMENT colorOverride (colorFactory? , colorValue*)>

<!ATTLIST colorOverride

id CDATA #REQUIRED

value CDATA #IMPLIED

colorFactory CDATA #IMPLIED>

Allows overriding of colors defined in `colorDefinition` elements. These colors will be applied when the theme is in use.

- id - a unique id that can be used to identify this color definition override. This should match an existing font identifier. Strictly speaking, you may ovverride colors that do not exist in the base theme although this practice is not recommended. In effect, such overrides will have behaviour similar to `colorDefinition`s that have `isEditable` set to `false`.
- value - the overriding value of this color. The value may be specified in the following ways:
  - a String containing comma seperated integers in the form red,green,blue
  - a String that maps to an SWT color constant (ie: COLOR_RED).
  Only one of `value` or `colorFactory` may be defined. Unlike a `colorDefinition`, you may not supply a `defaultsTo` for an override.
- colorFactory - a class that implements `org.eclipse.ui.themes.IColorFactory`. This may be used instead of `value` to specify the default value of the color. Please be advised that this should be used with caution - usage of this attribute will cause plugin activation.

<!ELEMENT fontOverride (fontValue*)>

<!ATTLIST fontOverride

id CDATA #REQUIRED

value CDATA #REQUIRED>

Allows overriding of fonts defined in `fontsDefinition` elements. These fonts will be applied when the theme is in use.

- id - a unique id that can be used to identify this font definition override. This should match an existing font identifier. Strictly speaking, you may ovverride fonts that do not exist in the base theme although this practice is not recommended. In effect, such overrides will have behaviour similar to `fontDefinition`s that have `isEditable` set to `false`.
- value -

  the overriding value of this font. This is in the form: `fontname-style-height` where `fontname` is the name of a font, `style` is a font style (one of `"regular"`, `"bold"`, `"italic"`, or `"bold italic"`) and `height` is an integer representing the font height.

  Example: `Times New Roman-bold-36`.

  `value` must be defined for a font override. Unlike a `fontDefinition`, you may not supply a `defaultsTo` for a `fontOverride`.

<!ELEMENT description (#PCDATA)>

A short description of the elements usage.

<!ELEMENT colorFactory (parameter*)>

<!ATTLIST colorFactory

class CDATA #REQUIRED

plugin CDATA #IMPLIED>

The element version of the `colorFactory` attribute. This is used when the colorFactory implements `org.eclipse.core.runtime.IExecutableExtension` and there is parameterized data that you wish used in its initialization.

- class - a class that implements `org.eclipse.ui.themes.IColorFactory`. It may also implement `org.eclipse.core.runtime.IExecutableExtension`.
- plugin - the identifier of the plugin that contains the class

<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name CDATA #REQUIRED

value CDATA #REQUIRED>

A parameter element to be used within the colorFactory element. This will be passed as initialization data to the colorFactory class.

- name - the parameter name
- value - the parameter value

<!ELEMENT data EMPTY>

<!ATTLIST data

name CDATA #REQUIRED

value CDATA #REQUIRED>

An element that allows arbitrary data to be associated with a theme or the default theme. This data may be gradient directions or percentages, labels, author information, etc.

This element has behaviour similar to definitions and overrides. If a key is present in both the default theme and an identified theme, then the identified themes value will be used when that theme is accessed. If the identified theme does not supply a value then the default is used.

- name - the data name,
- value - the data value

<!ELEMENT colorValue (colorFactory?)>

<!ATTLIST colorValue

os CDATA #IMPLIED

ws CDATA #IMPLIED

value CDATA #IMPLIED

colorFactory CDATA #IMPLIED>

This element allows specification of a color value on a per-platform basis.

- os - an optional os string to enable choosing of color based on current OS. eg: win32,linux
- ws - an optional os string to enable choosing of color based on current WS. eg: win32,gtk
- value - The default value of this color. The value may be specified in the following ways:
  - a String containing comma seperated integers in the form red,green,blue
  - a String that maps to an SWT color constant (ie: COLOR_RED).
  Only one of `value` or `colorFactory` may be defined.
- colorFactory - a class that implements `org.eclipse.ui.themes.IColorFactory`. This may be used instead of `value` to specify the value of the color. Please be advised that this should be used with caution - usage of this attribute will cause plugin activation.

<!ELEMENT fontValue EMPTY>

<!ATTLIST fontValue

os CDATA #IMPLIED

ws CDATA #IMPLIED

value CDATA #REQUIRED>

This element allows specification of a font value on a per-platform basis.

- os - an optional os string to enable choosing of font based on current OS. eg: win32,linux
- ws - an optional os string to enable choosing of font based on current WS. eg: win32,gtk
- value -

  the font value. This is in the form: `fontname-style-height` where `fontname` is the name of a font, `style` is a font style (one of `"regular"`, `"bold"`, `"italic"`, or `"bold italic"`) and `height` is an integer representing the font height.

  Example: `Times New Roman-bold-36`.

<!ELEMENT categoryPresentationBinding EMPTY>

<!ATTLIST categoryPresentationBinding

categoryId CDATA #REQUIRED

presentationId CDATA #REQUIRED>

This element allows a category to be bound to a specific presentation as described by the `org.eclipse.ui.presentationFactory` extension point. If a category has any presentation bindings then it (and it's children) is only configurable by the user if it is bound to the active presentation. This is useful for removing unused items from user consideration.

- categoryId -
- presentationId -

###### Examples:

The following is an example of several color and font definitions as well as a theme that overrides them.

       <extension point="org.eclipse.ui.themes">
          <themeElementCategory
           id="com.xyz.ThemeCategory"
           class="com.xyz.XYZPreview"
           label="XYZ Elements"/>
          <colorDefinition
            id="com.xyz.Forground"
            categoryId="com.xyz.ThemeCategory"
            label="XYZ Foreground Color"
            value="COLOR_BLACK">
             <!-- white should be used on GTK -->
             <colorValue
              value="COLOR_WHITE"
              os="linux"
              ws="gtk"/>
            <description>
            This color is used for the forground color of the XYZ plugin editor.
            </description>
          </colorDefinition>
          <colorDefinition
            id="com.xyz.Background"
            categoryId="com.xyz.ThemeCategory"
            label="XYZ Background Color">
            <colorFactory
             class="org.eclipse.ui.themes.RGBBlendColorFactory"
             plugin="org.eclipse.ui">
             <parameter
              name="color1"
              value="COLOR_WHITE"/>
             <parameter
              name="color2"
              value="COLOR_BLUE"/>
            </colorFactory>
            <!-- black should be used on GTK -->
            <colorValue
             value="COLOR_BLACK"
             os="linux"
             ws="gtk"/>
            <description>
            This color is used for the background color of the XYZ plugin editor.
            </description>
          </colorDefinition>
          <fontDefinition
            id="com.xyz.TextFont"
            categoryId="com.xyz.ThemeCategory"
            label="XYZ Editor Font"
            defaultsTo="org.eclipse.jface.textfont">
            <description>
            This font is used by the XYY plugin editor.
            </description>
          </fontDefinition>
          <data
           name="com.xyz.EditorMarginWidth"
           value="5"/>
          <theme
            id="com.xyz.HarshTheme"
            label="Harsh Colors for XYZ">
            <colorOverride
             id="com.xyz.Forground"
             value="COLOR_CYAN"/>
            <colorOverride
             id="com.xyz.Background"
             value="COLOR_MAGENTA"/>
          <data
               name="com.xyz.EditorMarginWidth"
               value="1"/>
          </theme>
       </extension>

###### API Information:

The `org.eclipse.ui.IWorkbench.getThemeManager()` provides `org.eclipse.ui.themes.IThemeManager`. This class may be used to obtain a named theme (by id, including the default theme which has an id of `IThemeManager.DEFAULT_THEME`) or the current theme. From an `org.eclipse.ui.themes.ITheme` you may obtain a `org.eclipse.jface.resources.ColorRegistry`, an `org.eclipse.jface.resources.FontRegistry` and the arbitrary data associated with a theme.

###### Supplied Implementation:

The workbench provides the font definitions for the text, dialog, banner, header and part title fonts. it also supplies color definitions for the hyperlink, active hyperlink, error, active part (background gradient parts and forground) and the inactive part (background gradient parts and forground). The workbench also provides data constants for the title gradient percentages (active and inactive) and the gradient directions (active and inactive). The workbench does not provide any named themes.

Copyright (c) 2003, 2005 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html