e1ecacc1c776c9a47a3a0f4f652004d8c8783f72
[idea/community.git] / platform / platform-api / src / com / intellij / openapi / ui / popup / JBPopupFactory.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
17 package com.intellij.openapi.ui.popup;
18
19 import com.intellij.openapi.actionSystem.ActionGroup;
20 import com.intellij.openapi.actionSystem.AnAction;
21 import com.intellij.openapi.actionSystem.DataContext;
22 import com.intellij.openapi.components.ServiceManager;
23 import com.intellij.openapi.editor.Editor;
24 import com.intellij.openapi.ui.MessageType;
25 import com.intellij.openapi.util.Condition;
26 import com.intellij.ui.awt.RelativePoint;
27 import org.jetbrains.annotations.Nls;
28 import org.jetbrains.annotations.NotNull;
29 import org.jetbrains.annotations.Nullable;
30
31 import javax.swing.*;
32 import javax.swing.event.HyperlinkListener;
33 import java.awt.*;
34 import java.util.List;
35
36 /**
37  * Factory class for creating popup chooser windows (similar to the Code | Generate... popup) and various notifications/confirmations.
38  *
39  * @author mike
40  * @since 6.0
41  */
42 public abstract class JBPopupFactory {
43   /**
44    * Returns the popup factory instance.
45    *
46    * @return the popup factory instance.
47    */
48   public static JBPopupFactory getInstance() {
49     return ServiceManager.getService(JBPopupFactory.class);
50   }
51
52   @NotNull
53   public PopupChooserBuilder createListPopupBuilder(@NotNull JList list) {
54     return new PopupChooserBuilder(list);
55   }
56
57   /**
58    * Creates a popup with the specified title and two options, Yes and No.
59    *
60    * @param title the title of the popup.
61    * @param onYes the runnable which is executed when the Yes option is selected.
62    * @param defaultOptionIndex the index of the option which is selected by default.
63    * @return the popup instance.
64    */
65   @NotNull
66   public abstract ListPopup createConfirmation(String title, Runnable onYes, int defaultOptionIndex);
67
68   /**
69    * Creates a popup allowing to choose one of two specified options and execute code when one of them is selected.
70    *
71    * @param title the title of the popup.
72    * @param yesText the title for the Yes option.
73    * @param noText the title for the No option.
74    * @param onYes the runnable which is executed when the Yes option is selected.
75    * @param defaultOptionIndex the index of the option which is selected by default.
76    * @return the popup instance.
77    */
78   @NotNull
79   public abstract ListPopup createConfirmation(String title, String yesText, String noText, Runnable onYes, int defaultOptionIndex);
80
81   /**
82    * Creates a popup allowing to choose one of two specified options and execute code when either of them is selected.
83    *
84    * @param title the title of the popup.
85    * @param yesText the title for the Yes option.
86    * @param noText the title for the No option.
87    * @param onYes the runnable which is executed when the Yes option is selected.
88    * @param onNo the runnable which is executed when the No option is selected.
89    * @param defaultOptionIndex the index of the option which is selected by default.
90    * @return the popup instance.
91    */
92   @NotNull
93   public abstract ListPopup createConfirmation(String title,
94                                                String yesText,
95                                                String noText,
96                                                Runnable onYes,
97                                                Runnable onNo,
98                                                int defaultOptionIndex);
99
100   @NotNull
101   public abstract ListPopupStep createActionsStep(@NotNull ActionGroup actionGroup,
102                                                   @NotNull DataContext dataContext,
103                                                   boolean showNumbers,
104                                                   boolean showDisabledActions,
105                                                   String title,
106                                                   Component component,
107                                                   boolean honorActionMnemonics);
108
109   @NotNull
110   public abstract ListPopupStep createActionsStep(@NotNull ActionGroup actionGroup,
111                                                   @NotNull DataContext dataContext,
112                                                   boolean showNumbers,
113                                                   boolean showDisabledActions,
114                                                   String title,
115                                                   Component component,
116                                                   boolean honorActionMnemonics,
117                                                   int defaultOptionIndex, final boolean autoSelectionEnabled);
118
119   @NotNull
120   public abstract RelativePoint guessBestPopupLocation(@NotNull JComponent component);
121
122   public boolean isChildPopupFocused(@Nullable Component parent) {
123     return getChildFocusedPopup(parent) != null;
124   }
125
126   public JBPopup getChildFocusedPopup(@Nullable Component parent) {
127     if (parent == null) return null;
128     List<JBPopup> popups = getChildPopups(parent);
129     for (JBPopup each : popups) {
130       if (each.isFocused()) return each;
131       JBPopup childFocusedPopup = getChildFocusedPopup(each.getContent());
132       if (childFocusedPopup != null) {
133         return childFocusedPopup;
134       }
135     }
136     return null;
137   }
138
139   /**
140    * Possible ways to select actions in a popup from keyboard.
141    */
142   public enum ActionSelectionAid {
143     /**
144      * The actions in a popup are prefixed by numbers (indexes in the list).
145      */
146     NUMBERING,
147
148     /**
149      * Same as numbering, but will allow A-Z 'numbers' when out of 0-9 range.
150      */
151     ALPHA_NUMBERING,
152
153     /**
154      * The actions in a popup can be selected by typing part of the action's text.
155      */
156     SPEEDSEARCH,
157
158     /**
159      * The actions in a popup can be selected by pressing the character from the action's text prefixed with
160      * an &amp; character.
161      */
162     MNEMONICS
163   }
164
165   /**
166    * Creates a popup allowing to choose one of the actions from the specified action group.
167    *
168    * @param title the title of the popup.
169    * @param actionGroup the action group from which the popup is built.
170    * @param dataContext the data context which provides the data for the selected action
171    * @param selectionAidMethod keyboard selection mode for actions in the popup.
172    * @param showDisabledActions if true, disabled actions are shown as disabled; if false, disabled actions are not shown
173    * @return the popup instance.
174    */
175   @NotNull
176   public abstract ListPopup createActionGroupPopup(@Nullable @Nls(capitalization = Nls.Capitalization.Title) String title,
177                                                    @NotNull ActionGroup actionGroup,
178                                                    @NotNull DataContext dataContext,
179                                                    ActionSelectionAid selectionAidMethod,
180                                                    boolean showDisabledActions);
181
182   /**
183    * Creates a popup allowing to choose one of the actions from the specified action group.
184    *
185    * @param title the title of the popup.
186    * @param actionGroup the action group from which the popup is built.
187    * @param dataContext the data context which provides the data for the selected action
188    * @param selectionAidMethod keyboard selection mode for actions in the popup.
189    * @param showDisabledActions if true, disabled actions are shown as disabled; if false, disabled actions are not shown
190    * @param actionPlace action place for ActionManager to use when creating the popup
191    * @return the popup instance.
192    */
193   @NotNull
194   public abstract ListPopup createActionGroupPopup(@Nls(capitalization = Nls.Capitalization.Title) String title,
195                                                    @NotNull ActionGroup actionGroup,
196                                                    @NotNull DataContext dataContext,
197                                                    ActionSelectionAid selectionAidMethod,
198                                                    boolean showDisabledActions,
199                                                    @Nullable String actionPlace);
200
201   /**
202    * Creates a popup allowing to choose one of the actions from the specified action group.
203    *
204    * @param title the title of the popup.
205    * @param actionGroup the action group from which the popup is built.
206    * @param dataContext the data context which provides the data for the selected action
207    * @param selectionAidMethod keyboard selection mode for actions in the popup.
208    * @param showDisabledActions if true, disabled actions are shown as disabled; if false, disabled actions are not shown
209    * @param disposeCallback method which is called when the popup is closed (either by selecting an action or by canceling)
210    * @param maxRowCount maximum number of popup rows visible at once (if there are more actions in the action group, a scrollbar
211    *                    is displayed)
212    * @return the popup instance.
213    */
214   @NotNull
215   public abstract ListPopup createActionGroupPopup(@Nls(capitalization = Nls.Capitalization.Title) String title,
216                                                    @NotNull ActionGroup actionGroup,
217                                                    @NotNull DataContext dataContext,
218                                                    ActionSelectionAid selectionAidMethod,
219                                                    boolean showDisabledActions,
220                                                    @Nullable Runnable disposeCallback,
221                                                    int maxRowCount);
222
223   @NotNull
224   public ListPopup createActionGroupPopup(@Nls(capitalization = Nls.Capitalization.Title) String title,
225                                           @NotNull ActionGroup actionGroup,
226                                           @NotNull DataContext dataContext,
227                                           boolean showDisabledActions,
228                                           @Nullable Runnable disposeCallback,
229                                           int maxRowCount) {
230     return createActionGroupPopup(title, actionGroup, dataContext, JBPopupFactory.ActionSelectionAid.SPEEDSEARCH, showDisabledActions, disposeCallback, maxRowCount);
231   }
232
233   @NotNull
234   public abstract ListPopup createActionGroupPopup(@Nls(capitalization = Nls.Capitalization.Title) String title,
235                                                    @NotNull ActionGroup actionGroup,
236                                                    @NotNull DataContext dataContext,
237                                                    boolean showNumbers,
238                                                    boolean showDisabledActions,
239                                                    boolean honorActionMnemonics,
240                                                    @Nullable Runnable disposeCallback,
241                                                    int maxRowCount,
242                                                    @Nullable Condition<AnAction> preselectActionCondition);
243
244   @NotNull
245   public abstract ListPopup createActionGroupPopup(@Nls(capitalization = Nls.Capitalization.Title) String title,
246                                                    @NotNull ActionGroup actionGroup,
247                                                    @NotNull DataContext dataContext,
248                                                    ActionSelectionAid selectionAidMethod,
249                                                    boolean showDisabledActions,
250                                                    @Nullable Runnable disposeCallback,
251                                                    int maxRowCount,
252                                                    @Nullable Condition<AnAction> preselectActionCondition,
253                                                    @Nullable String actionPlace);
254
255   /**
256    * @deprecated use {@link #createListPopup(ListPopupStep)} instead (<code>step</code> must be a ListPopupStep in any case)
257    */
258   @NotNull
259   public abstract ListPopup createWizardStep(@NotNull PopupStep step);
260
261   /**
262    * Creates a custom list popup with the specified step.
263    *
264    * @param step the custom step for the list popup.
265    * @return the popup instance.
266    */
267   @NotNull
268   public abstract ListPopup createListPopup(@NotNull ListPopupStep step);
269
270   /**
271    * Creates a custom list popup with the specified step.
272    *
273    * @param step        the custom step for the list popup.
274    * @param maxRowCount the number of visible rows to show in the popup (if the popup has more items,
275    *                    a scrollbar will be displayed).
276    * @return the popup instance.
277    * @since 14.1
278    */
279   @NotNull
280   public abstract ListPopup createListPopup(@NotNull ListPopupStep step, int maxRowCount);
281
282   @NotNull
283   public abstract TreePopup createTree(JBPopup parent, @NotNull TreePopupStep step, Object parentValue);
284   @NotNull
285   public abstract TreePopup createTree(@NotNull TreePopupStep step);
286
287   @NotNull
288   public abstract ComponentPopupBuilder createComponentPopupBuilder(@NotNull JComponent content, @Nullable JComponent preferableFocusComponent);
289
290   /**
291    * Returns the location where a popup with the specified data context is displayed.
292    *
293    * @param dataContext the data context from which the location is determined.
294    * @return location as close as possible to the action origin. Method has special handling of
295    *         the following components:<br>
296    *         - caret offset for editor<br>
297    *         - current selected node for tree<br>
298    *         - current selected row for list<br>
299    */
300   @NotNull
301   public abstract RelativePoint guessBestPopupLocation(@NotNull DataContext dataContext);
302
303   /**
304    * Returns the location where a popup invoked from the specified editor should be displayed.
305    *
306    * @param editor the editor over which the popup is shown.
307    * @return location as close as possible to the action origin.
308    */
309   @NotNull
310   public abstract RelativePoint guessBestPopupLocation(@NotNull Editor editor);
311
312   /**
313    * @param editor the editor over which the popup is shown.
314    * @return true if popup location is located in visible area
315    *         false if center would be suggested instead
316    */
317   public abstract boolean isBestPopupLocationVisible(@NotNull Editor editor);
318
319   public abstract Point getCenterOf(JComponent container, JComponent content);
320   
321   @NotNull
322   public abstract List<JBPopup> getChildPopups(@NotNull Component parent);
323
324   public abstract boolean isPopupActive();
325
326   @NotNull
327   public abstract BalloonBuilder createBalloonBuilder(@NotNull JComponent content);
328
329   @NotNull
330   public abstract BalloonBuilder createDialogBalloonBuilder(@NotNull JComponent content, String title);
331
332   @NotNull
333   public abstract BalloonBuilder createHtmlTextBalloonBuilder(@NotNull String htmlContent, @Nullable Icon icon, Color fillColor, @Nullable HyperlinkListener listener);
334
335   @NotNull
336   public abstract BalloonBuilder createHtmlTextBalloonBuilder(@NotNull String htmlContent, MessageType messageType, @Nullable HyperlinkListener listener);
337
338   @NotNull
339   public abstract JBPopup createMessage(String text);
340
341   @Nullable
342   public abstract Balloon getParentBalloonFor(@Nullable Component c);
343
344 }