136f91d71e0f97d391f5ae71c458673b7da6c069
[idea/community.git] / platform / platform-api / src / com / intellij / openapi / ui / popup / JBPopup.java
1 /*
2  * Copyright 2000-2012 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
17 package com.intellij.openapi.ui.popup;
18
19
20 import com.intellij.openapi.Disposable;
21 import com.intellij.openapi.actionSystem.DataContext;
22 import com.intellij.openapi.actionSystem.DataProvider;
23 import com.intellij.openapi.editor.Editor;
24 import com.intellij.openapi.project.Project;
25 import com.intellij.ui.awt.RelativePoint;
26 import org.intellij.lang.annotations.JdkConstants;
27 import org.jetbrains.annotations.NonNls;
28 import org.jetbrains.annotations.NotNull;
29 import org.jetbrains.annotations.Nullable;
30
31 import javax.swing.*;
32 import java.awt.*;
33 import java.awt.event.InputEvent;
34 import java.awt.event.KeyEvent;
35
36 /**
37  * Base interface for popup windows.
38  *
39  * @author mike
40  * @see com.intellij.openapi.ui.popup.JBPopupFactory
41  * @since 6.0
42  */
43 public interface JBPopup extends Disposable, LightweightWindow {
44
45   @NonNls String KEY = "JBPopup";
46
47   /**
48    * Shows the popup at the bottom left corner of the specified component.
49    *
50    * @param componentUnder the component near which the popup should be displayed.
51    */
52   void showUnderneathOf(@NotNull Component componentUnder);
53
54   /**
55    * Shows the popup at the specified point.
56    *
57    * @param point the relative point where the popup should be displayed.
58    */
59   void show(@NotNull RelativePoint point);
60
61   void showInScreenCoordinates(@NotNull Component owner, @NotNull Point point);
62
63   /**
64    * Shows the popup in the position most appropriate for the specified data context.
65    *
66    * @param dataContext the data context to which the popup is related.
67    * @see com.intellij.openapi.ui.popup.JBPopupFactory#guessBestPopupLocation(com.intellij.openapi.actionSystem.DataContext)
68    */
69   void showInBestPositionFor(@NotNull DataContext dataContext);
70
71
72
73   /**
74    * Shows the popup near the cursor location in the specified editor.
75    *
76    * @param editor the editor relative to which the popup should be displayed.
77    * @see com.intellij.openapi.ui.popup.JBPopupFactory#guessBestPopupLocation(com.intellij.openapi.editor.Editor)
78    */
79   void showInBestPositionFor(@NotNull Editor editor);
80
81   /**
82    * Shows the popup in the center of the specified component.
83    *
84    * @param component the component at which the popup should be centered.
85    */
86   void showInCenterOf(@NotNull Component component);
87
88
89   /**
90    * Shows the popups in the center of currently focused component
91    */
92   void showInFocusCenter();
93
94   /**
95    * Shows in best position with a given owner
96    */
97   void show(Component owner);  
98
99   /**
100    * Shows the popup in the center of the active window in the IDEA frame for the specified project.
101    *
102    * @param project the project in which the popup should be displayed.
103    */
104   void showCenteredInCurrentWindow(@NotNull Project project);
105
106   /**
107    * Hides popup as if Enter was pressed or or any other "accept" action
108    */
109   void closeOk(@Nullable InputEvent e);
110
111   /**
112    * Cancels the popup as if Esc was pressed or any other "cancel" action
113    */
114   void cancel();
115
116   /**
117    * @param b true if popup should request focus
118    */
119   void setRequestFocus(final boolean b);
120
121   /**
122    * Cancels the popup as a response to some mouse action. All the subsequent mouse events originated from the event's point
123    * will be consumed.
124    * @param e
125    */
126   void cancel(@Nullable InputEvent e);
127
128   /**
129    * Checks if it's currently allowed to close the popup.
130    *
131    * @return true if the popup can be closed, false if a callback disallowed closing the popup.
132    * @see com.intellij.openapi.ui.popup.ComponentPopupBuilder#setCancelCallback(com.intellij.openapi.util.Computable)
133    */
134   boolean canClose();
135
136   /**
137    * Checks if the popup is currently visible.
138    *
139    * @return true if the popup is visible, false otherwise.
140    */
141   boolean isVisible();
142
143   /**
144    * Returns the Swing component contained in the popup.
145    *
146    * @return the contents of the popup.
147    */
148   JComponent getContent();
149
150   /**
151    * Moves popup to the given point. Does nothing if popup is invisible.
152    * @param screenPoint Point to move to.
153    */
154   void setLocation(@NotNull Point screenPoint);
155
156   void setSize(@NotNull Dimension size);
157   Dimension getSize();
158
159   boolean isPersistent();
160
161   boolean isModalContext();
162
163   boolean isNativePopup();
164   void setUiVisible(boolean visible);
165
166   @Nullable
167     <T>
168   T getUserData(Class<T> userDataClass);
169
170   boolean isFocused();
171
172   boolean isCancelKeyEnabled();
173
174   void addListener(JBPopupListener listener);
175   void removeListener(JBPopupListener listener);
176
177   boolean isDisposed();
178
179   Component getOwner();
180   
181   void setMinimumSize(Dimension size);
182
183   void setFinalRunnable(@Nullable Runnable runnable);
184
185   void moveToFitScreen();
186
187   Point getLocationOnScreen();
188
189   void pack(boolean width, boolean height);
190
191   void setAdText(String s, @JdkConstants.HorizontalAlignment int alignment);
192
193   void setDataProvider(@NotNull DataProvider dataProvider);
194
195   /**
196    * This callback is called when new key event from the event queue is being processed.
197    * <p/>
198    * The popup has a right to decide if its further processing should be continued (method return value).
199    * 
200    * @param e  new key event being processed
201    * @return   <code>true</code> if the event is completely dispatched, i.e. no further processing is necessary;
202    *           <code>false</code> otherwise
203    */
204   boolean dispatchKeyEvent(@NotNull KeyEvent e);
205 }