Themes

Identifier:
org.eclipse.ui.themes

Since:
3.0

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 entities. Themes allow applications to selectively override default color and font specifications for particular uses.

Configuration Markup:

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

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!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 component authors to contribute to existing themes.



<!ELEMENT themeElementCategory (description?)>

<!ATTLIST themeElementCategory

id       CDATA #REQUIRED

parentId IDREF #IMPLIED

class    CDATA #IMPLIED

label    CDATA #IMPLIED>

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



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

<!ATTLIST colorDefinition

id           CDATA #REQUIRED

label        CDATA #REQUIRED

defaultsTo   CDATA #IMPLIED

value        CDATA #IMPLIED

categoryId   IDREF #IMPLIED

colorFactory CDATA #IMPLIED

isEditable   (true | false) >

A symbolic color definition.



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

<!ATTLIST fontDefinition

id         CDATA #REQUIRED

label      CDATA #REQUIRED

value      CDATA #IMPLIED

categoryId IDREF #IMPLIED

defaultsTo CDATA #IMPLIED

isEditable (true | false) >

A symbolic font definition.



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

<!ATTLIST colorOverride

id           IDREF #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. The colors that are defined by workbench are:



<!ELEMENT fontOverride (fontValue*)>

<!ATTLIST fontOverride

id    IDREF #REQUIRED

value CDATA #IMPLIED>

Allows overriding of fonts defined in fontDefinition elements. These fonts will be applied when the theme is in use. The fonts that are defined by workbench are:



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



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



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



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



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



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 foreground 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 an instance of org.eclipse.ui.themes.IThemeManager that 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 foreground) and the inactive part (background gradient parts and foreground). 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, 2013 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