KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > debug > ui > IInstructionPointerPresentation


1 /*******************************************************************************
2  * Copyright (c) 2005, 2006 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 import org.eclipse.debug.core.model.IStackFrame;
14 import org.eclipse.jface.text.source.Annotation;
15 import org.eclipse.swt.graphics.Image;
16 import org.eclipse.ui.IEditorPart;
17
18 /**
19  * A debug model presentation may implement this interface to override
20  * standard annotations used to display instruction pointers for stack frames.
21  * <p>
22  * A client has several options when overriding default instruction pointer
23  * annotations, and the debug platform uses the following prioritized order
24  * when computing an annotation for a stack frame.
25  * <ol>
26  * <li>Specify the annotation object to use. This is done by returning a non-<code>null</code>
27  * value from <code>getInstructionPointerAnnotation(..)</code>.</li>
28  * <li>Specify an <code>annotationType</code> extension to use.
29  * This is done by returning a non-<code>null</code> value from
30  * <code>getInstructionPointerAnnotationType(..)</code>. When specified, the annotation
31  * type controls the image displayed via its associated
32  * <code>markerAnnotationSpecification</code>.</li>
33  * <li>Specify the image to use. This is done by returning a non-<code>null</code>
34  * value from <code>getInstructionPointerImage(..)</code>.</li>
35  * </ol>
36  * Additionally, when specifying an annotation type or image the text
37  * for the instruction pointer may be specified by returning a non-<code>null</code>
38  * value from <code>getInstructionPointerText(..)</code>.
39  * </p>
40  * <p>
41  * These methods are called when the debugger has opened an editor to display
42  * source for the given stack frame. The image will be positioned based on stack frame
43  * line number and character ranges.
44  * </p>
45  * <p>
46  * By default, the debug platform uses different annotations for top stack
47  * frames and non-top stack frames in a thread. The default platform annotations
48  * are contributed as <code>annotationType</code> extensions with
49  * the identifiers <code>IDebugUIConstants.ANNOTATION_INSTRUCTION_POINTER_CURRENT</code>
50  * and <code>IDebugUIConstants.ANNOTAION_INSTRUCTION_POINTER_SECONDARY</code>.
51  * </p>
52  * <p>
53  * Clients implementing a debug model presentation may also implement this interface.
54  * </p>
55  * @since 3.2
56  */
57 public interface IInstructionPointerPresentation extends IDebugModelPresentation {
58     /**
59      * Returns an annotation used for the specified stack frame in the specified
60      * editor, or <code>null</code> if a default annotation should be used.
61      *
62      * @param editorPart the editor the debugger has opened
63      * @param frame the stack frame for which the debugger is displaying
64      * source
65      * @return annotation or <code>null</code>
66      */
67     public Annotation getInstructionPointerAnnotation(IEditorPart editorPart, IStackFrame frame);
68     
69     /**
70      * Returns an identifier of a <code>org.eclipse.ui.editors.annotationTypes</code> extension used for
71      * the specified stack frame in the specified editor, or <code>null</code> if a default annotation
72      * should be used.
73      *
74      * @param editorPart the editor the debugger has opened
75      * @param frame the stack frame for which the debugger is displaying
76      * source
77      * @return annotation type identifier or <code>null</code>
78      */
79     public String JavaDoc getInstructionPointerAnnotationType(IEditorPart editorPart, IStackFrame frame);
80     
81     /**
82      * Returns the instruction pointer image used for the specified stack frame in the specified
83      * editor, or <code>null</code> if a default image should be used.
84      * <p>
85      * By default, the debug platform uses different images for top stack
86      * frames and non-top stack frames in a thread.
87      * </p>
88      * @param editorPart the editor the debugger has opened
89      * @param frame the stack frame for which the debugger is displaying
90      * source
91      * @return image or <code>null</code>
92      */
93     public Image getInstructionPointerImage(IEditorPart editorPart, IStackFrame frame);
94     
95     /**
96      * Returns the text to associate with the instruction pointer annotation used for the
97      * specified stack frame in the specified editor, or <code>null</code> if a default
98      * message should be used.
99      * <p>
100      * By default, the debug platform uses different images for top stack
101      * frames and non-top stack frames in a thread.
102      * </p>
103      * @param editorPart the editor the debugger has opened
104      * @param frame the stack frame for which the debugger is displaying
105      * source
106      * @return message or <code>null</code>
107      */
108     public String JavaDoc getInstructionPointerText(IEditorPart editorPart, IStackFrame frame);
109 }
110
Popular Tags