platform-ui-home/object-aware-contributions/objCont.htm

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (download) (as text) (annotate)
Fri Jun 11 15:12:05 2004 UTC (5 years, 5 months ago) by dwilson
Branch: MAIN
Changes since 1.1: +105 -58 lines 
Update for new format for object contributions

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Untitled Document</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body>
<h1>Content Sensitive Object Contributions</h1>
<p><em>Last modified June 10, 2004</em></p>
<p>Context menus for some applications have previously only been able to exclude 
  some menu options based on peripheral information known about the resources 
  selected (the number of resources selected, the physical name of the file, the 
  type of the resource, etc.). There are some cases where a restricted amount 
  of information known about the contents of the resource would significantly 
  reduce unusable options from the menus. Consider XML files as a good example 
  of where such information would be useful. There are numerous situations where 
  an action is applicable for one type of XML file but not another. For example, 
  some XML files contain Ant scripts. The action &quot;Run Ant...&quot; makes 
  sense in its context menu. But this action is not applicable to an XML file 
  used to define a plug-in.</p>
<p>The notion of a content type has been added to Eclipse. A new extension point, 
  org.eclipse.core.runtime.contentTypes allows plug-ins to contribute to the Platform 
  content type catalog. Further, classes called Content Type Describers have been 
  added.</p>
<p>Initially, two content describers will be supported: BinarySignatureDescriber 
  and XMLRootElementContentDescriber. Eclipse developers may create their own 
  content describers. The Platform Plug-in Developer Guide (Programmer's Guide 
  -&gt; Runtime overview -&gt; Content types) describes this in more detail.</p>
<h3>XMLRootElementContentDescriber</h3>
<p>It will now be possible to define object contributions which are specific to 
  an XML file with a given top level tag or which specify a given DTD. To do this, 
  define an extension to the org.eclipse.core.runtime.contentTypes extension point 
  with a describer class of XMLRootElementContentDescriber and parameters indicating 
  the top level tag name or the dtd name as follows:</p>
<pre>   &lt;extension
       point=&quot;org.eclipse.core.runtime.contentTypes&quot;&gt;
       &lt;content-type
           id=&lt;id&gt;
           name=&lt;name&gt; 	
           base-type=&quot;org.eclipse.core.runtime.xml&quot;&gt;
           &lt;describer class=&quot;org.eclipse.core.runtime.content.XMLRootElementContentDescriber&quot;&gt;
               &lt;parameter name=&quot;element&quot; value=<em>tagValue</em> /&gt;
           &lt;/describer&gt;
       &lt;/content-type&gt;
   &lt;/extension&gt;</pre>
or 
<pre>   &lt;extension
       point=&quot;org.eclipse.core.runtime.contentTypes&quot;&gt;
       &lt;content-type
           id=&lt;id&gt;
           name=&lt;name&gt; 	
           base-type=&quot;org.eclipse.core.runtime.xml&quot;&gt;
           &lt;describer class=&quot;org.eclipse.core.runtime.content.XMLRootElementContentDescriber&quot;&gt;
               &lt;parameter name=&quot;dtd&quot; value=<em>dtdValue</em> /&gt;
           &lt;/describer&gt;
       &lt;/content-type&gt;
    &lt;/extension&gt;</pre>

<blockquote>
  <p><font size="3">where <em>tagValue</em> represents the name of the top level 
    tag to match and</font></p>
  <p><font size="3"><em>dtdValue</em> represents the name of the DTD as seen in 
    the XML file.</font></p>
</blockquote>
<p><font size="3">Consider the following object contribution in a plugin.xml file:</font></p>
<pre>   &lt;extension
       point=&quot;org.eclipse.core.runtime.contentTypes&quot;&gt;
       &lt;content-type 
           id=&quot;topElementContentType&quot;
           name=&quot;Tests top-level element recognition&quot; 	
           base-type=&quot;org.eclipse.core.runtime.xml&quot;
           priority=&quot;high&quot;&gt;
           &lt;describer class=&quot;org.eclipse.core.runtime.content.XMLRootElementContentDescriber&quot;&gt;
               &lt;parameter name=&quot;element&quot; value=&quot;myTag&quot; /&gt;
           &lt;/describer&gt;
       &lt;/content-type&gt;
   &lt;/extension&gt;

   &lt;extension
       point=&quot;org.eclipse.core.runtime.contentTypes&quot;&gt;
       &lt;content-type 
           id=&quot;dtdContentType&quot;
           name=&quot;Tests dtd element recognition&quot; 	
           base-type=&quot;org.eclipse.core.runtime.xml&quot;
           priority=&quot;high&quot;&gt;
           &lt;describer class=&quot;org.eclipse.core.runtime.content.XMLRootElementContentDescriber&quot;&gt;
               &lt;parameter name=&quot;dtd&quot; value=&quot;myDTD.xml&quot; /&gt;
           &lt;/describer&gt;
       &lt;/content-type&gt;
   &lt;/extension&gt;
</pre>
<pre>   &lt;extension point=&quot;org.eclipse.ui.popupMenus&quot;&gt;
       &lt;objectContribution
           id=&quot;org.eclipse.ui.examples.objectContributions&quot;
           objectClass=&quot;org.eclipse.core.resources.IFile&quot;
           nameFilter=&quot;*.xml&quot;&gt;
           &lt;visibility&gt;
               &lt;or&gt;
                   &lt;objectState
                       name=&quot;contentTypeId&quot;
                       value=&quot;org.eclipse.ui.examples.topElementContentType&quot;/&gt;
                   &lt;objectState
                       name=&quot;contentTypeId&quot;
                       value=&quot;org.eclipse.ui.examples.dtdContentType&quot;/&gt;
               &lt;/or&gt;
           &lt;/visibility&gt;
           &lt;action id=&quot;org.eclipse.ui.examples.objectContributions.action1&quot;
               label=&quot;%PopupMenus.action&quot;
               icon=&quot;icons/ctool16/openbrwsr.gif&quot;
               menubarPath=&quot;additions&quot;
               class=&quot;org.eclipse.ui.examples.objectContributions.PopupMenuActionDelegate&quot;
               enablesFor=&quot;1&quot;&gt;
           &lt;/action&gt;
       &lt;/objectContribution&gt;
   &lt;/extension&gt;</pre>
<p>This will make action1 visible for any IFile with a name matching *.xml provided 
  it contains myTag as the top level XML tag or it uses the DTD called myDTD.xml. 
  So the following XML files will match:</p>
<blockquote> 
  <pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;myTag
  id=&quot;org.eclipse.ui.workbench&quot;
  name=&quot;%pluginName&quot;
  version=&quot;3.0.0&quot;
  provider-name=&quot;%providerName&quot;
  class=&quot;org.eclipse.ui.internal.WorkbenchPlugin&quot;&gt;
&lt;/myTag&gt;</pre>
<p>Or</p>
  <pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE Book SYSTEM &quot;myDTD.xml&quot;&gt;
&lt;fragment
   id=&quot;org.eclipse.ui.workbench&quot;
   name=&quot;%pluginName&quot;
	version=&quot;3.0.0&quot;
	provider-name=&quot;%providerName&quot;
	class=&quot;org.eclipse.ui.internal.WorkbenchPlugin&quot;&gt;
	&lt;runtime&gt;
	   &lt;library name=&quot;workbench.jar&quot;&gt;
	      &lt;export name=&quot;*&quot;/&gt;
		  &lt;packages prefixes=&quot;org.eclipse.ui, org.eclipse.jface&quot;/&gt;
	   &lt;/library&gt;
	&lt;/runtime&gt;
&lt;/fragment&gt;
</pre>
</blockquote>
<h3>BinarySignatureDescriber</h3>
The BinarySignatureDescriber is a content describer to detect a specified binary 
'signature' at a given offset within a file. This describer is used in the same 
fashion as the XMLRootElementContentDescriber with the exception that it takes 
parameters &quot;signature&quot;, &quot;offset&quot; and &quot;required&quot; 
instead of &quot;element&quot; or &quot;dtd&quot;. The Javadoc for BinarySignatureDescriber 
gives complete details on this content describer's class usage. 
</body>
</html>