1 /* 2 * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javafx.scene.control; 27 28 import javafx.beans.property.ObjectProperty; 29 import javafx.beans.property.ObjectPropertyBase; 30 import javafx.collections.ListChangeListener.Change; 31 import javafx.collections.ObservableList; 32 import javafx.event.Event; 33 import javafx.event.EventHandler; 34 import javafx.event.EventType; 35 import javafx.scene.Node; 36 37 import com.sun.javafx.collections.TrackableObservableList; 38 import com.sun.javafx.scene.control.Logging; 39 import javafx.beans.DefaultProperty; 40 import javafx.beans.property.ReadOnlyBooleanProperty; 41 import javafx.beans.property.ReadOnlyBooleanWrapper; 42 import javafx.event.EventDispatchChain; 43 44 /** 45 * <p> 46 * A popup menu of actionable items which is displayed to the user only upon request. 47 * When a menu is visible, in most use cases, the user can select one menu item 48 * before the menu goes back to its hidden state. This means the menu is a good 49 * place to put important functionality that does not necessarily need to be 50 * visible at all times to the user. 51 * <p> 52 * Menus are typically placed in a {@link MenuBar}, or as a submenu of another Menu. 53 * If the intention is to offer a context menu when the user right-clicks in a 54 * certain area of their user interface, then this is the wrong control to use. 55 * This is because when Menu is added to the scenegraph, it has a visual 56 * representation that will result in it appearing on screen. Instead, 57 * {@link ContextMenu} should be used in this circumstance. 58 * <p> 59 * Creating a Menu and inserting it into a MenuBar is easy, as shown below: 60 * <pre><code> 61 * final Menu menu1 = new Menu("File"); 62 * MenuBar menuBar = new MenuBar(); 63 * menuBar.getMenus().add(menu1); 64 * </code></pre> 65 * <p> 66 * A Menu is a subclass of {@link MenuItem} which means that it can be inserted 67 * into a Menu's {@link #items} ObservableList, resulting in a submenu being created: 68 * <pre><code> 69 * MenuItem menu12 = new MenuItem("Open"); 70 * menu1.getItems().add(menu12); 71 * </code></pre> 72 * <p> 73 * The items ObservableList allows for any {@link MenuItem} type to be inserted, 74 * including its subclasses {@link Menu}, {@link MenuItem}, {@link RadioMenuItem}, {@link CheckMenuItem}, 75 * {@link CustomMenuItem} and {@link SeparatorMenuItem}. In order to insert an arbitrary {@link Node} to 76 * a Menu, a CustomMenuItem can be used. One exception to this general rule is that 77 * {@link SeparatorMenuItem} could be used for inserting a separator. 78 * 79 * @see MenuBar 80 * @see MenuItem 81 * @since JavaFX 2.0 82 */ 83 @DefaultProperty("items") 84 public class Menu extends MenuItem { 85 86 /** 87 * <p>Called when the contextMenu for this menu <b>will</b> be shown. However if the 88 * contextMenu is empty then this will not be called. 89 * </p> 90 */ 91 public static final EventType<Event> ON_SHOWING = 92 new EventType<Event>(Event.ANY, "MENU_ON_SHOWING"); 93 94 /** 95 * <p>Called when the contextMenu for this menu shows. However if the 96 * contextMenu is empty then this will not be called. 97 * </p> 98 */ 99 public static final EventType<Event> ON_SHOWN = 100 new EventType<Event>(Event.ANY, "MENU_ON_SHOWN"); 101 102 /** 103 * <p>Called when the contextMenu for this menu <b>will</b> be hidden. However if the 104 * contextMenu is empty then this will not be called. 105 * </p> 106 */ 107 public static final EventType<Event> ON_HIDING = 108 new EventType<Event>(Event.ANY, "MENU_ON_HIDING"); 109 110 /** 111 * <p>Called when the contextMenu for this menu is hidden. However if the 112 * contextMenu is empty then this will not be called. 113 * </p> 114 */ 115 public static final EventType<Event> ON_HIDDEN = 116 new EventType<Event>(Event.ANY, "MENU_ON_HIDDEN"); 117 118 /*************************************************************************** 119 * * 120 * Constructors * 121 * * 122 **************************************************************************/ 123 124 /** 125 * Constructs a Menu with an empty string for its display text. 126 * @since JavaFX 2.2 127 */ 128 public Menu() { 129 this(""); 130 } 131 132 /** 133 * Constructs a Menu and sets the display text with the specified text. 134 * 135 * @param text the text to display on the menu button 136 */ 137 public Menu(String text) { 138 this(text,null); 139 } 140 141 /** 142 * Constructs a Menu and sets the display text with the specified text 143 * and sets the graphic {@link Node} to the given node. 144 * 145 * @param text the text to display on the menu button 146 * @param graphic the graphic to display on the menu button 147 */ 148 public Menu(String text, Node graphic) { 149 this(text, graphic, (MenuItem[])null); 150 } 151 152 /** 153 * Constructs a Menu and sets the display text with the specified text, 154 * the graphic {@link Node} to the given node, and inserts the given items 155 * into the {@link #getItems() items} list. 156 * 157 * @param text the text to display on the menu button 158 * @param graphic the graphic to display on the menu button 159 * @param items The items to display in the popup menu. 160 * @since JavaFX 8u40 161 */ 162 public Menu(String text, Node graphic, MenuItem... items) { 163 super(text,graphic); 164 getStyleClass().add(DEFAULT_STYLE_CLASS); 165 166 if (items != null) { 167 getItems().addAll(items); 168 } 169 170 parentPopupProperty().addListener(observable -> { 171 for (int i = 0; i < getItems().size(); i++) { 172 MenuItem item = getItems().get(i); 173 item.setParentPopup(getParentPopup()); 174 } 175 }); 176 } 177 178 179 180 /*************************************************************************** 181 * * 182 * Properties * 183 * * 184 **************************************************************************/ 185 186 /** 187 * Indicates whether the {@link ContextMenu} is currently visible. 188 * 189 * @defaultValue false 190 */ 191 private ReadOnlyBooleanWrapper showing; 192 193 private void setShowing(boolean value) { 194 if (getItems().size() == 0 || (value && isShowing())) return; 195 196 // these events will not fire if the showing property is bound 197 if (value) { 198 if (getOnMenuValidation() != null) { 199 Event.fireEvent(this, new Event(MENU_VALIDATION_EVENT)); 200 for(MenuItem m : getItems()) { 201 if (!(m instanceof Menu) && m.getOnMenuValidation() != null) { 202 Event.fireEvent(m, new Event(MenuItem.MENU_VALIDATION_EVENT)); 203 } 204 } 205 } 206 Event.fireEvent(this, new Event(Menu.ON_SHOWING)); 207 } else { 208 Event.fireEvent(this, new Event(Menu.ON_HIDING)); 209 } 210 showingPropertyImpl().set(value); 211 Event.fireEvent(this, (value) ? new Event(Menu.ON_SHOWN) : 212 new Event(Menu.ON_HIDDEN)); 213 } 214 215 public final boolean isShowing() { 216 return showing == null ? false : showing.get(); 217 } 218 219 public final ReadOnlyBooleanProperty showingProperty() { 220 return showingPropertyImpl().getReadOnlyProperty(); 221 } 222 223 private ReadOnlyBooleanWrapper showingPropertyImpl() { 224 if (showing == null) { 225 showing = new ReadOnlyBooleanWrapper() { 226 @Override protected void invalidated() { 227 // force validation 228 get(); 229 230 // update the styleclass 231 if (isShowing()) { 232 getStyleClass().add(STYLE_CLASS_SHOWING); 233 } else { 234 getStyleClass().remove(STYLE_CLASS_SHOWING); 235 } 236 } 237 238 @Override 239 public Object getBean() { 240 return Menu.this; 241 } 242 243 @Override 244 public String getName() { 245 return "showing"; 246 } 247 }; 248 } 249 return showing; 250 } 251 252 253 // --- On Showing 254 /** 255 * Called just prior to the {@code ContextMenu} being shown, even if the menu has 256 * no items to show. Note however that this won't be called if the menu does 257 * not have a valid anchor node. 258 */ 259 public final ObjectProperty<EventHandler<Event>> onShowingProperty() { return onShowing; } 260 public final void setOnShowing(EventHandler<Event> value) { onShowingProperty().set(value); } 261 public final EventHandler<Event> getOnShowing() { return onShowingProperty().get(); } 262 private ObjectProperty<EventHandler<Event>> onShowing = new ObjectPropertyBase<EventHandler<Event>>() { 263 @Override protected void invalidated() { 264 eventHandlerManager.setEventHandler(ON_SHOWING, get()); 265 } 266 267 @Override 268 public Object getBean() { 269 return Menu.this; 270 } 271 272 @Override 273 public String getName() { 274 return "onShowing"; 275 } 276 }; 277 278 279 // -- On Shown 280 /** 281 * Called just after the {@link ContextMenu} is shown. 282 */ 283 public final ObjectProperty<EventHandler<Event>> onShownProperty() { return onShown; } 284 public final void setOnShown(EventHandler<Event> value) { onShownProperty().set(value); } 285 public final EventHandler<Event> getOnShown() { return onShownProperty().get(); } 286 private ObjectProperty<EventHandler<Event>> onShown = new ObjectPropertyBase<EventHandler<Event>>() { 287 @Override protected void invalidated() { 288 eventHandlerManager.setEventHandler(ON_SHOWN, get()); 289 } 290 291 @Override 292 public Object getBean() { 293 return Menu.this; 294 } 295 296 @Override 297 public String getName() { 298 return "onShown"; 299 } 300 }; 301 302 303 // --- On Hiding 304 /** 305 * Called just prior to the {@link ContextMenu} being hidden. 306 */ 307 public final ObjectProperty<EventHandler<Event>> onHidingProperty() { return onHiding; } 308 public final void setOnHiding(EventHandler<Event> value) { onHidingProperty().set(value); } 309 public final EventHandler<Event> getOnHiding() { return onHidingProperty().get(); } 310 private ObjectProperty<EventHandler<Event>> onHiding = new ObjectPropertyBase<EventHandler<Event>>() { 311 @Override protected void invalidated() { 312 eventHandlerManager.setEventHandler(ON_HIDING, get()); 313 } 314 315 @Override 316 public Object getBean() { 317 return Menu.this; 318 } 319 320 @Override 321 public String getName() { 322 return "onHiding"; 323 } 324 }; 325 326 327 // --- On Hidden 328 /** 329 * Called just after the {@link ContextMenu} has been hidden. 330 */ 331 public final ObjectProperty<EventHandler<Event>> onHiddenProperty() { return onHidden; } 332 public final void setOnHidden(EventHandler<Event> value) { onHiddenProperty().set(value); } 333 public final EventHandler<Event> getOnHidden() { return onHiddenProperty().get(); } 334 private ObjectProperty<EventHandler<Event>> onHidden = new ObjectPropertyBase<EventHandler<Event>>() { 335 @Override protected void invalidated() { 336 eventHandlerManager.setEventHandler(ON_HIDDEN, get()); 337 } 338 339 @Override 340 public Object getBean() { 341 return Menu.this; 342 } 343 344 @Override 345 public String getName() { 346 return "onHidden"; 347 } 348 }; 349 350 351 352 /*************************************************************************** 353 * * 354 * Instance variables * 355 * * 356 **************************************************************************/ 357 358 private final ObservableList<MenuItem> items = new TrackableObservableList<MenuItem>() { 359 @Override protected void onChanged(Change<MenuItem> c) { 360 while (c.next()) { 361 // remove the parent menu from all menu items that have been removed 362 for (MenuItem item : c.getRemoved()) { 363 item.setParentMenu(null); 364 item.setParentPopup(null); 365 } 366 367 // set the parent menu to be this menu for all added menu items 368 for (MenuItem item : c.getAddedSubList()) { 369 if (item.getParentMenu() != null) { 370 Logging.getControlsLogger().warning("Adding MenuItem " + 371 item.getText() + " that has already been added to " 372 + item.getParentMenu().getText()); 373 item.getParentMenu().getItems().remove(item); 374 } 375 376 item.setParentMenu(Menu.this); 377 item.setParentPopup(getParentPopup()); 378 } 379 } 380 if (getItems().size() == 0 && isShowing()) { 381 showingPropertyImpl().set(false); 382 } 383 } 384 }; 385 386 387 388 /*************************************************************************** 389 * * 390 * Public API * 391 * * 392 **************************************************************************/ 393 394 /** 395 * The items to show within this menu. If this ObservableList is modified at 396 * runtime, the Menu will update as expected. 397 */ 398 public final ObservableList<MenuItem> getItems() { 399 return items; 400 } 401 402 /** 403 * If the Menu is not disabled and the {@link ContextMenu} is not already showing, 404 * then this will cause the {@link ContextMenu} to be shown. 405 */ 406 public void show() { 407 if (isDisable()) return; 408 setShowing(true); 409 } 410 411 /** 412 * Hides the {@link ContextMenu} if it was previously showing, and any showing 413 * submenus. If this menu is not showing, then invoking this function 414 * has no effect. 415 */ 416 public void hide() { 417 if (!isShowing()) return; 418 // hide all sub menus 419 for (MenuItem i : getItems()) { 420 if (i instanceof Menu) { 421 final Menu m = (Menu) i; 422 m.hide(); 423 } 424 } 425 setShowing(false); 426 } 427 428 /** {@inheritDoc} */ 429 @Override public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) { 430 eventHandlerManager.addEventHandler(eventType, eventHandler); 431 } 432 433 /** {@inheritDoc} */ 434 @Override public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) { 435 eventHandlerManager.removeEventHandler(eventType, eventHandler); 436 } 437 438 /** {@inheritDoc} */ 439 @Override public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) { 440 return tail.prepend(eventHandlerManager); 441 } 442 443 /*************************************************************************** 444 * * 445 * Stylesheet Handling * 446 * * 447 **************************************************************************/ 448 449 private static final String DEFAULT_STYLE_CLASS = "menu"; 450 private static final String STYLE_CLASS_SHOWING = "showing"; 451 }