Source code: jpicedt/graphic/view/View.java
1 /*
2 View.java - February 9, 2002 - jPicEdt 1.3.2, a picture editor for LaTeX.
3 Copyright (C) 1999-2002 Sylvain Reynal
4
5 Département de Physique
6 Ecole Nationale Supérieure de l'Electronique et de ses Applications (ENSEA)
7 6, avenue du Ponceau
8 F-95014 CERGY CEDEX
9
10 Tel : +33 130 736 245
11 Fax : +33 130 736 667
12 e-mail : reynal@ensea.fr
13 jPicEdt web page : http://www.jpicedt.org
14
15 This program is free software; you can redistribute it and/or
16 modify it under the terms of the GNU General Public License
17 as published by the Free Software Foundation; either version 2
18 of the License, or any later version.
19
20 This program is distributed in the hope that it will be useful,
21 but WITHOUT ANY WARRANTY; without even the implied warranty of
22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 GNU General Public License for more details.
24
25 You should have received a copy of the GNU General Public License
26 along with this program; if not, write to the Free Software
27 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 */
29
30 package jpicedt.graphic.view;
31
32 import jpicedt.graphic.model.Element;
33 import jpicedt.graphic.model.Drawing;
34 import jpicedt.graphic.PECanvas;
35 import jpicedt.graphic.event.PEMouseEvent;
36 import jpicedt.graphic.event.DrawingEvent;
37
38 import java.awt.*;
39 import java.awt.geom.*;
40
41 /**
42 * a View is a graphic representation of a Element. It can be rendered using its paint method.<p>
43 * It provides the following capabilities :
44 * <ul>
45 * <li> Rendering to a Graphics2D context ;
46 * <li> Highlighting ;
47 * <li> Mouse-hit testing (this is here because a View knows better than anyone how a graphic element
48 * looks on the screen, and thus where a user should click to select/whatever/... the element). As
49 * an example, consider a rectangle element that has a "fill-color" attribute set to "green", and
50 * is indeed paint in green in some View implementation, but is transparent in some other implementation :
51 * then when the user clicks inside the rectangle, the first implementation should return a "hit-ok" while
52 * the second should return "hit-fail", even thought the element has the same "fill-color" in both cases.
53 * <br>
54 * View implementation that don't implement editing capabilities may have their hitTest method
55 * simply return null to signal that every mouse-click just fails, and their paintHighlighter do
56 * nothing.
57 * <br>
58 * [pending] Another approach would be to define aka EditableView interface inheriting from View and adding
59 * the afore-mentioned methods ?
60 * </ul>
61 * View's belong to a tree that has the same structure as the associated Drawing, since each View is
62 * attached to an element in the tree.
63 */
64 public interface View {
65
66 /** a constant that can be used as the max. distance b/w a point and a mouse click that triggers
67 * a selection (in mm !!!) */
68 double CLICK_DISTANCE = 1.0;
69
70 /** a constant that can be used as the size of selection-barbells (in pixels !!!) */
71 double BARBELL_SIZE = 4.0;
72
73 /**
74 * @return the element the View is responsible for rendering
75 */
76 Element getElement();
77
78 /**
79 * set the element the View is responsible for rendering
80 */
81 void setElement(Element e);
82
83 ///////////////////////////////////////////////////////////////////
84 //// tree-structure
85 ///////////////////////////////////////////////////////////////////
86
87 /**
88 * Returns the parent of the view, as given by the tree-structure the associated graphic element belongs to.
89 * @return the parent, null if none
90 */
91 View getParentView();
92
93
94 /**
95 * Fetches the container hosting the view. This is useful for
96 * things like scheduling a repaint, finding out the host
97 * components font, etc.
98 *
99 * @return the container, null if none
100 */
101 PECanvas getContainer();
102
103 /**
104 * Fetches the ViewFactory implementation that is feeding the view hierarchy.
105 * @return the factory, null if none
106 */
107 ViewFactory getViewFactory();
108
109 /**
110 * Fetch a Graphics for rendering. This can be used to determine
111 * font characteristics, and will be different for a print view
112 * than a component view.
113 *
114 * @since 1.3
115 */
116 Graphics getGraphics();
117
118 /**
119 * Fetches the model associated with the view.
120 * @return the view model, null if none
121 */
122 Drawing getDrawing();
123
124
125 //////////////////////////////////////////////
126 /// EVENT HANDLING
127 /////////////////////////////////////////////
128
129 /**
130 * Give notification from the model that a change occured for an element this view is responsible
131 * for rendering.
132 */
133 void changedUpdate(DrawingEvent.EventType eventType);
134
135 ////////////////////////////////////////////////////////
136 //// PAINT
137 ////////////////////////////////////////////////////////
138
139 /**
140 * ask the hosting container to repaint itself
141 * @param clip the clip rectangle in model-coordinate
142 */
143 void repaint(Rectangle2D clip);
144
145 /**
146 * Render the View of the underlying Element to the given graphic context.
147 * @param allocation the graphic clip
148 * @since jPicEdt 1.3.2
149 * @author Sylvain Reynal
150 */
151 void paint(Graphics2D g, Rectangle2D allocation);
152
153
154 /**
155 * Render the Highlighter to the given graphic context.<br>
156 * @param allocation current clipping
157 * @param scale The current scale factor from model to screen for the Graphics2D context ;
158 * this may be used to scale down line thickess, etc... so that lines/rectangle/... appear with the
159 * same lenght on the screen whatever the scale factor that's set to the graphic context.
160 * @since jPicEdt 1.3.2
161 * @author Sylvain Reynal
162 */
163 void paintHighlighter(Graphics2D g, Rectangle2D allocation, double scale);
164
165 /**
166 * @return the bounds of this View<br>
167 * This will determine the clipping rectangle passed as a parameter to repaint, and may
168 * include the highlighter's bounds as well.
169 * <br>
170 * @since jPicEdt 1.3.2
171 * @author Sylvain Reynal
172 */
173 Rectangle2D getBounds();
174
175
176
177
178 /////////////////////////////////////////////////////
179 //// MOUSE
180 /////////////////////////////////////////////////////
181
182 /**
183 * Current implementation returns a HitInfo.Point if highlighter is visible and a click
184 * occured on an end-point ; return null otherwise.
185 * @return a HitInfo corresponding to the given mouse-event
186 * @param isHighlightVisible whether the receiver should include the highlighter shapes (e.g. end-points)
187 * in the click-sensitive area.
188 * @since jPicEdt 1.3.2
189 * @author Sylvain Reynal
190 */
191 HitInfo hitTest(PEMouseEvent e, boolean isHighlightVisible);
192 }
193