IDebugModelPresentation


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.debug.ui;
12  
13  
14  import org.eclipse.debug.core.model.IValue;
15  import org.eclipse.jface.viewers.ILabelProvider;
16  import org.eclipse.swt.graphics.Image;
17  
18  /**
19   * A debug model presentation is responsible for providing labels, images,
20   * and editors associated with debug elements in a specific debug model.
21   * Extensions of type <code>org.eclipse.debug.ui.debugModelPresentations</code> implement
22   * this interface. Generally, a debug model implementation will also provide a
23   * debug model presentation extension to render and display its elements. A debug
24   * model presentation is registered for a specific debug model, and is responsible
25   * for the presentation elements defined/implemented by that model.
26   * <p>
27   * A debug model presentation extension is defined in <code>plugin.xml</code>.
28   * Following is an example definition of a debug model presentation extension.
29   * <pre>
30   * &lt;extension point="org.eclipse.debug.ui.debugModelPresentations"&gt;
31   *   &lt;debugModelPresentation 
32   *      id="com.example.debugModelIdentifier"
33   *      class="com.example.ExamplePresentation"
34   *      detailsViewerConfiguration="com.example.ExampleSourceViewerConfiguration"&gt;
35   *   &lt;/debugModelPresentation&gt;
36   * &lt;/extension&gt;
37   * </pre>
38   * The attributes are specified as follows:
39   * <ul>
40   * <li><code>id</code> specifies the identifier of the debug model this presentation
41   *    is responsible for. Corresponds to the model identifier returned from a debug
42   *  element - see <code>IDebugElement.getModelIndentifier</code></li>
43   * <li><code>class</code> specifies the fully qualified name of the Java class
44   *   that implements this interface.</li>
45   * <li><code>detailsViewerConfiguration</code> optionally specifies the fully qualified name of the Java class
46   *   that is an instance of <code>org.eclipse.jface.text.source.SourceViewerConfiguration</code>.
47   *   When specified, the source viewer configuration will be used in the "details" area of the
48   *   variables and expressions view when displaying the details of an element from the
49   *   debug model associated with this debug model presentation. When unspecified,
50   *   a default configuration is used.</li>
51   * </ul>
52   * </p>
53   * <p>
54   * To allow for an extensible configuration, this interface defines
55   * a <code>setAttribute</code> method. The debug UI plug-in defines
56   * one presentation attribute:
57   * <ul>
58   *  <li><code>DISPLAY_VARIABLE_TYPE_NAMES</code> - This is a boolean attribute 
59   *     indicating whether variable elements should be rendered with the declared
60   *     type of a variable. For example, a Java debug model presentation would render
61   *     an integer as <code>"int x = 3"</code> when true, and <code>"x = 3"</code>
62   *     when false.</li>
63   * </ul>
64   * </p>
65   * <p>
66   * Clients may define new presentation attributes. For example, a client may wish
67   * to define a "hexadecimal" property to display numeric values in hexadecimal. Implementations
68   * should honor the presentation attributes defined by this interface where possible,
69   * but do not need to honor presentation attributes defined by other clients.
70   * To access the debug model presentation for a debug view, clients should use
71   * <code>IDebugView#getPresentation(String)</code>.
72   * </p>
73   * <p>
74   * Since 3.1, debug model presentations may optionally implement <code>IColorProvider</code>
75   * and <code>IFontProvider</code> to override default fonts and colors for debug elements. 
76   * </p>
77   * <p>
78   * Clients may implement this interface.
79   * </p>
80   * @see org.eclipse.debug.core.model.IDebugElement
81   * @see org.eclipse.jface.viewers.ILabelProvider
82   * @see org.eclipse.debug.ui.IDebugView
83   */
84  
85  public interface IDebugModelPresentation extends ILabelProvider, ISourcePresentation {
86      /** 
87       * Variable type names presentation property (value <code>"org.eclipse.debug.ui.displayVariableTypeNames"</code>).
88       * When <code>DISPLAY_VARIABLE_TYPE_NAMES</code> is set to <code>true</code>,
89       * this label provider should include the reference type of a variable  when rendering
90       * variables. When set to <code>false</code>, this label provider 
91       * should not include the reference type of a variable when rendering
92       * variables.
93       * @see #setAttribute(String, Object)
94       */
95      public final static String   DISPLAY_VARIABLE_TYPE_NAMES= IDebugUIConstants.PLUGIN_ID + ".displayVariableTypeNames"; //$NON-NLS-1$
96      /**
97       * Sets a presentation attribute of this label provider. For example,
98       * see the presentation attribute <code>DISPLAY_VARIABLE_TYPE_NAMES</code>
99       * defined by this interface.
100      *
101      * @param attribute the presentation attribute identifier
102      * @param value the value of the attribute
103      */
104     void setAttribute(String   attribute, Object   value);
105     /**
106      * Returns an image for the element, or <code>null</code> if a default
107      * image should be used.
108      *
109      * @param element the debug model element
110      * @return an image for the element, or <code>null</code> if a default
111      *    image should be used
112      * @see ILabelProvider
113      */
114     public Image getImage(Object   element);
115     /**
116      * Returns a label for the element, or <code>null</code> if a default
117      * label should be used.
118      *
119      * @param element the debug model element
120      * @return a label for the element, or <code>null</code> if a default
121      *    label should be used
122      * @see ILabelProvider
123      */
124     public String   getText(Object   element);
125     
126     /**
127      * Computes a detailed description of the given value, reporting
128      * the result to the specified listener. This allows a presentation
129      * to provide extra details about a selected value in the variable detail
130      * portion of the variables view. Since this can be a long-running operation,
131      * the details are reported back to the specified listener asynchronously.
132      * If <code>null</code> is reported, the value's value string is displayed
133      * (<code>IValue.getValueString()</code>).
134      * 
135      * @param value the value for which a detailed description
136      *  is required
137      * @param listener the listener to report the details to
138      *  asynchronously
139      * @since 2.0
140      */
141     void computeDetail(IValue value, IValueDetailListener listener);    
142 
143 }
144
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags