package com.explodingpixels.macwidgets;
import javax.swing.JPopupMenu;
/**
* <p>
* An interface to hook into the context-menu showing process. When installed on a
* {@link SourceList}, this interface will be notified just prior to a context menu being shown.
* </p>
* <p>
* Here's a sample implementation and installation of this interface:
* </p>
* <pre>
* SourceListContextMenuProvider menuProvider = new SourceListContextMenuProvider() {
* public JPopupMenu createContextMenu() {
* // create and install your custom menu items for context-menu's on the SourceList.
* JPopupMenu menu = new JPopupMenu();
* popupMenu.add(new JMenuItem("Generic Menu for SourceList"));
* return popupMenu;
* }
* public JPopupMenu createContextMenu(JPopupMenu popupMenu, SourceListItem item) {
* // create and install your custom menu items for context-menu's on a SourceListItem.
* JPopupMenu menu = new JPopupMenu();
* popupMenu.add(new JMenuItem("Menu for " + item.getText()));
* return menu;
* }
* public JPopupMenu createContextMenu(SourceListCategory category) {
* // create and install your custom menu items for context-menu's on a SourceListCategory.
* JPopupMenu menu = new JPopupMenu();
* popupMenu.add(new JMenuItem("Menu for " + category.getText()));
* return menu;
* }
* };
* mySourceList.setSourceListContextMenuProvider(menuProvider);
* <pre>
*/
public interface SourceListContextMenuProvider {
/**
* Called when the user requests that a context-menu be shown on the {@link SourceList} itself.
* This will only be called if the {@code SourceList} does not fill the entire view (doesn't
* have scroll bars) and the user clicks below any item or category. If the returned menu is
* null or if no menu items are added to the menu, then the menu will not be shown.
*
* @return the context menu for the associated {@code SourceList}. Can be null or have no menu
* items to indicate no menu should be shown.
*/
JPopupMenu createContextMenu();
/**
* Called when the user requests that a context-menu be shown on a {@link SourceListItem}.
* If the returned menu is null or if no menu items are added to the menu, then the menu will
* not be shown.
*
* @param item the {@code SourceListItem} that the context-menu was requested for.
* @return the context menu for the associated {@code SourceListItem}. Can be null or have no
* menu items to indicate no menu should be shown.
*/
JPopupMenu createContextMenu(SourceListItem item);
/**
* Called when the user requests that a context-menu be shown on a {@link SourceListCategory}.
* If the returned menu is null or no menu items are added to the menu, then the menu will not
* be shown.
*
* @param category the {@code SourceListCategory} that the context-menu was requested for.
* @return the context menu for the associated {@code SourceListCategory}. Can be null or have
* no menu items to indicate no menu should be shown.
*/
JPopupMenu createContextMenu(SourceListCategory category);
}