Property Pages

org.eclipse.ui.propertyPages

This extension point is used to add additional property page for objects of a given type. Once defined, these property pages will appear in the Properties Dialog for objects of that type.

A property page is a user friendly way to interact with the properties of an object. Unlike the Properties view, which restricts the space available for editing an object property, a property page may benefit from the freedom to define larger, more complex controls with labels, icons, etc. Properties which logically go together may also be clustered in a page, rather than scattered in the property sheet. However, in most applications it will be appropriate to expose some properties of an object via the property sheet and some via the property pages.

Property pages are shown in a dialog box that is normally visible when the "Properties" menu item is selected on a pop-up menu for an object. In addition to the object class, the name filter can optionally be supplied to register property pages only for specific object types.

If these filtering mechanisms are inadequate a property page may use the filter mechanism. In this case the attributes of the target object are described in a series of key value pairs. The attributes which apply to the selection are type specific and beyond the domain of the workbench itself, so the workbench will delegate filtering at this level to the actual selection.

An action's enablement and/or visibility can be defined using the elements enablement and visibility respectively. These two elements contain a boolean expression that is evaluated to determine the enablement and/or visibility.

The syntax is the same for the enablement and visibility elements. Both contain only one boolean expression sub-element. In the simplest case, this will be an objectClass, objectState, pluginState, or systemProperty element. In the more complex case, the and, or, and not elements can be combined to form a boolean expression. Both the and, and or elements must contain 2 sub-elements. The not element must contain only 1 sub-element.

<!ELEMENT extension (page*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT page (filter* , keywordReference* , enablement?)>

<!ATTLIST page

id          CDATA #REQUIRED

name        CDATA #REQUIRED

icon        CDATA #IMPLIED

objectClass CDATA #IMPLIED

class       CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false)

category    CDATA #IMPLIED>


<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

This element is used to evaluate the attribute state of each object in the current selection. A match only if each object in the selection has the specified attribute state. Each object in the selection must implement, or adapt to, org.eclipse.ui.IActionFilter.



<!ELEMENT keywordReference EMPTY>

<!ATTLIST keywordReference

id CDATA #IMPLIED>

A reference by a property page to a keyword. See the keywords extension point.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element is used to define the enablement for the extension.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element is used to define the visibility for the extension.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean AND operation on the result of evaluating its two sub-element expressions.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean OR operation on the result of evaluating its two sub-element expressions.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean NOT operation on the result of evaluating its sub-element expressions.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

This element is used to evaluate the class or interface of each object in the current selection. If each object in the selection implements the specified class or interface, the expression is evaluated as true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

This element is used to evaluate the attribute state of each object in the current selection. If each object in the selection has the specified attribute state, the expression is evaluated as true. To evaluate this type of expression, each object in the selection must implement, or adapt to, org.eclipse.ui.IActionFilter interface.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

This element is used to evaluate the state of a plug-in. The state of the plug-in may be one of the following: installed (equivalent to the OSGi concept of "resolved") or activated (equivalent to the OSGi concept of "active").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

This element is used to evaluate the state of some system property. The property value is retrieved from the java.lang.System.



The following is an example of the property page definition: 

   
<extension point=
"org.eclipse.ui.propertyPages"
>
 
        
<page 
            id=
"com.xyz.projectPage"
 
            name=
"XYZ Java Properties"
 
            objectClass=
"org.eclipse.core.resources.IFile"
 
            class=
"com.xyz.ppages.JavaPropertyPage"
 
            nameFilter=
"*.java"
>
 
            
<filter name=
"readOnly"
 value=
"true"
/>
 
        
</page>
 
    
</extension>

The attribute class must specify a fully qualified name of the class that implements org.eclipse.ui.IWorkbenchPropertyPage.

Some objects provided by the workbench may have property pages registered. Plug-ins are allowed to add more property pages for these objects. Property pages are not limited to workbench resources: all objects showing up in the workbench (even domain specific objects created by the plug-ins) may have property pages and other plug-ins are allowed to register property pages for them.