001package jmri.jmrix.loconet.swing.menuitemspi.spi;
002
003import java.util.ArrayList;
004import javax.swing.JMenu;
005import jmri.jmrix.loconet.LocoNetSystemConnectionMemo;
006import jmri.util.swing.WindowInterface;
007
008/**
009 * An interface which allows for extension of LocoNet menu items via an
010 * implementation of the {@link java.util.spi} mechanism.
011 * <br>
012 * The {@link jmri.jmrix.loconet.swing.menuitemspi.MenuItemsService} invokes the 
013 * {@link jmri.jmrix.loconet.swing.menuitemspi.spi.MenuItemsInterface#getMenuItems(boolean, jmri.util.swing.WindowInterface, jmri.jmrix.loconet.LocoNetSystemConnectionMemo)} 
014 * method to retrieve the service provider's menu items.
015 * <br>
016 * @author Bob Milhaupt  Copyright (C) 2021
017 */
018
019public interface MenuItemsInterface {
020    /**
021     * An interface for extension of the menu(s) associated with JMRI LocoNet-based
022     * connections, the JAVA SPI mechanism.
023     * 
024     * Implementers of this JAVA SPI interface provide an ArrayList of zero or 
025     * more items to be added to JMRI menu(s) for connection(s) of the "LocoNet" type.
026     * <br>
027     * The returned {@link java.util.ArrayList} may contain zero, one or more of any of the 
028     * objects allowed by a {@link javax.swing.JMenu} object.  This includes 
029     * objects of the class {@link jmri.jmrix.loconet.swing.LocoNetMenuItem}.
030     * <br>
031     * @param isLocoNetInterface informs whether the connection
032     *      has actual hardware.
033     * @param wi allows the extension menu items to be associated with the
034     *      {@link jmri.util.swing.WindowInterface} which relates to the connection's menu.
035     * @param memo the {@link jmri.jmrix.loconet.LocoNetSystemConnectionMemo} associated with the menu to
036     *      which the extension's MenuItem(s) are to be attached.
037     * @return an {@link java.util.ArrayList} of JMenu-compatible objects, as populated from the 
038     *      menu items reported by any available SPI extensions.  Implementer may
039     *      return an empty ArrayList if it does not implement any menu items.
040     */
041    public ArrayList<JMenu> getMenuItems(boolean isLocoNetInterface,
042            WindowInterface wi, LocoNetSystemConnectionMemo memo);
043
044}