Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Plug-in Developer Guide
Previous Page Home Next Page

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


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire