replaced <code></code> with more concise {@code}
[idea/community.git] / platform / platform-impl / src / com / intellij / openapi / editor / impl / softwrap / SoftWrapPainter.java
1 /*
2  * Copyright 2000-2010 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.openapi.editor.impl.softwrap;
17
18 import org.jetbrains.annotations.NotNull;
19
20 import java.awt.*;
21
22 /**
23  * Defines contract for the service that manages soft wrap-related graphical effects.
24  * <p/>
25  * For example we may want to draw an arrow just before and after soft wrap-introduced line feed:
26  * <p/>
27  * <pre>
28  *     This is a long text &#xE48B;
29  *         &#xE48C;that is soft-wrapped
30  * </pre>
31  * <p/>
32  * Implementations of this interface are not obliged to be thread-safe.
33  *
34  * @author Denis Zhdanov
35  * @since Jul 1, 2010 5:02:37 PM
36  */
37 public interface SoftWrapPainter {
38
39   /**
40    * Asks to paint drawing of target type at the given graphics buffer at the given position.
41    *
42    * @param g             target graphics buffer to draw in
43    * @param drawingType   target drawing type
44    * @param x             target {@code 'x'} coordinate to use
45    * @param y             target {@code 'y'} coordinate to use
46    * @param lineHeight    line height used at editor
47    * @return              horizontal offset introduced to the given 'x' coordinate after target drawing painting
48    */
49   int paint(@NotNull Graphics g, @NotNull SoftWrapDrawingType drawingType, int x, int y, int lineHeight);
50
51   /**
52    * Allows to ask about horizontal offset to be applied to the given {@code 'x'} coordinate if drawing of the given
53    * type is performed at the given graphics buffer.
54    * <p/>
55    * Generally, this method is useful when we don't want to perform actual drawing for now but want to reserve
56    * a space necessary to do that in future. I.e. the aim is to avoid horizontal movement of already drawn content
57    * when the drawing is actually performed.
58    *
59    * @param g             target graphics buffer to draw in
60    * @param drawingType   target drawing type
61    * @param x             target {@code 'x'} coordinate to use
62    * @param y             target {@code 'y'} coordinate to use
63    * @param lineHeight    line height used at editor
64    * @return              horizontal offset that would be introduced if the drawing is performed
65    */
66   int getDrawingHorizontalOffset(@NotNull Graphics g, @NotNull SoftWrapDrawingType drawingType, int x, int y, int lineHeight);
67
68   /**
69    * Allows to ask for the minimal width in pixels required for painting of the given type.
70    *
71    * @param drawingType   target drawing type
72    * @return              width in pixels required for the painting of the given type
73    */
74   int getMinDrawingWidth(@NotNull SoftWrapDrawingType drawingType);
75
76   /**
77    * Allows to answer if it's possible to use current painter implementation at local environment (e.g. there is a possible
78    * case that particular painter that exploits unicode symbols for drawing can't be used because there is no font
79    * at local environment that knows how to draw target symbols).
80    *
81    * @return    {@code true} if current painter can be used at local environment; {@code false} otherwise
82    */
83   boolean canUse();
84
85   /**
86    * Called after a change of font preferences in editor, so that a painter could reset any related internal caches.
87    */
88   void reinit();
89 }