platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java

   1 /*
   2  * Copyright 2000-2009 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.NotNull;
  28 import org.jetbrains.annotations.Nullable;
  29
  30 import javax.swing.*;
  31 import javax.swing.event.HyperlinkListener;
  32 import java.awt.*;
  33
  34 /**
  35  * Factory class for creating popup chooser windows (similar to the Code | Generate... popup).
  36  *
  37  * @author mike
  38  * @since 6.0
  39  */
  40 public abstract class JBPopupFactory {
  41   /**
  42    * Returns the popup factory instance.
  43    *
  44    * @return the popup factory instance.
  45    */
  46   public static JBPopupFactory getInstance() {
  47     return ServiceManager.getService(JBPopupFactory.class);
  48   }
  49
  50   public PopupChooserBuilder createListPopupBuilder(JList list) {
  51     return new PopupChooserBuilder(list);
  52   }
  53
  54   /**
  55    * Creates a popup with the specified title and two options, Yes and No.
  56    *
  57    * @param title the title of the popup.
  58    * @param onYes the runnable which is executed when the Yes option is selected.
  59    * @param defaultOptionIndex the index of the option which is selected by default.
  60    * @return the popup instance.
  61    */
  62   public abstract ListPopup createConfirmation(String title, Runnable onYes, int defaultOptionIndex);
  63
  64   /**
  65    * Creates a popup allowing to choose one of two specified options and execute code when one of them is selected.
  66    *
  67    * @param title the title of the popup.
  68    * @param yesText the title for the Yes option.
  69    * @param noText the title for the No option.
  70    * @param onYes the runnable which is executed when the Yes option is selected.
  71    * @param defaultOptionIndex the index of the option which is selected by default.
  72    * @return the popup instance.
  73    */
  74   public abstract ListPopup createConfirmation(String title, String yesText, String noText, Runnable onYes, int defaultOptionIndex);
  75
  76   /**
  77    * Creates a popup allowing to choose one of two specified options and execute code when either of them is selected.
  78    *
  79    * @param title the title of the popup.
  80    * @param yesText the title for the Yes option.
  81    * @param noText the title for the No option.
  82    * @param onYes the runnable which is executed when the Yes option is selected.
  83    * @param onNo the runnable which is executed when the No option is selected.
  84    * @param defaultOptionIndex the index of the option which is selected by default.
  85    * @return the popup instance.
  86    */
  87   public abstract ListPopup createConfirmation(String title, String yesText, String noText, Runnable onYes, Runnable onNo, int defaultOptionIndex);
  88
  89   public abstract ListPopupStep createActionsStep(ActionGroup actionGroup,
  90                                                   DataContext dataContext,
  91                                                   boolean showNumbers,
  92                                                   boolean showDisabledActions,
  93                                                   String title,
  94                                                   Component component,
  95                                                   boolean honorActionMnemonics);
  96
  97   public abstract ListPopupStep createActionsStep(ActionGroup actionGroup,
  98                                                   DataContext dataContext,
  99                                                   boolean showNumbers,
 100                                                   boolean showDisabledActions,
 101                                                   String title,
 102                                                   Component component,
 103                                                   boolean honorActionMnemonics,
 104                                                   int defaultOptionIndex, final boolean autoSelectionEnabled);
 105
 106   public abstract RelativePoint guessBestPopupLocation(JComponent component);
 107
 108   public boolean isChildPopupFocused(@Nullable Component parent) {
 109     if (parent == null) return false;
 110     final JBPopup child = getChildPopup(parent);
 111     return child != null && child.isFocused();
 112   }
 113
 114   /**
 115    * Possible ways to select actions in a popup from keyboard.
 116    */
 117   public enum ActionSelectionAid {
 118     /**
 119      * The actions in a popup are prefixed by numbers (indexes in the list).
 120      */
 121     NUMBERING,
 122
 123     /**
 124      * Same as numbering, but will allow A-Z 'numbers' when out of 0-9 range.
 125      */
 126     ALPHA_NUMBERING,
 127
 128     /**
 129      * The actions in a popup can be selected by typing part of the action's text.
 130      */
 131     SPEEDSEARCH,
 132
 133     /**
 134      * The actions in a popup can be selected by pressing the character from the action's text prefixed with
 135      * an &amp; character.
 136      */
 137     MNEMONICS
 138   }
 139
 140   /**
 141    * Creates a popup allowing to choose one of the actions from the specified action group.
 142    *
 143    * @param title the title of the popup.
 144    * @param actionGroup the action group from which the popup is built.
 145    * @param dataContext the data context which provides the data for the selected action
 146    * @param selectionAidMethod keyboard selection mode for actions in the popup.
 147    * @param showDisabledActions if true, disabled actions are shown as disabled; if false, disabled actions are not shown
 148    * @return the popup instance.
 149    */
 150   public abstract ListPopup createActionGroupPopup(String title,
 151                                                    ActionGroup actionGroup,
 152                                                    DataContext dataContext,
 153                                                    ActionSelectionAid selectionAidMethod,
 154                                                    boolean showDisabledActions);
 155
 156   /**
 157    * Creates a popup allowing to choose one of the actions from the specified action group.
 158    *
 159    * @param title the title of the popup.
 160    * @param actionGroup the action group from which the popup is built.
 161    * @param dataContext the data context which provides the data for the selected action
 162    * @param selectionAidMethod keyboard selection mode for actions in the popup.
 163    * @param showDisabledActions if true, disabled actions are shown as disabled; if false, disabled actions are not shown
 164    * @param disposeCallback method which is called when the popup is closed (either by selecting an action or by canceling)
 165    * @param maxRowCount maximum number of popup rows visible at once (if there are more actions in the action group, a scrollbar
 166    *                    is displayed)
 167    * @return the popup instance.
 168    */
 169   public abstract ListPopup createActionGroupPopup(String title,
 170                                                    ActionGroup actionGroup,
 171                                                    DataContext dataContext,
 172                                                    ActionSelectionAid selectionAidMethod,
 173                                                    boolean showDisabledActions,
 174                                                    @Nullable Runnable disposeCallback,
 175                                                    int maxRowCount);
 176
 177   public abstract ListPopup createActionGroupPopup(String title,
 178                                                    ActionGroup actionGroup,
 179                                                    DataContext dataContext,
 180                                                    boolean showNumbers,
 181                                                    boolean showDisabledActions,
 182                                                    boolean honorActionMnemonics,
 183                                                    @Nullable Runnable disposeCallback,
 184                                                    int maxRowCount,
 185                                                    @Nullable Condition<AnAction> preselectActionCondition);
 186
 187   /**
 188    * @deprecated use {@link #createListPopup(ListPopupStep)} instead (<code>step</code> must be a ListPopupStep in any case)
 189    */
 190   public abstract ListPopup createWizardStep(PopupStep step);
 191
 192   /**
 193    * Creates a custom list popup with the specified step.
 194    *
 195    * @param step the custom step for the list popup.
 196    * @return the popup instance.
 197    */
 198   public abstract ListPopup createListPopup(ListPopupStep step);
 199
 200   public abstract TreePopup createTree(JBPopup parent, TreePopupStep step, Object parentValue);
 201   public abstract TreePopup createTree(TreePopupStep step);
 202
 203   public abstract ComponentPopupBuilder createComponentPopupBuilder(JComponent content, JComponent preferableFocusComponent);
 204
 205   /**
 206    * Returns the location where a popup with the specified data context is displayed.
 207    *
 208    * @param dataContext the data context from which the location is determined.
 209    * @return location as close as possible to the action origin. Method has special handling of
 210    *         the following components:<br>
 211    *         - caret offset for editor<br>
 212    *         - current selected node for tree<br>
 213    *         - current selected row for list<br>
 214    */
 215   public abstract RelativePoint guessBestPopupLocation(DataContext dataContext);
 216
 217   /**
 218    * Returns the location where a popup invoked from the specified editor should be displayed.
 219    *
 220    * @param editor the editor over which the popup is shown.
 221    * @return location as close as possible to the action origin.
 222    */
 223   public abstract RelativePoint guessBestPopupLocation(Editor editor);
 224
 225   public abstract Point getCenterOf(JComponent container, JComponent content);
 226
 227   @Nullable
 228   public abstract JBPopup getChildPopup(@NotNull Component parent);
 229
 230   public abstract BalloonBuilder createBalloonBuilder(@NotNull JComponent content);
 231
 232
 233   public abstract BalloonBuilder createHtmlTextBalloonBuilder(@NotNull String htmlContent, @Nullable Icon icon, Color fillColor, @Nullable HyperlinkListener listener);
 234
 235   public abstract BalloonBuilder createHtmlTextBalloonBuilder(@NotNull String htmlContent, MessageType messageType, @Nullable HyperlinkListener listener);
 236
 237   public abstract JBPopup createMessage(String text);
 238
 239 }