Themes

org.eclipse.ui.themes

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.

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

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST theme

id   CDATA #REQUIRED

name CDATA #REQUIRED>

A collection of font, color and data overrides. Such a collection may be used to alter the appearance of the workbench.



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



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



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



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



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



<!ELEMENT description (#CDATA)>

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



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



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



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

      
</fontDefintion>

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

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.

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.