Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

Platform Plug-in Developer Guide Reference Extension Points Reference

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* , 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 component 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 IDREF #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 #REQUIRED

label CDATA #REQUIRED

defaultsTo CDATA #IMPLIED

value CDATA #IMPLIED

categoryId IDREF #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 separated 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 on workbench startup.
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 IDREF #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 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:

org.eclipse.jface.preference.JFacePreference.ERROR_COLOR
org.eclipse.jface.preference.JFacePreference.HYPERLINK_COLOR
org.eclipse.jface.preference.JFacePreference.ACTIVE_HYPERLINK_COLOR

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 override colors that do not exist in the base theme although this practice is not recommended. In effect, such overrides will have behavior similar to colorDefinitions 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 separated 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 on workbench startup.

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

org.eclipse.jface.resource.JFaceResources.BANNER_FONT
org.eclipse.jface.resource.JFaceResources.DIALOG_FONT
org.eclipse.jface.resource.JFaceResources.HEADER_FONT
org.eclipse.jface.resource.JFaceResources.TEXT_FONT

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 override fonts that do not exist in the base theme although this practice is not recommended. In effect, such overrides will have behavior similar to fontDefinitions 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.

If this value is not specified the default font will be used

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

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 separated 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 on workbench startup.

<!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 IDREF #REQUIRED

presentationId IDREF #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 - the id of the category to bind
presentationId - the id of the presentation to bind to

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>

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, 2006 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 https://www.eclipse.org/legal/epl-v10.html